Brand Guide

---
version: 1.0
name: universal-design-system
description: A neutral, token-driven foundation for content-led product and marketing interfaces. Full-bleed sections alternate light and dark canvases, a restrained type scale built on Inter carries hierarchy, and a single brand accent — left as a placeholder for each team to define — drives every interactive element. UI chrome stays quiet so content leads. Elevation is earned rather than decorative — surface-color change and one soft content shadow do the work of borders and drop-shadows. Every value below is a token; reference tokens, never raw values.

colors:
  # Brand accent — UNDEFINED ON PURPOSE. Replace every "TBD" with your
  # brand color before shipping. One accent carries all interactivity.
  brand-primary: "TBD"
  brand-primary-focus: "TBD"
  brand-on-dark: "TBD"
  on-brand: "#ffffff"

  # Neutral ramp — the structural backbone (brand-agnostic).
  white: "#ffffff"
  neutral-50: "#fafafa"
  neutral-100: "#f4f4f5"
  neutral-200: "#e4e4e7"
  neutral-300: "#d4d4d8"
  neutral-400: "#a1a1aa"
  neutral-500: "#71717a"
  neutral-600: "#52525b"
  neutral-700: "#3f3f46"
  neutral-800: "#27272a"
  neutral-900: "#18181b"
  black: "#000000"

  # Surfaces
  canvas: "#ffffff"
  canvas-muted: "#fafafa"
  surface: "#ffffff"
  surface-raised: "#f4f4f5"
  surface-dark: "#27272a"
  surface-dark-2: "#2a2a2e"
  surface-dark-3: "#1f1f22"
  surface-black: "#000000"

  # Text
  ink: "#18181b"
  body: "#27272a"
  body-muted: "#52525b"
  body-subtle: "#71717a"
  on-dark: "#ffffff"
  on-dark-muted: "#d4d4d8"
  on-dark-subtle: "#a1a1aa"
  text-disabled: "#a1a1aa"

  # Lines & focus
  hairline: "#e4e4e7"
  divider: "#f4f4f5"
  border-strong: "#d4d4d8"
  focus-ring: "TBD"

  # Status — suggested defaults, swap to taste (optional layer).
  success: "#1a7f37"
  warning: "#9a6700"
  danger: "#c0362c"
  info: "#1f6feb"

typography:
  hero-display:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 56px
    fontWeight: 700
    lineHeight: 1.05
    letterSpacing: -0.02em
  display-lg:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 40px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.02em
  display-md:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 32px
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: -0.01em
  title:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 24px
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: -0.01em
  lead:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 20px
    fontWeight: 400
    lineHeight: 1.4
    letterSpacing: 0
  body-lg:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 18px
    fontWeight: 400
    lineHeight: 1.55
    letterSpacing: 0
  body-strong:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 16px
    fontWeight: 600
    lineHeight: 1.5
    letterSpacing: 0
  body:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.55
    letterSpacing: 0
  caption:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.45
    letterSpacing: 0
  caption-strong:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 14px
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0
  eyebrow:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 12px
    fontWeight: 600
    lineHeight: 1.0
    letterSpacing: 0.08em
    textTransform: uppercase
  button:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 16px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: 0
  button-sm:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 14px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: 0
  nav-link:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 14px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: 0
  fine-print:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 12px
    fontWeight: 400
    lineHeight: 1.4
    letterSpacing: 0
  micro-legal:
    fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    fontSize: 11px
    fontWeight: 400
    lineHeight: 1.4
    letterSpacing: 0

rounded:
  none: 0px
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 24px
  pill: 9999px
  full: 9999px

spacing:
  3xs: 2px
  xxs: 4px
  xs: 8px
  sm: 12px
  md: 16px
  lg: 24px
  xl: 32px
  2xl: 48px
  3xl: 64px
  section: 80px
  section-lg: 120px

elevation:
  flat: none
  hairline: "0 0 0 1px {colors.hairline}"
  content: "0 6px 24px rgba(0, 0, 0, 0.12)"
  overlay: "0 8px 32px rgba(0, 0, 0, 0.16)"

motion:
  press-scale: "scale(0.97)"
  duration-fast: 120ms
  duration-base: 200ms
  duration-slow: 320ms
  easing-standard: "cubic-bezier(0.4, 0, 0.2, 1)"
  easing-emphasized: "cubic-bezier(0.2, 0, 0, 1)"

