@litfamily/litopencode 1.0.0

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

@@ -0,0 +1,93 @@
+An interaction is specified when its states, latency band, and focus moves are written under an id. Hand those ids to the independent review pass through the design contract hash.
+
+## State inventory
+
+Enumerate the applicable states for each surface before styling any of them.
+
+- `default`, `hover`, `focus-visible`, `active`, `selected`, `disabled`, `read-only`.
+- `loading`, `empty`, `partial`, `error`, `success`, `offline`, `permission-denied`.
+- `destructive-confirm` wherever the action cannot be undone.
+- Every state needs a visual and programmatic expression; `disabled` needs a stated reason.
+
+## Feedback matched to consequence
+
+Size feedback to the cost of the action, not to implementation convenience.
+
+- Under 100 ms: change in place. No spinner, no toast.
+- 100 ms to 1 s: inline skeleton or progress in the affected region only.
+- Over 1 s: determinate progress plus a cancel control.
+- Irreversible: a confirmation naming the object and effect; typed confirmation for bulk deletion.
+- Failure: a persistent inline message with retry; a vanishing toast is not a report.
+
+## Input and validation timing
+
+Validate when the user finishes a thought, never mid-thought.
+
+- Format checks on blur, cross-field checks on submit, nothing on every keystroke.
+- Live feedback only to confirm a constraint being met, announced politely.
+- Never clear entered values on error; keep them and mark the field.
+- Debounce search 200-300 ms, cancel superseded requests, keep the last valid result.
+
+## Focus management
+
+Focus is state. Decide origin, destination, and return for every transition.
+
+- On open, move focus into the new region: the dialog or its first control, never `body`.
+- Trap focus in modal dialogs only; non-modal panels stay escapable by Tab.
+- On dismissal, return focus to the exact trigger; if it is gone, focus its surviving container and announce it.
+- After deleting a row, focus the next sibling, not the top of the list.
+- On route change, focus the new heading and announce the title.
+
+## Gestures and keyboard equivalents
+
+Treat every gesture as an accelerator for something reachable another way.
+
+- Swipe-to-delete needs a visible delete control; drag reorder needs modifier-plus-arrow.
+- Pinch needs zoom controls; long-press needs a context-menu key path.
+- Any multipoint or path-dependent gesture needs a single-pointer alternative.
+- Announce the result ("moved to row 3 of 12"); offer undo for 5 s after a deletion.
+
+## Motion justification test
+
+Keep motion only when it answers yes to one of these; otherwise delete it.
+
+- Does it show where an element came from or went?
+- Does it hold continuity across a layout or route change?
+- Does it expose a state change that would otherwise be invisible?
+
+## Choreography
+
+Give every animated property an explicit duration and curve.
+
+- 100-150 ms micro-feedback, 200-300 ms enter and exit, up to 400 ms for a full-screen change.
+- Decelerate on enter, accelerate on exit; no bounce or overshoot on data.
+- Stagger 30-50 ms per item, capped at 5; the rest arrive together.
+- One moving focal region per view. Two competing animations read as a defect.
+
+## Reduced motion
+
+Remove the travel, keep the message.
+
+- Substitute an instant change or a cross-fade of 100 ms or less.
+- Keep progress, direction cues, and status changes in static form.
+- Stop autoplay, loops, and parallax; expose a play control.
+
+## Per-interaction record
+
+Hand review one record per interaction, keyed by id, coupled through the contract hash.
+
+- Trigger, target, precondition, and permitted inputs.
+- Applicable states with visual and programmatic expression for each.
+- Latency band with its feedback; focus origin, destination, and return target.
+- Animated property, duration, easing, and the reduced-motion substitute.
+- Failure path, undo window, and announcement text.
+
+## Failure patterns
+
+Reject:
+
+- A hover style presented as the interaction specification.
+- Focus landing on `body` after dismissal, or scrolling out of view on open.
+- Spinners for sub-100 ms work, or skeletons sized unlike the arriving content.
+- Gesture-only affordances with no button or keyboard path.
+- Reduced motion implemented as slower motion.

package/skills/frontend-ui-ux/references/operating-lanes.md

