| name | design-ui |
| description | Design a UI surface before it is implemented, the four-layer procedure (intent, information architecture, interaction, presentation) chosen from tokens, plus the full set of states. Invoked before write-ui when a new or changed UI surface needs a design. |
| user-invocable | false |
design-ui
Design a UI surface before it is built. This recipe produces a design
spec: the surface's intent, information architecture, interactions,
and presentation chosen from tokens. It precedes write-ui, which
implements the spec. Design first, then implement; do not decide the
design inside the implementation.
The design spec is the deliverable. It can be a short doc, a section in
a feature's notes, or an annotated view-spec sketch. It is data and
prose, never running code.
Read first:
- the project's design-language reference: principles, the layered
model, the token system, the component template, state design, the
design-review checklist.
- the project's view-spec reference: the widget vocabulary the design
composes.
- the project's token catalog: the tokens the presentation step chooses
from.
- write-ui (sibling): the implementation recipe this design precedes.
- check-design: the review dimension the design is held to.
The procedure
Work the four layers in order. Never start with visuals.
- Intent. State the one thing the user is trying to accomplish on
this surface, in one sentence. If you cannot state it, the surface is
not designed yet.
- Information architecture. List the information that serves the
intent. Mark what is primary, what is secondary, what can be hidden
behind progressive disclosure, and what belongs together. Place the
surface in the nesting the view-spec reference defines (section,
view, panel).
- Interaction. For each thing the user does, name the intent, the
action, and the binding: the action keyword and the click or key that
triggers it. Cover selection, navigation, and editing.
- Presentation. Only now choose the visuals, all from tokens:
- The widgets from the vocabulary; reach for an existing type before
proposing a new one.
- The depth layer for each widget.
- The motion for appearance, change, and exit; the camera move where
the surface is spatial.
- The spacing, type, and color tokens; never a raw value.
- The density mode or modes the surface supports.
Design every state
The design is not done until every state is designed. For this surface,
specify:
- Empty: no data yet, or a filter with no match. What guides the
next step?
- Loading: a load or transform in progress. What shows progress, and
what stays usable?
- Success: the populated, interactive state.
- Error: a load failed, a resource is missing. What names the cause?
- Permission denied: a resource the OS will not read. What names the
fix?
Do not invent a state the product cannot reach.
Check the design
Before handing off, run the design-review checklist: the user goal, the
simplest version, first-time understanding, expert speed, motion and
depth that communicate, the states, accessibility (focus visible,
contrast, reduced-motion), the frame budget, and consistency with
existing patterns and tokens.
Always
- Tokens, not raw values. Every spacing, size, color, duration, and
depth in the spec names a token from the catalog. A raw value in a
design spec becomes a raw value in the view-spec.
- Reuse the vocabulary. A new widget type is a design commitment;
propose one only when no existing type parameterized would serve, and
when it is a real choice between alternatives, record it with
record-decision before it spreads.
- Familiar where it counts, novel where it pays. Navigation,
selection, editing, and confirmation stay conventional; spend the
novelty budget on motion, depth, and presentation.
- Hand off to write-ui. The design spec is the contract the
implementation builds against; the implementer does not re-decide the
design.
Boundaries
Owns: the design spec (intent, information architecture, interaction,
presentation, states) for one UI surface. Cites: the project's
design-language reference, view-spec reference, and token catalog.
Siblings: write-ui owns the implementation of the spec; check-design
owns the review dimension; check-clarity owns the prose of the spec
itself; write-prose owns the prose standard. Produces data and prose,
never running code; the design decision that belongs in the architecture
goes to record-decision, not into this spec.
Return
One line: the surface designed, the spec's location, and whether every
state is covered.
