AI-Assisted Theming
Use a design.md file as the single natural-language source of truth for your brand. An AI reads it and writes every token file, theme CSS override, and component customization for you.
What is the design.md workflow?
Instead of writing JSON tokens by hand, you describe your brand in plain English in a file called design.md. An AI agent reads that file and produces all the necessary token files, CSS overrides, and theme registrations that the TOUI pipeline expects.
The workflow has three steps:
design.md → AI → tokens/ + themes/ → npm run tokens:build → live UI
- You write
design.md— brand vision, color palette, shape language, spacing personality, component notes - AI reads
design.md+ the TOUI token schema, then writes every file it needs to touch - Pipeline runs — Style Dictionary compiles tokens to CSS, the dev server picks up changes
The AI never touches component source code. It only writes token JSON and CSS override files. All component logic stays intact.
Why a markdown file?
- Human-readable — designers, PMs, and developers can all edit it without knowing JSON syntax
- Version-controlled — diffs are meaningful prose, not cryptic value changes
- AI-optimised — a well-structured markdown file is the ideal input format for language models
- Figma-agnostic — works whether you have a Figma file or not
File locations
| File | Purpose |
|---|---|
design.md | Brand specification — source of truth |
tokens/base/palette.json | Raw color palette (Tier 1) |
tokens/semantic/colors.json | Semantic color roles (Tier 2) |
tokens/semantic/radii.json | Border radius system (Tier 2) |
tokens/semantic/scale.json | Component sizing scale (Tier 2) |
tokens/components/*.json | Per-component overrides (Tier 3) |
tokens/output/themes/*.css | Runtime theme CSS scoped to [data-theme] |
lib/themes.ts | Theme registry consumed by ThemeSwitcher |
Pages in this section
- design.md Reference — Full specification of the design.md format. Every section, field, and accepted value documented with a production example.
- AI Theme Generation — End-to-end walkthrough: write a design.md for a real brand, run the AI prompt, review every generated file, run the build, see the result.
Quick start
Write your design.md
Create design.md at the project root. Use the design.md reference as your template. The minimum viable file needs three sections: Brand, Colors, and Shape.
Run the AI prompt
Open your AI tool of choice (Claude, GPT-4o, Cursor, Copilot Chat) and send:
Read design.md and the TOUI token schema documented in TOKENS.md.
Generate all token files and theme CSS overrides needed to implement this brand.
Follow the exact file paths and JSON structure from TOKENS.md.
Review the output
The AI will produce a list of files. Review each one against the token chain documentation. Pay attention to:
- OKLCH values being perceptually valid (lightness 0–1, chroma 0–0.4)
- Component scale tokens pointing to semantic vars (
var(--component-height-md)) not hard-coded px values - Theme CSS overrides scoped to
[data-theme='your-theme']
Run the build
npm run tokens:buildRegister the theme
Add your theme to lib/themes.ts so ThemeSwitcher shows the new swatch.