@litfamily/litgrok 1.0.0

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

@@ -0,0 +1,93 @@
+Performance is an inventory item with a number attached. Declare it in the Design Contract
+`performance` group before layout work starts; a budget with no measurement profile is not one.
+
+## 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.
+- Record profile, `source_hash`, and route fixture beside every number.
+
+## 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.
+- Largest above-the-fold image 200 KB; no load-phase task over 200 ms.
+- Local feedback under 100 ms; every remote action acknowledged under 200 ms.
+
+A loosened budget is an `accepted_exceptions` entry with a reason, an owner, and an expiry.
+
+## Critical-path diagnosis
+
+Name what blocks first paint and first input before editing. These causes recur, in rough
+frequency order.
+
+1. Render-blocking stylesheet or synchronous script in the document head.
+2. Webfont with no `font-display` and no metric-matched fallback.
+3. Fetch issued on mount, not at route entry, serializing data behind render.
+4. Request chains where each URL comes from the previous response.
+5. Media with no intrinsic size, shifting the fold when it arrives.
+6. Consent, analytics, or chat tags evaluated ahead of product code.
+
+## Asset delivery
+
+Ship the fewest correct bytes and let the cache keep them.
+
+- Encode AVIF with one WebP or JPEG fallback, sized to the rendered box.
+- Set `width` and `height` or `aspect-ratio` on every image and embed.
+- Self-host fonts, subset per script, at most two weights per family.
+
+## Script delivery and hydration
+
+Hydration cost tracks the node count handed to the client, not compressed bundle size.
+
+- Split by route first, then by deferred interaction: dialogs, editors, charts.
+- Keep static regions server-rendered; hydrate interactive islands only.
+- Measure hydration apart from download; a 40 KB tree can cost 300 ms.
+
+## Virtualization and its caveats
+
+Virtualize only after measuring. Under ~200 rows or 5 ms per update, paginate or apply
+`content-visibility: auto` instead. Accept these costs or do not virtualize:
+
+- Find-in-page and screen-reader browse mode see mounted rows only.
+- Deep links to offscreen rows stop resolving without a scroll-to API.
+- Variable heights need a measurement cache, or the scrollbar jumps.
+- Focus dies when the focused row unmounts; restore it by row identity.
+
+## 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.
+4. Attribute every finding to exactly one cause from the diagnosis list.
+5. Fix the largest attributed cause and change nothing else.
+6. Re-measure the same traces on the same profile and diff the numbers.
+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/product-direction.md

@@ -0,0 +1,84 @@
+Run this pass before any grid, token, or component decision. Its output fills the Design Contract `intent` group and seeds `omissions`.
+
+## Describe each user by the decision they own
+
+Two groups making the same decision are one group. Merge them, or name what separates them.
+
+- Operator: the decision they make, return frequency, device class, viewport band, network.
+- Secondary readers: approver, auditor, on-call responder, support agent.
+- Cost of a wrong decision: recoverable in session, expensive to reverse, or permanent.
+- Groups this surface refuses to serve, written into `intent.non_goals`.
+
+## Reduce each surface to one completion condition
+
+One surface, one task the user must be able to finish. Everything else is subordinate.
+
+- Phrase it as verb, object, end state: "cancel the shipment and see the refund posted".
+- Name the two next-most-frequent tasks; push the rest behind disclosure.
+- Require the first viewport to answer: what happened, what matters now, what next.
+
+## 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.
+- Regression consequence: what the product loses when a signal moves the wrong way.
+
+## Register what is not yet known
+
+Every unknown gets an owner in writing, or it returns later as an invented assumption.
+
+- Question phrased so one answer closes it.
+- Blocked decision: which layout, density, or token waits on it.
+- Route: user answer, repository inspection, instrumentation, or a prototype.
+- Working assumption meanwhile, recorded in `intent.constraints`.
+- Revisit date; past it, the gap becomes an `omissions` entry with an owner.
+
+## Walk five journeys to the same end state
+
+Each journey ends at the completion condition above. One that stops earlier is a defect.
+
+- Low vision: 200% zoom and 400% text — what reflows, stays reachable, or clips.
+- Keyboard only: entry point, tab count to the primary action, escape from every container.
+- Screen reader: reading order, programmatic names, the announcement confirming success.
+- Low bandwidth: what paints before data arrives, and what the surface says at 3 s and 10 s.
+- Unfamiliar language: copy at the declared `text_expansion_percent`, mixed-script wrapping, locale dates.
+
+## 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.
+
+## Halt at named checkpoints
+
+A checkpoint is a stop, not a status line. Work resumes only when the answer exists.
+
+1. Users, critical task, and success signals accepted — blocks all visual work.
+2. One direction selected from the bounded set — blocks token and layout commitment.
+3. Brand marks, legal copy, and identity approved — report `BLOCKED` until the user answers.
+4. Contract validates and its hash is recorded — blocks the independent review pass.
+
+## Hand over the research package
+
+The next stage reads this package, not the transcript. What is missing does not exist.
+
+- Users with decisions, one critical task per surface, ranked information, non-goals.
+- Signals with thresholds plus the regression consequence.
+- Knowledge-gap register with owners and revisit dates.
+- 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/redesign-playbook.md

