@litfamily/litgrok 1.0.0

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

@@ -0,0 +1,92 @@
+Access is a property of the markup and the flow, not a layer applied at the end. Every rule here
+belongs in `accessibility` or `localization` with a proof channel attached.
+
+## Structure before styling
+
+Build the outline first and read it as a plain document. A correct outline removes most ARIA.
+
+- one `h1` per view, then ranks in order with no level skipped
+- landmarks present and unique: banner, navigation, one `main`, complementary, contentinfo
+- native `button`, `a`, `input`, `dialog`, `table` before any composite widget
+- an element needing `role`, `tabindex`, and three key handlers is the wrong element
+
+## Visual access
+
+Measure contrast against the pixels actually painted behind the text, in every theme and state.
+
+- 4.5:1 body text, 3:1 at 24px or 19px bold, 3:1 for icons and control boundaries
+- focus indicator 2px or thicker, at 3:1 against control and surroundings
+- state never carried by hue alone; add a label, glyph, shape, or position
+- 200% zoom reflows without loss; 400% must not require scrolling on two axes
+
+## 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
+- announce async results through a live region; a visual change alone is silent
+
+## Localization
+
+Assume translation and mirroring from the first commit.
+
+- interpolate whole sentences; never assemble copy from fragments
+- logical properties (`margin-inline`, `inset-inline`) so `dir="rtl"` mirrors
+- locale-aware dates, numbers, currency, pluralization, and collation
+- `lang` on the root element and at every inline language change
+
+## CJK and IME checklist
+
+Latin-only testing hides these defects. 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
+- read `event.isComposing`; hold validation, filtering, and submit until `compositionend`
+- accept full-width digits and Latin in inputs; normalize with NFKC before comparison
+
+## Adaptive preferences
+
+Each preference is a stated requirement, not a hint. Verify all four.
+
+- `prefers-reduced-motion: reduce` removes travel and parallax, keeps state
+- `forced-colors: active` yields to system keywords; no hardcoded background survives
+- `prefers-contrast: more` strengthens text and boundaries, not only the accent
+- size in `rem` so OS text scaling applies; never pin the root to `px`
+
+## Proof channels
+
+Each channel finds defects the others cannot. Run all four and name them in `evidence_policy`
+with the route and state each covered.
+
+1. `keyboard`: full traversal, no trap, visible focus, every action reachable.
+2. `screen-reader`: name, role, value, state, announcement order on one real reader.
+3. `accessibility-tree`: the repository's automated audit per route and critical state.
+4. `localization`: a second locale at 200% zoom, under forced colors and reduced motion.
+
+## Severity ladder
+
+Triage by what the user can no longer do, then order the queue.
+
+- S1: a keyboard or screen-reader user cannot finish. Report `FAIL`; blocks release.
+- 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

@@ -0,0 +1,101 @@
+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.
+
+## 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.
+
+- 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
+
+Answer all three before adding motion. One "no" removes it.
+
+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?
+
+## Choreography and sequencing
+
+Sequence movement to direct attention. Specify trigger, property, duration, easing, interruption.
+
+- 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
+
+## Reduced motion without lost meaning
+
+Under `prefers-reduced-motion: reduce`, keep the information and drop the travel.
+
+- 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
+
+## The record handed to review
+
+Give the independent review pass one entry per interaction, keyed to the design contract hash.
+Anything missing counts as untested.
+
+- 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
+
+## Failure patterns
+
+Reject:
+
+- an interaction with no pending, empty, or failure state named
+- validation on every keystroke, or an error that discards user input
+- focus dropped to `body` after dismissal, or a dialog with no return target
+- a gesture, hover, or drag as the only route to an action
+- motion longer than 400ms, or completion gated on an animation callback

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