components:
  top-nav:
    backgroundColor: "{colors.surface-black}"
    textColor: "{colors.on-dark}"
    typography: "{typography.nav-link}"
    height: 48px
    padding: 0px 24px
  sub-nav:
    backgroundColor: "{colors.canvas-muted}"
    textColor: "{colors.ink}"
    typography: "{typography.title}"
    height: 52px
    padding: 0px 24px
  button-primary:
    backgroundColor: "{colors.brand-primary}"
    textColor: "{colors.on-brand}"
    typography: "{typography.button}"
    rounded: "{rounded.pill}"
    padding: 12px 22px
  button-primary-focus:
    backgroundColor: "{colors.brand-primary}"
    textColor: "{colors.on-brand}"
    rounded: "{rounded.pill}"
    outline: "2px solid {colors.brand-primary-focus}"
  button-primary-active:
    backgroundColor: "{colors.brand-primary}"
    textColor: "{colors.on-brand}"
    rounded: "{rounded.pill}"
    transform: "{motion.press-scale}"
  button-secondary:
    backgroundColor: "{colors.surface-raised}"
    textColor: "{colors.ink}"
    typography: "{typography.button}"
    rounded: "{rounded.pill}"
    padding: 12px 22px
  button-outline:
    backgroundColor: transparent
    textColor: "{colors.brand-primary}"
    border: "1px solid {colors.brand-primary}"
    typography: "{typography.button}"
    rounded: "{rounded.pill}"
    padding: 12px 22px
  button-utility:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-dark}"
    typography: "{typography.button-sm}"
    rounded: "{rounded.sm}"
    padding: 8px 16px
  button-icon:
    backgroundColor: "{colors.surface-raised}"
    textColor: "{colors.ink}"
    rounded: "{rounded.full}"
    size: 44px
  text-link:
    backgroundColor: transparent
    textColor: "{colors.brand-primary}"
    typography: "{typography.body}"
  text-link-on-dark:
    backgroundColor: transparent
    textColor: "{colors.brand-on-dark}"
    typography: "{typography.body}"
  section-tile-light:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.display-lg}"
    rounded: "{rounded.none}"
    padding: 80px
  section-tile-muted:
    backgroundColor: "{colors.canvas-muted}"
    textColor: "{colors.ink}"
    typography: "{typography.display-lg}"
    rounded: "{rounded.none}"
    padding: 80px
  section-tile-dark:
    backgroundColor: "{colors.surface-dark}"
    textColor: "{colors.on-dark}"
    typography: "{typography.display-lg}"
    rounded: "{rounded.none}"
    padding: 80px
  section-tile-dark-2:
    backgroundColor: "{colors.surface-dark-2}"
    textColor: "{colors.on-dark}"
    rounded: "{rounded.none}"
  content-card:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-strong}"
    border: "1px solid {colors.hairline}"
    rounded: "{rounded.lg}"
    padding: 24px
  product-card:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-strong}"
    border: "1px solid {colors.hairline}"
    rounded: "{rounded.lg}"
    padding: 24px
  option-chip:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.caption}"
    border: "1px solid {colors.hairline}"
    rounded: "{rounded.pill}"
    padding: 12px 16px
  option-chip-selected:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    border: "2px solid {colors.brand-primary-focus}"
    rounded: "{rounded.pill}"
  input-text:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    border: "1px solid {colors.border-strong}"
    rounded: "{rounded.md}"
    padding: 12px 16px
    height: 44px
  input-text-focus:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    border: "1px solid {colors.brand-primary-focus}"
    outline: "2px solid {colors.focus-ring}"
    rounded: "{rounded.md}"
  input-text-error:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    border: "1px solid {colors.danger}"
    rounded: "{rounded.md}"
  search-input:
    backgroundColor: "{colors.surface-raised}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    rounded: "{rounded.pill}"
    padding: 12px 20px
    height: 44px
  sticky-action-bar:
    backgroundColor: "{colors.canvas-muted}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    height: 64px
    padding: 12px 32px
  feature-quote-card:
    backgroundColor: "{colors.surface-dark}"
    textColor: "{colors.on-dark}"
    typography: "{typography.display-lg}"
    rounded: "{rounded.none}"
    padding: 80px
  footer:
    backgroundColor: "{colors.canvas-muted}"
    textColor: "{colors.body-muted}"
    typography: "{typography.fine-print}"
    padding: 64px
---

## Overview

This is a **brand-neutral, token-driven design system** for content-led product and marketing interfaces. It is intentionally quiet: layout, type, and a single accent color do the work, while decorative chrome stays out of the way so the content leads. It ships as a foundation, not a finished skin — every value is a token, and the one brand decision left to you (the accent color) is marked `TBD` so you can drop a brand into the system without touching its structure.