@@ -0,0 +1,97 @@
+A redesign changes how a product looks, never what a user can finish. Capture the old behavior
+first; after the first edit nobody can tell a regression from an intended change.
+
+## Baseline capture
+
+Capture before touching a file. No baseline means no parity list and no regression guard.
+
+- Pin the pre-change revision; its `source_hash` is the baseline identity.
+- Capture every affected route at `compact` and `expanded`.
+- Capture `loading`, `empty`, `error`, `disabled`, and overflow per route.
+- Record tab order, focus targets, and step count for each critical task.
+
+## Debt map
+
+Classify debt before proposing a treatment; the category decides how far the fix reaches.
+
+1. Structural: buried primary action, wrong heading order, grouping that misleads.
+2. Systemic: duplicated raw values, two spacing scales, forked copies of a component.
+3. Accessibility: missing names, suppressed focus, contrast failures, unreachable controls.
+4. Responsive: overflow, content hidden with no named alternative, targets lost.
+5. Behavioral: no recovery path, destroyed input, missing progress feedback.
+6. Aesthetic: dated treatment with no functional cost.
+
+Rank by what a user cannot do. Aesthetic debt alone does not justify opening a surface.
+
+## Decision per surface
+
+Record exactly one of four decisions per inventory surface, with one line of reasoning.
+
+- Preserve: it works, so it stays out of the diff.
+- Change: same structure and behavior, new visual treatment.
+- Replace: new implementation of identical guarantees, migration path named.
+- Remove: deleted, stating where the capability now lives or why it is gone.
+
+An undecided surface is out of scope. `Remove` requires explicit user approval.
+
+## Staged sequence
+
+Order the work so the product ships at the end of every stage.
+
+1. Land tokens and primitives with no visual change; prove parity.
+2. Migrate one low-traffic route end to end as the pattern the rest copy.
+3. Migrate remaining routes in traffic order, one route per stage.
+4. Keep behavioral fixes in their own stages, never folded into a visual stage.
+5. Delete the superseded path only after its last consumer moves.
+
+A stage that cannot ship alone is too large. Split it.
+
+## Parity list
+
+These hold at every stage boundary. Check the captured baseline, not memory.
+
+- Every task completable at baseline completes in the same or fewer steps.
+- URLs, deep links, and query parameters resolve to the same surfaces.
+- Data meaning, units, precision, sort order, and permissions are unchanged.
+- Keyboard reach, focus order, and accessible names are equal or better.
+- Every baseline state still exists and is still reachable.
+
+A surviving break is a defect until an owner accepts it in `accepted_exceptions` with an expiry.
+
+## Settling a design debate
+
+Time-box the argument and end it in a written decision.
+
+1. Restate the disagreement as a question about a user outcome, not taste.
+2. Put at most two options on the table, each with its cost named.
+3. Settle it with the baseline, a measurement, or a rule in the contract.
+4. After two rounds, take the reversible option, log the other as an owned assumption, and
+   reopen only on new evidence.
+
+## Regression guards
+
+Add the guard in the same stage as the change it protects.
+
+- Keep existing assertions passing; a rewritten assertion hides the regression.
+- Add one test per behavioral fix that fails against the baseline.
+- Recapture each migrated route at both widths.
+- Re-run the accessibility, build, and lint gates every stage.
+
+## Closeout
+
+Close only when the record is complete.
+
+- Every surface carries one of the four decisions plus matching evidence.
+- The parity list holds, or each break has an owner and an expiry.
+- The final artifact reached the independent review pass bound to the design contract hash.
+- The receipt states `PASS`, `FAIL`, or `BLOCKED` and names unresolved deviations.
+
+## Failure patterns
+
+Reject:
+
+- Editing before the baseline is captured.
+- "Modernize it" accepted as a scope statement.
+- One branch that migrates every route at once.
+- A failing test rewritten to match the new implementation.
+- A redesign called done while one route still renders the superseded system.