@@ -0,0 +1,92 @@
+Every interface request runs in exactly one lane. The lane fixes the evidence you gather, what
+you may edit, what stays frozen, and what closes the work.
+
+## Selecting a lane
+
+Pick from observable repository facts, not from phrasing. Name the lane before the first edit.
+
+1. No production UI exists for the surface: `new-build`.
+2. UI exists and the request repairs or extends it: `brownfield`.
+3. UI exists and the request replaces its visual language: `redesign`.
+4. A screenshot, mockup, or live product is the acceptance target: `reference-fidelity`.
+5. The deliverable is primitives other surfaces consume: `design-system`.
+
+## Lane: new-build
+
+Settle the system before drawing screens. Your first component becomes the convention.
+
+- Evidence: package boundaries, routing, data layer, global styles, locales, device classes.
+- Permitted: every file in the new surface, plus new tokens and primitives.
+- Frozen: file layout, naming, import boundaries, test placement, data-fetching pattern.
+- Failure mode: a second styling system grows beside the one already in the repository.
+- Exit: inventory finite, every declared state renders, no raw value a token already names.
+
+## Lane: brownfield
+
+Audit before editing. The existing system is the specification until told otherwise.
+
+- Evidence: covering primitives, their variants and call sites, untouched captures at two widths.
+- Permitted: the named defect and its direct call sites.
+- Frozen: exported props, imported token and class names, keyboard model, test assertions.
+- Failure mode: a local fix mutates a shared primitive and breaks surfaces nobody opened.
+- Exit: defect gone, and every other consumer of the touched code has parity evidence.
+
+## Lane: redesign
+
+Current behavior is the specification. Only the visual language is negotiable.
+
+- Evidence: baseline capture of every affected route and state, the debt map, keyboard paths.
+- Permitted: tokens, spacing, typography, density, motion, component internals.
+- Frozen: task paths and step counts, URLs and parameters, data meaning, permissions, copy.
+- Failure mode: old and new surfaces coexist with no owner for the remainder.
+- Exit: parity holds at every stage boundary; no route stranded on the superseded system.
+
+## Lane: reference-fidelity
+
+Separate what the reference proves from what you supplied. Only observed claims are criteria.
+
+- Evidence: provenance and permission, pixel dimensions, device scale, the exact state depicted.
+- Permitted: the depicted surface, to the agreed fidelity level.
+- Frozen: the repository stack, the accessibility floor, licensing of every mark and asset.
+- Failure mode: one width matches while responsive and interaction behavior is invented.
+- Exit: every observed claim checked; every inference recorded as an assumption with an owner.
+
+## Lane: design-system
+
+The consumers are the deliverable, not the gallery. Specify the contract first.
+
+- Evidence: duplicated implementations across consumers, variants in use, call sites.
+- Permitted: primitive internals, token definitions, documented variants, migration paths.
+- Frozen: published prop contracts until a migration exists; keyboard model of replaced controls.
+- Failure mode: a gallery ships that no production route adopts.
+- Exit: two representative consumers migrated and passing, with a dated removal plan.
+
+## Requests spanning two lanes
+
+Split it; never average it.
+
+1. Name both lanes and assign each surface to exactly one.
+2. Write one contract per lane, each with its own inventory, budgets, and exit.
+3. Sequence them: repairs before a redesign of the same surface, primitives before consumers.
+4. If the split is refused, apply the stricter lane's frozen list to the whole scope.
+5. Re-declare the lane as soon as discovery changes it, then revalidate the contract.
+
+## Where the lane is recorded
+
+The lane is a required, machine-checkable `lane` field of the authoritative
+`litfamily.design-contract/v1beta2` artifact. A valid `litfamily.design-contract/v1beta1` artifact
+remains a compatibility input for existing implementation paths. The validator rejects a missing lane,
+an unknown lane, or a prose synonym. The review package repeats the same value beside the contract hash;
+it does not substitute for the field. A v1alpha1 contract has no lane and is migration-only, so its
+otherwise valid report carries `LEGACY_SCHEMA_V1ALPHA1` and `evidence_eligible: false`.
+
+## Failure patterns
+
+Reject:
+
+- A change whose review package names no lane.
+- A `brownfield` or `redesign` lane opened with no baseline capture.
+- A lane switch first visible in the diff.
+- A `reference-fidelity` verdict claimed from a general visual review.
+- An unlaned change entering the independent review pass, leaving the reviewer to guess which
+  frozen list the design contract hash covers.

package/.grok/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/.grok/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.**