The /page-design pipeline
Before a page is coded, it gets designed on paper: a draft, then three critics reading it at once, one for craft, one for how it feels to use, one for whether it earns the action it exists for. A referee filters what they find, and the result is locked for the code plan to build from.
One critique cycle, on purpose, no endless polishing loops. If that feels too thin for design, or about right, tell us. Reply on LinkedIn.
How to read this map
Pick a stage to walk, or start at the top
The walkthrough, as text
Every stage of the interactive walkthrough above, as plain readable text. Each stage has its own link.
Stage 0Find the page in the specConfirm it, flag the risk
Pre-flight
First the pipeline finds the locked Module Spec and confirms the page you named is actually in it. It also notes early whether this page touches anything sensitive, so the security lens gets sharpened later if it does.
Locate the locked spec, confirm the page is in its plan, and flag any risk surface before design starts.
What happens
The pipeline reads the most recent locked Module Spec and checks that the page from your request is on its page list. If it isn't, it stops and asks rather than designing something the spec never planned.
It also runs a quick gate: is this genuinely page-sized work, and does it touch a risk surface like logins, payments, or money math? A yes on risk sharpens the usability and outcome critics toward those concerns.
Who acts
- Read, tool: Reads the locked Module Spec to confirm the page.
The rules
- The page must be in the spec. Design only starts for a page the locked spec actually planned; anything else pauses for you.
In: A page name from the Module Spec. Out: A confirmed page and a note of any risk surface.
Stage 1Draft the designHierarchy, states, flow, outcome
Draft
The pipeline drafts the page's design in plain terms: what's most important on it, which existing pieces it reuses, every state it can be in, the path the user takes through it, and the one action it's meant to earn. Then it stops for your sign-off.
A design draft: visual hierarchy, reused components, every state, the user flow, the outcome it earns, and its mobile shape.
What happens
The draft covers the visual hierarchy, which existing components are reused versus what is genuinely new, and every state the page can be in: empty, loading, error, and the edge cases like no data, too much data, and a slow network.
It also names the user flow, the outcome the page exists to earn, and the mobile shape at a narrow screen with proper touch targets. This is the first hard pause; you approve it, redirect it, or defer the page.
Who acts
- AskUserQuestion, command: The approval gate after the draft, before the critics.
The rules
- Reuse before new. The draft reaches for existing components first; anything new has to justify itself.
- Every state, not just the happy one. Empty, loading, error, and the edge cases are designed up front, not discovered in code.
In: The confirmed page and its spec context. Out: A design draft ready for critique.
Stage 2Three critics at onceCraft, usability, outcome
Critique
The draft goes to three critics at the same time, none seeing the others' notes. One watches the craft and brand. One hunts usability friction and accessibility. One asks whether the page actually earns the action it's built for.
Three parallel critics: a craft-and-brand lens, a usability-and-accessibility lens, and an outcome lens. Blind to each other.
What happens
The craft critic checks brand fidelity and refuses generic AI-default design. The usability critic enumerates friction explicitly: extra clicks, ambiguous states, lost form data on an error, tab-order mismatches, format-rigid inputs. The outcome critic asks the blunt question, does this page earn its intended action?
All three run in parallel and blind, so none anchors on another. Their findings are collected into one block for the referee.
Who acts
- craft critic, agent: Brand fidelity; refuses generic AI-default design.
- usability critic, agent: State coverage, mobile, accessibility, and named friction.
- outcome critic, agent: Whether the page earns its intended action.
The rules
- Blind and parallel. Each critic reads the draft without the others' notes, so the overlap that survives is a real signal.
- Friction is named, not hand-waved. The usability critic lists specific friction, so it can be fixed rather than argued about.
In: The design draft. Out: Three sets of findings, ready for the referee.
Stage 3Referee, then your callKeep, ditch, or modify
Adjudicate
The same referee from the change-heavy pipeline marks each finding keep, ditch, or modify against the project's standards, cutting the noise. Then it stops and asks which findings you actually want folded into the design.
The Adjudicator rules on each finding, then a checkpoint asks which to absorb into the revised design.
What happens
The referee reads the three critics' findings and marks each one keep, ditch, or modify against the project's real standards, so generic best-practice noise does not survive. Its own field guide walks how it judges.
Then your checkpoint: absorb everything it kept, keep the design as-is, or pick specific findings. You decide what the revision includes.
Who acts
- the Adjudicator, agent: Marks each finding KEEP, DITCH, or MODIFY. Has its own guide.
- AskUserQuestion, command: The checkpoint: which findings to absorb.
The rules
- The referee cuts the noise. Findings are judged against the project's standards, not generic best practice, before they reach you.
- Your call on what lands. You choose which surviving findings the revision absorbs.
In: The three critics' findings. Out: A filtered set of findings to fold in.
Stage 4Revise and lockFreeze the design
Lock
The pipeline folds in the findings you chose and writes the design to a locked doc on disk, tied to its parent spec. From here, the code plan reads this file; the design is settled.
Apply the absorbed findings, then write a locked design doc that /page-code builds against.
What happens
The revised design is written to a dated design doc marked locked, carrying the module, the page, and a pointer back to the parent spec.
That lock is the hand-off. The /page-code pipeline reads this design and plans the code from it; the design is not quietly changed downstream.
Who acts
- Write, tool: Writes the locked design doc to disk.
The rules
- Locked means settled. The design doc is the source of truth for the code plan; a later change means a fresh design run.
In: The filtered findings and the draft. Out: A locked design doc, ready for /page-code.
Stage ✓A page designed before it's codedReady for the code plan
Design locked
What you end with is a settled design: how the page looks, every state it holds, the flow through it, and the action it earns, all filtered through three lenses and a referee. The next step plans the code.
A locked design is the hand-off point: /page-code reads it and plans the code before anything is built.
What happens
No code was written here. The pipeline produced one thing: a design solid and specific enough that the code plan never has to guess what the page is.
From here, /page-code turns the design into a locked code plan, and /page-implement builds it. Both have their own field guides.
The rules
- Design, then code. Nothing is coded until the design is locked; the design is what the code plan reads first.
In: An approved, filtered design. Out: A locked design, ready for /page-code.