The visual model is a stack of **full-bleed sections** that alternate light and dark canvases. Each section occupies roughly one viewport: an optional eyebrow, a headline, a one-line subhead, one or two CTAs, and a supporting visual. The **color change between sections is the divider** — no borders, no decorative frames, no shadows on chrome. Elevation appears only where it earns its keep: a hairline on cards, a backdrop blur on sticky bars, and exactly one soft **content shadow** under media resting on a surface.

Density is deliberately low. Whitespace is generous, the type scale is restrained, and interactivity collapses to a single accent so the "click me" signal is unmistakable. The same chassis scales from a marketing homepage to a catalog grid to a long-form editorial page by changing volume — surface mix, spacing rhythm, and headline size — not by introducing new languages.

**Key characteristics**

- Content-first presentation; UI recedes so the subject can speak.
- Alternating full-bleed sections — light/muted ↔ dark — where the color change itself is the section divider.
- **Single brand accent** (`{colors.brand-primary}`, defined per brand) carries every interactive element. No second accent.
- Two button grammars: a pill primary (`{rounded.pill}`) and a compact utility rect (`{rounded.sm}`).
- Inter on a system fallback stack; negative tracking at display sizes for a tight, modern headline cadence.
- Earned elevation: one content shadow for media, a hairline for cards, backdrop blur for sticky surfaces. Nothing else.
- A clean 8px spacing base and a normalized radius ladder (`4 / 8 / 12 / 16 / 24 / pill`).
- A predictable section pulse: light hero → dark feature → light utility → dark feature → muted footer.

## How to Use This System

1. **Define the accent.** Replace `brand-primary`, `brand-primary-focus`, `brand-on-dark`, and `focus-ring` (all `TBD`). One hue, three-or-four steps: a base, a slightly brighter focus sibling, a lighter on-dark variant for text on dark surfaces, and a focus-ring value (usually equal to `brand-primary-focus`). Set `on-brand` to whichever of black/white meets contrast on your accent.
2. **Keep the neutral ramp.** `neutral-50 → neutral-900` is the structural backbone; the semantic surface/text/line tokens are aliases into it. Re-tint the ramp only if your brand needs warm or cool grays.
3. **Reference tokens, never raw values.** Every component reads from `{colors.*}`, `{typography.*}`, `{rounded.*}`, `{spacing.*}`, `{elevation.*}`, `{motion.*}`. Change the token, not the call site.
4. **Adopt the optional layers as needed.** Status colors and input states are provided so feedback and forms aren't an afterthought; delete them if a surface doesn't need them.

## Colors

The system is **neutral by default**. A 12-step neutral ramp provides every surface, text, and line tone; a single brand accent — defined per brand — provides interactivity. There is no secondary brand color.

### Brand & Accent (define these)

- **Brand Primary** (`{colors.brand-primary}` — `TBD`): The single brand-level interactive color. All text links, all primary CTAs, and the focus-ring root resolve to this. Press state shifts via the `{motion.press-scale}` transform rather than a hex change.
- **Brand Primary Focus** (`{colors.brand-primary-focus}` — `TBD`): A marginally brighter sibling reserved for the keyboard focus ring on buttons and the selected/active border on inputs and chips (`outline: 2px solid`).
- **Brand On Dark** (`{colors.brand-on-dark}` — `TBD`): A brighter accent for inline links on dark surfaces, where the base accent would lose contrast against a near-black tile.
- **On Brand** (`{colors.on-brand}` — `#ffffff`): Text/icon color that sits on top of the accent. Flip to a dark value if your accent is light.

### Surface

- **Canvas** (`{colors.canvas}` — `#ffffff`): The dominant light canvas. Body content, cards, grids.
- **Canvas Muted** (`{colors.canvas-muted}` — `#fafafa`): The off-white used for alternating light sections, the footer region, and default page canvas in utility sections. Just different enough from white to create rhythm.
- **Surface Raised** (`{colors.surface-raised}` — `#f4f4f5`): Fill for secondary/ghost buttons and search inputs — light enough to still read as a control against muted canvas.
- **Surface Dark** (`{colors.surface-dark}` — `#27272a`): The primary dark-section surface.
- **Surface Dark 2 / 3** (`#2a2a2e` / `#1f1f22`): Micro-steps lighter and darker than Surface Dark — used when two dark sections sit adjacent and need the faintest separation, or for embedded media frames.
- **Surface Black** (`{colors.surface-black}` — `#000000`): Reserved for true void — media player backgrounds, edge-to-edge photographic overlays, and the top nav bar.