@@ -0,0 +1,80 @@
+Every request sits in exactly one build situation, and the lane fixes which evidence is mandatory before anything is touched. Record the lane id in the contract; the independent review pass enforces that lane's exit condition.
+
+## Choosing the lane
+
+Select from observed repository facts, not request wording. Record the lane id with the two facts that chose it.
+
+- No app, tokens, or routes exist yet: new-build.
+- Working product, request adds or repairs a bounded surface: brownfield.
+- Working product, request restyles the system across existing surfaces: redesign.
+- A supplied image, page, or prose is declared a fidelity target: reference-fidelity.
+- The deliverable is tokens or primitives other surfaces consume: design-system.
+
+## New-build lane
+
+Choose the smallest system that expresses the whole inventory.
+
+- Gather: platform, stack, locales, minimum viewport, auth model, complete route list.
+- May change: anything inside the new application boundary.
+- Preserve: host repository conventions, lint rules, build configuration.
+- Failure mode: inventing a component library and forty tokens to serve three screens.
+- Exit: a hashed valid contract whose inventory the chosen primitives fully express.
+
+## Brownfield lane
+
+Make the new surface indistinguishable in system terms from what already shipped.
+
+- Gather: current tokens and primitives, states of components you touch, dirty-worktree status, consumers of what you would modify.
+- May change: the requested surface, plus additive tokens following existing naming.
+- Preserve: token semantics, public props, keyboard order, route URLs, untouched copy.
+- Failure mode: a second parallel design system diverging one commit at a time.
+- Exit: nothing outside the requested scope renders differently.
+
+## Redesign lane
+
+Change how the product looks without changing what it does.
+
+- Gather: baseline capture per affected route and state, a debt map by category, the owner of each behavior.
+- May change: visual system, layout, hierarchy, density, spacing, motion.
+- Preserve: every flow, permission, data contract, URL, and shortcut not listed for removal.
+- Failure mode: reworking behavior under a visual change so regressions read as intent.
+- Exit: the parity list holds and each intentional difference carries an exception id.
+
+## Reference-fidelity lane
+
+Rebuild the system the reference implies, not its pixels.
+
+- Gather: reference hash, classification, per-trait comparison scope, traits it cannot show.
+- May change: implementation matching observed structure, type scale, spacing, color roles.
+- Preserve: real text as text, semantics, accessibility, your content, undepicted states.
+- Failure mode: matching the image while shipping raster text and a short state inventory.
+- Exit: paired comparison per declared trait, plus a fidelity report of inferred and unknown calls.
+
+## Design-system lane
+
+Treat the token and primitive surface as a published API.
+
+- Gather: every consumer, the publication path, the states each primitive must express.
+- May change: token values and primitive internals behind a stable name; new tokens.
+- Preserve: token names and public props; deprecate with a migration note, never rename in place.
+- Failure mode: shipping a breaking rename inside a release labeled polish.
+- Exit: consumers render unchanged, or every intended break carries its migration step.
+
+## When a request spans two lanes
+
+Split it. A blended lane forfeits both sets of guarantees.
+
+- Sequence design-system work first, then the lane that consumes it.
+- Give each lane its own contract hash, inventory, and exit check.
+- If only one can ship now, record the other as an omission id with its deferred scope.
+- If the split is impossible, return blocked and name the decision the user owes you.
+
+## Failure patterns
+
+Reject:
+
+- A contract carrying no lane id, or a lane id with no selecting facts.
+- A greenfield rebuild inside a working product with no redesign evidence.
+- Reference fidelity claimed while the state inventory stays open-ended.
+- Additive tokens duplicating an existing semantic under a new name.
+- A lane switched after implementation started, to excuse a deviation.

package/skills/frontend-ui-ux/references/perfection/README.md

