| name | design-tokens |
| description | Defines all design token values including colors, typography, spacing, shadows, borders, CTA styles, and brand invariants. Single source of truth for the visual identity. Use when applying design tokens, setting up brand colors, typography, or spacing for any landing page. |
| version | 5.4.0 |
Design Guide — Token Authority
v5.0 note: All {PLACEHOLDER} values in this file are now filled by design-tokens/token-values.md — the centralized token value file. Read design-tokens/token-values.md alongside this file in every session.
This file is the single source of truth for all design token values. No other skill file defines token values — they reference this file.
→ For how tokens are expressed in CSS: see css-js-generator/SKILL.md
→ For how tokens are applied to components: see component-library/SKILL.md
→ For how tokens are overridden by trends: see trend-adapter/SKILL.md
→ For how token values are extracted from various sources: see design-tokens/token-sources.md
1 — Brand Invariants
These values are locked. No trend adaptation, variation, or override may change them. The agent must verify these after any modification pipeline.
| Invariant | Value | Notes |
|---|
| Brand primary color | {PLACEHOLDER} | Dominant brand theme color — the visual identity of the site |
| CTA color | {PLACEHOLDER} | Action button color — may or may not equal brand primary |
| Brand font (headings) | {PLACEHOLDER} | Heading font family |
| Body font | {PLACEHOLDER} | System font stack or brand-specified body font |
| CTA hierarchy | Primary (filled action) → Secondary (filled brand) → Highlight (filled accent) → Outline → Outline-inverse | Order and visual weight must be maintained |
→ Additional invariants enforced in code output: see css-js-generator/SKILL.md (breakpoints, file format, naming conventions)
2 — Color Palette
2.1 — Brand Colors
| Token Name | Value | Usage |
|---|
color-primary | {PLACEHOLDER} | Dominant brand theme color — headers, nav accents, section tints, feature highlights. This is the site's visual identity (50%+ of branded areas). |
color-secondary | {PLACEHOLDER} | Complementary brand color — supports primary, used sparingly |
2.2 — CTA Colors
CTA color is separated from brand primary because many brands use a contrasting action color (e.g. red CTAs on a blue-themed site). When CTA and primary happen to be the same color, both tokens hold the same value.
| Token Name | Value | Usage |
|---|
color-cta | {PLACEHOLDER} | Primary action button background. May equal color-primary or be a distinct contrasting color. |
color-cta-hover | {PLACEHOLDER} | Primary CTA hover state (typically color-cta darkened ~10%) |
color-cta-active | {PLACEHOLDER} | Primary CTA active/pressed state (typically color-cta darkened ~15%) |
2.3 — Neutral Colors
| Token Name | Value | Usage |
|---|
color-text-primary | {PLACEHOLDER} | Headings, primary body text |
color-text-secondary | {PLACEHOLDER} | Descriptions, supporting text |
color-text-tertiary | {PLACEHOLDER} | Captions, metadata, muted text |
color-text-inverse | {PLACEHOLDER} | Text on dark backgrounds |
color-border-default | {PLACEHOLDER} | Default borders on cards, inputs, dividers |
color-border-light | {PLACEHOLDER} | Subtle borders, section separators |
color-bg-page | {PLACEHOLDER} | Page background |
color-bg-surface | {PLACEHOLDER} | Card and component backgrounds |
color-bg-elevated | {PLACEHOLDER} | Elevated surfaces (modals, dropdowns) |
2.4 — Semantic Colors
| Token Name | Value | Usage |
|---|
color-success | {PLACEHOLDER} | Success states, positive indicators |
color-warning | {PLACEHOLDER} | Warning states, caution indicators |
color-error | {PLACEHOLDER} | Error states, destructive actions |
color-info | {PLACEHOLDER} | Informational highlights |
2.5 — Section Surfaces
Surfaces are named section backgrounds chosen by semantic role, not by position. The builder picks a surface based on what the section means, not where it falls on the page.
| Surface Name | Token | Value | Role |
|---|
| Brand | surface-brand | {PLACEHOLDER} | Bold brand sections — hero banners, feature showcases |
| Brand Strong | surface-brand-strong | {PLACEHOLDER} | Deeper emphasis — reinforcement sections, pricing highlights |
| Subtle | surface-subtle | {PLACEHOLDER} | Light tinted break — feature overviews, FAQ, social proof |
| Brand Subtle | surface-brand-subtle | {PLACEHOLDER} | Alternate light tint — same visual weight as Subtle, used to avoid repeating the same surface |
| Inverse | surface-inverse | {PLACEHOLDER} | Dark sections — hero, footer, closing CTA, dark testimonials |
| Default | surface-default | {PLACEHOLDER} | White/page-default — standard content sections |
Surface assignment rules:
- Surfaces alternate to create visual rhythm — never place two of the same surface adjacent
- Default and Subtle/Brand Subtle alternate for the main page body
- Brand and Inverse are reserved for high-impact sections (hero, CTA, pricing highlight)
- Brand Strong is used sparingly — max 1–2 per page for deep emphasis
- Text on Brand/Brand Strong/Inverse surfaces must use
color-text-inverse (white)
- Text on Default/Subtle/Brand Subtle surfaces uses
color-text-primary
→ For surface assignment by section type: see layout-patterns/SKILL.md Section 2.2
→ For surface CSS implementation: see css-js-generator/SKILL.md
3 — Color Placement Map
This section defines where each color token is applied on the page. Placements are split into two categories: hardcoded (always follow the rule) and AI-flexible (the builder selects from token options, validated by WCAG).
3.1 — Color Application Model
- Primary color is the dominant brand color — 50%+ of branded areas (theme backgrounds, accents). Visual identity of the site.
- CTA color is the action button color — may equal primary or be a distinct contrasting color (e.g., red CTA on a blue-themed site).
- Surfaces are section backgrounds chosen by semantic role (§2.5): Brand, Brand Strong, Subtle, Brand Subtle, Inverse, Default.
- Text color follows surface: dark text on light surfaces, inverse text on dark/brand surfaces.
→ Color extraction: design-tokens/token-sources.md
3.2 — Hardcoded Placements
No AI discretion — follow exactly.
| Placement Area | Token | Rule |
|---|
| Primary button background | button-primary-bg | Action color (typically CTA red) |
| Primary button hover | button-primary-bg-hover | Always |
| Primary button text | button-primary-text | From DS (typically white) |
| Secondary button background | button-secondary-bg | Brand color (typically blue) |
| Secondary button hover | button-secondary-bg-hover | Always |
| Secondary button text | button-secondary-text | From DS (typically white) |
| Highlight button background | button-highlight-bg | Accent color (typically yellow/gold) |
| Highlight button hover | button-highlight-bg-hover | Always |
| Highlight button text | button-highlight-text | From DS (typically dark) |
| Outline button border | button-primary-bg | CTA-colored border, transparent fill |
| Outline button text | button-primary-bg | Matches border color |
| Outline-inverse border | color-neutral-700 | Neutral border for dark surfaces |
| Body text | color-text-primary | All paragraph text, list items |
| Description / supporting text | color-text-secondary | Subtitles, metadata, card descriptions |
| Caption / muted text | color-text-tertiary | Timestamps, footnotes, helper text |
| Text on Brand/Inverse surfaces | color-text-inverse | Any text over Brand, Brand Strong, or Inverse surfaces |
| Page background | color-bg-page | <body> and surface-default sections |
| Card / component surface | color-bg-surface | Card backgrounds, modal backgrounds |
| Default borders | color-border-default | Card borders, input borders, dividers |
3.3 — AI-Flexible Placements
The builder selects a surface (§2.5) based on section purpose. Every choice must pass WCAG validation (§3.4).
| Section Type | Surface Options | Guidance |
|---|
| Hero banner | surface-brand, surface-inverse, surface-default + image | Brand/Inverse for impact; Default if hero has a background image |
| Feature overview / grid | surface-default, surface-subtle | Light surfaces — content is the focus |
| How it works / value props | surface-subtle, surface-brand-subtle | Gentle visual break from Default sections |
| Social proof / testimonials | surface-subtle, surface-default | Subtle differentiation |
| Trust signals / logos | surface-subtle, surface-brand-subtle | Light tint to group logos visually |
| Statistics / metrics | surface-brand, surface-brand-strong | Bold surface draws attention to numbers |
| Pricing | surface-default, surface-subtle | Clean background; use surface-brand only for the highlighted tier card |
| FAQ | surface-subtle, surface-default | Low-emphasis section |
| Closing CTA | surface-brand, surface-brand-strong, surface-inverse | High-impact — match or complement hero surface |
| Footer | surface-inverse | Dark footer is standard for marketing sites |
| Feature icon color | color-primary, color-secondary | Match brand emphasis |
| Nav active state | color-primary | Active link indicator |
| Tag / badge background | surface-subtle or color-primary at low opacity | Labels, category tags |
3.4 — WCAG Validation Rules
Every color placement — hardcoded or AI-flexible — must satisfy WCAG 2.1 AA contrast requirements before final output.
| Content Type | Minimum Contrast Ratio | Against |
|---|
| Normal text (< 18px regular, < 14px bold) | 4.5 : 1 | Its background color |
| Large text (≥ 18px regular, ≥ 14px bold) | 3 : 1 | Its background color |
| UI components (buttons, inputs, icons) | 3 : 1 | Adjacent background color |
| Focus indicators | 3 : 1 | Surrounding background |
| Non-text contrast (graphical objects, charts) | 3 : 1 | Adjacent colors |
Validation process for AI-flexible placements:
- Choose a token from the options column
- Calculate contrast ratio between text/element color and its background
- If it passes → apply
- If it fails → try next token option from the list
- If all options fail → adjust opacity or lightness to meet ratio, flag with
/* WCAG-adjusted */
- Never skip validation — every color pair in the final output must pass
Text hierarchy proximity check (pre-build):
After extracting color-text-primary and color-text-secondary, verify they are visually distinguishable. If too similar, the heading/body hierarchy is invisible.
Approximate perceptual distance (simplified):
ΔR = R1 - R2, ΔG = G1 - G2, ΔB = B1 - B2
distance = sqrt(ΔR² + ΔG² + ΔB²)
distance < 30 → FLAG: "text-primary and text-secondary are near-identical
(distance {N}). Hierarchy will be invisible. Confirm with
user or lighten text-secondary by +40 on lightness."
distance 30–60 → OK but subtle — note in Build Card
distance > 60 → good separation
Run this check once after token extraction, before any frame creation. If flagged, ask the user before proceeding.
4 — Typography Scale
4.1 — Font Families
| Token Name | Value | Usage |
|---|
font-heading | {PLACEHOLDER} | All headings (H1–H6), display text |
font-body | {PLACEHOLDER} | Body text, descriptions, UI elements |
font-mono | {PLACEHOLDER} | Code snippets, technical content (if applicable) |
CDN reference for heading font: {PLACEHOLDER} (if applicable)
4.2 — Size Scale
| Token Name | Value | Usage |
|---|
font-size-display | {PLACEHOLDER} | Hero H1, oversized display headings |
font-size-h1 | {PLACEHOLDER} | Page-level H1 (if not display) |
font-size-h2 | {PLACEHOLDER} | Section headings |
font-size-h3 | {PLACEHOLDER} | Sub-section headings, card titles |
font-size-h4 | {PLACEHOLDER} | Minor headings, feature names |
font-size-body-lg | {PLACEHOLDER} | Lead paragraphs, hero subheadlines |
font-size-body | {PLACEHOLDER} | Default body text |
font-size-body-sm | {PLACEHOLDER} | Captions, metadata, small print |
4.3 — Weight Scale
| Token Name | Value | Usage |
|---|
font-weight-bold | {PLACEHOLDER} | Headings, emphasis |
font-weight-semibold | {PLACEHOLDER} | Sub-headings, button labels |
font-weight-regular | {PLACEHOLDER} | Body text, descriptions |
font-weight-light | {PLACEHOLDER} | Display text (if light style is used) |
4.4 — Line Heights
| Token Name | Value | Usage |
|---|
line-height-heading | {PLACEHOLDER} | All headings |
line-height-body | {PLACEHOLDER} | Body text, descriptions |
line-height-tight | {PLACEHOLDER} | Display text, compact headings |
4.5 — Letter Spacing
| Token Name | Value | Usage |
|---|
letter-spacing-heading | {PLACEHOLDER} | Headings (typically negative for large text) |
letter-spacing-body | normal | Body text (default) |
letter-spacing-caps | {PLACEHOLDER} | Uppercase labels, overlines |
5 — Spacing Scale
5.1 — Base Scale
A consistent spacing scale used across all components and layouts. All spacing values are derived from a base unit.
| Token Name | Value | Usage |
|---|
space-unit | {PLACEHOLDER} | Base unit (e.g., 4px or 8px) |
space-xs | {PLACEHOLDER} | Tightest spacing — inline elements, icon gaps |
space-sm | {PLACEHOLDER} | Small gaps — within components |
space-md | {PLACEHOLDER} | Medium gaps — between related elements |
space-lg | {PLACEHOLDER} | Large gaps — between component groups |
space-xl | {PLACEHOLDER} | Extra large — section internal padding |
space-2xl | {PLACEHOLDER} | Section top/bottom padding |
space-3xl | {PLACEHOLDER} | Maximum spacing — hero sections, major breaks |
5.2 — Layout-Specific Spacing
| Token Name | Value | Usage |
|---|
section-padding-y | {PLACEHOLDER} | Vertical padding for standard sections |
section-padding-y-lg | {PLACEHOLDER} | Vertical padding for hero / emphasis sections |
content-max-width | {PLACEHOLDER} | Maximum content width within sections |
content-max-width-narrow | {PLACEHOLDER} | Narrow content width (text-heavy sections) |
sidebar-width | {PLACEHOLDER} | Fixed width of sidebar in sidebar layout types |
grid-gutter | {PLACEHOLDER} | Gap between grid columns |
card-padding | {PLACEHOLDER} | Internal padding of card components |
→ For responsive adjustments to spacing: see css-js-generator/SKILL.md
6 — Shadows & Elevation
| Token Name | Value | Usage |
|---|
shadow-sm | {PLACEHOLDER} | Subtle depth — hover states, light cards |
shadow-md | {PLACEHOLDER} | Default card elevation |
shadow-lg | {PLACEHOLDER} | Prominent elevation — modals, featured cards |
shadow-none | none | Flat elements, no elevation |
7 — Border Radius
| Token Name | Value | Usage |
|---|
radius-sm | {PLACEHOLDER} | Buttons, inputs, small elements |
radius-md | {PLACEHOLDER} | Cards, containers |
radius-lg | {PLACEHOLDER} | Large cards, hero images, featured elements |
radius-full | 9999px | Circular elements (avatars, badges) |
radius-none | 0 | Sharp corners when needed |
8 — Button Styles
Five button styles, ordered by visual weight. Every page must respect this hierarchy — Primary carries the strongest emphasis, Outline-inverse the lightest.
8.1 — Primary (Filled Action)
The main conversion button. Uses the CTA/action color (typically red or a high-contrast action tone).
| Property | Token | Notes |
|---|
| Background | button-primary-bg | Action color — distinct from brand primary |
| Hover bg | button-primary-bg-hover | Darkened ~10% |
| Text | button-primary-text | Typically white |
| Font weight | font-weight-semibold | |
| Border radius | radius-sm or radius-pill | From DS — pill (9999px) if DS uses rounded buttons |
| Min height | {PLACEHOLDER} | e.g., 48px |
| Padding | {PLACEHOLDER} | e.g., 12px 32px |
8.2 — Secondary (Filled Brand)
Supporting action button. Uses the brand primary color to reinforce identity without competing with Primary.
| Property | Token | Notes |
|---|
| Background | button-secondary-bg | Brand primary color |
| Hover bg | button-secondary-bg-hover | Darkened ~10% |
| Text | button-secondary-text | Typically white |
| Font weight | font-weight-semibold | |
| Border radius | Same as Primary | |
| Min height | Same as Primary | |
| Padding | Same as Primary | |
8.3 — Highlight (Filled Accent)
Attention-drawing button for promotions, special offers, or pricing tier CTAs. Uses an accent color (typically yellow/gold) that contrasts with both Primary and Secondary.
| Property | Token | Notes |
|---|
| Background | button-highlight-bg | Accent color (e.g., yellow/gold) |
| Hover bg | button-highlight-bg-hover | Darkened ~10% |
| Text | button-highlight-text | Typically dark text (for light accent bg) |
| Font weight | font-weight-semibold | |
| Border radius | Same as Primary | |
| Min height | Same as Primary | |
| Padding | Same as Primary | |
8.4 — Outline (Ghost Action)
Low-emphasis action button for light surfaces. Transparent fill with a CTA-colored border.
| Property | Token | Notes |
|---|
| Background | transparent | |
| Border | 2px solid button-primary-bg | Uses CTA color for border |
| Hover bg | button-primary-bg at 8–10% opacity | Subtle fill on hover |
| Text | button-primary-bg | Matches border color |
| Font weight | font-weight-semibold | |
| Border radius | Same as Primary | |
| Min height | Same as Primary | |
| Padding | Same as Primary | |
8.5 — Outline-inverse (Ghost on Dark)
Low-emphasis button for dark/inverse surfaces. Neutral light border with white text.
| Property | Token | Notes |
|---|
| Background | transparent | |
| Border | 2px solid color-neutral-700 | Light neutral border |
| Hover bg | color-text-inverse at 10% opacity | Subtle white fill |
| Text | color-text-inverse | White |
| Font weight | font-weight-semibold | |
| Border radius | Same as Primary | |
| Min height | Same as Primary | |
| Padding | Same as Primary | |
8.6 — Button Placement Rules
| Context | Recommended Styles | Avoid |
|---|
| Hero CTA (primary action) | Primary | Highlight, Outline-inverse |
| Hero CTA (secondary action) | Outline, Outline-inverse (on dark hero) | Highlight |
| Pricing — highlighted tier | Primary or Highlight | Outline |
| Pricing — other tiers | Secondary or Outline | |
| Closing CTA section | Primary | Outline (too subtle for closing) |
| Card actions | Secondary, Outline | Primary (too heavy per-card) |
| Nav CTA | Primary or Secondary | Highlight |
| Form submit | Primary | Outline (too subtle for conversion) |
| Banner / promo | Highlight | Outline-inverse |
9 — Iconography Guidelines
| Property | Value |
|---|
| Default icon size | {PLACEHOLDER} |
| Feature icon size | {PLACEHOLDER} |
| Icon color (on light bg) | {PLACEHOLDER} |
| Icon color (on dark bg) | {PLACEHOLDER} |
| Icon style | {PLACEHOLDER} (e.g., outlined, filled, duotone) |
| Icon stroke width | {PLACEHOLDER} (if outlined) |
10 — Form & Input Tokens
Tokens for the Form component and all input fields. Applied consistently across contact, registration, newsletter, and download-gate form variants.
| Token Name | Value | Usage |
|---|
input-height | {PLACEHOLDER} | Height of single-line text inputs and selects |
input-bg | {PLACEHOLDER} | Input field background color |
input-border | {PLACEHOLDER} | Input border (e.g. 1px solid {color-border-default}) |
input-border-focus | {PLACEHOLDER} | Border color on focus state |
input-radius | {PLACEHOLDER} | Border radius of input fields |
input-placeholder-color | {PLACEHOLDER} | Placeholder text color |
input-padding | {PLACEHOLDER} | Internal padding within input fields |
11 — Image Treatment
| Property | Value |
|---|
| Product screenshot border | {PLACEHOLDER} |
| Product screenshot shadow | {PLACEHOLDER} |
| Product screenshot radius | {PLACEHOLDER} |
| Hero image max height | {PLACEHOLDER} |
| Thumbnail aspect ratio | {PLACEHOLDER} |
| Avatar size | {PLACEHOLDER} |
| Map embed height | {PLACEHOLDER} |
12 — Token Sources
Token values can be supplied from 7 different sources. The agent detects which source is available (see pipeline-workflow — Token Source Detection) and extracts values accordingly. All sources produce the same output: resolved values in token-values.md format.
| # | Source | Recognition Signal |
|---|
| 1 | Product token file (.md) | A {product}-design-tokens.md file is attached or referenced |
| 2 | Manual fill | token-values.md already has values filled in |
| 3 | Website URL | A website URL is provided alongside the brief |
| 4 | Figma Design System | A Figma library or design system reference is provided |
| 5 | Figma Design Frame | A Figma frame URL or dev link is provided |
| 6 | Screenshot | A .png / .jpg image is attached |
| 7 | JSON token file | A .json file is attached or referenced |
→ Full extraction protocols, token name normalization rules, and gap handling: see design-tokens/token-sources.md
13 — Token Override Protocol
When trend-adapter/SKILL.md produces a Trend Adaptation Brief, it contains a Token Override Sheet — a set of replacement values for tokens defined in this file.
Override rules:
- Overrides apply as a layer on top of base values — this file is never modified directly
- Only tokens listed in the override sheet change; unlisted tokens retain their base values
- Brand invariants (Section 1) cannot be overridden — the agent must reject any override that attempts to change them
- The agent applies overrides after reading this file and before generating output
Override format example:
--{product}-section-padding-y: 64px;
--{product}-font-size-display: 4.2rem;
--{product}-shadow-md: 0 4px 24px rgba(0, 0, 0, 0.08);
→ Full trend dimension definitions and profiles: see trend-adapter/SKILL.md
→ For how overrides are expressed as CSS custom properties: see css-js-generator/SKILL.md