### Text

- **Ink** (`{colors.ink}` — `#18181b`): Headlines and high-emphasis text on light surfaces. A near-black rather than pure black, to keep the page feeling photographic rather than printed.
- **Body** (`{colors.body}` — `#27272a`): Default paragraph text on light surfaces — a hair softer than ink.
- **Body Muted** (`{colors.body-muted}` — `#52525b`): Secondary copy, supporting labels.
- **Body Subtle** (`{colors.body-subtle}` — `#71717a`): Tertiary copy and legal fine print on light surfaces.
- **On Dark** (`{colors.on-dark}` — `#ffffff`): All primary text on dark sections and the top nav.
- **On Dark Muted / Subtle** (`#d4d4d8` / `#a1a1aa`): Secondary and tertiary copy on dark sections, where pure white would be too loud.
- **Text Disabled** (`{colors.text-disabled}` — `#a1a1aa`): Disabled control labels.

### Hairlines & Borders

- **Hairline** (`{colors.hairline}` — `#e4e4e7`): The 1px border on cards and chips; functions as a soft ring more than a hard line.
- **Divider** (`{colors.divider}` — `#f4f4f5`): The lightest separator, for in-card or list dividers.
- **Border Strong** (`{colors.border-strong}` — `#d4d4d8`): The default input border, where a control needs a clearly visible edge.

### Status (optional)

Functional feedback colors, provided as sensible defaults so forms and alerts aren't an afterthought. They are not brand colors — adjust to taste, but keep them distinct from `brand-primary`.

- **Success** `#1a7f37` · **Warning** `#9a6700` · **Danger** `#c0362c` · **Info** `#1f6feb`.

### On Gradients

**No decorative gradients by default.** Depth and atmosphere should come from real imagery and from the light/dark surface alternation, not from CSS gradient overlays. If a brand needs a gradient, define it as an explicit token rather than inlining it — but the base system ships gradient-free on purpose.

## Typography

### Font Family

- **Primary**: `Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif`. Inter is open-source, free, and variable; the `system-ui` and `-apple-system` fallbacks resolve to each platform's native UI font, so the system looks at home everywhere with zero licensing cost.
- **One family, two registers**: Inter covers both display and text. At display sizes, lean on weight (600–700) and negative tracking; at text sizes, use 400/500/600 with neutral tracking. If you want optical refinement, Inter's variable "opsz" axis (or the "Inter Display" cut) can be wired to the display tokens — optional, not required.
- **OpenType**: enable `font-feature-settings: "cv05", "ss03"` if you prefer Inter's single-story `a`/`g`; enable `"tnum"` for tabular figures in pricing and spec tables.

### Hierarchy

| Token | Size | Weight | Line Height | Letter Spacing | Use |
|---|---|---|---|---|---|
| `{typography.hero-display}` | 56px | 700 | 1.05 | -0.02em | Hero headline; the tightest tracking in the system |
| `{typography.display-lg}` | 40px | 700 | 1.10 | -0.02em | Section/feature headlines atop full-bleed tiles |
| `{typography.display-md}` | 32px | 600 | 1.15 | -0.01em | Sub-section heads |
| `{typography.title}` | 24px | 600 | 1.25 | -0.01em | Card titles, sub-nav category name |
| `{typography.lead}` | 20px | 400 | 1.40 | 0 | Section subhead / lead paragraph |
| `{typography.body-lg}` | 18px | 400 | 1.55 | 0 | Long-form reading copy |
| `{typography.body-strong}` | 16px | 600 | 1.50 | 0 | Inline strong emphasis, card headings |
| `{typography.body}` | 16px | 400 | 1.55 | 0 | Default paragraph |
| `{typography.caption}` | 14px | 400 | 1.45 | 0 | Secondary captions, chip text |
| `{typography.caption-strong}` | 14px | 600 | 1.40 | 0 | Emphasized captions, column headings |
| `{typography.eyebrow}` | 12px | 600 | 1.0 | 0.08em · uppercase | Overline above a headline |
| `{typography.button}` | 16px | 500 | 1.0 | 0 | Primary/secondary button labels |
| `{typography.button-sm}` | 14px | 500 | 1.0 | 0 | Utility/compact button labels |
| `{typography.nav-link}` | 14px | 500 | 1.0 | 0 | Top-nav menu items |
| `{typography.fine-print}` | 12px | 400 | 1.4 | 0 | Footer body, fine print |
| `{typography.micro-legal}` | 11px | 400 | 1.4 | 0 | Micro legal disclaimers |

