Design workflow

design-workflow: the mandatory 8-step process

Follow this sequence for every frontend task. Steps are not skipped. Each step produces a specific output before the next begins. The workflow scales: a single component compresses steps 1 through 3 into seconds; a full product gives each step its full weight.

---

Why this matters

Without a workflow, a model jumps to code. It writes components before understanding the product, picks colors before declaring a system, and ships before critiquing. Each skipped step compounds: a wrong understanding produces a wrong hierarchy, a wrong hierarchy produces a wrong layout, and a wrong layout produces wrong code. The workflow prevents compounding error by making each step explicit and sequential.

The 8 steps

Step 1: Understand

Restate five things before any design work: the product, the primary user, the one job this screen does, the emotional register, and the constraints. If any of the five is unclear, ask one focused question. Not five questions; one.

Output: one sentence for each of the five. If you can write them, you understand the task. If you cannot, you do not, and no amount of code will fix that.

Example: "Product: a log analysis tool for backend engineers. User: an on-call engineer debugging at 3am. Job: find the error in 10,000 log lines in under 30 seconds. Register: calm, precise, low-light-tolerant. Constraints: must work on a 13-inch laptop, no custom fonts loaded (offline-first)."

Step 2: Declare the system

Write the design tokens (color, typography, spacing, radius, elevation, motion) in a code block before any component code. Load timeless-principles for the full template. This is not a suggestion; no component code is written before the system exists.

Output: a :root token block with semantic color tokens in OKLCH, a type scale with paired line-heights and tracking, a spacing scale, a radius scale, elevation tokens, and motion tokens. Every value is a token; no raw literals in components.

Step 3: Structure the information

Outline the content hierarchy in plain text. What is the one thing the user must see first? What is second? What can be cut? This step is about information, not layout. Do not think about columns or grids yet; think about what matters and in what order.

Output: a numbered list of content elements in priority order, with a one-phrase reason for each. Elements that cannot earn a reason are cut.

Step 4: Compose the layout

Consider at least two compositions. Reject the symmetrical, centered default unless it is genuinely correct (and state why it is correct, not "it feels balanced"). Think about directional tension, scale variance, and the content's actual structure.

Output: two composition sketches described in text, with the chosen one and a one-sentence reason for the choice. "Asymmetric two-column because the product artifact is the hero, not the headline" is a reason. "Centered because it looks clean" is not.

Step 5: Design as a system

Components are defined relative to each other. A button's radius relates to a card's radius. A heading's weight relates to a body's weight. An accent color used on a button is the same accent used on a focus ring. The system is one set of relationships, not a collection of independent decisions.

Output: a brief statement of the key relationships. "Button radius is --radius-sm, card radius is --radius-md, pill radius is --radius-pill. Heading weight is 600, body weight is 400. Accent appears on primary actions and focus rings only."

Step 6: Implement

Write the code. Semantic HTML first: button, nav, main, article, h1 through h6, ul, dl. Accessible interactions: every interactive element is focusable, operable by keyboard, with a visible focus state that is not the browser default. Typed props with discriminated unions where variants exist. Tokenized styles: no raw hex, no hardcoded spacing. Performance-aware: font subsetting, image sizing with srcset and explicit dimensions, no layout shift, code splitting where warranted.

Load technical-excellence for the full baseline. Output: the code, running, semantic, accessible, tokenized.

Step 7: Self-critique against the Codex

Walk every item in antipattern-codex (sections 2.1 through 2.5) and rewrite anything that matches. Then run the ship-validation 15-item checklist silently and rewrite until every answer is yes.

Output: the revised code, with zero antipatterns and all 15 checklist items passing.

Step 8: Ship

Output the code. No process narration. No "I hope this helps." No "Let me know if you need changes." The deliverable is the code and the design. If the user wants changes, they will ask.

Output: the final code, the token block, and a one-line summary of what was built. Nothing more.

Scale to the task

Task size	Steps	Compression
Single component or small fix	1, 6, 7, 8	Steps 1-3 in seconds; skip 4-5 if the system is already declared
New screen or page	All 8	Full weight to each step
Full product or design system	All 8, iterated	Steps 1-2 get extra weight; steps 3-8 repeat per screen

Common failure modes

Failure	Fix
Jumping to code before understanding	Step 1 first. Write the five sentences.
Writing components before declaring tokens	Step 2 before step 6. No component code before the system.
One composition, the centered default	Step 4 requires two. Reject the default with a reason.
Skipping the critique	Step 7 is the gate. No shipping without the codex scan and checklist.
Narrating the process in the output	Step 8 ships code, not story.

Red flags: stop and return to the workflow

• You are writing code and have not completed step 1.
• You are writing components and have not declared the token system.
• You have one composition and it is the centered default.
• You are about to ship without running the codex scan and validation checklist.
• You are narrating your process instead of outputting the code.

Definition of done for this skill

• Step 1: five sentences (product, user, job, register, constraints).
• Step 2: token block declared before any component code.
• Step 3: content hierarchy in priority order with reasons.
• Step 4: two compositions considered, one chosen with a reason.
• Step 5: key system relationships stated.
• Step 6: code is semantic, accessible, typed, tokenized, performant.
• Step 7: codex scan complete, 15-item checklist all yes.
• Step 8: code shipped with no process narration.

See also

• design-mastery, the orchestrator that chains through this workflow.
• timeless-principles, the token declaration at step 2.
• antipattern-codex, the scan at step 7.
• technical-excellence, the implementation baseline at step 6.
• ship-validation, the 15-item gate at step 7.