@@ -0,0 +1,160 @@
+
+# Frontend Perfectionist
+
+You are a senior frontend engineer with one binding standard: **every page hits 100 in EVERY Lighthouse category, measured on a REAL browser, without sacrificing a single drop of UX quality.**
+
+## TENETS. NON-NEGOTIABLE.
+
+### 1. AUDIT THROUGH A REAL BROWSER. NEVER THROUGH THE CLI.
+
+The `lighthouse` CLI runs `chrome-headless-shell` with default settings. That is **NOT** what your users see, and the number it produces will lie to you. **REJECT** any report based on the CLI, even if the CI shows green.
+
+The correct path:
+
+1. Build the app in production mode (`next build && next start`, `vite build && vite preview`, `astro build && astro preview`, `bun run build && bun run start`). **NEVER** measure a dev server.
+2. Launch Playwright with `channel: "chrome"` (real Chrome stable, not the headless-shell binary).
+3. Run Lighthouse against the Playwright-controlled page via `playwright-lighthouse` OR via `chrome-launcher` + the `lighthouse` Node API, attaching to the Playwright CDP endpoint so cookies, auth state, and warmed caches mirror what a real returning user sees.
+4. Use the **mobile** preset (4x CPU throttle, Fast 3G) for the primary number, AND the **desktop** preset for the secondary number. Report both.
+
+If the `playwright` skill is not loaded in this session, load it now via the `skill` tool.
+
+### 2. 100 IN EVERY CATEGORY IS THE FLOOR.
+
+A 99 is a regression. A 95 is a fire. You do NOT report "performance 93, accessibility 100, SEO 100, best-practices 100" as a pass. You diagnose what cost the 7 points, fix the root cause, re-run, and only report when all four panels show 100. On mobile AND desktop.
+
+### 3. WIN THE SCORE IN THE ARCHITECTURE.
+
+Performance is decided at architecture and code-quality level. Bundle size, render path, hydration strategy, asset pipeline, image format and dimensions, font loading, third-party scripts, critical CSS, deferred JS, route-level code splitting. These are the LEVERS that move the score. Slapping `loading="lazy"` on a hero image is not optimization. It is panic.
+
+For EVERY failing audit, trace it back to a SPECIFIC line of code or a SPECIFIC build-config choice. Fix it at the source. No band-aids.
+
+### 4. NEVER WEAKEN UX TO BUY POINTS.
+
+If your fix removes a hover state, drops a CSS transition, replaces an animated mount with an abrupt one, swaps a smooth scroll-into-view for an instant jump, degrades a 60fps interaction to 30fps, or hides content you would normally render, **REJECT THE FIX**. The animation language, motion design, and tactile feel of the product are load-bearing.
+
+Find another way:
+
+- Split the bundle further (route-level, then component-level, then feature-flag-level).
+- Defer non-critical paint work to `requestIdleCallback`.
+- Move expensive work off the main thread via Web Workers (use Comlink for ergonomics).
+- Use the `View Transitions API` for cross-route transitions.
+- Use `content-visibility: auto` plus `contain-intrinsic-size` for offscreen sections.
+- Use `will-change` precisely, ONLY on the property actually animating, ONLY for the duration of the animation.
+- Preload the LCP image: `<link rel="preload" as="image" fetchpriority="high" imagesrcset="...">`.
+- HTTP/2 server-push or `<link rel="modulepreload">` for the critical chunk.
+- GPU-composited animations only (`transform`, `opacity`, `filter`). NEVER animate `width`, `height`, `top`, `left`, `margin`, `padding`.
+
+### 5. LOAD THE DESIGN RULESET IN LOCKSTEP.
+
+You **MUST** read the design ruleset (`../design/README.md`) alongside this one for any visual or layout work. That skill carries the brand-grade taste references (Apple, Stripe, Linear, Vercel, Claude, Notion, Airbnb, Figma, etc.) and the anti-AI-SaaS-slop posture.
+
+A page that scores 100 but looks like AI SaaS slop has failed. Speed serves design; design rides on speed. **Both win or neither does.**
+
+Use the design ruleset:
+
+- BEFORE writing JSX/CSS: pull a relevant brand reference to ground the visual direction.
+- DURING implementation: cross-check against the anti-slop guardrails.
+- BEFORE declaring done: verify the page passes the design taste bar, not just the Lighthouse bar.
+
+### 6. DESIGN SYSTEM COMPLIANCE IS NOT OPTIONAL.
+
+The design ruleset (`../design/README.md`) enforces a **Phase 0 Design System Gate** — every project must have a `DESIGN.md` before any UI work begins. This skill enforces the other side: **every audit must verify compliance.**
+
+During the audit loop, after Lighthouse scores pass, run a Design System Compliance check:
+
+- **Colors**: grep the codebase for raw hex/rgb values not declared in `DESIGN.md`. Each is a violation.
+- **Typography**: every font-size in CSS/Tailwind must map to the type scale in `DESIGN.md`. No arbitrary sizes.
+- **Spacing**: every margin/padding/gap value must be a multiple of the base unit (4px) and ideally use a declared token.
+- **Components**: any component used 2+ times must be documented in `DESIGN.md` Section 5. If it isn't, add it.
+- **Depth**: if `DESIGN.md` says "borders-only", there must be zero `box-shadow` declarations. If "tonal-shift", zero borders for surface separation.
+
+A page that scores Lighthouse 100 but uses 14 undeclared hex codes and 8 magic spacing values is **NOT DONE**. The design system is the architecture — Lighthouse measures the performance of that architecture.
+
+### 7. REACT-SPECIFIC PERF TOOLING IS PART OF THE AUDIT.
+
+If the project ships React, Lighthouse alone does NOT see render-layer issues by component. You MUST also run:
+
+- **`react-doctor`** (static): cheapest. `npx react-doctor@latest --json` before any browser audit. Treat perf-category findings as audit failures.
+- **`react-scan/lite`** (runtime, headless): injected via `page.addInitScript` in the Playwright run. Drain its `onEvent` stream and fail the audit if any commit is classified `unnecessary`.
+
+The full recipe — including the Playwright + `playwright-lighthouse` + `react-scan/lite` integration, the per-route render budget assertion, and the React-specific root-cause checklist that EXTENDS the one below — lives in **[react-perf-tooling.md](react-perf-tooling.md)**. Read it before any React audit.
+
+Lighthouse 100 with `react-scan` reporting 30+ unnecessary renders per route is **NOT DONE**. Both gates must clear: synthetic score AND render quality. The synthetic score lies under real load if the React layer is thrashing.
+
+For initial install of react-scan + react-doctor (and react-grab) in a fresh React project, the canonical install snippets live in `../design/react-dev-tooling-skill.md`. Use them if the project doesn't yet have the tools wired.
+
+## AUDIT WORKFLOW
+
+Quick audit via the cross-platform Python CLI (macOS, Linux, Windows):
+
+```bash
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000 --threshold 95
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000 --desktop-only
+```
+
+Or use the TypeScript approach directly in your test suite:
+
+```ts
+// scripts/audit.ts
+import { chromium } from "playwright";
+import { playAudit } from "playwright-lighthouse";
+
+const browser = await chromium.launch({ channel: "chrome" });
+const context = await browser.newContext();
+const page = await context.newPage();
+await page.goto("http://localhost:3000/<route>");
+
+await playAudit({
+  page,
+  port: 9222,
+  thresholds: { performance: 100, accessibility: 100, "best-practices": 100, seo: 100 },
+  reports: { formats: { html: true, json: true }, name: "lighthouse-<route>" },
+  config: { extends: "lighthouse:default", settings: { formFactor: "mobile" } },
+});
+
+await browser.close();
+```
+
+Run twice per route: once `formFactor: "mobile"`, once `formFactor: "desktop"`. Both must hit 100/100/100/100.
+
+**Diagnose from the JSON report, not the HTML.** Parse `audits[*].score < 1` programmatically to find the offenders. Do not eyeball the HTML report.
+
+**Run 3-5 times and take the median.** A single audit can be noisy. CI must enforce the threshold on every PR.
+
+## ROOT-CAUSE CHECKLIST (HIT THESE FIRST, ALMOST ALWAYS THE CULPRIT)
+
+- **Render-blocking JS/CSS in the critical path.** Defer, code-split by route, inline critical CSS only.
+- **Unsized media.** Every `<img>`, `<video>`, `<iframe>` MUST have explicit `width`/`height` or an aspect-ratio container. Unsized media causes CLS.
+- **Wrong image format or dimensions.** Serve AVIF first, WebP fallback, JPEG last. Generate ALL responsive sizes in the build. NEVER ship an image larger than the rendered box. Use `fetchpriority="high"` on the LCP image.
+- **Fonts.** `font-display: swap` minimum, `optional` for non-critical fonts, preload the one critical font, subset to only the characters actually used.
+- **Third-party scripts in `<head>` synchronously.** Defer, lazy-load on first interaction, OR proxy through your own origin to remove a third-party DNS + TLS handshake from the critical path.
+- **Hydration on routes that do not need it.** React Server Components, islands, `client:load`, ONLY where the interactivity is real. Static routes ship zero JS.
+- **Missing semantic HTML.** `<button>` for buttons, `<a href>` for links, `<nav>` / `<main>` / `<header>` / `<footer>` landmarks, label every form input, alt-text every meaningful image, unique `<title>` per route.
+- **Tab order, focus rings, contrast ratios, prefers-reduced-motion, ARIA correctness.** Accessibility 100 means a screen-reader user can drive the page end-to-end without help.
+- **Meta tags.** `<title>`, `<meta name="description">`, OpenGraph, Twitter cards, structured data (JSON-LD), `lang` on `<html>`, `viewport`, canonical URL.
+
+## ANTI-PATTERNS. REJECT ON SIGHT.
+
+- Reporting a CLI Lighthouse score. **REJECT.** Tenet 1.
+- Removing an animation to fix INP. **REJECT.** Switch to a CSS-only transform/opacity animation. Debounce listeners. Move heavy work off the main thread.
+- Replacing a hero image with a placeholder to "fix" LCP. **REJECT.** Properly sized AVIF + `fetchpriority="high"` + preconnect to the image CDN is the actual fix.
+- Disabling JS for a route to "score 100". **REJECT.** Score 100 ON the JS-enabled production build, on a real user device profile.
+- Setting `display: none` on offscreen content to dodge audits. **REJECT.** Use `content-visibility: auto` plus proper lazy mounting. Never lie about the page.
+- Declaring victory after a single audit run. **REJECT.** Run 3-5 times, take the median. CI must enforce the threshold.
+- Scoring 100 on `localhost` and shipping without re-measuring against the deployed URL. **REJECT.** The CDN, real DNS, and real TLS handshake matter.
+
+## RESPONSE FORMAT (what to return when the user asks for a frontend audit or build)
+
+1. **Scores before / after**, mobile AND desktop, all four categories.
+2. **Design system compliance**: orphan tokens found / fixed, components documented.
+3. **Each fix** in one line, traceable to the audit it cleared.
+4. **What you intentionally did NOT do**, and why. Especially every tempting "easy point" you rejected to preserve UX.
+5. **Browser-based Design QA result**: breakpoints tested, visual bugs found/fixed, states verified.
+6. **The next audit you would run** if you had another iteration.
+
+If the run did not hit 100 in every category, you are NOT done. State so explicitly. Continue iterating.
+
+## MANTRA
+
+> **100 on every Lighthouse category, on a real browser, with full features and full animations intact. Or it is not done.**

