Design System Workbook

A web resource for building design systems for different projects. It takes the Design System Documentation workbook — principles, foundations, tokens, colour, typography, spacing, iconography, motion, components, patterns, content, accessibility, governance, release, documentation standards, audit — and turns it from a document you read into a tool you work in.

Each project gets its own workbook. You are taught the rules beside the worksheet that applies them, the system is validated against those rules as you type, and the finished result exports as real artefacts: CSS custom properties, a Tailwind v4 theme, W3C design tokens, Markdown documentation, and a print-ready workbook.

What it does

Guidance beside the work. Every one of the seventeen sections carries its full teaching content — rules, reference tables, do-and-don't comparisons — next to the worksheet it governs.

Checks that run. The rules the workbook states as non-negotiable are computed, not just printed:

Check	Rule enforced
Contrast matrix	Every colour pairing, in both themes, against WCAG AA (4.5:1 body, 3:1 large and UI)
Colour-vision simulation	Protanopia, deuteranopia, tritanopia — flags palette entries that collapse together
Tinted neutrals	Neutrals must carry brand hue at chroma 0.005–0.015, never pure gray
Dark theme	Flags colours whose dark value merely repeats the light one
Type floors	12px absolute minimum, 16px body minimum, 1.5 body line-height
Spacing base	Steps that fall off the 4px base unit
Motion	Banned bounce/elastic easing, bare ease, non-composited properties, missing reduced-motion fallbacks
Components	Components marked Stable that have not documented all eight states
Tokens	Component tokens that hardcode a raw value instead of referencing a semantic one

Real outputs. Five export formats plus the printable workbook, all generated from what the project has recorded.

One system per project. Duplicate a finished system as the starting point for the next client rather than beginning from an empty page.

Running it

npm install
npm run dev

Open http://localhost:3000. The app works immediately with no configuration — projects are stored in the browser and can be exported and re-imported as JSON.

Adding Supabase

Accounts, server-side persistence, and share links need Supabase. Create a .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Then apply the schema in supabase/migrations/0001_init.sql — either through the Supabase SQL editor, or with the CLI:

supabase db push

The migration creates profiles, projects, audit_log, and releases, with row-level security so a user reaches only their own projects. Shared projects are readable by anyone holding the link, which is what makes /s/{slug} work for signed-out visitors.

Authentication is email magic-link. Enable the email provider in your Supabase project's auth settings.

Deploying

The app is a standard Next.js App Router project and deploys to Vercel with no extra configuration. Set the two NEXT_PUBLIC_SUPABASE_* variables in the project's environment settings.

The PDF workbook

/projects/{id}/print renders the complete document — cover, contents, all seventeen sections with their guidance, your completed worksheets, glossary, release history, change log, and outstanding checks — then you print it to PDF.

Page geometry is set in CSS (@page { size: letter portrait; margin: 0.75in }), with print-specific colours, break control, and grayscale-safe output. Going through the browser's own print pipeline rather than a server-side renderer keeps font embedding and pagination correct and avoids shipping a headless browser to production.

Worksheets that have not been filled in print as ruled fill-in prompts rather than being hidden, so a partly-complete system is still usable on paper and its gaps stay visible.

How it is put together

src/
  content/            The workbook itself, as data
    types.ts          Guidance blocks, worksheet fields, section shape
    sections/         All 17 sections: guidance, worksheets, checklists
    index.ts          Section order and progress computation
  lib/
    color.ts          OKLCH parsing, WCAG contrast, ramp generation, CVD simulation
    tokens.ts         Worksheet answers → token set; system-wide validation
    export/formats.ts CSS, Tailwind, DTCG JSON, Markdown, project backup
    repository.ts     Supabase or localStorage, behind one interface
    supabase/
  components/         Builder shell, guidance renderer, worksheet editors,
                      colour lab, specimens, print workbook
  app/                Routes
supabase/migrations/  Schema and RLS policies

Sections are expressed as data rather than JSX, so the builder UI, the Markdown export, and the printed workbook all render from one source, and progress can be computed by walking the schema.

Project answers are stored in a single JSONB column rather than a table per worksheet. The workbook's shape is content-defined and will keep changing; normalising it would mean a migration every time a field is added. The integrity that matters — ownership and sharing — is enforced relationally.

Dogfooding

The application follows the rules it teaches. Its neutrals are tinted rather than pure gray, spacing sits on a 4px base, semantic tokens sit above primitives, focus is always visible via :focus-visible, interactive targets meet 44px, dark mode is designed rather than inverted, and prefers-reduced-motion is respected. The exported CSS ships the reduced-motion block for the same reason.