Design: Build It With a Point of View

Production-grade UI with a committed visual direction. If it could have been generated by a default prompt, it is not good enough.

Lock the Direction First

Before writing a single line of code, use AskUserQuestion to get answers to these four questions:

Who uses this, and in what context? A dashboard reviewed by analysts differs from a landing page or an onboarding flow.
What is the aesthetic direction? Name it precisely: dense editorial, raw terminal, layered glassmorphism, ink-on-paper, brutalist grid, warm analog. "Clean and modern" is not a direction.
What is the one thing this leaves in memory? A distinctive typeface, an unexpected color system, a motion that surprises, an asymmetric layout. Pick one and make it obvious.
What are the hard constraints? Framework, bundle size, contrast minimums, keyboard accessibility.

Do not proceed until all four are answered. State the chosen direction in one sentence before writing any code.

Then load references/design-reference.md and check the tech stack conflicts table. Name the single CSS strategy before writing the first component.

Typography

The typeface is the loudest design decision. Pair one display font with one text font. The display font should carry the aesthetic weight of the whole page: something with a clear personality that was chosen, not defaulted to.

Do not use Inter, Roboto, or system-ui as the primary display typeface. They are invisible.

Color

Build a system, not a collection of hex values. Use CSS variables. A single dominant color with one or two sharp accents is almost always stronger than an evenly distributed palette. Avoid colors that do not commit to anything.

Motion and Interaction

One coordinated entrance beats ten scattered hover states. If using React, reach for a motion library. For plain HTML, CSS transitions and @keyframes are enough. Put animation budget where attention is: the first thing the user sees, and the most important interaction state.

Timing: entrance animations 200-400ms, exits 150-250ms. Ease-out for entrances, ease-in for exits. The test: if removing the animation changes nothing about how the page feels to use, the animation is decoration. Remove it.

Layout

The grid is a starting point, not a rule. Controlled asymmetry, overlapping elements, and diagonal emphasis create interfaces that feel designed. Choose a spatial approach: generous breathing room or tight information density. Do not split the difference.

Backgrounds should have atmosphere: mesh gradients, subtle noise, geometric texture, layered depth. Flat white or flat black is rarely the right choice.

If the aesthetic direction conflicts with mobile constraints (e.g., glassmorphism on low-power devices, dense editorial on small screens), name the tradeoff explicitly and decide which wins.

Code Quality

CSS variables for every design token: color, spacing, type scale, radius
No placeholder content without a comment explaining what replaces it
Semantic HTML throughout
Responsive from the start: state whether mobile-first or desktop-first
Contrast ratios that pass WCAG AA at minimum

The implementation complexity must match the visual ambition. Do not write sparse code for a layered design, or over-engineer a minimal one.

Before submitting, reload references/design-reference.md and check the common traps list. Then ask the user to open the result in a browser and confirm it looks right. Code that looks correct in your head but wrong in the browser is not done.

Gotchas

Real failures from prior sessions, in order of frequency:

Used Inter as display font. It was the path of least resistance. Inter is invisible: it communicates nothing about the design direction. Pick something with a personality.
Generated a template, not a design. Three cards with identical shadows, identical padding, identical rounded corners. Swapping content in and out left the layout unchanged. That is a template. Redo it.
Claimed it looked right without opening a browser. Code that renders correctly in your head can still look broken in the browser. Open it, confirm it, then hand off.
Chose glassmorphism and ignored the mobile constraint. backdrop-filter is expensive on low-power devices. Picked the direction without naming the tradeoff. Name conflicts explicitly and decide which wins.
Picked colors that don't commit. A muted blue-gray that "goes with everything" goes with nothing. Dominant color plus one sharp accent. Commit.
Layout jittered on state transitions. Switching between idle/connecting/active shifted the UI because element sizes changed per state. All states must occupy the same layout footprint; use fixed dimensions or min-height.

Handoff

End with:

The aesthetic direction, named and justified in two or three sentences
Any non-obvious choices explained: typeface selection, color decisions, layout logic
Clear instructions for replacing placeholder content with real content

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