Design

What "finished" means for an interface, and the documents that keep it true. The bar is not taste — every item below is checkable.

This is the generic craft bar. A project with its own design system overrides the tokens; it does not override the states, the craft checks, or the design-doc rule.

The five questions before any UI code

Answer these in the reply, one line each. If any answer is "whatever looks fine", that is the decision to make first.

1. Who is looking, and at what size? Phone at arm's length, laptop at a desk, a TV across a room. It changes the type scale, not just the breakpoints.
2. What is the one thing on this screen? If there are two, one is the page and one is a card.
3. What is the page's job in one verb? Browse, compare, confirm, edit, monitor. The verb picks the layout.
4. What is the empty, loading, error, and done state? Four states per surface, not one.
5. What existing component or token does this reuse? Copy the nearest existing surface. A new shape must earn itself.

The craft bar

Each row is verifiable by looking. Full explanations and the anti-pattern behind each: CRAFT-BAR.md.

States are the work

Most unfinished UI is missing states, not missing polish. For every surface that fetches or mutates:

A loading state that changes the layout when it resolves is a bug, not a rough edge.

The design doc rule

A component is not done until its DESIGN.md matches. The doc is not a write-up after the fact; it is the contract the next change checks against.

Per component or surface, DESIGN.md holds:

---
tokens: [surface-1, text-primary, accent, radius-md]
states: [empty, loading, error, success]
---

## Purpose
One sentence: what this is for and where it appears.

## Anatomy
The parts, and which are optional.

## Contract
Props, variants, and what each variant is for.

## Tokens consumed
The exact names, from the token layer.

## Not for
The adjacent case this should not be used for.

Plus one row in the component index (map) so the doc is findable. A component whose tokens changed without its doc changing is a review finding, not a nit.

When the project has no design system yet: create docs/design-system.md with the tokens, and put the first DESIGN.md beside the first real component. Do not write thirty design docs for zero components.

Reviewing UI

Two axes, reported side by side:

• Craft — the table above, checked by looking at a rendered screen.
• Contract — the design doc and tokens match the code; states exist; the change did not invent a new pattern where one existed.

A review that never rendered the UI is a code review, and should say so.

Anti-patterns at a glance

• Accent colour used for more than one purpose on a screen.
• A card inside a card inside a card.
• Icons without labels where the icon is not universal.
• A toast as the only confirmation of a destructive action.
• Text contrast below 4.5:1 for body copy.
• A modal for something that could be inline.
• Three different border radii in one view.
• Motion on hover for every element, so nothing reads as interactive.

Related

• The full reasoning per area → CRAFT-BAR.md
• Design docs in a monorepo → skill project-scaffold → targets/monorepo.md
• Proving a UI change → skill verify-change § UI changes