### Principles

- **Negative tracking at display sizes.** Headlines tighten by `-0.01 → -0.02em`. Tracking is expressed in `em` (not px) so it scales correctly with font size across breakpoints. Never tighten text at 14px or below.
- **16px body, not 14px.** Default reading copy is 16px with a 1.55 line-height — an editorial "reading, not scanning" pace. Use `body-lg` (18px) for long-form articles.
- **A full, conventional weight ladder.** `400 / 500 / 600 / 700`, with optional `300` for large airy reads. Medium (500) is present and used for controls and nav — no missing rungs.
- **Weight 600 for most headings, 700 for hero.** Reserve 700 for the largest display moments; section heads sit at 600.
- **Line-height is context-specific.** Display sizes run tight (1.05–1.25); body runs relaxed (1.45–1.55). Don't apply body leading to headlines or vice-versa.
- **One family, many roles.** Hierarchy comes from size, weight, and tracking — not from mixing typefaces.

### Substituting the Typeface

If you swap Inter for a brand face, keep the roles intact: a display register (600–700, tight tracking) and a text register (400–600, neutral tracking). Re-tune two things after swapping — display `letter-spacing` (most faces need a different tightening than Inter) and body `line-height` (taller x-heights need slightly less leading). Keep the system-ui fallbacks last in the stack so first paint never breaks.

## Layout

### Spacing System

- **Base unit:** 8px, with a 4px sub-step for tight typographic adjustments. Structural layout snaps to `8 / 12 / 16 / 24 / 32`.
- **Tokens:** `{spacing.xxs}` 4 · `{spacing.xs}` 8 · `{spacing.sm}` 12 · `{spacing.md}` 16 · `{spacing.lg}` 24 · `{spacing.xl}` 32 · `{spacing.2xl}` 48 · `{spacing.3xl}` 64 · `{spacing.section}` 80 · `{spacing.section-lg}` 120.
- **Section vertical padding:** `{spacing.section}` (80px) inside a full-bleed tile; tiles stack edge-to-edge with 0 gap (the color change provides the break). Use `{spacing.section-lg}` (120px) for marquee heroes.
- **Card padding:** `{spacing.lg}` (24px) inside utility/product cards.
- **Button padding:** 8–12px vertical, 16–22px horizontal.

### Grid & Container

- **Max content width:** ~960px on text-heavy sections, ~1440px on grids, full-bleed for section tiles.
- **Column patterns:** 3–5 column utility/product grids; 2-column side-by-side tiles; single-column centered stack on section heroes.
- **Gutters:** 20–24px between cards in a grid.

### Whitespace Philosophy

Whitespace is the content's pedestal. Begin each section with at least 64px of air above the headline and 48–64px below. Keep media uncrowded — the nearest content to an image should be at least 40px away. The footer is the one place where going deliberately dense is correct, so the full information architecture is visible at a glance.

## Elevation & Depth

| Level | Token | Treatment | Use |
|---|---|---|---|
| Flat | `{elevation.flat}` | No shadow, no border | Full-bleed sections, top nav, footer, body |
| Hairline | `{elevation.hairline}` | `0 0 0 1px {colors.hairline}` | Cards, chips, sub-nav separator |
| Backdrop blur | — | `backdrop-filter: saturate(180%) blur(20px)` on a translucent surface | Sticky bars, frosted sub-nav |
| Content | `{elevation.content}` | `0 6px 24px rgba(0,0,0,0.12)` | Media/imagery resting on a surface |
| Overlay | `{elevation.overlay}` | `0 8px 32px rgba(0,0,0,0.16)` | Popovers, menus, dialogs (use sparingly) |

**Shadow philosophy.** Elevation is **earned, not decorative.** The default content shadow exists to give media physical weight when it rests on a surface — not to rank UI. Most hierarchy comes from (a) surface-color change (light ↔ dark) and (b) backdrop blur on sticky surfaces. Reach for `{elevation.overlay}` only for genuinely floating layers (menus, dialogs); never put it on static cards, buttons, or text.

### Decorative Depth

- **Real imagery** supplies mood; avoid CSS gradients standing in for atmosphere.
- **Edge-to-edge surface alternation** creates rhythm without borders or shadows — the color change is the divider.
- **Backdrop blur** on sticky surfaces creates a functional "floating over content" effect, not a decorative one.