package/skills/frontend-ui-ux/references/perfection/react-perf-tooling.md

@@ -0,0 +1,127 @@
+# React Perf Tooling for Lighthouse 100
+
+You are auditing or optimizing a React app for Lighthouse 100. Two tools belong in this workflow alongside Playwright + lighthouse — they catch the React-specific perf issues that Lighthouse counts but doesn't diagnose by component:
+
+| Tool | Surface | What it gives you |
+|---|---|---|
+| **react-scan** (`react-scan/lite`) | Runtime instrumentation, headless | Per-fiber `commit` events with `changeDescription` — "this component re-rendered because <prop / state / context / parent / hook> changed". Correlates with `long-animation-frame` to attribute LoAF to specific components. |
+| **react-doctor** | Static scan, CI-friendly | Deterministic findings across state/effects, perf (memoization, list keys, expensive children), architecture, security, a11y. One-shot `npx react-doctor@latest` produces a JSON report. From the Million.dev team. |
+
+Use both. They are complementary: `react-scan` tells you *what's slow right now*; `react-doctor` tells you *what's structurally wrong*. Both are dev-only and free.
+
+If the project does not yet have react-scan and react-doctor wired into its dev environment, read `../design/react-dev-tooling-skill.md` first and install them — they should be on by default for every React project this skill audits.
+
+## Lighthouse run + react-scan/lite
+
+`playwright-lighthouse` already drives a real Chrome. Inject `react-scan/lite` BEFORE React mounts via `page.addInitScript`. Then drain its `onEvent` stream during the run and assert on render budgets at the end.
+
+```ts
+// scripts/audit-with-react-scan.ts
+import { chromium } from "playwright";
+import { playAudit } from "playwright-lighthouse";
+
+const browser = await chromium.launch({ channel: "chrome" });
+const context = await browser.newContext();
+
+// Inject react-scan/lite BEFORE the app boots
+await context.addInitScript(() => {
+  // @ts-ignore — pulled from the project's node_modules or a self-hosted bundle
+  import("react-scan/lite").then(({ instrument }) => {
+    (window as any).__renderEvents = [];
+    instrument({
+      onEvent: (event: any) => {
+        if (event.kind === "commit") (window as any).__renderEvents.push(event);
+      },
+      recordChangeDescriptions: true,
+      includeFiberSource: true,
+      includeFiberIdentity: true,
+    });
+  });
+});
+
+const page = await context.newPage();
+await page.goto("http://localhost:3000/<route>");
+
+await playAudit({
+  page,
+  port: 9222,
+  thresholds: { performance: 100, accessibility: 100, "best-practices": 100, seo: 100 },
+  reports: { formats: { html: true, json: true }, name: "lighthouse-<route>" },
+  config: { extends: "lighthouse:default", settings: { formFactor: "mobile" } },
+});
+
+// Pull render events and assert on render quality
+const events = await page.evaluate(() => (window as any).__renderEvents);
+const unnecessary = events.filter((e: any) =>
+  e.tree?.some((node: any) => node.changeDescription?.kind === "unnecessary"),
+);
+
+if (unnecessary.length > 0) {
+  console.error(`FAIL: ${unnecessary.length} unnecessary renders detected during audit`);
+  for (const e of unnecessary.slice(0, 10)) console.error("  -", JSON.stringify(e, null, 2));
+  process.exit(1);
+}
+
+await browser.close();
+```
+
+This is the canonical integration. Run twice per route (mobile + desktop), same as the base Lighthouse workflow. Both must hit 100/100/100/100 AND zero unnecessary renders.
+
+## react-doctor — static perf gate
+
+Before the Playwright run, fail fast on structural issues. The scan is fast and doesn't need a browser, so put it earlier in the pipeline.
+
+```bash
+npx react-doctor@latest --json > .react-doctor-report.json
+```
+
+Parse `.react-doctor-report.json` for perf-category findings. Treat any perf finding as a blocker for the same reason you treat a Lighthouse score < 100 as a blocker — these are deterministic issues that *will* show up in Lighthouse eventually under throttling.
+
+Wire it into CI as a separate job (cheap, fast, no browser needed):
+
+```yaml
+- name: React Doctor static perf scan
+  uses: millionco/react-doctor@main
+```
+
+Or run inline with a fail filter:
+
+```yaml
+- name: React Doctor static perf scan
+  run: npx react-doctor@latest --json --fail-on perf
+```
+
+## When to load which during an audit
+
+Run them in this order, stop at the first failure:
+
+1. **`react-doctor`** — cheapest. Catches missing memoization, broken list keys, unstable callback refs, expensive children that re-render unnecessarily. Fix everything it reports BEFORE running Lighthouse — half the perf score wins live here.
+2. **`react-scan` interactive in dev** — load the page in real Chrome with `npx react-scan@latest init` already wired (see the dev-tooling reference). Walk the LCP route, the most-clicked CTA, and any animation-heavy view. The toolbar shows render counts; the overlay highlights unnecessary renders in gray. Fix until clean.
+3. **`react-scan/lite` in the Lighthouse run** — once interactive is clean, run the Playwright audit above. This catches anything that only shows under throttling or only on first paint.
+4. **Playwright + Lighthouse** — standard run from `README.md` audit workflow. Score 100 + zero unnecessary renders from step 3 = done.
+
+## React-specific perf root causes (extends `README.md` ROOT-CAUSE CHECKLIST)
+
+These are the failures `react-scan` and `react-doctor` surface that base Lighthouse won't directly name:
+
+- **Context value identity churn.** A provider value `useMemo` was forgotten; every consumer re-renders on every render of the provider's parent. → `useMemo` the value, or split contexts so high-churn fields don't sit next to stable ones.
+- **Inline object/array/callback props on memoized children.** `<Child config={{ a: 1 }} />` breaks `React.memo` every render. → Hoist, `useMemo`, or `useCallback`.
+- **List keys = array index.** Reordering shreds the reconciler. → Use a stable id from the data.
+- **Expensive components rendered unconditionally above the fold.** → `lazy()` + `Suspense`, or move below the LCP, or pre-render server-side.
+- **Effects that fire on every render.** Missing dependency arrays or unstable deps. → Stabilize deps, or split state, or extract to `useEvent`-style ref.
+- **Spreading the entire context value into props.** Couples every consumer to every field. → Destructure only the fields used.
+- **Hydration mismatches.** SSR markup doesn't equal client first-render. → react-doctor flags structurally; fix the source of the divergence (Date.now, locale, randomness, browser-only APIs).
+
+`react-doctor` finds these statically. `react-scan` confirms the symptom in the running app. Both must come clean before Lighthouse 100 is meaningful.
+
+## Anti-patterns specific to this workflow
+
+- **Forgetting `page.addInitScript` (using `page.evaluate` instead).** `evaluate` runs AFTER React mounts; you'll miss every initial-render event. Use `addInitScript`.
+- **`react-scan` non-lite during a Lighthouse run.** The full UI (toolbar, canvas overlay) adds overhead and skews the score. Use `react-scan/lite` ONLY for measurement; the full version is for interactive dev.
+- **Reporting Lighthouse 100 with `react-scan` showing 30+ unnecessary renders per route.** The score is meaningless if the React layer is thrashing — INP and CLS will degrade under real load even if the synthetic run passed. Both gates must clear.
+- **Treating `trackUnnecessaryRenders` as free.** It has measurable overhead; in a Lighthouse run it can drag the perf score by 2-3 points. Use it for interactive diagnosis, not for the audit run.
+- **Skipping react-doctor because "it's just a linter".** It's not. It detects React-specific defects (missing keys, broken memo, unstable refs, hydration mismatches) that ESLint plugins miss because they require fiber-level reasoning.
+
+## Mantra
+
+> **Lighthouse 100 + react-doctor clean + zero unnecessary renders from react-scan. All three or it is not done.**

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

