Drawer 5: Building it

Open it when: you're choosing a component library, writing the DESIGN.md, or setting up a page that runs with no build step.

What it is

One markdown file that holds a design system. Tokens (named values for colour, type, corners, spacing) sit at the top in YAML. Written rules sit below. [awesome-design-md]
awesome-design-md credits the idea to Google Stitch. It needs no Figma export, schema or special tools. [awesome-design-md]
AGENTS.md tells an agent how to build. DESIGN.md tells it how the result should look. [awesome-design-md]
Our build: write the look down in one DESIGN.md. Colours, type, spacing and components first, then layout, motion, voice, and what to do and not do. Every later change reads it, so the look doesn't drift. [our build]

What goes in it

impeccable's document command writes it in Google's format: tokens up top, then up to eight sections in a fixed order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. [impeccable]
The 74 awesome-design-md files with tokens up top use those same eight sections. Many add Responsive Behavior (61 files), an Iteration Guide (50) and Known Gaps (43). [awesome-design-md]
Leave out a section that doesn't apply. Don't invent rules to fill it. [impeccable]
The tokens are the rule. The written part explains how to apply them. [impeccable]
Build each component from token names in braces. Never type a raw hex colour into a component. [awesome-design-md]
Give colours descriptive names ("Deep Muted Teal-Navy", not "blue-800"). [impeccable]
Change one component at a time. Add variants as separate entries. [awesome-design-md]
34 awesome-design-md files say to run npx @google/design.md lint DESIGN.md after edits. Nobody here has run it. [awesome-design-md]

When to write it: the sources clash

Our build: write DESIGN.md first, so every later change reads it. A skill for a new site should make DESIGN.md the first thing it writes. [our build]
impeccable: for a new look, write DESIGN.md at the finish, from what was built. A rulebook written before the build gets defended against reality. [impeccable]
impeccable also says a missing DESIGN.md doesn't make a project new. A look already in the code counts. [impeccable]
Never overwrite an existing DESIGN.md without asking. Offer refresh, overwrite or merge. [impeccable]

Use a component for anything the library covers before reaching for raw HTML. [Astryx]
Name tokens by purpose, not by value or looks. [Astryx; impeccable]
Read the component docs before using a component. Don't invent props. [Astryx]
Astryx's rules for agents: start every page from a template, no raw divs, no inline style={{}}, tokens instead of made-up values. [Astryx]
Restyle without forking: pass className with Tailwind, CSS modules or plain CSS. swizzle copies a component's source into your project to own. [Astryx]
impeccable: in a committed look, rebuild nav, buttons, inputs and links in that look. A stock component left in is a lapse. [impeccable]
Our build: Astryx reads clean and systematic, so it needs a lot of theming to feel warm. [our build]
Pull something into the shared system only when it's used three or more times for the same purpose. Two buttons that look alike but do different jobs stay separate. Early abstraction is worse than repetition. [impeccable]
Match the code to the look. A maximal design needs elaborate code and effects. A minimal one needs restraint and precise spacing and type. [frontend-design]

React 19 has no single-file build any more, so the old unpkg link fails. [our build; Astryx]
For React without a build step, load it from esm.sh with an import map, and write the markup with htm. [our build]
Astryx gives the same route: an import map and esm.sh. npx @astryxdesign/cli template --cdn writes a no-build HTML page pinned to your installed version. [Astryx]
On an Astryx no-build page, set data-astryx-theme on <html>, or the theme won't apply. Add the font link yourself. [Astryx]
With a bundler, Astryx needs no build plugin: three CSS imports (reset.css, then astryx.css, then the theme's theme.css, in that order) plus a theme wrapper. Recipes exist for Next.js and Vite. [Astryx]
For plain HTML, keep motion to CSS. [frontend-design]
Astryx's layered pop-ups need recent browsers: CSS anchor positioning (Baseline 2026), the Popover API and light-dark(). In older supported browsers, pop-ups open but aren't positioned. [Astryx]

Look at the real rendered page before editing. Check it at the sizes it ships at. Fix everything one look shows before looking again. [impeccable]
If more than one agent takes screenshots at once, give each its own browser. Sharing one, they take each other's pages. Each one checks the address before it takes a shot. [our build]
Every requirement in the brief must be on the page and findable within seconds. [impeccable]
Never copy the written direction (the brief) into code or anything sent to the browser. [impeccable]

Tool: DESIGN.md, the look written down. Pick it once the direction is chosen, so every later change reads the same rules.
Tool: borrow from a brand (awesome-design-md). Pick it when you want a finished DESIGN.md to start from or learn from.
Tool: Astryx for agents (CLI and MCP server). Pick it when an agent builds on Astryx and must look things up instead of guessing.
Tool: Astryx theming. Pick it to make Astryx match your DESIGN.md.
Tool: Astryx forms. Pick it when the site needs real forms on React.

Leads onward