## Shapes

### Border Radius Scale

| Token | Value | Use |
|---|---|---|
| `{rounded.none}` | 0px | Full-bleed section tiles (no corner rounding) |
| `{rounded.xs}` | 4px | Subtle inline chips, small inner imagery |
| `{rounded.sm}` | 8px | Utility buttons, inline card imagery |
| `{rounded.md}` | 12px | Inputs, secondary capsules |
| `{rounded.lg}` | 16px | Utility/product cards |
| `{rounded.xl}` | 24px | Large feature cards, modals |
| `{rounded.pill}` | 9999px | Primary CTAs, chips, search input — the "action" shape |
| `{rounded.full}` | 9999px / 50% | Circular icon controls and avatars |

### Imagery Geometry

- **Hero imagery:** full-bleed, 21:9 or taller in marquee heroes; 16:9 elsewhere. The subject may rest on a tinted surface that becomes the tile background.
- **Media renders:** PNG/WebP with transparency rest on a surface tile and pick up `{elevation.content}`.
- **Grid imagery:** square 1:1 crops at `{rounded.lg}`, neutral backgrounds, subject centered with 20–40px internal padding.
- **No rounded hero imagery** — heroes are full-bleed rectangles; rounding appears only on inline/card imagery.
- Serve responsive `srcset`/`sizes` across breakpoints; prefer CDN-optimized WebP and lazy-load below-the-fold media.

## Components

> All components reference tokens only. Document **default** and **active/pressed** (and, for inputs, **focus** and **error**) states — not hover.

### Top Navigation

**`top-nav`** — Persistent, ultra-thin bar pinned to the top of every page. Background `{colors.surface-black}`, height 48px, text `{colors.on-dark}` in `{typography.nav-link}`. Links sit ~20px apart, edge-to-edge; a right-aligned cluster (search, account, cart) stays visible. Collapses to a hamburger at the tablet-portrait breakpoint.

**`sub-nav`** — A surface-specific bar that sticks below the top nav. Background `{colors.canvas-muted}` (apply at ~80% opacity with `backdrop-filter` for a frosted effect), height 52px. Left: section/category name in `{typography.title}`. Right: inline links in `{typography.button-sm}`, ending in a persistent `{component.button-primary}` or utility link.

### Buttons

**`button-primary`** — The signature action. Background `{colors.brand-primary}`, text `{colors.on-brand}` in `{typography.button}`, `{rounded.pill}`, padding 12×22px. The full-pill radius is the "action" signal.
- Active: `{component.button-primary-active}` — `transform: {motion.press-scale}` (the system-wide micro-interaction).
- Focus: `{component.button-primary-focus}` — `2px solid {colors.brand-primary-focus}` outline.

**`button-secondary`** — The second CTA when two buttons appear together. Background `{colors.surface-raised}`, text `{colors.ink}`, `{rounded.pill}`, padding 12×22px. A quiet, neutral companion to the accent primary.

**`button-outline`** — Ghost pill. Transparent background, text `{colors.brand-primary}`, `1px solid {colors.brand-primary}`, `{rounded.pill}`. Use where a transparent-on-imagery action reads better than a filled one.

**`button-utility`** — Compact nav/toolbar actions (sign in, cart, language). Background `{colors.ink}`, text `{colors.on-dark}` in `{typography.button-sm}`, `{rounded.sm}`, padding 8×16px. Active state uses `{motion.press-scale}`.

**`button-icon`** — Floats over imagery or sits in toolbars. 44×44px, background `{colors.surface-raised}` (apply at ~64% alpha over photography), icon in `{colors.ink}`, `{rounded.full}`. Carousel controls, close buttons, in-image controls.

**`text-link`** — Inline body links in `{colors.brand-primary}`. Underlined or not per context.

**`text-link-on-dark`** — Inline links on dark sections in `{colors.brand-on-dark}` — the base accent would lose contrast on `{colors.surface-dark}`.

### Cards & Containers

**`section-tile-light`** — Full-bleed light section. Background `{colors.canvas}`, text `{colors.ink}`, `{rounded.none}`, vertical padding `{spacing.section}`. Centered stack: optional `{typography.eyebrow}` → headline in `{typography.display-lg}` → subhead in `{typography.lead}` → one or two CTAs → supporting media resting on the surface with `{elevation.content}`.

**`section-tile-muted`** — Same as `section-tile-light` on `{colors.canvas-muted}`. Use to break two consecutive white sections.

