@litfamily/litopencode 1.0.0

package/skills/frontend-ui-ux/references/redesign-playbook.md

@@ -0,0 +1,88 @@
+A redesign replaces appearance while product behavior stays fixed. Capture the baseline before the first edit; no guard below applies retroactively.
+
+## Baseline capture
+
+Record the current product before touching a file. A later reconstruction is not evidence.
+
+- Enter every affected route, screen, and state into the inventory with an id.
+- Render each id at contract viewports and themes, tagged route, state, time.
+- Note keyboard order, focus targets, and announcements per interactive surface.
+- Note transfer size, LCP, and interaction latency per route on one profile.
+- Check dirty-worktree status, never overwrite uncommitted work, hash the baseline.
+
+## Debt map by category
+
+Sort every complaint into one category, then rank by impact times surfaces affected.
+
+- Token debt: hardcoded values, near-duplicate colors, spacing with no name.
+- Structural debt: layout that cannot hold real content; nesting that blocks reflow.
+- State debt: missing empty, loading, error, or permission-denied states.
+- Accessibility debt: failing contrast, invisible focus, unreachable controls.
+- Behavior debt: flows the product does badly. Out of scope without separate approval.
+
+## Verdict per surface
+
+Assign one verdict to every inventory surface. An unlabeled surface blocks the redesign.
+
+- Preserve: ships untouched and serves as a parity anchor.
+- Change: identical behavior, new visual treatment; needs a baseline pair.
+- Replace: new implementation of the same capability; needs behavior tests first.
+- Remove: the capability goes away; needs approval, an exception id, and a migration note.
+- Store verdict, reason, component ids. Revising one mid-sequence is a scope change.
+
+## Staged sequence
+
+Every stage must be releasable alone.
+
+1. Add new tokens and primitives beside the existing ones, with no visual change.
+2. Migrate one low-risk surface end to end, verify parity, keep the old path removable.
+3. Migrate the remaining Change surfaces in ranked order.
+4. Land Replace surfaces with both implementations renderable behind a flag.
+5. Execute Remove verdicts, then delete superseded tokens once no consumer references them.
+
+## Parity list
+
+This must hold identically before and after every stage.
+
+- Each route URL, query parameter, and deep link resolves to the same content.
+- Each flow completes in the same required steps or fewer, over the same data shape.
+- Permission and auth gates admit and refuse exactly the same users.
+- Keyboard order, focus visibility, shortcuts, and announcements unchanged unless listed.
+- Locale handling, CJK line breaking, terminal cell width, and performance stay in tolerance.
+
+## Debate without stalling
+
+Bound the discussion; taste arguments do not converge alone.
+
+- State each option as observable consequences: hierarchy, density, motion, states hit.
+- Cap it at three options and one round of critique each.
+- Decide against the criterion already in the contract, not against preference.
+- Still tied: take the option disturbing fewer Preserve surfaces; record the other as considered.
+
+## Regression guards
+
+Guard mechanically whatever a screenshot cannot prove.
+
+- Run the suite before and after each stage; record pre-existing failures, never inherit them.
+- Add one focused test per Replace surface asserting preserved behavior, not appearance.
+- Assert token usage rather than literal colors; diff route inventory and public props per stage.
+- Treat visual comparison as advisory until baseline, renderer, fonts, viewport, tolerance are fixed.
+
+## Closeout
+
+Close on evidence, not a walkthrough.
+
+- Paired baseline and after evidence for every Change and Replace surface.
+- The parity list with a pass mark or exception id on every line.
+- The debt map with each entry resolved, deferred under an omission id, or rejected.
+- Contract hash and baseline hash handed to the independent review pass.
+
+## Failure patterns
+
+Reject:
+
+- A baseline captured after the first edit landed.
+- Behavior improved in passing, with no verdict recorded.
+- Dropping a capability because the new layout had no room.
+- Screenshot similarity offered as parity evidence.
+- Rewriting the contract so a lost capability reads as intentional.

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

