@litfamily/litgrok 1.0.26 → 1.0.28

package/.grok/skills/frontend-ui-ux/references/house-styles.md

@@ -0,0 +1,234 @@
+# House styles, the kit and the design lock
+
+Read this before writing markup for a new page or screen. It replaces the decisions a run used to
+make from scratch every time (typeface, palette, scale, radii, component anatomy, page skeleton)
+with a small closed set that a script writes into the project and the interface probe checks on the
+render. The point is that two runs of the same brief land in the same register at the same level of
+craft; what still varies is the content, the composition inside the skeleton and the accent art. One
+place on every page is allowed to be bold: its signature moment (section 6), declared in the lock and
+checked like the rest.
+
+## 1. Lock the look first
+
+```bash
+FRONTEND_UIUX_SKILL_ROOT="<directory containing the selected installed SKILL.md>"
+node "$FRONTEND_UIUX_SKILL_ROOT/scripts/design-lock.mjs" list
+node "$FRONTEND_UIUX_SKILL_ROOT/scripts/design-lock.mjs" match "<the request>"
+node "$FRONTEND_UIUX_SKILL_ROOT/scripts/design-lock.mjs" init --family <family> [--style <id>] [--brief "<the request>"] [--density calm] --dir <project> --scaffold \
+  --moment <kind> --moment-note "<what it shows>" [--moment-place "<where it sits>"]
+node "$FRONTEND_UIUX_SKILL_ROOT/scripts/design-lock.mjs" moment --dir <project> --kind <kind> --note "<what it shows>"
+```
+
+`init` writes into the project:
+
+| File | What it is |
+|---|---|
+| `design.lock.json` | The declaration the probe reads: style id, family, density, fonts, type scale, display range and moment ceiling, radii, spacing, light and dark palette, elevation, and the signature moment (scale, kind, note, place) |
+| `ui/tokens.css` | Generated custom properties (`--c-*`, `--fs-*`, `--fw-*`, `--sp-*`, `--radius-*`, `--shadow-*`, `--dur-*`) with dark mode and the `@font-face` rules |
+| `ui/components.css` | The shared `ui-*` component sheet; it reads only tokens |
+| `ui/ui.js` | Charts with a table fallback, sortable tables, keyboard tabs |
+| `ui/fonts/` | Pretendard (Latin and Hangul) and JetBrains Mono with their OFL texts, copied from this plugin after a sha256 check; nothing is fetched |
+| `index.html` | Only with `--scaffold` and no existing page: the starter for the family |
+
+**Density.** Every lock records `density: rich` unless the request asks for a calm page. Rich is
+the default because the user wants pages that feel made, not emptied: a tighter section rhythm
+(48, 72 and 96 px), the style's texture (field-notes notebook dots), a second accent family
+(`--c-accent-2`, `-ink`, `-wash`, `on-accent-2`), colour bands (`ui-band`, `ui-band--accent-2`,
+`ui-band--support`), a two-accent wash (`ui-wash`) and an atmosphere glow (`ui-glow`, a soft
+glow token that is `none` on flat and offset locks). `density: calm` is opt-in: `--density calm`,
+or a brief that says minimal, calm, quiet, restrained, understated, 미니멀, 차분, 절제, 담백 or 간결
+(`match` prints the density it reads). Calm restores the broad 64, 96 and 128 px sections, a flat
+canvas, no glow, and holds the probe to one accent hue (CF-205). Contrast, focus, overflow,
+reduced motion and every other floor are the same in both.
+
+Choose in this order and stop at the first rule that decides:
+
+1. **Existing product or brand tokens** (brownfield, a design system in the repo, colours or type the
+   user named): do not lock a kit style over them. Either write a style file in the same schema as
+   `kit/styles/*.json` with the brand's values and lock it with `--from <file>` (a new id), or skip
+   the lock and say the DS rules did not run.
+2. **The brief names a register.** A style keyword in the request picks it: pass the request as
+   `--brief` (or run `match`) and `init` locks the style whose keyword it contains, the longest
+   keyword winning, so "neo-brutalism" never lands on `computational-brutalism`. Brutalist,
+   brutalism, retro-futurist, CRT, 브루탈리즘 and 레트로퓨처 pick `computational-brutalism`;
+   neo-brutalism, neubrutalism and 네오브루탈리즘 pick `neo-brutalism`; `list` prints every
+   keyword. A register named in other words matches a style's `use_when` line: lock that style.
+3. **Competing directions left open** by the brief: ask, as `references/production-interview.md`
+   says, before locking.
+4. **No visual direction at all:** the family decides, and `init` without `--style` applies it.
+   A `landing` page (read once: landing, docs, report) locks `field-notes`, the authored default
+   profile (`references/default-editorial-pixel.json`) made complete: same palette, spacing, type
+   ranges and pixel-art rule, plus the fonts, radii, elevation and component anatomy the profile
+   left open. A `workspace` or `settings` screen (dashboards, settings, forms, admin and data-dense
+   screens) locks `graphite`. `meadow` is never a default; it needs a brief that asks for its
+   register. The same holds for `computational-brutalism` and `neo-brutalism`: opt-in only.
+
+| Style | Register | Accent art |
+|---|---|---|
+| `field-notes` | Default for `landing`. Warm paper with notebook dots, deep ink, a terracotta accent with a deep-teal second accent, mist as the tint, thin rules instead of shadows, large editorial title, small lowercase mono labels | An original pixel motif on read-once pages (section 5) |
+| `graphite` | Default for `workspace` and `settings`. Cool greys, white surfaces, a blue accent with a rose second accent, 6–8 px radii, soft two-layer elevation | None |
+| `meadow` | Opt-in only. Near-white, deep teal accent, coral second accent, sand tint, 12–18 px radii, soft elevation | None |
+| `computational-brutalism` | Opt-in only. Retro-futurist instrument with its structure on show: drafting-film grey on a 32 px plotting grid with a stronger line every 160 px, monospaced text and mono headings and figures at real size, square corners, 3 px section rules carrying `data-coord` labels, 2 px compartments with inverse ink header bars, uppercase mono meta, heavy uppercase display, a hazard-orange signal with a plotter-blue second accent; dark mode is a phosphor CRT with an amber signal. Flat elevation | Instrument parts (section 5) |
+| `neo-brutalism` | Opt-in only. Lavender canvas, white surfaces, 3 px ink outlines on surfaces and 2 px on controls, zero-blur ink offset shadows (6 px surfaces, 3 px controls), solid sunflower-yellow panel heads and accent with ink text, an electric-blue second accent, pink support block, chunky 900-weight display and 800-weight headings, buttons that press into their shadow. Offset elevation | Stickers and colour blocks (section 5) |
+
+Each style file also carries `signature` (what must show for the register to read) and `forbid`
+(what breaks it); `design-lock.mjs list` prints both. The two brutalist registers differ on
+purpose: computational brutalism is flat, square and monospaced, neo-brutalism is outlined, offset
+and loud. Never mix their signatures on one page.
+
+Families decide the skeleton, not the look:
+
+| Family | Use for | Starter |
+|---|---|---|
+| `landing` | Pages read once: landing, product, launch, portfolio, docs home | Site bar, split hero, steps, feature split with a real kit view, quote, three plans, FAQ, footer |
+| `workspace` | Screens worked in: dashboards, consoles, admin, tables | App shell (side nav, top bar), headline figures, 8 + 4 panel row, full-width table with filter and search |
+| `settings` | Guided forms: settings, account, onboarding, checkout | Section index plus one column capped near 720 px, labelled fields with hints and errors, save bar with status, danger zone with a typed confirmation dialog |
+
+A starter is a skeleton: keep its order unless the brief says otherwise, delete what the brief does
+not ask for, add sections by reusing its parts. Replace every `{{slot}}`; the probe fails a page
+that still shows one (DS-006). Mixed products use one style and the family of each screen.
+
+## 2. Build only with the kit
+
+- Link `ui/tokens.css` first, then `ui/components.css`, then page rules. Load `ui/ui.js` with
+  `defer` when a chart, sortable table or tab set is on the page.
+- Page rules may set layout (grid areas, widths, order, `gap`) and may only use `var(--…)` for
+  colour, type size, weight, radius, shadow, spacing and duration. A literal colour, font family or
+  off-scale size is drift; the probe reports it (DS-002 to DS-005).
+- Something the kit lacks is built from tokens in a page rule, in the kit's idiom. It is not a reason
+  to import a framework, a second icon set or another font.
+- Copy is still the work: product names, numbers and sentences specific to the brief. Mark invented
+  figures as examples where a reader could take them as real.
+
+### Class catalogue
+
+| Area | Classes |
+|---|---|
+| Type | `ui-display` (the one display title), `ui-h1` `ui-h2` `ui-h3` `ui-h4`, `ui-lead`, `ui-body`, `ui-muted`, `ui-small`, `ui-meta`, `ui-label` (mono, lowercase, short), `ui-num` (tabular), `ui-code` |
+| Layout | `ui-container` (`--narrow`, `--wide`), `ui-section` (`--sunken`), `ui-band` (`--accent-2`, `--support`: a full-bleed colour band whose text takes the band's ink), `ui-section-head`, `ui-stack` (`--tight`, `--loose`), `ui-cluster`, `ui-split` (`--even`, `--top`), `ui-grid` with `--cols` |
+| Actions | `ui-btn` with `--primary`, `--ink`, `--quiet`, `--danger`, `--sm`; one primary per view |
+| Forms | `ui-field` with `__label`, `__hint`, `__error`; `ui-input`, `ui-select`, `ui-textarea`; `ui-input-group` with `__addon`; `ui-check`; `ui-switch` (a checkbox with `role="switch"`); `ui-segmented` (buttons with `aria-pressed`); `ui-form-actions` |
+| Surfaces | `ui-panel` (`--flush`, `--accent-2`) with `__head` and `__title`; `ui-wash` (the two-accent wash); `ui-glow` (the lock's glow, for one surface such as the moment); `ui-rule`; `ui-callout` (`--info`, `--positive`, `--warning`, `--negative`) |
+| Status | `ui-status` (`--positive`, `--warning`, `--negative`, `--info`) always with words; `ui-tag` with the same variants, `--accent` and `--accent-2` |
+| Figures | `ui-stat-row` of `ui-stat` with `__label`, `__value` (a `div`), `__note`; `ui-meter` with an inner `span` width |
+| Tables | `ui-table-wrap` around every `ui-table` (`--compact`, `--stack` for phones with `data-label` on each cell); numeric cells `is-num`; sortable headers `<th><button class="ui-sort">` inside `table[data-ui-sortable]` |
+| Lists | `ui-list`, `ui-steps` (an `ol` of real steps), `ui-checklist` |
+| Disclosure | `details.ui-disclosure`, `ui-tabs` with `role="tablist"` and `data-ui-tabs`, `dialog.ui-dialog` with `__body` and `__actions`, `ui-toast-region` and `ui-toast` |
+| Site | `ui-skip`, `ui-sitebar` with `__inner`, `ui-brand`, `ui-sitenav`, `details.ui-menu` with `__panel`, `ui-hero` (`--stage`: the art takes the larger column and the height) with `__copy` and `__art`, `ui-quote`, `ui-plans` of `ui-plan` (`--featured`) with `__price`, `ui-cta-band`, `ui-footer`, `ui-pixel` |
+| App | `ui-app` with `__nav` and `__main`, `ui-navgroup` with `__label`, `ui-navlist` with `aria-current`, `ui-topbar`, `ui-page` with `__head` and `__title`, `ui-workgrid` with `ui-span-12/8/7/6/5/4/3`, `ui-scroll`, `ui-toolbar`, `ui-search`, `ui-empty` |
+| Settings | `ui-settings` with `__nav` and `__body`, `ui-setting-section` (`--danger`) with `__head`, `ui-savebar` |
+| Moment | `ui-setpiece` (display type at the lock's moment size), `ui-bignum` (one figure at moment size, heading font, tabular); both only inside `[data-ui-moment]` (section 6) |
+| Signature | `ui-coord` (bracketed mono coordinate or measurement label), `ui-prompt` (a `>` prefix; `--cursor` adds a static block cursor), `data-coord="…"` on a `ui-section` or `ui-hero` (a label on the section rule where the lock shows section marks), `ui-ruler` (tick bar), `ui-frame` (a ruled box with registration crosses), `ui-scan` (static scanlines), `ui-readout` (mono value well), `ui-panel--accent` and `ui-panel--support` (colour blocks), `ui-sticker` (tilted tag) |
+| Charts | `UI.bars(el, { labels, series: [{ name, values, role: "chart-1" }], marker: { index, label }, caption, indexLabel, unit, stacked })` and `UI.lines(…)`; roles are `chart-1` to `chart-5`; each chart gets a legend when it has two series and a "Show as table" fallback |
+
+## 3. What the probe checks against the lock
+
+The interface probe finds `design.lock.json` beside the page it serves (or takes `--lock <path>`)
+and runs these rules at every matrix row. Without a lock they are listed under Not verified.
+
+| Id | Rule | Severity |
+|---|---|---|
+| DS-001 | `ui/tokens.css` is not applied: `--ui-lock` on `:root` is missing or names another style | HIGH |
+| DS-002 | Visible text set in a family the lock does not name | HIGH |
+| DS-003 | Text, background, border or SVG colour more than 8 per channel from every palette role (light and dark); four or more distinct colours is HIGH, fewer is MEDIUM | HIGH / MEDIUM |
+| DS-004 | Font size neither on the scale (±0.5 px) nor inside the display range | MEDIUM |
+| DS-005 | Corner radius not in the lock and not fully round | LOW |
+| DS-006 | A `{{slot}}` from a starter left in text, a title or a labelling attribute (the static fallback reads `.html` files only, since framework templates use braces) | HIGH |
+| DS-007 | A shadow outside the lock's elevation grammar: a `flat` lock (computational-brutalism) takes only rings, no blur and no offset past a hairline; an `offset` lock (neo-brutalism) takes zero-blur offsets but no blur. Inset shadows never count; `soft` locks leave offsets to CF-403 | MEDIUM |
+| DS-008 | The signature moment: the lock declares none (a lock written before signature moments counts; add one with `design-lock.mjs moment`); no visible `[data-ui-moment]`; the marked kind differs from the lock; it is smaller than 40 000 px² (bold) or 4 800 px² (small); a read-once page's moment starts below the first screen at 1024 px and wider (more than 120 px short of the fold) or past 1.5 screens on narrower viewports; it lacks what its kind needs (section 6); or it is a generic gradient-and-centred-text hero. Two marked moments, and a work-surface moment over half the screen at 1024 px and wider, are MEDIUM. Fold and size-share checks run on the base rows | HIGH |
+
+A lock with `offset` elevation is also the recorded neo-brutalist register CF-403 asks for, so the
+probe clears CF-403 on a neo-brutalism page; on any other lock a hard offset shadow is still CF-403.
+
+Media, `img`, `video`, `canvas`, `iframe` and anything inside `[data-lock-exempt]` are skipped. Use
+the exemption only for third-party embeds and real brand marks, and say so in the reply.
+
+Thresholds live in `scripts/interface-probe-rules.mjs` like every other rule. Never widen a
+tolerance or add an exemption to make a page pass; change the page.
+
+## 4. Look, then fix
+
+After the rule table, a rendered probe run prints the paths of the 1440, 390 and 320 screenshots
+and six fixed questions (LOOK-1 to LOOK-6: one focal point, shared edges, grouping by space, kit not
+costume, composed mobile, specific content). Open the screenshots, answer each question in one line,
+fix the two worst answers, and run the probe again. Stop after two look rounds; keep the better
+version if a round made it worse. The questions are concrete on purpose: a reviewer, human or
+model, agrees with itself on "do the sections share a left edge" far more often than on "is it
+beautiful".
+
+## 5. Accent art by style
+
+The landing starter's art slot takes the locked style's art; work surfaces keep at most a small mark.
+
+| Style | Accent art |
+|---|---|
+| `field-notes` | The pixel motif below |
+| `graphite`, `meadow` | A real product view set on a `ui-wash` or between `ui-band` sections, with the second accent on the featured panel |
+| `computational-brutalism` | Instrument parts on real content: a `ui-frame` around the product view or a key figure, `ui-coord` labels that name real positions, sizes or revisions, one `ui-ruler`, `data-coord` on each section (sheet, grid reference or revision, not 01/02/03), a `ui-prompt--cursor` line, and `ui-readout ui-scan` wells on the readouts that carry real values. No made-up telemetry: every number labels something on the page |
+| `neo-brutalism` | `ui-sticker` labels with real facts (price, launch date, a count), never over body text, and colour blocks in all three fills (`ui-panel--accent`, `ui-panel--accent-2`, `ui-panel--support`) |
+
+### Pixel motif (field-notes)
+
+On read-once pages the field-notes hero carries an original pixel motif of the product's subject.
+Draw it as a character grid and convert it, rather than hand-placing rectangles:
+
+```bash
+node "$FRONTEND_UIUX_SKILL_ROOT/scripts/pixel-art.mjs" motif.txt --label "<what it shows>" --cell 12
+```
+
+Characters map to palette roles (`i` ink, `a` accent, `b` second accent, `m` support, `s` sunken, `p` surface,
+`c` canvas, `l` line-strong, `2` ink-2, `.` empty), so the motif follows dark mode and stays inside
+the lock. Keep it recognisable: a scene of the product's subject, 20 to 64 cells wide, hard edges, as
+many roles as the subject needs, the accent on the one detail that matters. Cells render at 6 px or more. On a
+work surface the motif is at most a small mark beside the product name.
+
+## 6. Signature moment
+
+The lock makes runs agree on the look. The signature moment is the one place a page is allowed to be
+bold, so a locked page still has something that makes a person stop. Choose it from the content before
+writing markup, record it in the lock, mark it in the page, and let the probe check it (DS-008).
+
+1. Record it: `init … --moment <kind> --moment-note "<what it shows>" [--moment-place "<where>"]`, or
+   later `design-lock.mjs moment --dir <project> --kind <kind> --note "<what it shows>"`. Until a kind
+   is recorded the probe fails every render.
+2. Mark the one element that carries it: `data-ui-moment="<kind>"`.
+3. Build it from this page's content, inside the lock: palette roles, the kit's type, radii and
+   elevation. The moment may use `--fs-moment` (`ui-setpiece`, `ui-bignum`) up to the lock's moment
+   ceiling; DS-004 accepts that size only inside `[data-ui-moment]`.
+
+| Family | Scale | Kinds | Where |
+|---|---|---|---|
+| `landing` (landing, product, launch, portfolio, docs home, report) | bold | `hero-composition`, `type-set-piece`, `data-moment`, `diagram`, `motion-detail`, `interactive-object` | Starts in the first screen at 1024 px and wider, within 1.5 screens on phones |
+| `workspace`, `settings` | small | `chart`, `empty-state`, `header-detail` | Anywhere; under half the screen at desktop widths. The data stays the focus |
+
+| Kind | What it is | DS-008 needs inside it |
+|---|---|---|
+| `hero-composition` | The hero arranged around the product's one concrete object: the invoice, the truck, the score, drawn or built from kit parts at a size that dominates the first screen (`ui-hero--stage`) | An image, drawing, figure, frame or product view |
+| `type-set-piece` | The pitch set as type: a short line at moment size with the accent on the one word that matters, aligned to the grid, never centred over a gradient | Text at display size or above |
+| `data-moment` | One real number or small dataset made big: a `ui-bignum` with its unit and source, a chart that answers the page's question | A chart, table, figure or readout |
+| `diagram` | The product's process or structure drawn once, clearly: inputs, the step the product does, the result | An image, drawing or figure |
+| `motion-detail` | One movement that explains something (a figure counting up to its real value, a step sequence), short, in the style's durations, stopped under reduced motion (RS-003) | An animation or transition (not checked on the reduced-motion row) |
+| `interactive-object` | Something to try on the page: a fee calculator, a toggle between before and after, a slider on a real variable | A control a reader can operate |
+| `chart` | The work surface's main chart, with one annotated marker that names the event a person acts on | A chart, table or readout |
+| `empty-state` | The empty state drawn with care: a small mark from the style, one sentence, the next action | Nothing beyond presence |
+| `header-detail` | The page header's one detail: the product mark, a live status, the plan or period, set with care | Nothing beyond presence |
+
+Choose the kind from the content in this order: the one object or number the reader cares about
+(`data-moment`, `hero-composition`); a process they must grasp (`diagram`); words that carry the
+pitch (`type-set-piece`); something worth trying (`interactive-object`); `motion-detail` only when
+movement is the point. State the choice and the note in the reply.
+
+Moments by style:
+
+| Style | A moment that belongs to it |
+|---|---|
+| `field-notes` | A pixel scene of the product's subject filling the art column (`ui-hero--stage`, cells of 10 to 16 px, the accent on the one detail that matters), or a `ui-setpiece` line in the editorial display with a small pixel mark |
+| `graphite`, `meadow` | On a landing page, the real product view at full size with one live state shown (`ui-panel` parts, `UI.bars`); on a work surface, the main chart with its annotated marker |
+| `computational-brutalism` | An instrument plate on the plot grid: a `ui-frame` holding a `ui-bignum` readout in mono at moment size, a `ui-ruler` and `ui-coord` labels that measure real values, one `ui-scan`; or a heavy uppercase `ui-setpiece` that spans the grid columns |
+| `neo-brutalism` | A stacked block composition: the product object in a `ui-panel--accent` with its offset shadow, more blocks in `ui-panel--accent-2` and `ui-panel--support`, `ui-sticker` labels with real facts, chunky `ui-setpiece` type |
+
+Never, in a moment or anywhere: a centred headline over a gradient (DS-008 reports it as a generic
+hero), scattered floating blobs, glass, a stock 3D object, a fake dashboard with invented numbers, or
+a second moment competing with the first. Everything outside the moment stays inside the kit and, in
+the default rich register, may be layered: bands, a wash, the style's texture, the second accent and
+an atmosphere glow.

package/.grok/skills/frontend-ui-ux/references/implementation-platforms.md

@@ -3,8 +3,6 @@ the repository, then apply the universal rules plus that lane's rules.
 
 ## Universal rules
 
-These hold in every lane. A stack constraint never justifies dropping one.
-
 - the platform's native control before any custom composite
 - tokens for color, space, type, and radius; no raw values inside components
 - behavior separate from decoration; state lives outside the styling layer
@@ -12,8 +10,6 @@ These hold in every lane. A stack constraint never justifies dropping one.
 
 ## Rendering lanes
 
-Name the rendering boundary first; it decides where state and escaping live.
-
 ### Server-rendered
 
 - ship a complete document; first paint must not depend on JavaScript
@@ -32,8 +28,6 @@ Name the rendering boundary first; it decides where state and escaping live.
 
 ## Styling lanes
 
-Keep one token layer whichever styling system the repository uses.
-
 ### Utility CSS
 
 - utilities resolve to tokens; no raw hex or arbitrary pixels in class strings
@@ -97,3 +91,13 @@ Verify the lane from the repository, not from the prompt and not from memory.
 4. Run the repository's build and its package-native validation checks.
 5. For a Grok skill surface, verify the `.grok/skills/` path and run the package's documented
    integrity checks; do not infer a host route from an unrelated harness.
+
+## Failure patterns
+
+Reject:
+
+- a stack claim taken from the prompt with no manifest or lockfile check
+- a client-rendered route with no pending or error branch
+- utility classes carrying raw hex or arbitrary pixel values
+- component-kit internals overridden by descendant selectors
+- one platform verified, parity asserted for the rest

package/.grok/skills/frontend-ui-ux/references/inclusive-interface.md

@@ -21,15 +21,11 @@ Measure contrast against the pixels actually painted behind the text, in every t
 
 ## Cognitive access
 
-Cut what the user must remember, infer, or type twice.
-
 - one primary action per view, everything else visibly subordinate
 - say what happened, what it means now, and what to do next, in that order
 
 ## Names, errors, and announcements
 
-Write names and messages that survive being heard alone, with no screen.
-
 - the accessible name contains the visible label; on conflict the visible label wins
 - an error names the field, the problem, and the correction
 - bind errors with `aria-describedby`; focus the first invalid control
@@ -46,7 +42,7 @@ Assume translation and mirroring from the first commit.
 
 ## CJK and IME checklist
 
-Latin-only testing hides these defects. Exercise Korean, Japanese, and Chinese copy.
+Exercise Korean, Japanese, and Chinese copy.
 
 - Korean prose: `word-break: keep-all` with `overflow-wrap: anywhere` for long tokens
 - declare a per-script font stack; check for tofu, synthetic bold, shifted baselines
@@ -80,3 +76,13 @@ Triage by what the user can no longer do, then order the queue.
 - S2: the task finishes with wrong or missing information. Fix before merge.
 - S3: finishes at unreasonable cost. Record in `accepted_exceptions` with an owner.
 - S4: cosmetic or preference-level. Record in `omissions` with a reason and owner.
+
+## Failure patterns
+
+Reject:
+
+- an overlay widget or audit score offered in place of evidence
+- `outline: none` with no replacement indicator reaching 3:1
+- `aria-hidden` on anything focusable, or a role restating the native element
+- a positive `tabindex`, or focus order diverging from reading order
+- validation fired mid-composition, or CJK copy verified only with Latin strings

package/.grok/skills/frontend-ui-ux/references/interaction-motion.md

@@ -1,91 +1,47 @@
-Every interactive surface must answer three questions: what can be done here, what is happening
-now, what just happened. Settle all three in `inventory.interactions` and `inventory.states`
-first.
+# Interaction states
 
-## State inventory
-
-List the states each element can occupy. A state nobody listed is a state nobody built.
-
-- default, hover, active, focus-visible, disabled, read-only
-- selected, expanded, current, checked, indeterminate
-- loading, optimistic, retrying, succeeded, failed
-- empty, partial, truncated, overflowing, stale
-
-Each maps to one contract state kind: `loading`, `empty`, `error`, `success`, `disabled`,
-`permission`, `offline`, `ready`.
-
-## Feedback proportional to consequence
-
-Weigh the response against what the action costs to undo. Cheap actions stay quiet.
-
-| Consequence | Required feedback |
-|---|---|
-| Reversible, local | Immediate change, no confirmation step |
-| Reversible, remote | Inline pending state plus undo for 5-10s |
-| Longer than 1s | Progress in place; skeleton only where layout is known |
-| Irreversible | Confirmation naming object and effect; typed name for bulk delete |
-| Failed | Persistent inline error, input preserved, retry within reach |
-
-## Input and validation timing
-
-Validate when the user can act on the answer, not while it is still being typed.
+Use `references/motion-guide.md` for animation choices. This guide covers what a control
+does, how it reports state, and where keyboard focus goes.
 
-- one field: validate on blur; cross-field rules: validate on submit
-- once a field has failed, revalidate on input so the error clears
-- debounce remote checks at 300-500ms and cancel superseded requests
-
-## Focus rules
-
-Focus is application state. Move it on purpose and put it back exactly.
-
-1. On open, focus the first meaningful control, not the container.
-2. Contain focus in a modal surface; `Escape` closes unless it discards data silently.
-3. On dismissal, return focus to the opener; if it is gone, focus its nearest surviving
-   ancestor, never `body`.
-4. After deleting a row, focus the next row, or the list when none remains.
-5. On route change, focus the new `h1` or the skip target.
-
-## Gestures and their keyboard equivalents
-
-Treat a gesture as an accelerator over a control that already exists. A touch-only path is a
-defect.
-
-- swipe to dismiss requires a close control
-- drag to reorder requires up and down controls or a position field
-- pull to refresh requires a refresh control
-
-## The motion test
+## State inventory
 
-Answer all three before adding motion. One "no" removes it.
+For each interactive element, name only the states it can actually reach:
 
-1. Which relationship does it explain: origin, continuity, hierarchy, or outcome?
-2. Does removing it lose information rather than polish?
-3. Does it finish within 400ms, with completion never waiting on it?
+- pointer and keyboard: default, hover, pressed, focus-visible, disabled
+- selection: selected, expanded, current, checked, indeterminate
+- async work: loading, retrying, succeeded, failed
+- content: empty, partial, truncated, stale, overflowing
 
-## Choreography and sequencing
+Map each state to its visual treatment, accessible announcement, and transition. The
+Design Contract owns the state inventory; an unlisted state is a coverage gap.
 
-Sequence movement to direct attention. Specify trigger, property, duration, easing, interruption.
+## Feedback follows consequence
 
-- 100-150ms direct feedback, 200-300ms entry and exit, 300-400ms layout change
-- stagger 20-40ms per item, capped at five; the remainder arrive together
-- animate `transform` and `opacity` only, and never queue a transition
+| Action | Feedback |
+| --- | --- |
+| Reversible local change | Apply immediately; avoid a confirmation step. |
+| Remote action | Show pending state and offer undo when the operation supports it. |
+| Work taking over a second | Keep progress in place and preserve the current layout. |
+| Irreversible action | Name the object and effect before confirmation. |
+| Failure | Keep the user's input, explain the next step, and make retry reachable. |
 
-## Reduced motion without lost meaning
+Validate a single field on blur and cross-field rules on submit. After an error, revalidate
+as the user edits. Debounce remote checks and cancel requests made stale by newer input.
 
-Under `prefers-reduced-motion: reduce`, keep the information and drop the travel.
+## Focus and keyboard paths
 
-- replace slide and scale with a 100ms opacity change or an instant swap
-- keep progress indicators; make them determinate or a static pending label
-- the reduced path still shows every confirmation and result announcement
+1. On open, focus the first meaningful control.
+2. Keep focus inside a modal; Escape closes it when that does not discard unsaved work.
+3. On dismissal, return focus to the opener or its nearest surviving control.
+4. After removing a row, move focus to the next row or the list when empty.
+5. After navigation, focus the new heading or skip target.
 
-## The record handed to review
+Treat gestures as shortcuts. Swipe-to-dismiss needs a close control; drag-to-reorder needs
+keyboard controls or a position field; pull-to-refresh needs a visible refresh action.
 
-Give the independent review pass one entry per interaction, keyed to the design contract hash.
-Anything missing counts as untested.
+## Review record
 
-- trigger and target element with its accessible name
-- every state, with its visual and its announced change
-- keyboard sequence: keys, focus after each, exit path
-- async contract: pending threshold, timeout, error text, retry
-- motion: property, duration, easing, interruption, reduced path
-- evidence: route, viewport, state, and how the state was reached
+For each interaction, retain an internal Design Contract or QA record keyed to its hash:
+the trigger, accessible name, reachable states, keyboard path, async failure and retry
+behavior, and how QA reached the state. Keep this record detailed. In the chat reply,
+mention only the limitation that changes the user's next decision.

package/.grok/skills/frontend-ui-ux/references/motion-guide.md

@@ -1,8 +1,8 @@
-# Motion guide for frontend work
+# Motion guide for LitGrok frontend work
 
-This guide turns motion into a small, testable part of the interface. Start with one sentence naming the page, target components, and out-of-scope areas; follow it with labeled sections in implementation order. Specify the stack, visual tokens, layers, timing, viewport behavior, reduced-motion behavior, assets, and performance limits before describing a page. Name exact files or components so the implementation does not invent unrelated sections. A page brief may name component families such as hero, pricing, footer, or dashboard before detailing the chosen one.
+Use this guide with the active frontend Design Contract and `references/interaction-motion.md`. Motion decisions belong to named components and states; they do not grant implementation scope. Start with the target page, components, and exclusions. Specify the stack, visual tokens, layers, timing, viewport behavior, reduced-motion path, assets, and performance limits before implementation. Name exact files or components so the work does not invent unrelated sections.
 
-All values below are starting defaults. Keep the page calm when motion does not explain hierarchy, state, or cause and effect.
+All values below are starting defaults. The default register is rich: layered motion (an atmosphere layer drifting behind the hero, the headline entering, the moment animating its own detail) is welcome when each layer has a job and a budget. A calm page is the opt-in, used when the request asks for a minimal or quiet page or the lock records `density: calm`. Either way, every layer stops under `prefers-reduced-motion: reduce`.
 
 ## 1. Stack, tokens, and composition
 
@@ -49,9 +49,9 @@ Use named curves so a later editor can change the motion family without hunting
 
 ## 3. Motion and resource budgets
 
-**Do:** Give each section one entrance sequence and no more than two simultaneously moving elements. Give the hero one principal scroll or entrance effect and one animated headline. Keep controls responsive while decorative motion runs.
+**Do:** Layer motion by depth: a slow atmosphere layer (8 s or longer, transform or opacity only), one entrance sequence per section, and the signature moment's own detail. Up to four elements may move at once when they sit on separate layers and none of them is body text. Keep controls responsive while decorative motion runs, and keep each layer inside the frame budget below.
 
-**Don't:** animate the headline, background, cards, icons, and navigation at once. Remove any motion whose absence does not change comprehension or feedback.
+**Don't:** animate every card, icon and nav item on the same beat, move body text while it is being read, or loop anything faster than three flashes a second (the flash floor stays absolute). Drop a layer that costs the frame budget before dropping the moment.
 
 **Do:** Animate `transform` and `opacity` for routine movement. Target a frame callback below 4 ms so the page has room for layout, paint, and input work within a 60 Hz frame. Check for dropped frames on a mid-range device.
 
@@ -122,6 +122,9 @@ Give cursor tracking its own interaction scope and budget. For a 3D scene or car
 - Are focus, keyboard use, contrast, and nonanimated content complete?
 - Are package versions pinned, and does the page remain readable when motion or media is unavailable?
 
-## Phase 3 README examples
+## Phase 3 README A/B example slot
 
-Record verified before/after examples at `examples/phase-3-readme-motion-ab.md`. Include the Phase 3 evidence path, the README and motion context, verbatim excerpts in Markdown fences, and the observed change. Replace the template placeholders with run material; do not invent examples.
+Keep `examples/phase-3-readme-motion-ab.md` as the verified A/B format (evidence path, README and motion context, verbatim excerpts, observed change). Add examples only after the Phase 3 README motion runs exist. Store each case at
+`.grok/skills/frontend-ui-ux/examples/phase-3-readme-ab/<case>/` with
+`before.md`, `after.md`, `before.png`, and `after.png`. The Markdown files hold the
+README excerpts; the PNGs show the matching rendered states and viewport size.

package/.grok/skills/frontend-ui-ux/references/performance-delivery.md

@@ -3,8 +3,6 @@ Performance is an inventory item with a number attached. Declare it in the Desig
 
 ## Measurement environment
 
-Fix one profile and reuse it. Numbers from two profiles cannot be compared.
-
 - CPU throttled 4x; network 1.6 Mbps down, 750 kbps up, 150 ms round trip.
 - Cold cache, cleared storage, no extensions, declared locale.
 - Median of five runs at `compact` 360x800; repeat at `expanded` 1440x900.
@@ -12,8 +10,6 @@ Fix one profile and reuse it. Numbers from two profiles cannot be compared.
 
 ## Declared budgets
 
-Write each as a number the contract can carry. Tighten per project; never loosen silently.
-
 - LCP 2.5 s, FCP 1.8 s, INP 200 ms, CLS 0.10, each at p75 on the profile above.
 - Initial route JavaScript 170 KB compressed; total critical-path transfer 500 KB.
 - Initial CSS 60 KB compressed; webfonts 100 KB across at most two files.
@@ -62,15 +58,11 @@ Virtualize only after measuring. Under ~200 rows or 5 ms per update, paginate or
 
 ## Perceived versus measured
 
-Record both. Neither substitutes for the other.
-
 - Under 200 ms show nothing; to 1 s an inline indicator; past 1 s determinate progress.
 - A skeleton must match the final box, or it trades layout shift for shimmer.
 
 ## Audit protocol
 
-Run in order and end in a verdict.
-
 1. Reproduce on the declared profile with a cold cache.
 2. Capture one load trace and one interaction trace; save both paths.
 3. Rank findings by milliseconds against the budget each breaks.
@@ -80,3 +72,14 @@ Run in order and end in a verdict.
 7. Report `PASS` when every declared budget holds, `FAIL` with the violated number and artifact
    path, or `BLOCKED` with the missing profile or capture capability. Escalate after three
    iterations that cross no budget.
+
+## Failure patterns
+
+Reject:
+
+- A budget written as "fast" or "lightweight" with no number.
+- Optimization argued from source reading with no trace attached.
+- Virtualizing a 40-row table because long lists "should" be virtualized.
+- A perceived-performance win offered as closure on a measured budget.
+- A performance claim entering the independent review pass with no trace bound to the design
+  contract hash.

package/.grok/skills/frontend-ui-ux/references/probe-loop.md

@@ -4,7 +4,7 @@ This reference is the execution contract for the four interface modes. Keep the
 
 ## Run the page
 
-Finish or build the page, then run `node "$FRONTEND_SKILL_ROOT/scripts/probe.mjs" --url <built-page-or-directory> --out <task-evidence-directory>`. The driver serves a local page on `127.0.0.1`, uses the already available `agent-browser` command, and closes its owned session and server. It never installs a browser or opens a `file://` page. Use an isolated evidence directory for each pass. The seven required views are 320, 390, 768, 1440, 390 dark, 390 reduced motion, and a 720×450 CSS viewport that approximates 1440 at 200% zoom. The last pass is a reflow emulation, not a claim that native browser zoom was changed.
+Finish or build the page, then run `node "$FRONTEND_SKILL_ROOT/scripts/interface-probe.mjs" <built-page-or-directory> --out <task-evidence-directory>`. The driver serves a local page on `127.0.0.1`, uses the already available `agent-browser` command, and closes its owned session and server. It never installs a browser or opens a `file://` page. Use an isolated evidence directory for each pass. The seven required views are 320, 390, 768, 1440, 390 dark, 390 reduced motion, and a 720×450 CSS viewport that approximates 1440 at 200% zoom. The last pass is a reflow emulation, not a claim that native browser zoom was changed.
 
 Open the 320, 390, and 1440 screenshots yourself. Look for clipping, hierarchy, focus and labels, image meaning, state handling, and any visual defect that a DOM measurement cannot decide. Inspect the dark and reduced-motion captures when those variants are relevant. The screenshots and the JSON must describe the same build.
 

package/.grok/skills/frontend-ui-ux/references/product-direction.md

@@ -19,8 +19,6 @@ One surface, one task the user must be able to finish. Everything else is subord
 
 ## Convert quality words into measured signals
 
-"Fast" and "intuitive" are not acceptance criteria. Each becomes a number you can read.
-
 - Completion time at p50 and p90, with the ceiling you will defend.
 - Error rate on the primary form, and the share of errors preserving entered input.
 - Interaction cost on the frequent path, as a keystroke or tap ceiling.
@@ -48,8 +46,6 @@ Each journey ends at the completion condition above. One that stops earlier is a
 
 ## Keep more than one answer alive
 
-Hand the next stage a bounded set. One inevitable option is a decision nobody reviewed.
-
 - Produce 2-3 directions separated by structure or density, never by accent hue.
 - Give each the task it accelerates, the task it slows, and its migration cost.
 - Mark one recommendation with a one-sentence reason; keep the rejected ones legible.
@@ -73,3 +69,12 @@ The next stage reads this package, not the transcript. What is missing does not
 - Five journeys with pass conditions; bounded directions with costs and recommendation.
 - Finite surface list: routes, states, viewport bands, auth requirements.
 - The design contract hash the independent review pass binds its receipt to.
+
+## Failure patterns
+
+Reject:
+
+- A persona described by demographics rather than by a decision.
+- "Improve the experience" accepted as an outcome with no observable task.
+- One direction presented with no alternative and no stated cost.
+- A success claim resting on a single happy-path capture.

package/.grok/skills/frontend-ui-ux/references/production-interview.md

@@ -0,0 +1,17 @@
+# From a design request to a working screen
+
+Choose the output mode from the user's actual request. A critique or plan is read-only. A build with a clear target proceeds to source changes and inspection. A bare skill name with several frontends needs a target choice; naming a skill does not settle scope. PostToolUse guidance is a reminder to inspect the changed UI, never permission to redesign unrelated screens.
+
+Before implementation, record a short direction and the finite routes, controls and states that matter. Read current components, brand tokens and dirty files. Preserve established identity in brownfield work. For new work with no visual direction in the brief, apply the authored default pixel profile without asking; absence of direction is not an unresolved choice. The profile is not a mandate to recolor an existing product.
+
+There is no mandatory interview. Ask only when two plausible answers would materially change scope, architecture, permissions, accessibility, or visual direction. Resolve a known conflict before installing tooling or producing a baseline capture; a capture is not needed to ask the question. Ask one high-impact question at a time, present concrete alternatives and their consequences, then wait for the answer before choosing the next unresolved material decision. Continue for as many rounds as materially necessary; there is no fixed question count.
+
+If the brief itself names competing directions and says both directions are acceptable, acceptance alone is not a selection or delegation: that visual axis remains unresolved. This is different from a brief that gives no visual direction at all. Ask about the competing directions as their own round after higher-impact questions have been answered. You may include a recommendation in a concrete alternatives question, but do not treat that recommendation as a selection or begin work on the unresolved direction before the user selects or delegates it. Apply the same rule to any other material axis the brief leaves undecided. Give each remaining open axis its own round after higher-impact choices have been answered. A default is valid only when the brief settles that axis, expressly delegates it to you (for example, “your call” or “pick one”), or the alternatives would not materially change the result.
+
+Retain earlier answers across rounds in the conversation and task-local direction note. On resume, reread the confirmed choices and inspect partial work before asking anything new; do not re-ask a resolved question. When all material choices have been answered or delegated, state the default and proceed only on remaining details that do not materially change the result. A skill name or keyword-only request does not authorize a build: review, plan, and keyword-only requests remain read-only. An answer resolves the stated design choice; it does not grant broader file, host, permission, credential, or publication authority.
+
+The beta2 contract records the real inventory, tokens, responsive transformations and acceptance criteria as they develop. It can evolve with the code. Validate it before acceptance using the helper rooted at the selected installed skill directory. A validator result proves schema consistency, not an attractive or working interface. Do not stop after handing over a contract when the user requested a screen.
+
+Use deliberate type hierarchy, one coherent palette and an original crisp pixel illustration tied to the product's purpose. A smooth generic icon does not satisfy the pixel direction. Compose separate mobile line breaks; use Korean display leading above Latin display leading. Keep readable body text and comfortable controls. Effects stay behind content. Prefer an asymmetric layout that still gives the primary task an obvious reading order.
+
+Exercise the actual page: initial empty state, successful primary action, validation error and recovery, keyboard focus, responsive layout and reduced motion. Check 320, 390 and 1440 CSS pixels. A class that sets display can override the hidden attribute; include a targeted `[hidden] { display: none }` rule and verify the transition in the browser. Record unavailable browser capability separately from implementation completion; never substitute source inspection for rendered evidence.