@ericrisco/rsc 3.1.3 → 3.3.0

package/skills/design/references/signature-and-craft.md

@@ -1,148 +0,0 @@
-# Signature & Craft — manufacturing the distinctive idea, then the finish that sells it
-
-A page that obeys every constraint in this skill and still feels generic is the default failure mode.
-Constraints get you to *competent*. They do not get you to *premium*. The difference is a **visual
-concept** — one defensible idea the whole surface commits to — plus the **craft moves** that make the
-rendered artifact read as authored rather than assembled. This reference is the method for both. Use it
-whenever the output has to be genuinely good, not merely compliant.
-
-## Why compliant output still scores ~7.7
-
-The checklist tells you the page *ships*. It cannot tell you the page is *good*, because every defect it
-catches is an absence (no missing `<h1>`, no `transition: all`, contrast passes). Premium is a presence:
-a point of view. The common shortfalls that keep correct work at "competent" are predictable — fix these
-and the output moves up a band:
-
-| Symptom of generic output | Root cause | The move |
-| --- | --- | --- |
-| "Looks like a nice template" | No visual concept; defaults filled every slot | Commit to ONE signature idea (below) |
-| Tonally flat — everything medium-sized | No scale contrast; safe type ramp | Force a dominant element 3–5× the body (below) |
-| Sections blur into one stripe | No rhythm; identical `py`, identical card grids | Vary section format + background + density (below) |
-| Hero is a centered headline + gradient | The default the model reaches for under-specified | Show the product doing the job; earn the layout |
-| Correct but forgettable color | Brand hue used like everyone's brand hue | One owned accent move, applied with restraint |
-| Everything is rounded cards on white | One container idiom repeated | Mix surface treatments; let some content breathe edge-to-edge |
-
-## Step 1 — Choose a visual concept (do this before any markup)
-
-A visual concept is a single sentence the entire page can be checked against. It is NOT a color or a font;
-it is an organizing idea that dictates layout, type, color, motion, and imagery together. Write it down,
-then make every section answer to it.
-
-> Concept = `[adjective of feeling]` + `[structural metaphor]` for `[audience doing job]`.
-> e.g. "Quiet, instrument-panel precision for ops engineers who live in this all day."
-> e.g. "Confident editorial broadsheet for a brand that wants to feel like a publication, not an app."
-> e.g. "Tactile, mechanical-keyboard heft for a dev tool that should feel engineered."
-
-Pick the concept from the DIRECTION BRIEF + brand study + research exemplars — never from your prior. If
-you cannot say in one sentence what makes this surface different from the median SaaS page, you have not
-chosen a concept yet, and the output will default to generic.
-
-## Step 2 — Manufacture the signature element (the "ONE idea")
-
-Every premium page has one element you would describe first to a friend. The brief asks for it; this is how
-to actually generate it instead of defaulting to a gradient. Pick **exactly one** primary signature (a
-second, quieter echo is fine; three competing signatures is noise). Choose from this vocabulary, biased by
-the concept and domain:
-
-- **A hero that demonstrates, not describes** — the product mid-task: a real terminal session, a live
-  chart updating, an actual diff, a populated dashboard. The single highest-leverage move for dev tools and
-  SaaS; it passes the 5s test by *showing* the value instead of claiming it.
-- **An owned type moment** — one oversized display setting (a 96–160px headline, a tight-tracked all-caps
-  eyebrow, a serif/grotesk pairing with real contrast) that no template ships by default.
-- **A structural signature** — an unexpected but legible layout: a horizontal-scroll feature rail, an
-  asymmetric split hero, a numbered editorial index, a sticky side-rail that tracks the section.
-- **A material signature** — a consistent, restrained physical treatment: hairline grid lines, a single
-  grain/noise pass, a duotone photographic style, a precise mono-spaced data aesthetic.
-- **A motion signature** — one purposeful move that recurs (a scroll-driven reveal cadence, a hover that
-  uncovers state) — only if it earns its INP/CLS budget.
-- **A data/proof signature** — a real number rendered as the visual centerpiece (a live metric, a benchmark
-  bar, a before/after). Strongest when the proof IS the product's claim.
-
-Rule: the signature must be *true to the product*. A fintech dashboard's signature is precision and density;
-a creative tool's is expression. A signature borrowed from the wrong domain reads as costume. Cite which
-research exemplar inspired the move (e.g. "feature rail per linear.app/changelog") so it is grounded, not
-invented.
-
-## Step 3 — Force scale contrast (the fastest fix for "flat")
-
-Generic pages are tonally flat: the headline, the section titles, and the body are all within ~1.5× of each
-other, so nothing dominates and the eye has nowhere to land. Premium pages have a **dramatic range**.
-
-- Establish a clear **hero dominant**: the largest single element on the page (a headline or product visual)
-  should be **3–5× the body size**, not 2×. Commit to it.
-- Then **demote ruthlessly**: eyebrows, labels, and metadata go *smaller and quieter* (13–14px, muted,
-  tracked) than you instinctively want. Contrast is created by the small things being genuinely small.
-- One **focal point per viewport**. If two things compete for "biggest", neither wins — shrink one.
-- Apply the same logic to weight (one heavy display weight against a regular body), and to color (the 10%
-  accent appears once or twice per viewport, never spread thin).
-
-If a section feels flat, the fix is almost always *more* contrast, not more elements.
-
-## Step 4 — Give the page rhythm (sections must not blur)
-
-A landing page that is ten identical white sections with `py-24` and a 3-up card grid reads as one long
-stripe. Authored pages have a **beat**: the eye is paced. Vary, section to section, at least one of:
-
-- **Format** — full-bleed vs. contained; centered vs. asymmetric; grid vs. single statement; media-left vs.
-  media-right (alternate, don't repeat one side).
-- **Background** — alternate base / subtly tinted / inverted (a dark section between two light ones is a
-  classic rhythm device and creates a natural CTA anchor).
-- **Density** — a breathing, near-empty statement section after a dense feature grid resets the eye.
-- **Container idiom** — don't make *everything* a bordered card on white. Let a hero visual run edge-to-edge;
-  let one statement sit in open space with no container at all.
-
-Spacing rhythm is load-bearing here: section padding should step on the scale (e.g. 64 → 96px), and the
-*gap between sections* should be visibly larger than the gap *within* a section, so groups read as groups.
-A flat `py` on every section is the tell of generated output.
-
-## Step 5 — The craft finish (compounding micro-decisions)
-
-These are in the SKILL's "Premium details" table; apply them as a deliberate pass, not by accident:
-
-- Concentric radius (`outer = inner + padding`); never same-radius nesting.
-- Layered transparent OKLCH shadows; hairline `fg/10` borders for separation, shadow only for true float.
-- `text-wrap: balance` on headings, `pretty` on body; `tabular-nums` on any changing number/price.
-- Optical alignment: trust the eye over the math for icon centering and cap-height padding.
-- Restraint: glass on floating surfaces only; gradient as seasoning on one surface; one accent, used rarely.
-
-## Step 6 — Self-critique before you claim done (the senior-designer pass)
-
-Before shipping, interrogate your own output with the questions a senior designer would ask in a crit. Answer
-them honestly in your own head (or out loud to the user); if any answer is weak, iterate before delivering.
-
-1. **What is the one idea here?** If you cannot name it in a sentence, there is no concept — go to Step 1.
-2. **Would this place on Awwwards / Godly, or just pass review?** If "just pass", it is at ~7; name the
-   single most generic element and replace it.
-3. **What's the most generic thing on this page right now?** (Usually: the hero, the gradient, the 3-up card
-   grid, or the stock-feeling copy.) Fix that one thing first — it has the highest leverage.
-4. **Where does the eye land first, and is that the thing that should win?** If not, fix scale contrast.
-5. **If I deleted the logo, would anyone know whose product this is?** If not, the concept/signature is too
-   timid.
-6. **Does every section earn its place, or is one there out of habit?** Cut the weakest section entirely;
-   removal is a design decision.
-7. **Is the copy carrying a specific, verifiable claim, or vibes?** Swap one vague benefit for a concrete,
-   quantified one.
-
-The point of the pass is not to pass it — it is to make at least one concrete change as a result. A surface
-that survives this crit unchanged on the first try usually means the crit was not honest.
-
-## Worked example — generic → signature (dev-tool hero)
-
-**Generic (≈7, competent):** centered `<h1>` "Ship faster with our developer platform", subhead, two buttons,
-purple→blue gradient blob behind it, 3-up feature cards below, all sections `py-24` on white.
-
-**Signature (≈9, premium):**
-- *Concept:* "Engineered precision — this tool should feel like instrumentation."
-- *Signature element:* the hero IS a live, syntax-highlighted terminal session running the actual command,
-  output streaming — the product demonstrates the value (Step 2, "demonstrate not describe").
-- *Scale contrast:* a tight-tracked 13px mono eyebrow ("v2.4 — now with preview environments"), a 72px
-  display headline with one concrete claim ("Spin up a preview in 4s"), demoted everywhere else (Step 3).
-- *Rhythm:* light hero → dark proof section with a real benchmark bar → light asymmetric feature split
-  (media alternating sides) → dark final CTA (Step 4).
-- *Finish:* hairline grid lines as the material signature, mono `tabular-nums` on the benchmark, concentric
-  radius on the terminal chrome, one accent used only on the active prompt and the primary CTA (Step 5).
-- *Crit result:* "the live terminal" is the one idea; logo-removed it still reads as this product; eye lands
-  on the streaming output, which is the value (Step 6 passed honestly).
-
-Same constraints, same tokens, same stack — the difference is concept + signature + contrast + rhythm +
-honest crit. That is the gap between 7.7 and premium.