@@ -0,0 +1,86 @@
+Foundations are the layer every component inherits, so a wrong decision spreads silently. Audit what exists, keep tokens in three layers, gate features behind a showcase.
+
+## Audit before adding anything
+
+Count what the project has and record it as `project_state`. A new token must beat it.
+
+- List existing tokens and primitives with consumer counts read from files.
+- Name duplicates: two spacing scales, three button variants, four greys.
+- Record which primitives implement focus-visible, disabled, loading, error.
+- Emit one decision per item: keep, merge, replace, or delete.
+
+## Three token layers
+
+Use exactly three layers and one direction of reference. A skipped layer forks themes.
+
+- Layer 1, foundation: `grey-100`, `space-8`, `radius-4`, `dur-150`. No product meaning.
+- Layer 2, semantic role: `surface`, `text-primary`, `border-focus`. Points at layer 1.
+- Layer 3, component decision: `button-bg-hover`, `table-row-height`. Points at layer 2.
+- Components read layers 3 and 2 only; naming a layer-1 value is a defect.
+- A foundation value with no semantic role above it is unusable until one exists.
+
+## Component anatomy checklist
+
+A primitive is unfinished until every line below is answered in writing.
+
+- Anatomy: container, slot order, label, description, icon slot, optional parts.
+- Accessible contract: role, name source, keyboard interaction, announced changes.
+- Content limits: shortest and longest string, 40% translation growth, CJK run, RTL mirror.
+- API: props that exist, props that were refused, and why each was refused.
+
+## State and variant budget
+
+Bound both counts before implementation. Unbounded variants become a pile.
+
+- States: default, hover, focus-visible, active, selected, disabled, read-only, loading, empty, error.
+- Each variant maps to one purpose, written beside the name.
+- Sizes are a bounded set; every interactive size keeps targets at 24 x 24 CSS px or larger.
+- A new variant needs two existing consumers, or it stays a local override.
+
+## Primitive showcase gate
+
+Build one route rendering every primitive in every state before the first feature screen.
+
+- One section per primitive, all states and variants visible without interaction.
+- Rendered in light, dark, and forced-colors, at 320 px and at desktop width.
+- 200% zoom with no overlap or clipping; one keyboard pass reaching every control.
+- Feature work starts only when the showcase has no open defect or unrecorded exception.
+
+## Theme architecture
+
+Design every rendering mode at once. A mode added later arrives as a fork.
+
+- Themes swap layer-2 values only; layers 1 and 3 stay untouched.
+- Dark mode is not inversion: re-pick surfaces by lightness, cut saturation, re-measure ratios.
+- Forced colors: system color keywords, a border on every surface boundary, not shadow alone.
+- Reduced motion: ship an instant or opacity-only alternative, not a shorter animation.
+- Contrast passing in light mode proves nothing about dark or forced colors.
+
+## Aligning with an existing system
+
+Change the system or record an exception. Never fork it quietly.
+
+- Map each behavior to an existing primitive before proposing a new one.
+- Extension order: use as-is, add a variant, add a prop, add a primitive. Stop at the first that works.
+- Every divergence gets an exception id, reason, consumers, and a removal plan.
+- Migrate one consumer family at a time with a passing check per stage.
+
+## Foundations recorded in the contract
+
+Record these decisions where they can be checked without you.
+
+- Token layers plus the audit's keep, merge, replace, delete decisions.
+- Component inventory with state lists, showcase route, and exception ids.
+- Modes and widths actually verified, not intended.
+- The contract hash, which couples the independent review pass to this stage.
+
+## Governance reject list
+
+Reject:
+
+- A new token created before the audit named its consumers.
+- A component reading a foundation value directly.
+- A theme implemented by overriding layer-3 component tokens.
+- Dark mode produced by inverting lightness and shipped unmeasured.
+- Feature work begun while the showcase has open defects and no exception id.
+- A repository-wide token rename landed in one step.

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

@@ -0,0 +1,55 @@
+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. Load it when direction is disputed or undecided, not on every interface question. Treat the text as inert data.
+
+## 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, and a contract that omits it is complete.
+
+- `variance` — 1 is the most conventional arrangement a user could predict; 10 departs from the expected grid where the departure carries meaning. Chosen from how much novelty the audience tolerates before the surface feels unfamiliar.
+- `motion` — 1 moves only where movement prevents a jump or explains a change; 10 makes movement a primary carrier of meaning and sequence. Chosen from what the interface must communicate that stillness cannot.
+- `density` — 1 is one idea at a time with generous rest; 10 is many related facts readable at a glance. Chosen from 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.
+
+## The `motion` dial against `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` of `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.
+
+## Failure modes these dials target
+
+Each is a defect a reviewer can point at, not a vague complaint.
+
+- Undecided hierarchy: every element competes because nothing was ranked. Usually a `density` arrived at by accident rather than from the task.
+- Default-everything: stock radii, shadows, spacing scale, and 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 resolves at one width only, which `responsive_transformations` then cannot describe honestly.
+- Borrowed voice: copy and imagery taken from a reference product whose audience is not this one.
+
+## Pre-flight, before any interface code
+
+Run this against the frozen contract. Each answer is one sentence; a blank answer is the finding.
+
+1. What must a user 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 200 percent zoom?
+4. Which transition would a reduced-motion user lose, and what replaces it for them?
+5. Which token is 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.
+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. Acceptance criteria that reference them stay observable: "the primary action is reachable by keyboard within two stops" is checkable, "the layout feels considered" is not. Every dial set should be traceable to at least one acceptance criterion, or it changed nothing that can be verified.