Design system
The kit ships pre-themed from a DESIGN.md. Swap in another to re-skin the whole site.
This kit is pre-configured with a DESIGN.md — the design system you picked
when you got the kit. Every color, font, radius, shadow, and spacing value on
every page already comes from it, so the kit looks like a finished brand on the
first run.
What DESIGN.md is
DESIGN.md is a single, human-readable spec for a whole design language:
palette, typography scale, radii, spacing, elevation, and the per-component
rules built from them. It lives at the project root and is mirrored into
app/styles/app.css under @theme { } as CSS variables (design tokens).
Components never hard-code a value — they only reference tokens
(var(--color-foreground), var(--radius-card), text-heading-2). That single
indirection is what makes a re-skin small: change the spec once, every page
follows.
You can generate a DESIGN.md for any brand — yours or one you admire — at
getdesign.md. It extracts the colors, type, and
component rules into the same format this kit reads.
Applying a different DESIGN.md
The kit is built to absorb a new brand by re-authoring tokens, not by editing every component. To re-skin:
- Drop a new
DESIGN.md(and itsDESIGN-DARK.mdfor dark mode) at the project root. - Tell your AI coding agent "apply this DESIGN.md" — it rewrites
app/styles/app.css@theme { }from the spec (colors, fonts, radii, spacing, typography roles). Because the conventions are already documented inCLAUDE.md/AGENTS.md, your agent knows the procedure and can do it automatically. - Hot reload does the rest — the whole site re-themes, no per-page edits.
Why it just works
Every consumer references role tokens, never raw values. Swap the values in
@theme and colors, type sizes, radii, and dark-mode polarity all flow through
to the live pages on their own.
The live reference
The /design-system route is a living styleguide rendered straight from the
real tokens — colors, typography, buttons, forms, spacing, and elevation. Keep
it while you build to see your DESIGN.md applied; delete the route before you
ship if you don't want a public styleguide.
Changing one thing
- Font: say "change the font to Inter" — the
swap-fontskill updates the token, the loader, and the fallback stack. - A color or radius: edit
DESIGN.mdfirst, syncapp.css, hot reload.
shadcn/ui is installed
The kit ships with shadcn/ui wired in. Any component you
add with the CLI (pnpm dlx shadcn@latest add dialog) automatically inherits the
kit's tokens through the bridge in app/styles/app.css, so it lands in your
brand's look with no extra styling. See the shadcn/ui components page for how
the bridge works.
The one rule
Never introduce a value outside the system. If a new color is needed, add it to
DESIGN.md and app.css once, then use the token.