package/skills/design/references/starting-point.md

@@ -1,75 +0,0 @@
-# Reference — proposing a starting point
-
-Three places promise to propose one: `../../design-loop/SKILL.md` phase 1 when the user says *skip*,
-the closing line of `brand-grounding.md` when a visual dimension has no direction, and
-`../../design-dna/SKILL.md`'s REUSE mode. This file is what they propose *from*. Without it the
-fallback is your own prior, which is the AI-template median — the thing the whole area exists to escape.
-
-## 0. What the project already owns wins
-
-**Look before you offer.** Run it; do not reason about it:
-
-```bash
-npx @ericrisco/rsc doctor --json   # read `designStartingPoint`
-```
-
-| State | What it means | What you do |
-| --- | --- | --- |
-| `owned` | An identity article or at least one legible style record exists | Propose **that**, by name, first. Offer nothing external until the user rejects it. More than one record → all of them are candidates, ordered as reported. Never pick one silently. |
-| `none` | Looked in both scopes, found nothing | Go to §1. |
-| `inconclusive` | Something could not be read | Say what, and ask for another route to it. **Do not propose past a blind spot** — a proposal made without looking is the defect this file exists to remove. |
-
-If the owned identity **contradicts** what the user is now asking for, name the conflicting rule and let
-them decide which wins. Same rule the loop's preflight already applies to a bar from outside.
-
-A record that `doctor` reports with a pair below its contrast floor is not offered as a starting point.
-
-## 1. What are you building → which bar
-
-At most **three** candidates. Each one gets a name, one line on why it fits *this* product, and one line
-on when it would be the wrong choice. Then **wait**. No answer → take the most demanding one and say so.
-
-Sources are in `inspiration-sources.md`; the tier-1 set and the dated-looking list are in
-`trends-2026.md`. **Only propose what you can actually open** — that registry marks several sources as
-bot-blocked, and a bar that cannot be fetched dies in the loop's preflight.
-
-| Building | Candidate bars | Wrong choice when |
-| --- | --- | --- |
-| SaaS marketing | Stripe · [SaaS Landing Page](https://saaslandingpage.com) browsed by section · Linear | The product is a daily tool, not a purchase decision — a marketing skin on a workhorse |
-| Dev tool | Linear · Vercel · Resend · [Primer](https://primer.style) | The audience is not technical: dev-tool restraint reads as unfinished to them |
-| Dashboard / internal tool | [Carbon](https://carbondesignsystem.com) · [Polaris](https://polaris.shopify.com) · [Mobbin](https://mobbin.com) flows | It is a landing page with a chart on it — density is not the job |
-| Portfolio / editorial | [Awwwards](https://www.awwwards.com) · [Recent](https://recent.design) · [One Page Love](https://onepagelove.com) | Anything with a conversion target: award craft routinely costs LCP and the 5s test |
-| E-commerce | [Minimal Gallery](https://minimal.gallery) for restraint · [Nicely Done](https://nicelydone.club) for real product surfaces | The catalogue is huge and the real problem is search and filtering, not the hero |
-| Docs | [Stripe docs](https://docs.stripe.com) · [Material 3](https://m3.material.io) on states | Reading is not the job — it is a reference table, so density beats calm |
-
-Nothing here fits what they are building? **Say so and interview.** Do not stretch the nearest row: a bar
-chosen because it was closest is the vague bar that makes the loop approve everything on round one.
-
-## 2. A proposal is not an answer
-
-1. **Open the reference.** No value is proposed from a page you did not fetch. Blocked → say so, pick
-   another. Never substitute a description from memory.
-2. **Measure it** — the loop's teardown already does this and writes 5 to 7 mechanisms. Those measured
-   values *are* the researched default this file was missing. They are not invented, and they come from
-   a page that already ships.
-3. **Check colour before writing it.** Any text pairing must measure **≥ 4.5:1** (≥ 3:1 for large text
-   and UI). Below that, it is **not proposed** — not proposed-with-a-warning.
-4. **Write it marked `propuesto`, naming the reference it came from.** Never as a confirmed value.
-5. A dimension that is proposed and not yet confirmed **does not count as complete** against
-   `brand-grounding.md`'s checklist. The hard STOP stays up for it. Otherwise the prefill becomes the
-   way to cross the gate with nobody having confirmed anything.
-6. Only what the user confirms becomes the project's identity.
-
-## 3. The base is the floor, not the concept
-
-A starting point gets you a defensible floor in one exchange. It does **not** satisfy the ONE signature
-element (`signature-and-craft.md` §2), and it never will: every project that picked the same bar would
-converge on the same page. If the only thing making this surface distinctive is the bar it started from,
-there is no concept yet.
-
-## See Also
-
-- `inspiration-sources.md` — the source registry, dated, with the bot-blocked entries marked.
-- `trends-2026.md` — the tier-1 set, and what currently reads as a template.
-- `brand-grounding.md` — the checklist this fills in, and the STOP it does not lift.
-- `signature-and-craft.md` — the part a starting point cannot give you.

package/skills/design/references/trends-2026.md

@@ -1,80 +0,0 @@
-# 2026 UX/UI Trends — Dated Snapshot (re-verify per project)
-
-This is a **point-in-time snapshot**, last verified **June 2026**. Trends churn quarterly and your built-in aesthetic prior is the AI-template median — so this file is a starting reference, not a substitute for live research. **Re-run WebSearch/WebFetch per project** (per `research-method.md`) and refresh this file when you do; cite sources with their dates. Treat anything here older than ~3 months as suspect.
-
-## How to use this file
-
-- When the brand study (`brand-grounding.md`) leaves a visual dimension with no user direction, or the user asks for "modern" / "2026" / "premium", pull current trends and fold the findings into the output **with citations + dates**.
-- Extract *principles*, not pixels. "Bento for feature sections" is a principle; cloning a competitor's exact grid is theater.
-- Cross-check every trend against the non-negotiables in `SKILL.md` — a trend that breaks contrast, CWV, or the 5s test is out, however current.
-
-## Stack currency (verified June 2026)
-
-| Tool | Current | Notes |
-| --- | --- | --- |
-| Tailwind CSS | v4.3 (2026-05-08) | OKLCH-native `@theme`, no `tailwind.config.js`; v4.2 added scrollbar/logical-property utilities and new palettes. |
-| Next.js | 15 stable (16 released; this skill targets 15 + App Router) | Async request APIs, Turbopack stable, React 19 required for App Router. |
-| React | 19.2.x (19.2.6, 2026-05-06) | Stable in Next.js 15.1+. |
-
-Sources: [Tailwind v4.3 / v4.2 release notes](https://tailwindcss.com/blog), [InfoQ — Tailwind 4.2](https://www.infoq.com/news/2026/04/tailwind-css-4-2-webpack/), [Next.js 15 blog](https://nextjs.org/blog/next-15), [React versions](https://react.dev/versions). Re-verify before quoting a version.
-
-## Typography (2026)
-
-- **Type as the hero, not decoration.** Oversized headlines, expressive display faces, and variable fonts that respond to interaction/context. Serif and ledger-style numerals are back for editorial weight where the brand allows.
-- **Kinetic typography** — headlines that animate on scroll — but only behind a purpose gate and reduced-motion guard (see `motion-and-interaction.md`); decorative letter-jelly is out.
-- **Still true:** modular scale, ≤2 families, 45–75ch measure, `text-wrap: balance` on headings. Trends do not override the fundamentals in `visual-system.md`.
-
-Source: [Figma — Web design trends](https://www.figma.com/resource-library/web-design-trends/) (2026), [Tubik — UI trends 2026](https://blog.tubikstudio.com/ui-design-trends-2026/) (2026).
-
-## Color (2026)
-
-- **Two poles this cycle:** (1) high-energy / "dopamine" — deep blacks layered with electric neon, sunset coral, holographic accents (Y2K-adjacent); (2) calm/adaptive — light "morning", low-contrast "focus", warm "evening" modes. Pick the pole the *brand* dictates; do not default to the loud one.
-- **OKLCH is the production default** for ramps and dark-mode token swaps (perceptually even lightness, wider P3 gamut). Build ramps by holding hue+chroma and stepping L (see `visual-system.md`).
-- **Adaptive / time-of-day theming** is emerging beyond binary light/dark — only worth it when the audience benefits; otherwise it is complexity for its own sake.
-- **Still true:** 60-30-10 allocation, text ≥ 4.5:1, the brand color earns attention by being rare. Vivid palettes raise the contrast-failure risk — verify, never eyeball.
-
-Source: [Envato — UX/UI trends 2026](https://elements.envato.com/learn/ux-ui-design-trends) (2026), [Figma](https://www.figma.com/resource-library/web-design-trends/) (2026).
-
-## Layout (2026)
-
-- **Bento** remains the standard for feature → benefit sections: asymmetric grid, one focal cell the eye lands on first.
-- **Visible grids / wireframe logic as foreground** — exposed columns and structural lines used as decoration, not hidden scaffolding.
-- **Experimental navigation** (radial menus, drawers, nonlinear journeys) and maximalist/collage layering — high-risk; only where the brand is expressive and it does not cost the 5s test or accessibility.
-- **Container queries** (`@container`, core in Tailwind v4) for components that adapt to their slot, not just the viewport.
-- **Still true:** clear focal point, max-width ~1024–1200px, body measure ~65ch.
-
-Source: [Figma](https://www.figma.com/resource-library/web-design-trends/) (2026), [Index.dev — 12 UI/UX trends 2026](https://www.index.dev/blog/ui-ux-design-trends) (2026).
-
-## Motion (2026)
-
-- **Motion earns its keep by guiding, not flashing.** The cycle has moved away from bouncy micro-interactions toward *believable* motion: progress that reports real wait time, transitions that preserve continuity.
-- **Native CSS scroll-driven animation** (`animation-timeline: view()/scroll()`) is the default engine — zero JS, no CLS — behind an `@supports (animation-timeline: view())` feature query and a `prefers-reduced-motion` guard (see `motion-and-interaction.md`). As of June 2026 it ships in Chromium (115+) and Safari (18+, full in Safari 26); Firefox has it implemented but still behind a flag, so the `@supports` query is load-bearing for the graceful fallback.
-- **Still true:** purpose gate (guide / communicate / preserve), compositor-only properties (`transform`/`opacity`/`filter`), enter ~250ms / exit ~150ms, reduced-motion honored.
-
-Source: [Tubik — UI trends 2026](https://blog.tubikstudio.com/ui-design-trends-2026/) (2026), [Envato](https://elements.envato.com/learn/ux-ui-design-trends) (2026).
-
-## Tier-1 reference set (re-fetch live)
-
-The benchmark for premium product/landing work this cycle — fetch the live sites in the research loop rather than trusting memory of them:
-
-- **Linear** — radical restraint, dark near-monochrome, one accent, product-forward.
-- **Stripe** — docs + marketing balance, gradients used as restrained seasoning.
-- **Vercel** — type-led minimalism, dev-tool voice, product shown immediately.
-- **Resend** — dev-tool voice in copy, clean bento, annual-default pricing.
-- **Awwwards / Godly / Land-book / Mobbin** — galleries for direction, motion, and section order; weight by domain (skip the expressive entries for a dense dev tool).
-
-## What now reads as dated / AI-generic (avoid)
-
-- Purple→blue gradient on every surface; centered headline over an atmospheric mesh with the product hidden below the fold.
-- Heavy glassmorphism / neumorphism everywhere; blob backgrounds.
-- Cards-inside-cards; one hard `0 4px 8px #000` drop shadow on everything.
-- Bouncy jelly micro-interactions with no informational purpose.
-
-These are the AI-template median the research-first protocol exists to escape (`research-method.md`).
-
-## See Also
-
-- `research-method.md` — the live research loop that refreshes this snapshot.
-- `brand-grounding.md` — offer these researched defaults when a brand dimension has no direction.
-- `visual-system.md` — fundamentals these trends sit on top of (and never override).
-- `motion-and-interaction.md` — the scroll-driven / reduced-motion implementation referenced above.

package/skills/design/references/visual-system.md

@@ -1,237 +0,0 @@
-# Visual System — Tokens, Type, Color, Layout, Depth
-
-The full design-token and aesthetics system. Define tokens once with Tailwind v4 `@theme`; consume them everywhere as utilities and raw `var()`. Targets the current stack (verified June 2026): Tailwind CSS v4.3, Next.js 15, React 19, OKLCH-native color.
-
-## Spacing scale
-
-Spacing rhythm is what separates "designed" from "thrown together". Anchor every gap, padding, and margin to a 4/8px base scale so vertical and horizontal rhythm stays consistent.
-
-| Step | rem | px | Typical use |
-| --- | --- | --- | --- |
-| 0 | 0 | 0 | reset |
-| 1 | 0.25rem | 4 | icon gap, hairline inset |
-| 2 | 0.5rem | 8 | tight label/input gap |
-| 3 | 0.75rem | 12 | button padding-y |
-| 4 | 1rem | 16 | base block gap |
-| 6 | 1.5rem | 24 | card padding |
-| 8 | 2rem | 32 | section inner gap |
-| 12 | 3rem | 48 | sub-section gap |
-| 16 | 4rem | 64 | section padding-y (mobile) |
-| 24 | 6rem | 96 | section padding-y (desktop) |
-
-Tailwind utilities (`p-4`, `gap-6`, `py-24`) map directly to this scale. **When to break it:** only for *optical* alignment — nudging an icon 1px to look centered, or trimming 2px off cap-height padding. Optical fixes are deliberate exceptions, not a second arbitrary scale.
-
-## Typographic scale
-
-Pick a modular ratio and step every size from a 16px base. Larger ratios read more editorial; smaller ratios read denser and more utilitarian.
-
-| Ratio | Name | Ladder from 16px (rounded) |
-| --- | --- | --- |
-| 1.200 | Minor third | 16 · 19 · 23 · 28 · 33 · 40 |
-| 1.250 | Major third | 16 · 20 · 25 · 31 · 39 · 49 |
-| 1.333 | Perfect fourth | 16 · 21 · 28 · 38 · 51 · 67 |
-
-Use fluid `clamp()` so headings scale with the viewport instead of jumping at breakpoints:
-
-```css
-/* min, preferred (rem + vw), max — never snaps, never overflows */
-.h1   { font-size: clamp(2.25rem, 1.5rem + 3vw, 3.75rem); line-height: 1.05; text-wrap: balance; }
-.h2   { font-size: clamp(1.75rem, 1.25rem + 2vw, 2.5rem);  line-height: 1.1;  text-wrap: balance; }
-.lead { font-size: clamp(1.125rem, 1rem + 0.5vw, 1.375rem); line-height: 1.5; }
-```
-
-Rules:
-
-- **Line-height:** 1.5 for body, 1.05–1.15 for display. Tighter type wants tighter leading.
-- **Measure:** keep body text at 45–75ch (`max-w-prose` ≈ 65ch). Long lines kill readability.
-- **Pairing:** one display face + one text face, or a single superfamily with weight contrast. Never three+ families.
-
-Self-host with `next/font` so there is no FOUT swap shift (a CLS source):
-
-```tsx
-// app/fonts.ts — next/font, self-hosted, no layout shift
-import { Geist, Inter } from "next/font/google";
-export const display = Geist({ subsets: ["latin"], variable: "--font-display", display: "swap" });
-export const text = Inter({ subsets: ["latin"], variable: "--font-text", display: "swap" });
-```
-
-```tsx
-// app/layout.tsx — apply the font variables on <html>
-import { display, text } from "./fonts";
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className={`${display.variable} ${text.variable}`}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-`next/font` auto-computes a size-adjusted fallback so the layout does not shift when the web font loads. Pair `display: "swap"` with that fallback to keep CLS at 0.
-
-## Color theory (OKLCH)
-
-OKLCH is the modern default: `oklch(L C H)` where **L** is perceptual lightness (0–1), **C** is chroma, **H** is hue (0–360). Unlike HSL, equal L steps look equally bright across hues, and OKLCH reaches the wider P3 gamut on capable displays.
-
-Build a ramp by **holding hue and chroma, stepping L**:
-
-```css
-/* Brand ramp — hold hue 256 + chroma, step lightness */
-@theme {
-  --color-brand-50:  oklch(0.97 0.02 256);
-  --color-brand-100: oklch(0.93 0.05 256);
-  --color-brand-300: oklch(0.78 0.13 256);
-  --color-brand-500: oklch(0.62 0.19 256);
-  --color-brand-700: oklch(0.48 0.17 256);
-  --color-brand-900: oklch(0.32 0.10 256);
-}
-```
-
-- **60-30-10 allocation:** ~60% background/neutral, ~30% foreground/structure, ~10% brand/accent. The brand color earns attention precisely because it is rare.
-- **Semantic tokens** decouple meaning from value: `bg`, `fg`, `muted`, `brand`, `accent`, `destructive`. Components reference meaning, never raw hex.
-- **Accessible contrast:** verify body text ≥ 4.5:1, large text / UI ≥ 3:1. Check with an APCA-aware contrast checker or browser DevTools (the Color Picker shows the live ratio). Do not eyeball it.
-- **Dark mode via token swap,** not per-component overrides — swap the semantic values at the root and every component follows.
-
-```css
-:root { --color-bg: oklch(0.99 0 0); --color-fg: oklch(0.21 0.01 256); }
-@media (prefers-color-scheme: dark) {
-  :root { --color-bg: oklch(0.17 0.01 256); --color-fg: oklch(0.96 0.01 256); }
-}
-```
-
-Gradients and mesh are seasoning. A single subtle gradient on one surface (a CTA, a hero glow) can lift a page; the same gradient on every card flattens it into AI-slop. **Do not** gradient text, borders, and backgrounds simultaneously, and never make a gradient the value prop.
-
-```css
-/* Good — one restrained brand-tinted glow behind the hero, low chroma */
-.hero-glow { background: radial-gradient(60% 50% at 50% 0%, oklch(0.62 0.19 256 / 0.15), transparent); }
-```
-
-## Grid & layout
-
-- **12-column grid** for marketing pages; **container queries** (`@container`, core in Tailwind v4) for components that must adapt to their slot rather than the viewport.
-- **Bento** is the 2026 standard for feature → benefit sections: an asymmetric grid with one focal cell that scans because the eye lands on the largest tile first, then sweeps the supporting cells.
-- **Asymmetry / optical balance:** an off-center focal point with balanced negative space reads more intentional than a rigid symmetric grid.
-- **Max-width + measure:** cap content at ~1024–1200px and body copy at ~65ch.
-
-```html
-<!-- Good — responsive bento: stacks on mobile, focal cell spans 2x2 on desktop -->
-<section aria-label="Features" class="mx-auto grid max-w-5xl grid-cols-1 gap-4 p-6 md:grid-cols-3 md:grid-rows-2">
-  <article class="rounded-card border border-fg/10 bg-bg p-6 md:col-span-2 md:row-span-2">
-    <h3 class="text-2xl font-semibold">Preview every branch</h3>
-    <p class="mt-2 text-pretty text-fg/70">One command spins up an isolated environment.</p>
-  </article>
-  <article class="rounded-card border border-fg/10 bg-bg p-6">
-    <h3 class="font-semibold">No staging queue</h3>
-  </article>
-  <article class="rounded-card border border-fg/10 bg-bg p-6">
-    <h3 class="font-semibold">Auto-teardown</h3>
-  </article>
-</section>
-```
-
-```html
-<!-- Bad — symmetric 3-up of identical cards: nothing to anchor the scan -->
-<section class="grid grid-cols-3 gap-4">
-  <div class="card">A</div><div class="card">B</div><div class="card">C</div>
-</section>
-```
-
-## Depth
-
-Depth is layered transparent shadow + hairline border + concentric radius — not one hard drop shadow.
-
-```css
-/* Layered transparent shadows read as real elevation across any background */
---shadow-card:
-  0 1px 2px oklch(0 0 0 / 0.06),
-  0 8px 24px oklch(0 0 0 / 0.08),
-  0 16px 48px oklch(0 0 0 / 0.06);
-```
-
-**Concentric radius:** `outer = inner + padding`. Worked number — an inner element with `border-radius: 8px` and `16px` of padding wants an outer `border-radius: 24px` so the corners stay parallel. Same-radius nesting (parent and child both `12px`) looks subtly wrong.
-
-**Hairline borders before shadows.** Use a 1px `fg/10` border for separation; add shadow only when a surface genuinely floats (dropdown, popover, modal).
-
-**Tasteful glass — floating surfaces only:**
-
-```html
-<div class="rounded-card border border-white/10 bg-white/5 shadow-card backdrop-blur-xl">
-  <!-- floating surface only — never the whole page -->
-</div>
-```
-
-**Film grain / noise** via an inline SVG `data:` background adds texture without an image request:
-
-```css
-.grain {
-  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='2'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
-}
-```
-
-**When depth becomes slop:** glass on every card, a drop shadow on every element, or multiple competing elevations on one screen. Reserve depth for the few surfaces that genuinely sit above the page.
-
-## Design tokens end-to-end
-
-The canonical Tailwind v4 `@theme` block — colors, type, spacing, radius, shadow, easing — consumed as utilities (`bg-brand-500`, `rounded-card`) AND raw `var(--color-brand-500)`:
-
-```css
-@import "tailwindcss";
-@theme {
-  /* color */
-  --color-bg:          oklch(0.99 0 0);
-  --color-fg:          oklch(0.21 0.01 256);
-  --color-muted:       oklch(0.55 0.01 256);
-  --color-brand-500:   oklch(0.62 0.19 256);
-  --color-brand-600:   oklch(0.55 0.19 256);
-  --color-accent-500:  oklch(0.78 0.13 256);
-  --color-destructive: oklch(0.58 0.22 27);
-  /* type */
-  --font-display: "Geist", ui-sans-serif, system-ui, sans-serif;
-  --font-text:    "Inter", ui-sans-serif, system-ui, sans-serif;
-  --font-mono:    "Geist Mono", ui-monospace, monospace;
-  /* radius + shadow */
-  --radius-card: 0.875rem;
-  --shadow-card: 0 1px 2px oklch(0 0 0 / 0.06), 0 8px 24px oklch(0 0 0 / 0.08);
-  /* easing — same values as references/motion-and-interaction.md; two definitions that drift
-     is worse than one, so change them together */
-  --ease-out:    cubic-bezier(0.23, 1, 0.32, 1);
-  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
-}
-```
-
-Mirror the source-of-truth tokens in a `tokens.json` so other tools (Flutter, icon pipelines, Figma sync) consume the same values:
-
-```json
-{
-  "color": {
-    "bg":    "oklch(0.99 0 0)",
-    "fg":    "oklch(0.21 0.01 256)",
-    "brand": "oklch(0.62 0.19 256)"
-  },
-  "radius": { "card": "0.875rem" }
-}
-```
-
-Make the cross-platform parity concrete — the Flutter app uses the same brand hue. OKLCH is the source of truth; the sRGB hex is an **approximation** (Flutter's `Color` is sRGB-only, so the wider-gamut OKLCH value cannot round-trip exactly). Label it as such so no one treats the hex as canonical:
-
-```dart
-// lib/theme.dart — Flutter mirror of the brand token (Dart 3 / Flutter stable).
-// 0xFF5B54FF is an sRGB APPROXIMATION (≈) of the canonical oklch(0.62 0.19 256);
-// regenerate from the OKLCH source token, never hand-edit this hex.
-final brand = const Color(0xFF5B54FF); // ≈ oklch(0.62 0.19 256)
-final theme = ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: brand));
-```
-
-```html
-<!-- Bad — magic hex, hand-tuned per component, drifts instantly -->
-<button style="background:#5b54ff;border-radius:13px">Buy</button>
-<!-- Good — semantic token utilities, single source of truth -->
-<button class="bg-brand-500 rounded-card px-6 py-3 text-white">Buy</button>
-```
-
-## See Also
-
-- `motion-and-interaction.md` — animate these tokens with intent.
-- `landing-anatomy-and-cro.md` — apply the system across a full page.
-- `../../flutter/SKILL.md` — implement the mirrored tokens in the Flutter app.