Your Site's Design System

When the platform is running in its design.md mode, every site the AI builds for you starts the same way: before it draws a single pixel, it writes down a design system — a plain-English document describing the palette, type, spacing, and component conventions it's about to use, ending in a block of real CSS. That document is resources/design.md, and it lives in your site like any other file. (The platform's default mode skips this document and paints straight against its own built-in premium design bar instead — see Sites without a design.md below for what that means for your site.)

#What design.md is

resources/design.md is a normal file in your site — visible and editable in Code mode, tracked in file history, included in every AI context the same way any other file is. It isn't compiled or rendered anywhere; it's the site's own record of why it looks the way it looks, written so both you and the AI can read it back later.

For a prompt-built site under the design-md mode, the AI authors it on the very first turn — before the layout, before the hero — because everything visual that follows is built to match it. Templates can ship one too; open a template's files and you may find resources/design.md already sitting there, explaining the choices baked into that starter.

#The sections

design.md always follows the same shape:

• Atmosphere — a paragraph on personality and mood, plus a handful of brand adjectives.
• Colors — a table of every color role (background, foreground, primary, and friends), with a name, a hex value, and where it's used.
• Typography — the display and body fonts, the weights in play, and the type scale from hero down to small print.
• Spacing & Radius — how much room sections get, and the corner language for controls, cards, and large surfaces.
• Components — how buttons, cards, forms, and navigation are meant to look and behave.
• Voice — a line or two on how the site's copy should sound.
• Anti-patterns — the generic, AI-flavored choices this particular site should never make.
• Tokens — a fenced CSS block with one @theme rule: the actual custom-property values every other file in your site reads.

The first seven sections are the why. The last one, Tokens, is the how — real CSS, ready to use.

#Tokens → site.css

The Tokens block is not just documentation — it's copied, verbatim, into resources/css/site.css. In design.md it sits inside its own fenced example under the ## Tokens heading:

@theme {
    --color-background: #FAF7F2;
    --color-foreground: #1C1917;
    --color-primary: #B35A3B;
    --font-display: "Recoleta", serif;
    --font-sans: "Söhne", sans-serif;
    --radius-medium: 0.5rem;
    /* … */
}

Once that block lives in site.css, every page, layout, and section in your site can use the matching Tailwind utilities — bg-background, text-foreground, bg-primary, rounded-medium, and so on — and they render in your site's exact values. This is also what makes the section library and shared community designs drop in already wearing your palette: they're written against the same token names, and CSS does the rest — no theme system, no toggle to flip, just a normal stylesheet.

The one rule design.md always follows: the Tokens block defines the platform's fixed set of role names (background, foreground, card, primary, muted, border, ring, the two font tokens, and the radius trio), with whatever values your site's design calls for. The names are what let sections and designs travel between sites; the values are what make your site look like your site and not a template.

#Restyling your site

Because the design language lives in two places that agree with each other, restyling means changing both, together:

1. Open resources/design.md in Code mode and update the relevant section — say, the Colors table with a new primary color.
2. Update the matching value in the Tokens block at the bottom of the same file.
3. Copy that value into the real @theme rule in resources/css/site.css.

Ask the AI to do this instead, and it follows the same rule: a request that changes the design language — a new palette, a different type pairing, a rounder corner radius — updates resources/design.md and the site.css tokens in the same turn, so the document never describes a design your site has moved on from. A request that only changes copy or layout leaves both files alone.

#Sites without a design.md

Not every site has one. A site built under the platform's default mode, built before this document existed, or a legacy template that ships its own hand-written theme.css, keeps working exactly as it always has — nothing is migrated or rewritten automatically. Edit turns on a site with no design.md fall back to reading the existing code directly to infer the current style, the same way they always have. If you want one, just ask the AI to write a resources/design.md for your current design, or start one by hand using the section structure above.

#Where to next

• The Builder — Code mode, where you'll edit design.md and site.css directly
• Sections — the library that reads your site's tokens
• Templates — starters, some of which ship their own design system
• Components — how @props and companion .yml files work alongside your tokens