Docs / Format spec
Standard sections
After the closing --- delimiter, the markdown body uses ## headings to define named sections. These sections give AI agents the rationale and usage rules behind your token values.
All sections are optional, but the eight below are the standard set. AI agents are trained to recognise these names and apply their content contextually when generating UI code. A short, accurate section outperforms a long, vague one every time.
1. Overview
A brief description of the product and its visual intent. Cover who the audience is, what emotional response the design should evoke, and the overall aesthetic direction. Aim for 3–5 sentences.
Example
Pebble Banking is a mobile-first fintech product for everyday users aged 25–50. Visual language: clean, trusted, approachable. Emotional response: secure, calm, and competent. Never flashy, never cold.
2. Colors
Explain the role and intended use of each color token. Don’t just list the hex values (those are already in the front matter) — explain when and why to use each one.
Example
primary (#1A1C1E) is for the single highest-emphasis action per screen. accent (#B8422E) is reserved for alerts and destructive states only — never use it for CTAs. neutral (#F7F5F2) is the default page background.
3. Typography
Describe typographic rules that go beyond token values: hierarchy decisions, maximum weights per context, font pairing rules, and any restrictions.
Example
Headlines use Plus Jakarta Sans at tight leading (1.05–1.1). Body copy uses Inter at 1.6 line height. Never mix more than two weights in a single card. All-caps labels always use Manrope — never set uppercase body copy.
4. Spacing
Clarify spacing intentions: the grid base unit, which scale steps to prefer for which contexts (card padding vs. section gaps vs. inline spacing), and any off-grid values that are explicitly allowed.
Example
Base unit is 4px. Use sm (8px) for inline gaps between icons and text. Use md (16px) for card internal padding at mobile. Use lg (32px) for card padding at desktop and section gaps.
5. Components
Prose rules for components that supplement the token definitions. Cover interaction patterns, compositional rules, and constraints that can’t be expressed in a property list.
Example
All buttons are pill-shaped (rounded-full). Primary buttons should appear once per screen. Cards use 16px radius and 32px internal padding on all sides. Badges never carry interactive affordance.
6. Do’s and Don’ts
A direct list of allowed and prohibited patterns. These are the rules AI agents cite most often — make them short and unambiguous.
Example
Do: use surface (#FFFFFF) for elevated card backgrounds on the neutral base. Don't: use accent (#B8422E) for primary CTAs — it signals caution. Don't: mix font families within a single component.
7. Accessibility
State your accessibility baseline and any design-specific rules. The linter already checks WCAG AA contrast for token pairs — this section is for rules the linter can’t infer: focus indicators, motion preferences, minimum tap target sizes, icon requirements.
Example
Minimum WCAG AA compliance on all text. Focus rings: 2px solid accent, 2px offset. Minimum tap target 44×44px. Never communicate state through colour alone — always pair with an icon or text label.
8. Motion
Optional. Define your animation vocabulary: easing curves, duration ranges, and which elements should or should not animate. Respecting prefers-reduced-motion should be stated here if it applies.
Example
Default transition: 150ms ease-out on interactive elements (hover, focus). Page transitions: 250ms ease-in-out. Never animate layout — only opacity, transform, and color. Always respect prefers-reduced-motion.