Use DESIGN.md

DESIGN.md is the single source of truth for how your site looks: colors, typography, spacing, radius, shadow, motion. It sits at the root of your kit alongside CLAUDE.md and README.md.

Every AI coding tool that opens this project reads it automatically and uses its tokens when writing or editing code. You do not have to remind it on every prompt.

Why it exists

Without a single design source, AI output drifts. One component gets a #0a0a0a background, another gets bg-zinc-900, a third gets bg-[#0d0d0d]. Three weeks later your site looks like three sites stitched together.

DESIGN.md fixes that. It defines tokens with names (--color-foreground, --font-sans, --radius-md) and explains when to use which. The same tokens live in app/styles/app.css under @theme { }. AI reaches for the named token, not a hex code.

It already steers your AI (no extra prompt needed)

Your kit ships with rules files that point every AI tool at DESIGN.md:

Each one contains the same rule:

Never introduce a new font, color palette, or radius scale outside DESIGN.md. If a design change is needed, update DESIGN.md first and sync app/styles/app.css.

So when you ask your AI to "build a pricing card section", it composes existing components and reaches for var(--color-card), var(--color-border), var(--radius-lg) automatically. No "stick to the design system" reminder needed.

Apply DESIGN.md to the kit

Your kit ships with DESIGN.md (light) and DESIGN-DARK.md (dark) as files at the root. The kit is not pre-painted with them; you apply the design system to the site with a normal prompt. Run it on day one to paint the kit in your design, and again any time you change direction.

Reach for this when:

• You want to apply your DESIGN.md to the kit for the first time.
• You swap to a completely different DESIGN.md (a new brand direction).
• You drop in a DESIGN.md from another project or a fresh export.
• The two files drift and you want app.css rebuilt from the markdown.

Paste this into your AI chat:

Read DESIGN.md and DESIGN-DARK.md, then apply the whole design system across the site. Sync all the design tokens into app/styles/app.css and make every page use them. Don't change the content.

That is usually enough. The kit's CLAUDE.md / AGENTS.md / GEMINI.md already tell the AI that DESIGN.md is the source of truth and app/styles/app.css is the sync target, so it knows where to put tokens without spelling each one out.

Hot reload picks up the new tokens. If something looks off after the run (most often because the AI forgot to set font-family: var(--font-display) on headings, or a component referenced a token name that got renamed), reply with one short follow-up — "also apply the display font to all headings" or "fix the broken token reference in Header.tsx" — and it will patch it.

Change the design

When you want to actually change how the site looks, talk to your AI in plain English. Tell it the change and let it update both DESIGN.md and app/styles/app.css in one go.

Change a color

Make the primary color a warmer orange (something around #d97706). Update DESIGN.md and sync the tokens in app.css.

The AI updates the Color Palette section in DESIGN.md, then changes --color-primary (and any related foreground/hover values) in app/styles/app.css. Hot reload picks it up.

Change the font

For typography, use the bundled skill. Just say:

Use Inter for body and Playfair Display for headings.

Your AI runs the Swap the font skill, which adds the Google Fonts link, updates --font-sans and --font-display tokens, and syncs the Typography section in DESIGN.md.

Change spacing or radius

Make the corners a bit softer across the site. Bump --radius-md from 0.5rem to 0.75rem. Update DESIGN.md and app.css.

Same pattern: token name, new value, both files.

Add a token that did not exist

Add a --color-accent-soft token for subtle hover backgrounds, set to a 10% tint of accent. Document it in DESIGN.md and add it to app.css.

The AI extends both files. New components can now use bg-[var(--color-accent-soft)].

When AI drifts off-token

Long sessions or vague prompts can pull AI into hardcoded values. If you spot a hex code or a raw font family in a generated file, paste this back:

Stick to the tokens in DESIGN.md. Replace hardcoded colors and font families with var(--...) references.

That is usually enough. If a token genuinely does not exist for what the AI is trying to express, ask it to add the token first (see "Add a token that did not exist" above).

Where DESIGN.md and app.css meet

You only need to know this if you are curious or debugging:

• DESIGN.md is human-readable. Tables of token names with descriptions and example values.
• app/styles/app.css is what Tailwind v4 actually compiles. The @theme { } block declares the same tokens as CSS custom properties.
• Components reference tokens with bg-[var(--color-foreground)], text-[var(--color-muted)], rounded-[var(--radius-md)], etc.
• Dark mode is class-based: .dark on <html> swaps the values inside @theme { }.

Keep DESIGN.md and app.css in sync. If they diverge, future AI sessions get confused. The skills and rules above are designed to keep them in lockstep, but if you ever edit one by hand, edit the other too.