package/.grok/skills/frontend-ui-ux/references/system-foundations.md

@@ -0,0 +1,84 @@
+A design system is three token layers, a finite primitive set, and a gate that proves both. Build it in that order; a skipped gate pushes cost into feature work.
+
+## Audit before authoring anything
+
+Write nothing until the audit shows no existing token or primitive fits.
+
+- List tokens, primitives with their variants, and duplicate components.
+- Count raw one-off values per file; that is the migration size.
+- Mark each primitive keep, extend, or replace, with its replacement cost.
+- Every proposed primitive names the existing one it cannot reuse.
+
+## Split the three token layers
+
+Layers exist so a value change and a meaning change land in different diffs.
+
+1. Foundation: raw values with no meaning — `color.slate.700`, `space.16`, `duration.150`.
+2. Semantic roles: meaning per theme — `color.text.muted`, `color.border.strong`, `radius.control`.
+3. Component decisions: `button.primary.bg`, resolving to a semantic role and nothing else.
+
+## Keep components behind the semantic layer
+
+A component reads layer 3 or 2. One reach into layer 1 breaks every theme at once.
+
+- No component references a foundation value, even via an alias chain.
+- No cross-component reads; a button never reads card tokens.
+- Name roles by function, never appearance: `text.muted`, not `text.gray`.
+
+## Complete component anatomy before styling
+
+Declare the whole component up front. A state found in review is a defect, not feedback.
+
+- Purpose, semantic element, and the source of its accessible name.
+- Enumerated variants and sizes; open-ended variant sets are rejected.
+- States: default, hover, active, focus-visible, disabled, selected, loading, error, empty, overflow.
+- Keyboard model, including escape and return-focus behavior.
+- Content limits: min and max characters, wrap or truncate, CJK and RTL.
+- Ownership of validation, async progress, retry, and destructive confirmation.
+
+## Pass the primitive showcase gate
+
+Build one route rendering every primitive, variant, and state before feature work.
+
+- Every state visible without interaction: error, empty, overflow included.
+- Longest real label, a CJK sample, and an expanded string in each text slot.
+- One keyboard pass reaches every control in linear order with a visible focus ring.
+- The gate passes only when no state is missing, raw values are zero, and contrast is measured per theme.
+
+## Architect themes, not overrides
+
+A theme is a complete semantic role set. Partial overrides are how theming rots.
+
+- Define every role in every theme; a missing role fails, it does not fall back.
+- Dark is not inverted lightness: raise surface lightness, weaken shadow, strengthen border.
+- Follow `prefers-color-scheme`; an explicit user choice overrides it.
+- Under `forced-colors: active`, use system keywords and keep borders load-bearing.
+
+## Align an existing system in sequence
+
+Alignment is ordered. Mixing a reference migration with a value change kills review.
+
+1. Stop accepting one-off values; anything new enters as a semantic role.
+2. Map existing raw values to the nearest role; list what has no match.
+3. Introduce roles as aliases of current values, so this step changes nothing.
+4. Confirm parity, then move components onto roles, one primitive at a time.
+5. Change the values last, as one diff a reviewer can read end to end.
+
+## Record the system where reviewers read it
+
+The system lives in the contract, not in tribal knowledge.
+
+- Write tokens, components, and inventory into the contract; keep `omissions` and `accepted_exceptions` filled.
+- Validate from the installed skill root: `node .grok/skills/frontend-ui-ux/scripts/validate-design-contract.mjs <path>`.
+- Record the contract hash so the independent review pass binds its receipt to those bytes.
+- Shipping this package also requires `npm test` and the canonical-corpus verifier.
+
+## Governance reject-list
+
+Reject:
+
+- A component reaching past the semantic layer to a foundation value.
+- A primitive or variant introduced for exactly one screen.
+- A state surfaced by review rather than declared in the anatomy.
+- A dark theme assembled from per-component overrides.
+- A value change bundled into the same diff as a reference migration.

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