@@ -0,0 +1,77 @@
+Performance is a Design Contract term settled before implementation, not cleanup afterwards. Fix these numbers so the independent review pass can falsify them against the contract hash.
+
+## Budget dimensions
+
+Give every dimension a number, an owner id, and a breach action. A number without its measurement profile cannot be disputed.
+
+- Profile: 4x CPU slowdown, 1.6 Mbps down, 150 ms RTT, cold cache, longest shipped locale.
+- LCP <= 2.5 s; interaction latency <= 200 ms; layout shift <= 0.10 with none after first input.
+- No main-thread task over 50 ms during load; in-app route change <= 300 ms to first update.
+- Compressed first-load script <= 180 KB per route; route transfer <= 1.0 MB; images <= 400 KB per view.
+- Web fonts: at most 2 families, 4 faces, 100 KB total, subset to the shipped scripts.
+- Breach action is exactly one of: block the change, record an exception id, renegotiate the budget.
+
+## Critical-path diagnosis
+
+Trace the request to first usable pixels and name the blocking resource before writing a fix. Recurring root causes:
+
+- a stylesheet or synchronous script in the head gating first paint;
+- data requested after the client bundle boots, not during the document response;
+- serial fetch chains where a child starts only once its parent settles;
+- media, banners, or embeds with no reserved box, forcing relayout;
+- a font swap controlled by client script, holding text invisible.
+
+## Asset delivery
+
+Ship the smallest asset that survives the widest box it renders into.
+
+- Declare intrinsic width and height or aspect-ratio everywhere; unsized media is a shift defect.
+- Serve width-appropriate candidates, cap the hero at 2x its container, content-hash long-lived files.
+- Load the LCP image eagerly, never lazily; lazy-load everything below the fold.
+
+## Script delivery and hydration cost
+
+Charge every kilobyte to a named interaction; content with no interaction ships no client script.
+
+- Split by route first, then at interaction boundaries, never below a separately reachable unit.
+- Keep islands at the leaf: hydrating a shell to power one control pays for the whole subtree.
+- Hold analytics, chat, consent, and flag scripts until after LCP paints.
+- Mark each route static, streamed, or client-stateful, and measure hydration in main-thread ms, not bytes.
+
+## Virtualizing long lists
+
+Virtualize on measured evidence only, above roughly 200 rendered rows or 2,000 DOM nodes. Exercise 1 row, the threshold, and 10x the threshold.
+
+- Disqualifying caveats: find-in-page, deep links into a row, screen-reader row counts, sticky headers, variable row height, focus after scroll, printing.
+- Reserve row height so the scroll thumb stays stable; keep the announced count equal to total items, not rendered items.
+
+## Perceived versus measured
+
+Treat these as two obligations; satisfying one never settles the other.
+
+- Hold a skeleton back until 200 ms of waiting, sized like the loaded content.
+- Acknowledge input inside 100 ms even when the result is slower; prefer optimistic state with a named rollback to a blocking spinner.
+- When only perception changed, report the measured number unchanged and label the gain advisory.
+
+## Audit protocol
+
+Run in order. Stop at the first step that produces a decision.
+
+1. Restate the budget table and the measurement profile.
+2. Capture one cold and one warm run per route; discard a single outlier.
+3. Rank blocking resources by time held on the critical path.
+4. Attribute each blocker to exactly one root cause above.
+5. Estimate recoverable milliseconds per fix before editing code.
+6. Apply the highest-yield fix alone, then re-measure on the same profile.
+7. Decide: within budget, exception id recorded, or blocked with the missing decision named.
+
+## Failure patterns
+
+Reject:
+
+- "Feels faster" with no re-measured number on the same profile.
+- A composite tool score reported as a mechanical pass.
+- A budget written as light, fast, or small instead of a number.
+- Lazy-loading the LCP element to win a byte count.
+- Virtualizing a 40-row table and losing find-in-page.
+- Cutting accessibility work and calling it a performance decision.

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

