How to start a project with the toolkit

TL;DR

Pick one stage and two or three tools. Not ten.
Put every colour in tokens before you write a component.
Build one experience, then prove it moves, stops and fits at 390px.

Goal: a first piece of the site that looks designed, not generated, and passes every check.

You need

The brief, and DESIGN.md open beside it.
toolkit/toolkit.json (or the tools page).
A Next.js app with Tailwind 4, and Playwright for the check at the end.

 brief ─► stage ─► tools ─► tokens ─► build ─► verify
 why      look     2 or 3   values    one      frames
                                      piece    + 390px

Steps

1. Read the brief, then write one line

Say what the thing is and who it is for, in one sentence. A coffee roaster, a bank dashboard and a game studio should never share a template. Write the line at the top of your plan.

2. Pick a stage

This site has three looks. Choose the one the brief needs, or one per section:

win95: grey bevels, pixel fonts, ASCII. Nostalgic and playful.
mono: black and white with 3D and shaders. Calm and precise.
colour: loud, full-bleed colour fields. The finale.

Open /tools or ask your agent "what in toolkit.json fits this brief?". A typical site needs one motion library, at most one 3D or shader approach, and one component source. For example: gsap plus lenis for a scroll story, or threejs plus gsap for a 3D hero.

4. Set the tokens

Every colour, font and curve lives in app/global.css, inside Tailwind 4's @theme. Components use the names, never the hex.

@theme {
  /* mono */
  --color-v-bg: #080808;
  --color-v-ink: #f5f5f5;
  --color-v-dim: #8a8a8a;
  /* win95 */
  --color-w-face: #c0c0c0;
  --color-w-shadow: #808080;
  /* colour finale */
  --color-c-1: #ff2e00;
  --color-c-4: #00b3ff;
  /* type and motion */
  --font-pixel: 'Web IBM VGA 8x16', var(--font-mono), monospace;
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
}

Now bg-v-bg, text-c-1 and font-pixel work as utilities.

5. Build one experience

Make one self-contained component that takes active, reducedMotion and an optional progress. Register it in lib/experiences/ so it shows at /lab/<id>. The contract is in Drive any component from progress.

6. Verify it

npx tsx scripts/validate-exp.ts <your-id>

It checks that two frames 1.5 s apart differ, that reduced motion is still, and that 390px has no sideways scroll. Then open the screenshots in .validate/<id>/ and look at them yourself.

Pitfalls

Too many tools. The site starts to look like its dependencies. Three is plenty.
Raw hex in a component. It will drift from the palette. Add a token instead.
Trusting a green check. A black canvas "moves" if one pixel flickers. Read the screenshots.