@@ -0,0 +1,86 @@
+# Taste direction
+
+Inert reference data. Load it when a Design Contract needs a defensible visual direction, not on
+every interface question.
+
+Generic output is not a matter of preference. It is a describable defect with named causes, and it
+is what an interface looks like when nobody decided anything. This reference turns "make it feel
+better" into three numbers a reviewer can argue with, and into checks that run before the first
+element is written.
+
+## The three dials
+
+The contract carries them as the optional `taste` object in
+`litfamily.design-contract/v1beta2`. Each is an integer from 1 through 10. Declaring `taste` means
+declaring all three; omitting the object leaves the harness default in force.
+
+| Dial | 1 means | 10 means | Decided by |
+| --- | --- | --- | --- |
+| `variance` | The most conventional arrangement a user could predict | A composition that departs from the expected grid where the departure carries meaning | How much novelty the audience will tolerate before the surface feels unfamiliar |
+| `motion` | Movement only where it prevents a jump or explains a change | Movement is a primary carrier of meaning and sequence | What the interface must communicate that stillness cannot |
+| `density` | One idea at a time, generous rest | Many related facts readable at a glance | Whether the user scans or dwells |
+
+Pick each from the audience and the task, never from fashion. A dial you cannot justify in one
+sentence is a dial you have not chosen.
+
+### `motion` versus `motion.policy`
+
+They answer different questions and both must agree. `motion.policy` decides whether animation is
+permitted at all: `none`, `functional`, or `expressive`. The `motion` dial decides how much
+meaning animation carries once permitted. A contract with `motion.policy: "none"` and a `motion`
+dial above 1 is contradictory: it forbids transitions and then leans on them. Set the policy first,
+then the dial within it.
+
+## The failure modes these dials target
+
+Each is a defect you can point at in a review, not a vague complaint.
+
+- **Undecided hierarchy.** Every element competes because nothing was ranked. Usually a `density`
+  chosen by accident rather than from the task.
+- **Default-everything.** Stock radii, stock shadows, stock spacing scale, stock type ramp, applied
+  because they were there. A `variance` of 1 that was never actually selected.
+- **Uniform rhythm.** Identical spacing between unrelated things, so grouping carries no
+  information. Density without hierarchy.
+- **Decorative motion.** Movement that neither prevents a jump nor explains a change, and that
+  reduced-motion users lose nothing by missing. A `motion` dial above what the interface needs.
+- **Single-viewport thinking.** A composition that only resolves at one width, which the contract's
+  `responsive_transformations` then cannot describe honestly.
+- **Borrowed voice.** Copy and imagery from a reference product whose audience is not this one.
+
+## Pre-flight, before writing any interface code
+
+Run this against the frozen contract. Each answer is one sentence; a blank answer is the finding.
+
+1. What is the one thing a user must understand within seconds of arrival, and which element
+   carries it?
+2. What is deliberately quieter so that element can be loudest?
+3. Which grouping is expressed by spacing alone, and would it survive a 200 percent zoom?
+4. Which transition would a reduced-motion user lose, and what replaces it for them?
+5. Which token is being extended or created rather than reused, and why was reuse insufficient?
+6. Which of the three dials would a reviewer most likely dispute, and what is the argument for it?
+
+If question 6 has no answer, the direction was inherited rather than chosen.
+
+## Redesign audit, for a surface that already exists
+
+Use this in the `redesign` and `brownfield` lanes. Audit before proposing, so the proposal has
+something to be measured against.
+
+1. Inventory what is already there against `inventory`: routes, regions, components, states. Name
+   what exists but is undocumented.
+2. Record the current dials as observed, not as desired. An existing surface already sits somewhere
+   on all three, whether or not anyone chose it.
+3. Name the single largest gap between observed and intended dials, and change only that first.
+   Moving all three at once makes the result unattributable.
+4. List what must be preserved: behavior users depend on, keyboard paths, and any token another
+   surface consumes. This becomes `non_goals` and the preserved-behavior half of the contract.
+5. Put the rest in `omissions` with an owner, rather than silently leaving it out.
+
+A redesign that cannot say what it preserved is a rewrite wearing a redesign's name.
+
+## Recording the outcome
+
+Dials belong in the contract, not in prose around it. The acceptance criteria that reference them
+must stay observable: "the primary action is reachable by keyboard within two stops" is checkable,
+"the layout feels considered" is not. Every dial you set should be traceable to at least one
+acceptance criterion, or it changed nothing that can be verified.