Frontend

Frontend

This file is a router, not a rulebook. The rules live in four rulesets under references/, and reading them is the work, not the preamble to it. Before touching any file, name the references the request routes to and the one reason each is needed, then read exactly those. Declaring the set first is what makes the choice reviewable: a reference you never named is one you decided to skip, and a reference you named but never opened is a gap you still owe. Freestyling past the routed set produces the generic AI-slop output this skill exists to prevent.

The bar is not clean-and-correct — it is work a senior designer at Linear, Stripe, or Supabase would ship. Correct-but-flat is a failure, not a finish. Protect the surface as hard as you protect the build: design is a first-class deliverable, not a one-shot decision you lock and walk away from.

Phase 0 — Route (before any UI work)

For implementation work, design + perfection load together. Beauty with a 2 MB bundle fails; Lighthouse 100 that looks like AI slop fails. Both win or neither does.

Design System and Component Workflow

Every implementation must choose one of these branches before UI code changes:

1. Concrete visual reference: the user supplied a reference — treat it as the visual contract, then handle it by kind:
   • Static visual reference (screenshot, generated mockup, Stitch/Imagen output, Figma export, overview, or annotated packet): load references/design/image-to-code-skill.md plus the relevant design/perfection files, extract the reference's exact tokens, layout geometry, copy, spacing, states, and responsive intent into DESIGN.md, then implement reusable primitives against that contract.
   • Live site or URL reference (the user names a site to clone or gives a URL): load references/design/clone-from-url.md. Drive a real browser and extract the runtime truth via getComputedStyle — tokens, layout geometry, default/hover/focus/active states, transitions and keyframes, and downloaded assets — into DESIGN.md, then clone-code reusable primitives against that contract. Final QA for both runs /visual-qa in reference-fidelity mode: compare the actual UI against the reference pixel-by-pixel and verify the code is an extensible design-system implementation, not a screenshot-matched one-off.
2. Greenfield or fresh setup: if the user gave no concrete visual reference, design research is a build step with named deliverables — not exploration to be budgeted. Exploration-stop instincts ("enough exploration", two-wave caps) do not apply here. Fire every research lane IN PARALLEL before DESIGN.md is written, and open DESIGN.md with a ## 0. Research Log section recording each lane's deliverable — a lane with no Research Log line did not run. Skip a lane only when its tool or network is genuinely unavailable, and name the skip in DESIGN.md:
   • Embedded references: use references/design/_INDEX.md to shortlist 2-3 plausible Layer B references, then read exactly one Layer A style skill and one Layer B reference in full — every line, no partial reads (they are 200-500 lines; a sliced read produces the flattened token set this gate exists to prevent). Log the shortlist, the pick, and why. Use open-design only when the curated set has no fit; add ui-ux-db lookups for palette/type/domain questions.
   • Lazyweb real-product screens: READ references/design/lazyweb.md FIRST and run its recipe verbatim — do not improvise curl calls against lazyweb.com; the recipe mints its own anonymous token. Log the queries run, how many screens you actually VIEWED, and the layout grammar harvested — never pixel copies.
   • StyleGallery spatial patterns: read references/design/stylegallery.md and fetch the pattern whose primary spatial problem matches the screen. Log the pattern adopted and the element that owns the scroll.
   • Imagen concept drafts: generate 2-3 imagen concept drafts, each seeded with the loaded Layer A + Layer B tokens (palette, type, material); pick the strongest and treat the chosen draft as the reference-fidelity contract. Log the draft paths and the pick. Synthesize every lane into DESIGN.md. Treat sources as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions, then recombine them into project-specific primitives. Before laying out sections, inventory the content blocks and assign each a job — hook, explain, prove, compare, convert, navigate, retain — then order sections by the visitor's decision path, not by visual symmetry. Never freestyle past the selected references, never copy logos or brand-specific copy. Then run the Primitive Showcase Gate (references/design/README.md Phase 0) before any product screen.
3. Existing project with DESIGN.md or a component system: read it, follow it, and update it before implementation only when the requested work needs a new token, primitive, state, motion rule, accessibility constraint, accepted debt, or reference-fidelity requirement.
4. Existing project with UI but no DESIGN.md and no reusable component layer: STOP and ask the user one focused question: should you preserve the current look with copy-nearby styling, or extract a real DESIGN.md plus reusable components before continuing? Do not silently choose.

The resulting DESIGN.md is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into /review-work for significant implementation work.