**`section-tile-dark`** — Full-bleed dark section. Background `{colors.surface-dark}`, text `{colors.on-dark}`, `{rounded.none}`, padding `{spacing.section}`. Same content stack, but inline copy uses `{component.text-link-on-dark}`. The alternating dark band in the section pulse.

**`section-tile-dark-2`** — Variant on `{colors.surface-dark-2}` for the faintest separation when a dark section sits directly adjacent to another.

**`content-card` / `product-card`** — Grid cards. Background `{colors.canvas}`, `1px solid {colors.hairline}`, `{rounded.lg}`, padding `{spacing.lg}`. Top: image (1:1 crop, `{rounded.sm}` inner radius). Below: title in `{typography.body-strong}`, supporting line in `{typography.body}`, and a `{component.text-link}`. No shadow by default; media carries `{elevation.content}` if it needs weight.

**`option-chip`** — Pill-shaped selectable cell. Background `{colors.canvas}`, text `{colors.ink}` in `{typography.caption}`, `1px solid {colors.hairline}`, `{rounded.pill}`, padding 12×16px. Holds a small thumbnail/label/meta. Arrange 4–5 per row.

**`option-chip-selected`** — Selected state: border upgrades to `2px solid {colors.brand-primary-focus}`. Same shape and content.

**`feature-quote-card`** — An editorial dark hero. Background `{colors.surface-dark}` (or a photographic backdrop with that fallback), centered headline in `{typography.display-lg}`, optional `{typography.eyebrow}` above, a single `{component.button-primary}` below. Padding `{spacing.section}`.

**`sticky-action-bar`** — Floats at the bottom of the viewport during scroll on conversion pages. Background `{colors.canvas-muted}` at ~80% opacity with `backdrop-filter: blur(...)`, height 64px, padding 12×32px. Left: running summary in `{typography.body}`. Right: `{component.button-primary}`.

### Inputs & Forms

**`input-text`** — Default text field. Background `{colors.canvas}`, text `{colors.ink}` in `{typography.body}`, `1px solid {colors.border-strong}`, `{rounded.md}`, padding 12×16px, height 44px.
- **Focus** (`{component.input-text-focus}`): border to `{colors.brand-primary-focus}` plus a `2px solid {colors.focus-ring}` outline.
- **Error** (`{component.input-text-error}`): border to `{colors.danger}`; pair with a `{colors.danger}` helper message in `{typography.caption}`.

**`search-input`** — Pill-shaped search field matching the CTA grammar. Background `{colors.surface-raised}`, text `{colors.ink}` in `{typography.body}`, `{rounded.pill}`, padding 12×20px, height 44px, leading search glyph at 14px in a muted tint.

### Footer

**`footer`** — Background `{colors.canvas-muted}`, text `{colors.body-muted}`. Link columns in `{typography.fine-print}`; column headings in `{typography.caption-strong}`. Legal row at the bottom in `{typography.micro-legal}` with `{colors.body-subtle}` text. Vertical padding 64px. The one intentionally dense region.

## Do's and Don'ts

### Do

- Use `{colors.brand-primary}` for every interactive element — links, primary CTAs, focus signals — and nothing else. The single accent is the rule.
- Set headlines in `{typography.hero-display}` or `{typography.display-lg}` with negative tracking (`-0.01 → -0.02em`) for a tight, modern cadence.
- Run body copy at `{typography.body}` (16px / 1.55) — and `{typography.body-lg}` (18px) for long-form reading.
- Alternate `section-tile-light` (or muted) and `section-tile-dark` for full-bleed rhythm. The color change IS the divider.
- Reserve `{rounded.pill}` for elements that should read as an "action" (primary CTA, chips, search input, sticky-bar CTA).
- Apply `{elevation.content}` only to media resting on a surface — never on cards, buttons, or text.
- Use `{motion.press-scale}` as the active/press state on every button — the system-wide micro-interaction.
- Keep the top nav `{colors.surface-black}` (true black) — often the only place pure black appears.
- Provide a visible focus state on every interactive element using `{colors.focus-ring}`.

### Don't

