This post builds on ideas from the Prerender.io Design System series. If you haven’t read it: Part 1 covers the tooling, Part 2 covers the wave-based build process, and Part 3 covers the collaboration lessons. This post is about what I do now, before any of that starts.
Every project I’ve started with Claude Code has taught me the same thing: the first hour determines the whole day.
When the Prerender.io Design System build went well, it was because I’d written a clear brief, split the work into waves, and given Claude something to orient itself with at the start of every session. When it went badly, it was because I skipped one of those steps and assumed Claude would figure it out.
After the third project, I stopped improvising. I built a template.
What is it?
It’s a folder called plan/ with eight markdown files. No code or some rigid framework but more of a structure. You drop it into any new project repo and fill in the blanks before building anything.
plan/
├── 01_Project_Intro.md
├── 02_Design_Patterns.md
├── 03_Intro_Page.md
├── 04_Wave_Plan.md
├── 05_Audit_Agents.md
├── 06_Pivots_and_Aha_Moments.md
├── 07_UX_Writing.md
└── 08_Session_Protocol.mdHere’s what each file does and why it exists.
01 Project intro – the living brief. What are we building, for whom, what’s in scope, what’s out. If you’re using a design system, it’s noted here. If you have a Figma file, the file key and nodes listing start here. There’s a set of onboarding questions at the bottom: seven specific prompts like “What are the 3–5 key screens?” and “Is there an existing design system?” If the brief has gaps, Claude asks 3 to 5 of those before doing anything else. The idea is that a 15-minute conversation upfront replaces hours of mid-build rework and token waste.
02 Design patterns – the rules of engagement. Design token structure, component import hierarchy, responsive breakpoints, styling approach, accessibility baseline. This includes a concrete rules table:
| Rule | What it prevents |
|---|---|
| Never use raw hex for brand tokens | Claude picking a slightly different blue every time |
| Never invent new components | Check DS / framework catalogue first, compose from existing |
| Tables always get horizontal scroll | Layout overflow on narrow viewports |
| WCAG 2.2 AA is mandatory | Accessibility treated as an afterthought |
The point isn’t to over-specify, it’s to prevent Claude from inventing a new pattern every time it builds a component. And it’s not an easy job to prevent inconsistencies with AI tooling. It takes shortcuts very often if not supervised.
03 Intro page – optional. For prototypes, it generates a Table of Contents page that lists every screen state with a direct link. Useful for design reviews and QA. Production apps skip this.
04 Wave plan – the build schedule. Every screen gets a wave, every wave has tasks with Figma node references (if they exist), every task has a status. This is the file Claude reads first when resuming a session. It’s also where the state matrix lives: a table that forces you to think through every state a page can be in before building it:
| Page | State | Figma node | Notes |
|---|---|---|---|
| Dashboard | empty | 12:345 | First-time / no data |
| Dashboard | loading | — | Skeleton, no Figma frame needed |
| Dashboard | loaded | 12:346 | Happy path |
| Dashboard | error | 12:347 | Full failure, show retry |
Every row becomes a task. If a state has no Figma frame, you note it explicitly, it still needs handling. This is the thing that prevents the “we only built the happy path” problem.
05 Audit agents – three pairs of auditor/builder agents that run after each wave. One checks general UX (visual hierarchy, layout fidelity, state coverage). One checks WCAG 2.2 AA compliance. One checks UX writing (microcopy, empty states, error messages). Each pair runs in a loop:
Auditor → reviews against checklist → produces findings
Builder → fixes each finding → marks fixed
Auditor → re-reviews → signs off or raises new findings
Loop continues until: "APPROVED"The UX auditor checklist alone covers visual hierarchy, design system consistency (however I think my improved template will have a separate auditor-type agent for this), layout structure, and state coverage for every data-driven page. The WCAG auditor has its own checklist: colour contrast ratios, keyboard navigation, semantic HTML, touch targets, the full AA spec. Running them as loops instead of single passes is what makes the difference. The first pass always finds things. The second pass finds the things the fixes introduced.
06 Pivots and aha moments – a log of every significant decision that deviates from the original plan. Scope changes, pattern changes, Figma discoveries, technology swaps. This file exists because I kept losing track of why things were built a certain way when I came back to them two weeks later.
07 UX writing – rules for all UI copy. Voice and tone, microcopy standards, empty state patterns, error message structure, capitalisation rules. It specifies things like: button labels start with a verb and use sentence case, error messages state what happened and what the user can do next, no “Oops” or “Whoops” on any screen. Sounds like overkill until you notice Claude writing technial copy or “Oops! Something went wrong!” without it.
08 Session protocol – what to do at the start, during, and end of every Claude session. The start ritual looks like this:
- Read the project intro – confirm project type, whether a DS is in use
- Read the wave plan – confirm which wave is active and what the next action is
- Read the pivots log – check for recent decisions that affect what you’re about to build
- Confirm the git branch is up to date
- State out loud: “I am working on Wave N, Task N.N”
There’s also a “resuming after a context interruption” section, because sessions sometimes end mid-work (especially when you hit the token limit). Read the wave plan’s “Where We Left Off” section, check the last few pivots, run git log, verify the last built screen on the dev server, continue from the next unchecked task. This is the file that makes multi-session projects survivable.
Two paths: with Figma and without
The template works either way. The difference is where the design truth comes from.
With Figma, you fill in the file key, collect all the node IDs upfront, and point Claude at individual nodes using get_design_context during the build. There’s a practical constraint here that’s worth knowing: the Figma MCP server can’t navigate a file’s hierarchy from the root. You can’t say “go find the dashboard screen.” You need the node ID before Claude can look at anything. Collecting those upfront, before Wave 0, saves a lot of mid-session friction. Also chunking down the complex screens into separate nodes is worth thinking of. Claude gets lost in sophisticated UI or long pages.
Without Figma, you define your tokens locally in design-tokens.ts, choose a UI framework (Ant Design, Material UI or whatever fits), and Claude builds from the brief and the design patterns file. The wave plan and audit agents work exactly the same way. You just skip the Figma node references. I’ve used this path twice now and the audit agents actually catch more issues, not fewer, there’s no Figma to visually check against, so the checklists do more of the heavy lifting. Often I reverse-engineer the design system from the ready-made prototype, but that’s a subject for another post. Stay tuned!
Both paths work the same way at the component level. This is the default pattern:
type PageState = 'empty' | 'loaded' | 'error'
export function DashboardPage({ state }: { state: PageState }) {
if (state === 'empty') return <EmptyState cta="Connect your data" />
if (state === 'error') return <ErrorBanner action="Retry" />
return <DashboardContent />
}One component per page, with a state prop that switches between empty, loaded, error, and whatever else the page needs. Not separate routes per Figma frame: one component, conditionally rendered. Figma shows each state as its own frame, which makes it tempting to build them as separate pages. Don’t.
What surprised me
I expected the wave plan to be the most useful file. It is important, but the files that changed the most about how projects actually go were the session protocol and the pivots log.
The session protocol sounds bureaucratic. Read these files. Check this state. Confirm the branch. It reads like something written by someone who doesn’t trust their own future self. Which is accurate. In practice, it’s the difference between spending ten minutes getting oriented and spending forty minutes rebuilding context that was already there yesterday. Claude has no memory between sessions. The protocol is the memory.
The pivots log surprised me because it turned out to be less about recording history and more about preventing repeated mistakes. When you log why you changed a pattern on Tuesday, you don’t have to re-discover the reason on Thursday. It also surfaces when the same kind of pivot keeps happening, which usually means the brief was wrong, not the implementation.
The audit agents were the least surprising but the most consistently useful. Running them as loops: auditor finds issues, builder fixes, auditor re-checks; produces better results than a single review pass. The UX writing auditor alone catches enough copy problems per wave to justify the entire setup.
Where to find it
The template is a standalone folder you can drop into any project. It’s framework-agnostic in principle: the examples use React and Ant Design because that’s what I use, but the structure works with anything.
What I’d change for your own use: adjust the breakpoints in the design patterns file to match your grid, update the tech stack references in the project intro, and decide whether you need all three audit pairs or just one or two. The session protocol and pivots log I’d keep as-is. Those are the ones that earn their keep regardless of stack.
The template didn’t come from theory. Every file in it exists because something went wrong without it, a missing brief that caused hours of rework, a state that wasn’t handled because nobody listed it, a session that started from scratch because there was no handoff document. It’s not elegant. It’s just the accumulated scar tissue from building things with an AI that’s very capable and has no memory.
If that sounds useful, take it. If it doesn’t fit, take the parts that do. The only file I’d insist on is the wave plan. Everything else is negotiable.