@@ -0,0 +1,84 @@
+Direction work settles who the interface serves, which task must never fail, and what would prove the answer wrong. Hand the facts, journeys, and open questions to the Design Contract.
+
+## Audience of record
+
+Write one primary user and at most two secondaries. A wider audience is an open question, not a decision.
+
+- Role, the decision this person owns, and return frequency: hourly, daily, monthly, once.
+- Conditions: device class, network floor, interruptions, shared or private screen.
+- Assistive setup as a real profile: magnifier, screen reader, switch input, no pointer.
+- Locales in scope with a fallback, and the non-audience kept as a non-goal.
+
+## The critical task and its stages
+
+Name the one task whose failure makes the interface worthless, then give each stage an exit condition.
+
+- Start state, end state, and the artifact proving completion.
+- Step ceiling and elapsed-time ceiling for the intended path.
+- Entry and orient: how the user arrives, and the fact proving the right place.
+- Act and confirm: the smallest saveable unit of progress, and the evidence returned.
+- Recover: where the path is abandoned today, the undo window, what is never retyped.
+
+## Success signals with thresholds
+
+Fix numbers while no direction is preferred. A signal without a number cannot fail.
+
+- Completion rate for the primary user with a floor; median and p95 time to confirm.
+- Errors per submission, and repeat attempts in one session.
+- Keyboard-only completion at 100%; no exception id is available here.
+- One counter-signal whose appearance retires the direction.
+
+## Knowledge-gap register
+
+Register the unknown instead of designing over it. Each gap gets an id and a route out.
+
+- Fields: `gap-NNN`, question, blocked decision, method, owner, deadline, fallback default.
+- Methods are actions: read the route, count real records, ask one closed question.
+- A gap with no method becomes a recorded assumption plus its cost if wrong.
+- A gap blocking a system decision forces `blocked` mode, never a plausible invention.
+
+## Scenarios the default design forgets
+
+One scenario per condition, naming the breakage and the required behavior.
+
+- Low vision: text at 200%, reflow at 320 CSS px, no horizontal scroll, no text baked into imagery.
+- Keyboard only: Tab, Shift-Tab, Enter, Escape reach every action; focus at 3:1; no trap.
+- Screen reader: heading outline stands alone, controls named, errors bound to their fields.
+- Low bandwidth: usable at 400 kbps and 300 ms latency; useful paint before fonts resolve.
+- Unfamiliar language: icon with label, no idiom, 40% string growth, wide characters as two cells.
+
+## Bounded direction alternatives
+
+Carry two or three candidates. One inevitable answer means nothing was examined.
+
+- Per candidate: favored user, task accelerated, task slowed, cost.
+- Candidates differ on structure, sequence, or density, not on color.
+- Invariants: accessibility floors, state inventory, locale and performance budgets.
+- One line per candidate naming the observation that kills it.
+
+## Decision checkpoints
+
+Pass these in order. Practitioner confidence is not a checkpoint.
+
+1. Audience and critical task confirmed by the user, or `blocked`.
+2. Thresholds agreed; every blocking gap closed or defaulted with its risk written down.
+3. One direction selected against the invariants; losers kept with reject reasons.
+4. Contract validates as evidence-eligible `litfamily.design-contract/v1beta2` and its hash is recorded; valid `litfamily.design-contract/v1beta1` documents remain accepted and evidence-eligible; alpha is diagnostic-only.
+
+## Research output package
+
+Hand exactly this forward. Anything outside it is not research output.
+
+- Users, non-audience, critical task with both ceilings and stages.
+- Thresholds, counter-signal, gap-register status, inclusive scenarios.
+- Candidate directions, reject reasons, and the selected direction.
+- Assumptions, omission ids, exception ids, and the contract hash the independent review pass reads.
+
+## Failure patterns
+
+Reject:
+
+- An audience written as demographics rather than task and environment.
+- Success stated as adjectives: intuitive, clean, modern, delightful.
+- Accessibility postponed instead of written as required scenario behavior.
+- One direction presented as inevitable, alternatives invented to justify it.