design-sync-kit

Your design and your code stay in one loop, on every project you touch from here on.

This is the companion kit for Claude Design Sync: Ship the Real App from youcanbuildthings.com. The book teaches the live Claude Design and Claude Code round-trip. This repo gives you the reusable files, checks, and scaffold that make that loop repeatable on your own projects.

Educational software, provided as-is, no warranty.

What you get here

The operating system around the round-trip. Not the round-trip itself, which is yours to drive, but everything that makes it repeatable, checkable, and portable to the next project:

• The support files the workflow actually runs on. .design-sync/conventions.md, the config shape with readmeHeader and guidelinesGlob wired, and the six-line gitignore block that separates what you commit from what regenerates.
• A machine-readable conventions template, written to the one test that governs it: could the design agent act on this without guessing?
• Token and contrast gates that catch generic, off-system output before it reaches a client. Two layers, set to fail rather than warn, because the version in the vendor docs exits zero and ships the bad value.
• Drift-recovery runbooks for the morning your teammate's merge makes the canvas stale.
• Backend and deploy reference files for turning a designed surface into a real app with data, auth, and a live URL.
• A scaffold that carries the whole system into your next repo from the first commit.
• Offline checks you can run in the next minute, with no account and no key.

What you do in your Claude workspace

The round-trip is live work, and it happens in your own Claude Design and Claude Code, the tools you already own to read this book. That part the kit can't do for you, and shouldn't:

• Wire the MCP server, then authorize with /design-login.
• Run /design-sync against your repo and watch the design agent build with your real components instead of generic ones.
• Measure your own token cost with /usage and ccusage.
• Drive the reconciliation driver on the day your repo and your canvas disagree.

The repo holds what you bring to that work and what you check afterward. You get real checks, not pretend results. Nothing here simulates a sync, and no file prints a token cost it didn't measure. No test in this repo exercises /design-sync or grades what it builds; that judgment stays in your workspace, where it belongs. The book won't hand you its numbers, so neither will this. Yours are the only ones that mean anything, and the gates below are the part you can trust precisely because you can watch them run.

Run the first proof

One command. No install, no account. It's a small piece of the kit and the fastest way to see the checks are real:

node chapters/11-accessibility-gate/contrast-gate.mjs

ok   light: --text-body on --surface-1 = 17.40
FAIL dark: --text-body on --surface-1 = 3.29 (need 4.5)

Exit 1, and that's the point: the same two token names pass in light mode and fail in dark, because contrast lives in the resolved pair, not the token name, and nothing else in your system can see it. Those numbers are computed on the shipped fixture, not claimed. Point it at your own resolved tokens:

node chapters/11-accessibility-gate/contrast-gate.mjs your-tokens.json

That's one check in isolation. EXAMPLE.md walks a single change (adding a dark mode) through the whole loop, start to finish, and marks which steps run here and which run in your Claude workspace.

The chapter map

Each folder covers one chapter: what it ships, the command, and how to run it on your own project. Some commands run here; the round-trip ones run in your workspace.

Chapter	What you build	Command	Success looks like
04 first round-trip	the connection, wired	/design-login then /design-sync (your workspace)	config.json holds projectId and pkg
05 design system as code	conventions.md + validator	bash chapters/05-design-system-as-code/validate-conventions.sh	prints the missing token, exit 1
06 token gate	two-layer gate	node chapters/06-token-gate/token-gate.mjs fixtures/off-token.tsx	fails on #7c3aed, passes clean
07 measured sync	the routine	/clear → /design-sync → /usage (your session)	your own before and after, measured
08 drift recovery	reconcile runbook	node .ds-sync/resync.mjs (your synced project)	the .d.ts-only change still ships
09 backend	RLS + reference wiring	bash chapters/09-backend/rls-curl-check.sh <url> <key>	unauthenticated read returns []
10 deploy	the server-only guard	bash chapters/10-deploy/server-only-demo/run.sh	a client import fails the build
11 accessibility gate	contrast + target gate	node chapters/11-accessibility-gate/contrast-gate.mjs	dark pair fails at 3.29
12 troubleshooting	the recovery runbook	bash chapters/12-troubleshooting/break-recover-demo.sh	the off switch flips and recovers
13 scaffold	a wired new repo	bash chapters/13-scaffold/scaffold/new-project.sh <dir>	the gates land in a fresh repo

Chapters 01 to 03 are the book's hook and foundation and have no build step, so they have no folder here.

The live surface

None of the offline checks touch the network. The one live surface is rls-curl-check.sh, which reads your own database with placeholders you supply. The Chapter 9 backend files are reference you verify against your own Supabase project rather than a runnable app, and the SQL turns row level security on, which is the safe direction. RLS being off by default is the danger they guard against.

Configuration

The offline tooling needs no configuration. The only values you ever supply are Supabase placeholders (YOUR_PROJECT, YOUR_PUBLISHABLE_KEY) for the curl check, and your own token maps for the contrast gate. No secrets ship here, and .env is gitignored.

Testing

The offline surface is the test. Layer one of the token gate needs Stylelint and the ch10 demo needs the server-only package, so install the two dev dependencies first:

npm install
npm test

The three pure checkers (validator, token gate layer two, contrast gate) run with zero dependencies; the test adds the Stylelint and server-only assertions once those are installed. CI runs the same surface.

Contributing

Fixes and clearer docs are welcome. New features are out of scope on purpose: the kit mirrors the book, so it stays inside the medium and prerequisites the book teaches (Node and Bash and the npm tools it names, no new language or framework).

License

MIT, author youcanbuildthings.com. See LICENSE.

The kit outlives the specific version of Claude Design you learned it on, because none of it depends on a command name staying put. Re-verify the drift-prone facts yourself, the way the book showed you. The skill of checking outlives every specific answer.