- Don't introduce a second accent color; every "click me" signal is `{colors.brand-primary}`.
- Don't add shadows to cards, buttons, or text — content shadow is reserved for media; overlay shadow for floating layers only.
- Don't use gradients as decorative backgrounds; depth comes from imagery and surface alternation.
- Don't round full-bleed tiles — sections are rectangular and edge-to-edge; the color change is the divider.
- Don't tighten body line-height below 1.5 — the editorial leading is part of the feel.
- Don't mix radius grammars — `{rounded.sm}` for compact utility, `{rounded.lg}` for cards, `{rounded.pill}` for actions; don't invent in-between values.
- Don't use `{colors.brand-on-dark}` on light surfaces — it's the dark-section variant; the base accent is for light surfaces.
- Don't express display tracking in px — use `em` so it scales with size.

## Responsive Behavior

### Breakpoints

| Name | Width | Key Changes |
|---|---|---|
| Small phone | ≤ 419px | Single-column sections; sub-nav collapses to category + primary CTA; hero type drops to ~28px |
| Phone | 420–640px | Single-column stack; media scales to ~80% of tile width; hero drops to ~34px |
| Large phone | 641–767px | Tighter section padding (48px vs 80px); fine print wraps |
| Tablet portrait | 768–1023px | Top nav collapses to hamburger; sub-nav hides inline links, keeps primary CTA; grids → 2-col |
| Desktop | 1024–1439px | Full layout; 3–4 column grids; ~1200px content frame |
| Wide desktop | ≥ 1440px | Content locks at 1440px; margins absorb extra width |

Structural breakpoints that matter most: **1440px** (content lock), **1024px** (desktop ↔ tablet), **768px** (nav collapse), **640px** (phone), **420px** (small phone).

### Touch Targets

- Minimum **44 × 44px**. `button-primary` lands at ~44px tall; the full-pill radius makes the visible hit area generous.
- `button-icon` is exactly 44 × 44px.
- Desktop nav links may sit at a tighter target since the mobile hamburger replaces them below the nav-collapse breakpoint.

### Collapsing Strategy

- **Top nav:** full horizontal link row → logo + hamburger + cart at ≤ 768px.
- **Sub-nav:** category + inline links + CTA → category + CTA only on mobile; inline links move into a tray.
- **Section tiles:** 2-column → 1-column at the nav-collapse breakpoint; vertical padding tightens 80px → 48px on small phones.
- **Grids:** 4-col → 3-col (1024px) → 2-col (768px) → 1-col (640px).
- **Hero type:** `hero-display` (56px) → `display-lg` (40px) at desktop → ~34px at phone → ~28px at small phone.

### Image Behavior

- Use responsive `srcset` with breakpoint-matched crops.
- Hero imagery may switch art direction at mobile (e.g., crop to a taller aspect ratio to keep the subject framed).
- Media maintains its aspect ratio across breakpoints; only scale changes.
- Lazy-load by default; load the above-the-fold hero eagerly.

## Iteration Guide

1. Work on ONE component at a time. Reference its YAML key directly (`{component.section-tile-dark}`, `{component.search-input}`).
2. Variants of a component (`-active`, `-focus`, `-error`, `-2`) live as separate entries under `components:`.
3. Use `{token.refs}` everywhere — never inline a raw hex, size, or radius.
4. Document default and active/pressed states only (plus focus/error for inputs). Skip hover.
5. Keep the display↔text typographic boundary: display tokens run 600–700 with negative tracking; text tokens run 400–600 at neutral tracking.
6. `{elevation.content}` is for media; `{elevation.overlay}` is for floating layers. Don't promote a static card to either.
7. When in doubt about emphasis, alternate the surface (light → dark) before adding chrome.
8. The only brand decision is the accent — keep `brand-primary` single and consistent; resist adding a second.

## Notes & Extension Points

- **Brand accent is undefined on purpose.** The four `TBD` tokens (`brand-primary`, `brand-primary-focus`, `brand-on-dark`, `focus-ring`) are the system's single configuration step.
- **Dark mode.** The dark surfaces here are a design device (alternating sections), not a full dark *theme*. For a true dark mode, add a parallel set of semantic aliases (canvas/ink/hairline inverted) rather than re-coloring components.
- **Status & forms** are an optional layer: status colors plus input focus/error states are provided so feedback isn't bolted on later; remove them on surfaces that don't need them.
- **Motion** is intentionally minimal: a press-scale plus two durations and easings. Add transitions by referencing `{motion.*}` rather than hardcoding timings.
- **Backdrop-blur radius** for frosted surfaces is platform-dependent; `saturate(180%) blur(20px)` is a reliable baseline. Formalize it as a token if you use it in more than one place.
- **Density** can be raised globally by stepping `{spacing.section}` down (80 → 64) and headline sizes down one rung — the system is tuned for low density but holds together denser.