Design: Build It With a Point of View

Prefix your first line with 🥷 inline, not as its own paragraph.

If it could have been generated by a default prompt, it is not good enough.

Lock the Direction First

Before writing any code, ask the user directly, using the environment's native question or approval mechanism if it has one:

1. Who uses this, and in what context? Analyst dashboard differs from landing page or onboarding flow. See "App shell exception" below if the answer is a sidebar + main workspace layout.
2. What is the aesthetic direction? Name it precisely: dense editorial, raw terminal, ink-on-paper, brutalist grid, warm analog. "Clean and modern" is not a direction. If the user names a reference site or product ("feels like Linear / Claude.ai / Vercel"), do not accept it as a direction -- extract 3 concrete properties from it: button radius philosophy, surface depth treatment (shadow vs background step vs border), and accent color family. Name those instead.
3. What is the one thing this leaves in memory? A typeface, color system, unexpected motion, asymmetric layout. Pick one and make it obvious.
4. What are the hard constraints? Framework, bundle size, contrast minimums, keyboard accessibility.
5. What is the signature micro-interaction? Scale on press, staggered reveal, or contextual icon animation. Pick one and know exactly how it's implemented.

Do not proceed until all five are answered.

App shell exception (sidebar + main workspace)

When the answer to question 1 is an app shell (Slack, Linear, Notion class):

• Decorative backgrounds default to off
• Surface hierarchy uses background-color steps and shadow only
• All interactive elements get active:scale-95
• Button radius is consistent within each component type (pick one: pill, square, or one fixed value -- do not mix)
• Commit to a named radius scale before the first component (see Border radius system in references/design-reference.md)

State the chosen direction in one sentence, then load references/design-reference.md and check the tech stack conflicts table. Name the single CSS strategy before writing the first component.

Summarize the direction as three lines before writing any code:

• Visual thesis: mood, material, and energy in one sentence (e.g. "warm brutalist editorial with high-contrast ink type and rough paper texture")
• Content plan: hero -> support -> detail -> final CTA, one line each. For app/dashboard surfaces: skip the marketing structure, default to utility mode (orient, show status, enable action), no hero unless explicitly requested.
• Interaction thesis: 2-3 specific motion ideas that change how the page feels (e.g. "hero text slides in on load, section headers pin while content scrolls beneath, CTA pulses on hover")

For production or multi-page UIs, expand the thesis into the 9-section DESIGN.md scaffold in references/design-reference.md (theme, palette, typography, components, layout, depth, do/don't, responsive, prompt guide). For a single component, the three lines are sufficient.

Non-Negotiable Constraints

references/design-reference.md is already loaded during direction lock. It owns the full rules: typography, OKLCH color, motion timings, layout defaults, CSS-pattern bans, accessibility baseline, and complexity matching. Apply them. Do not restate them here.

Mid-Build Checkpoint

After every third component or one complete page section (whichever comes first), stop and check:

1. Re-read the visual thesis (mood, material, energy) stated during direction lock.
2. Ask: does what is on screen right now match that thesis, or has it drifted toward a generic default?
3. If drifted: identify the specific element that broke first (typeface, color choice, card treatment, spacing) and fix it before continuing.

Do not wait until handoff to run the AI Slop Test. Catching drift early costs one component; catching it at handoff costs the entire build.

Gotchas

Handoff

Run these litmus checks before writing the handoff summary:

• Is the brand or product unmistakable in the first screen?
• Is there one strong visual anchor (real imagery, not a decorative gradient)?
• Can the page be understood by scanning headlines only?
• Does each section have one job?
• Are cards actually necessary, or just default styling?
• Does motion improve hierarchy or atmosphere, or is it ornamental?
• Would the design still feel premium if all decorative shadows were removed?
• AI Slop Test: would a stranger glancing at the first screen say "AI made this"? If yes, the committed direction was not committed enough. Fix the typography, color, or layout until the answer flips.

If any check fails, fix it first. Then revisit the common traps list from references/design-reference.md (already loaded during direction lock; do not re-read the file). Then ask the user to open the result in a browser and confirm it looks right at full width. Also check at 375px width: resize the browser or use DevTools device emulation. If the layout breaks, content overflows, or text is unreadable at mobile width, fix it before handing off. Do not hand off until both checks pass.

End with:

• Aesthetic direction, named and justified in 2-3 sentences
• Non-obvious choices explained: typeface, color decisions, layout logic
• Instructions for replacing placeholder content with real content

After handoff, stop. Do not iterate unless the user requests changes.