---
convoy: liquid-glass-design-tokens
brief_number: 1
depends_on: []
files:
  - styles/globals.css
  - docs/DESIGN_TOKENS.md
  - AGENTS.md
---

# Brief 1: Tokens and Docs

## Goal (1 sentence)

Add the canonical Liquid Glass CSS-variable layer to `styles/globals.css`
(both themes + `@supports` fallback), create `docs/DESIGN_TOKENS.md` as
the reference document, and append a `## Visual language` section to
`AGENTS.md` — touching zero `.js` files and shipping zero visual diff.

## Files in scope (do not edit anything else)

- `styles/globals.css` — modified. Adds **one** new well-delimited block
  (29 new CSS variables) and **one** `@supports not (...)` fallback
  block. Pre-existing rules untouched.
- `docs/DESIGN_TOKENS.md` — new. Reference doc per § "docs/DESIGN_TOKENS.md
  skeleton" below.
- `AGENTS.md` — modified. Insert a new `## Visual language` section
  between the existing `## Product vocabulary` (ends line ~27) and
  `## 1. Project overview` (line 29).

**Out of scope:** any file in `components/**`, `pages/**`, `lib/**`,
`test/**`. Any change to existing tokens / utility classes / keyframes
in `styles/globals.css`. Any deletion. See § "Anti-scope" below.

## Conventions to follow

- **Theme-token discipline** (`.cursor/rules/ui-and-theming.mdc`): no
  hardcoded hex in `.js` files — N/A here (no `.js` touched), but the
  new tokens themselves embed hex inside `rgba()` triples; that is the
  canonical pattern, see `styles/globals.css` lines 25–35 for precedent.
- **Theme symmetry** (`.cursor/rules/ui-and-theming.mdc`): every new
  variable that's color-dependent MUST get a value in BOTH `:root` and
  `[data-theme="dark"]`. Theme-independent values (blur px, saturate
  percentage) live only in `:root` and are inherited.
- **No-go zones** (`.cursor/rules/no-go-zones.mdc`): `styles/globals.css`
  is NOT a no-go zone; safe to edit. `AGENTS.md` is the canonical agent
  contract — edits go through the documented sections.
- **JavaScript-only repo** (`AGENTS.md` Gotcha #9): do not introduce
  any `.ts` / `.tsx` file. N/A here (no `.js` either).

## Verbatim CSS to add to `styles/globals.css`

**Insertion point**: append AFTER the existing
`[data-theme="dark"] { ... }` block that ends at line 74 (the block
that defines `--bg-primary-dark` through `--accent-ember-rgb`) and
BEFORE the existing `/* Apply theme colors */` block at line 76. This
keeps the token-definition section contiguous.

Add a clear comment fence so the block is greppable + recognizable:

```css
/* ============================================================
   Liquid Glass tokens — added by liquid-glass-design-tokens convoy
   (2026-06-03). See docs/DESIGN_TOKENS.md for the full reference,
   contrast tables, composite recipes, and "When NOT to use glass"
   guidance.
   ============================================================ */

:root {
  /* Glass surfaces (light) — 3-step legibility ramp.
     low:  modal panels inside a scrim, card detail, inline sub-panels.
     mid:  sidebar rail, header strip, mobile bottom-bar.
     high: popovers, dropdowns, tooltips (can land over anything). */
  --glass-surface-low:  rgba(254, 252, 248, 0.55);
  --glass-surface-mid:  rgba(254, 252, 248, 0.68);
  --glass-surface-high: rgba(254, 252, 248, 0.82);

  /* Glass blur + saturate (theme-independent; inherited by dark). */
  --glass-blur-low:  12px;
  --glass-blur-mid:  20px;
  --glass-blur-high: 32px;
  --glass-saturate:  140%;

  /* Rim-light (light) — inner highlight + outer hairline. */
  --rim-light-inner: inset 0 1px 0 0 rgba(255, 255, 255, 0.65);
  --rim-light-outer: 0 0 0 1px rgba(45, 24, 16, 0.08);

  /* Ember rim — composable RGB triple + two preset variants.
     Triple is theme-independent (ember orange #d84315);
     variants differ per theme for eye-perception correction. */
  --ember-rim-color: 216, 67, 21;
  --ember-rim-subtle: inset 0 0 0 1px rgba(216, 67, 21, 0.35);
  --ember-rim-pronounced:
    inset 0 0 0 1px rgba(216, 67, 21, 0.55),
    0 0 16px 0 rgba(216, 67, 21, 0.30);

  /* Elevation (light) — warm-brown-tinted shadows. */
  --elevation-flat: none;
  --elevation-ambient:
    0 4px 12px -2px rgba(45, 24, 16, 0.08),
    0 2px 4px -1px rgba(45, 24, 16, 0.04);
  --elevation-pronounced:
    0 24px 48px -12px rgba(45, 24, 16, 0.20),
    0 12px 24px -6px rgba(45, 24, 16, 0.10),
    0 4px 8px -2px rgba(45, 24, 16, 0.06);

  /* Modal scrim (light) — warm coffee-brown, NOT pure black. */
  --modal-scrim: rgba(45, 24, 16, 0.35);
}

[data-theme="dark"] {
  /* Glass surfaces (dark) — same alpha ramp over warm-charcoal base. */
  --glass-surface-low:  rgba(26, 15, 10, 0.55);
  --glass-surface-mid:  rgba(26, 15, 10, 0.68);
  --glass-surface-high: rgba(26, 15, 10, 0.82);

  /* Rim-light (dark) — softer warm-white inner + faint outer. */
  --rim-light-inner: inset 0 1px 0 0 rgba(255, 248, 240, 0.12);
  --rim-light-outer: 0 0 0 1px rgba(255, 248, 240, 0.06);

  /* Ember rim (dark) — alpha bumped to compensate for ember orange
     reading less vibrant on dark backgrounds (eye-perception correction,
     not a numerical drift). RGB triple inherits from :root. */
  --ember-rim-subtle: inset 0 0 0 1px rgba(216, 67, 21, 0.40);
  --ember-rim-pronounced:
    inset 0 0 0 1px rgba(216, 67, 21, 0.65),
    0 0 16px 0 rgba(216, 67, 21, 0.35);

  /* Elevation (dark) — pure-black shadows for crisp depth against
     the warm-charcoal floor. */
  --elevation-ambient:
    0 4px 12px -2px rgba(0, 0, 0, 0.40),
    0 2px 4px -1px rgba(0, 0, 0, 0.30);
  --elevation-pronounced:
    0 24px 48px -12px rgba(0, 0, 0, 0.55),
    0 12px 24px -6px rgba(0, 0, 0, 0.40),
    0 4px 8px -2px rgba(0, 0, 0, 0.25);

  /* Modal scrim (dark) — heavier black; dark theme starts dark so
     needs more contrast to feel "behind" the modal. */
  --modal-scrim: rgba(0, 0, 0, 0.55);
}

/* Fallback for browsers without backdrop-filter support (<3% of
   sessions per caniuse 2026-06-03). Collapses the alpha ramp toward
   solid so glass surfaces remain legible without the blur layer.
   Never goes fully opaque — preserves the design's tinted-surface
   intent and the ramp ordering. The @supports negation guards both
   the unprefixed property AND -webkit-backdrop-filter (Safari 9-17
   needed the prefix). */
@supports not ((backdrop-filter: blur(20px)) or (-webkit-backdrop-filter: blur(20px))) {
  :root {
    --glass-surface-low:  rgba(254, 252, 248, 0.92);
    --glass-surface-mid:  rgba(254, 252, 248, 0.95);
    --glass-surface-high: rgba(254, 252, 248, 0.98);
  }
  [data-theme="dark"] {
    --glass-surface-low:  rgba(26, 15, 10, 0.92);
    --glass-surface-mid:  rgba(26, 15, 10, 0.95);
    --glass-surface-high: rgba(26, 15, 10, 0.98);
  }
}
```

**Sanity check** before committing: the new block is purely **additive**.
No existing line in `styles/globals.css` should be deleted or modified.
`git diff styles/globals.css` should show only insertions in this block's
region.

## `docs/DESIGN_TOKENS.md` — full content

Create this file at `docs/DESIGN_TOKENS.md` (the `docs/` directory
already exists per repo layout). Use the exact content below:

````markdown
# Design tokens — Deck Hearth

Reference for the design-token surface. The canonical product brand is
**Deck Hearth** (post-`pick-a-name` PR #21, 2026-05-24); the visual
direction is **Liquid Glass** (post-`liquid-glass-design-tokens` PR
TBD, 2026-06-03 — see `.convoys/liquid-glass-redesign.md`).

Every color token is defined in `styles/globals.css` and consumed via
`var(--token-name)`. **Do not** hardcode hex in `.js` files; the post-
`cleanup-legacy-design-css` `forbidden-hex-in-jsx` lint gate will fail
the build (see `.convoys/cleanup-legacy-design-css.md` for the planned
gate).

## Layer overview

| Layer | Purpose | Tokens |
| --- | --- | --- |
| Base palette | Theme-tuned background + text + accent colors | `--bg-*`, `--text-*`, `--accent-*`, `--border` — pre-existing |
| Surface (glass) | Translucent panel fills | `--glass-surface-{low,mid,high}` |
| Blur + saturate | `backdrop-filter` ingredients | `--glass-blur-{low,mid,high}`, `--glass-saturate` |
| Rim-light | Edge definition on glass surfaces | `--rim-light-{inner,outer}` |
| Ember rim | Brand-accent rings for interactive primaries | `--ember-rim-color` (RGB triple), `--ember-rim-{subtle,pronounced}` |
| Elevation | Shadow stacks | `--elevation-{flat,ambient,pronounced}` |
| Modal scrim | Backdrop fill behind modals | `--modal-scrim` |

## Surface tokens

Three-step legibility ramp. Higher number = more opaque.

| Token | Light value | Dark value | Use |
| --- | --- | --- | --- |
| `--glass-surface-low` | `rgba(254, 252, 248, 0.55)` | `rgba(26, 15, 10, 0.55)` | Modal panels (inside a scrim), card detail, inline glass sub-panels |
| `--glass-surface-mid` | `rgba(254, 252, 248, 0.68)` | `rgba(26, 15, 10, 0.68)` | Sidebar rail, header strip, mobile bottom-bar |
| `--glass-surface-high` | `rgba(254, 252, 248, 0.82)` | `rgba(26, 15, 10, 0.82)` | Popovers, dropdowns, tooltips |

Always paired with `backdrop-filter: blur(...) saturate(var(--glass-saturate))`.

## Blur + saturate tokens

| Token | Value | Use |
| --- | --- | --- |
| `--glass-blur-low` | `12px` | Inline glass panels with adjacent flat surfaces |
| `--glass-blur-mid` | `20px` | Default panel + nav |
| `--glass-blur-high` | `32px` | Modal scrim — heavy, immersive |
| `--glass-saturate` | `140%` | Vibrancy boost on all glass surfaces |

Theme-independent (same value in both themes).

## Rim-light tokens

The hairline edges that define a glass surface against the background.

| Token | Light value | Dark value | Use |
| --- | --- | --- | --- |
| `--rim-light-inner` | `inset 0 1px 0 0 rgba(255, 255, 255, 0.65)` | `inset 0 1px 0 0 rgba(255, 248, 240, 0.12)` | Top-edge inner highlight (light cast onto glass from above) |
| `--rim-light-outer` | `0 0 0 1px rgba(45, 24, 16, 0.08)` | `0 0 0 1px rgba(255, 248, 240, 0.06)` | Hairline outer ring |

Consumed inside `box-shadow:` lists, typically together: `box-shadow:
var(--rim-light-inner), var(--rim-light-outer), var(--elevation-ambient);`.

## Ember rim tokens

Brand-accent rings. Pronounced on interactive primaries; subtle on
ambient surfaces.

| Token | Light value | Dark value | Use |
| --- | --- | --- | --- |
| `--ember-rim-color` | `216, 67, 21` (RGB triple) | same | Composable: `rgba(var(--ember-rim-color), 0.42)` for custom alphas |
| `--ember-rim-subtle` | `inset 0 0 0 1px rgba(216, 67, 21, 0.35)` | `inset 0 0 0 1px rgba(216, 67, 21, 0.40)` | Ambient surfaces (nav rail rest state, header) |
| `--ember-rim-pronounced` | `inset 0 0 0 1px rgba(216, 67, 21, 0.55), 0 0 16px 0 rgba(216, 67, 21, 0.30)` | `inset 0 0 0 1px rgba(216, 67, 21, 0.65), 0 0 16px 0 rgba(216, 67, 21, 0.35)` | Interactive primaries (buttons, focused inputs, selected cards) |

Dark theme rim alphas are slightly higher to compensate for ember orange
reading less vibrant on dark backgrounds (eye-perception correction).

## Elevation tokens

| Token | Light value | Dark value | Use |
| --- | --- | --- | --- |
| `--elevation-flat` | `none` | `none` | Explicit "no shadow" (inline glass sub-panels) |
| `--elevation-ambient` | `0 4px 12px -2px rgba(45, 24, 16, 0.08), 0 2px 4px -1px rgba(45, 24, 16, 0.04)` | `0 4px 12px -2px rgba(0, 0, 0, 0.40), 0 2px 4px -1px rgba(0, 0, 0, 0.30)` | Default elevated surfaces (popovers, sidebar) |
| `--elevation-pronounced` | `0 24px 48px -12px rgba(45, 24, 16, 0.20), 0 12px 24px -6px rgba(45, 24, 16, 0.10), 0 4px 8px -2px rgba(45, 24, 16, 0.06)` | `0 24px 48px -12px rgba(0, 0, 0, 0.55), 0 12px 24px -6px rgba(0, 0, 0, 0.40), 0 4px 8px -2px rgba(0, 0, 0, 0.25)` | Modal panels, card detail full view |

Light theme uses warm-brown-tinted shadows (`rgba(45, 24, 16, ...)`)
for thematic consistency. Dark theme uses pure black for crisp depth.

## Modal scrim token

| Token | Light value | Dark value |
| --- | --- | --- |
| `--modal-scrim` | `rgba(45, 24, 16, 0.35)` | `rgba(0, 0, 0, 0.55)` |

Combined with `backdrop-filter: blur(var(--glass-blur-high))` (32px)
at the `<Modal>` primitive level (sub-convoy #2 ships that primitive).

## Composite recipes

Six common compositions. These are documentation patterns — they're
NOT new CSS variables. Primitive authors compose them as shown.

| Recipe | CSS composition |
| --- | --- |
| Modal scrim | `background: var(--modal-scrim); backdrop-filter: blur(var(--glass-blur-high)) saturate(var(--glass-saturate));` |
| Modal panel | `background: var(--glass-surface-low); backdrop-filter: blur(var(--glass-blur-mid)) saturate(var(--glass-saturate)); box-shadow: var(--rim-light-inner), var(--rim-light-outer), var(--elevation-pronounced);` |
| Sidebar rail | `background: var(--glass-surface-mid); backdrop-filter: blur(var(--glass-blur-mid)) saturate(var(--glass-saturate)); box-shadow: var(--rim-light-inner), var(--rim-light-outer);` |
| Popover | `background: var(--glass-surface-high); backdrop-filter: blur(var(--glass-blur-mid)) saturate(var(--glass-saturate)); box-shadow: var(--rim-light-inner), var(--ember-rim-subtle), var(--elevation-ambient);` |
| Glass button (primary, hover) | `background: var(--glass-surface-high); backdrop-filter: blur(var(--glass-blur-low)) saturate(var(--glass-saturate)); box-shadow: var(--rim-light-inner), var(--ember-rim-pronounced);` |
| Glass card detail | `background: var(--glass-surface-low); backdrop-filter: blur(var(--glass-blur-mid)) saturate(var(--glass-saturate)); box-shadow: var(--rim-light-inner), var(--rim-light-outer), var(--elevation-pronounced);` |

## Contrast measurements (WCAG 2.2 AA target)

Glass surfaces composited over the **default** `--bg-primary` (best
case). For the "glass over busy card art" worst case, see § "When NOT
to use glass" below.

### Light theme

| Glass token | vs `--text-primary` (#2d1810) | vs `--text-secondary` (#5d4037) | AA pass? |
| --- | --- | --- | --- |
| `--glass-surface-low` (α=0.55) | 15.18 : 1 | 6.86 : 1 | ✅ ✅ AAA / AA |
| `--glass-surface-mid` (α=0.68) | 15.18 : 1 | 6.86 : 1 | ✅ ✅ |
| `--glass-surface-high` (α=0.82) | 15.18 : 1 | 6.86 : 1 | ✅ ✅ |
| Fallback (α=0.92) | 15.18 : 1 | 6.86 : 1 | ✅ ✅ |

### Dark theme

| Glass token | vs `--text-primary` (#fff8f0) | vs `--text-secondary` (#d7c4b0) | AA pass? |
| --- | --- | --- | --- |
| `--glass-surface-low` (α=0.55) | 17.84 : 1 | 11.42 : 1 | ✅ ✅ AAA / AAA |
| `--glass-surface-mid` (α=0.68) | 17.84 : 1 | 11.42 : 1 | ✅ ✅ |
| `--glass-surface-high` (α=0.82) | 17.84 : 1 | 11.42 : 1 | ✅ ✅ |
| Fallback (α=0.92) | 17.84 : 1 | 11.42 : 1 | ✅ ✅ |

### Ember rim (WCAG SC 1.4.11 — non-text contrast, AA = 3:1)

| Rim token | Light contrast | Dark contrast | AA pass? |
| --- | --- | --- | --- |
| `--ember-rim-subtle` | 3.18 : 1 | 4.41 : 1 | ✅ ✅ |
| `--ember-rim-pronounced` | 4.92 : 1 | 6.18 : 1 | ✅ ✅ |

## When NOT to use glass

The contrast measurements above assume glass over `--bg-primary`.
Glass over arbitrary card grids or vibrant card images is not
guaranteed-legible. Four rules:

1. **`--glass-surface-low`** — ONLY use inside a `--modal-scrim` (the
   scrim pre-darkens / pre-blurs the page; contrast becomes predictable).
2. **`--glass-surface-mid`** — Use over surfaces that are themselves
   flat (sidebar rails over the page background; NOT over card grids).
3. **`--glass-surface-high`** — Use for popovers, but ensure the popover's
   contents would hit 4.5:1 against `--bg-primary` directly. At 0.82α
   the surface is functionally a tinted-flat panel.
4. **Never** place body text on a glass surface positioned over a card
   grid without an opaque inner panel.

## Per-card grid performance budget

`backdrop-filter` is GPU-expensive. Stacked instances on long card
grids hurt scroll performance.

- **Card grid items** (`components/CardItem.js`): NO `backdrop-filter`.
  Solid `--bg-secondary` background + cheap shadow + rarity glow.
- **Card grid containers** (the wrapping panel): MAY use glass.
- **Card detail view** (`components/CardDetailView.js`): full glass.
- **Card3D hover preview**: keeps 3D transform; uses
  `--elevation-pronounced` + `--ember-rim-pronounced`; no
  `backdrop-filter`.

This is the contract sub-convoy #5 (`liquid-glass-card-surfaces`)
implements. See `.convoys/liquid-glass-card-surfaces.md` for detail.

## Browser support + fallback

`backdrop-filter` is supported in all evergreen browsers:

| Browser | Support |
| --- | --- |
| Safari 18+ (macOS, iOS) | Native |
| Chrome / Edge 76+ | Native |
| Firefox 103+ | Native |
| Safari 9–17 | `-webkit-backdrop-filter` prefix needed |
| Chrome 17–75, Firefox <103, IE 11 | **Unsupported — fallback fires** |

Global support >97% (caniuse 2026-06-03). Fallback fires on <3% of
sessions and collapses the surface ramp to 0.92 / 0.95 / 0.98 — visually
similar to flat panels but preserves ramp ordering.

## Reduced motion

This document does not document animations — those are governed by
`docs/MOTION_SYSTEM.md` (shipped by sub-convoy #7,
`.convoys/motion-system-pass.md`). When that doc lands, it MUST
respect `@media (prefers-reduced-motion: reduce)` for every animation.

## Deprecations

- **`fire-glow-bg`** (page-level background animation in
  `styles/globals.css` lines ~755–757) — scheduled for deletion by
  `motion-system-pass` (sub-convoy #7). Replacement: localized
  `ember-float` accent on landing hero only. Do NOT consume
  `fire-glow-bg` in new code.
- **`--accent-blue` / `--accent-purple` / `--accent-pink` aliases**
  (`styles/globals.css` lines ~116–118, ~146–149) — scheduled for
  deletion by `cleanup-legacy-design-css` (sub-convoy #8). They alias
  flame/ember/gold and are pre-Deck-Hearth-era debt. Do NOT consume
  in new code; use the canonical `--accent-flame` / `--accent-ember`
  / `--accent-gold` directly.
- **`.gradient-text-blue` / `.gradient-text-purple` / `.glow-blue` /
  `.glow-purple` / `.glow-pink`** — same; deletion in #8.
- **`.fire-glow` / `.ember-glow`** — utility classes superseded by
  `--ember-rim-{subtle,pronounced}`. Deletion in #8.

## Related convoys

- `.convoys/liquid-glass-redesign.md` — umbrella epic.
- `.convoys/liquid-glass-design-tokens.md` — this token surface.
- `.convoys/liquid-glass-modal-and-surface-primitive.md` — `<GlassSurface>` + `<Modal>` primitives consuming these tokens.
- `.convoys/cleanup-legacy-design-css.md` — sweeps deprecations.
- `.convoys/motion-system-pass.md` — motion taxonomy (parallel scope).
````

## AGENTS.md update

Insert this exact section between `## Product vocabulary` (current last
line: ~27) and `## 1. Project overview` (current line: 29). The new
section becomes a sibling to "Product vocabulary" — a documentation
home for visual-system guidance:

```markdown
## Visual language

Deck Hearth's visual direction is **Liquid Glass** (in-progress as of
2026-06-03 — see `.convoys/liquid-glass-redesign.md` umbrella). Every
translucent surface (modals, sidebar, header, popovers, card detail)
composes the canonical token surface defined in `styles/globals.css`
and documented in [`docs/DESIGN_TOKENS.md`](docs/DESIGN_TOKENS.md).
**Do not** hardcode hex in `.js` files; the post-cleanup
`forbidden-hex-in-jsx` gate (sub-convoy #8) will fail the build.

Three rules of thumb:

- **Surfaces are glass.** Modal panels, sidebars, dropdowns, and the
  header strip use `--glass-surface-{low,mid,high}` + `backdrop-filter`
  composition recipes from `docs/DESIGN_TOKENS.md` § "Composite recipes".
- **Brand warmth is accent, not panel fill.** Ember (`#d84315`), flame
  (`#ff6f00`), and gold (`#ffab40`) read as light cast onto glass — via
  `--ember-rim-{subtle,pronounced}` rings, focus glow, and gradient
  buttons. They are **NOT** the canonical panel-background color.
- **No `backdrop-filter` on card grid items.** GPU budget — glass goes
  on grid containers and detail views, not per-card. See
  `docs/DESIGN_TOKENS.md` § "Per-card grid performance budget".

```

## Acceptance criteria

- [ ] `styles/globals.css` contains the verbatim CSS block above —
      added in a comment-fenced region between the existing dark-theme
      `]` (line 74) and the `/* Apply theme colors */` comment (line 76).
- [ ] `styles/globals.css` `git diff` shows **only insertions** — no
      existing line is modified or deleted.
- [ ] `docs/DESIGN_TOKENS.md` exists at `docs/DESIGN_TOKENS.md` with
      the full content above.
- [ ] `AGENTS.md` has a new `## Visual language` section between
      `## Product vocabulary` and `## 1. Project overview` (per
      § "AGENTS.md update").
- [ ] **No `.js` file is modified.** Verify with `git diff --stat
      '*.js'` returning empty.
- [ ] **No existing CSS rule is modified.** Verify the diff against
      `styles/globals.css` shows only additive ranges.
- [ ] `npm run lint` exits 0.
- [ ] `npm run test:run` exits 0 (vitest 21/21).
- [ ] `npm run test:smoke` (against the preview) exits 0 (3/3).
- [ ] `Screenshot diff` workflow on the PR shows **zero or
      trivially-noisy** diff — no rendered pixel should change because
      no consumer of the new tokens is added. Architect must explain any
      non-trivial diff before merge.
- [ ] tests added: N/A (CSS-vars + docs only; no functional surface to
      unit-test in this brief).
- [ ] no scope expansion: no file edited outside `files:` in the
      frontmatter.

## Anti-scope (must not do)

- ❌ Touch any `.js` file under `components/**`, `pages/**`, `lib/**`,
  `test/**`.
- ❌ Delete or modify any existing CSS variable, utility class, or
  keyframe in `styles/globals.css`. The cleanup is sub-convoy #8.
- ❌ Wire `tailwind.config.js` to the new tokens. Pure CSS-var surface
  for v1; the Tailwind extension is a queued follow-up.
- ❌ Create `components/ui/` — that's sub-convoys #2 + #3.
- ❌ Create `docs/MOTION_SYSTEM.md` — that's sub-convoy #7.
- ❌ Add a new keyframe / animation. Motion work is sub-convoy #7.
- ❌ Add a CI grep gate. The `forbidden-*-css` gates land in #8.

## Verification commands (for the implementer to run pre-PR)

```bash
# 1. Confirm only the three in-scope files changed
git diff --stat -- 'components/**' 'pages/**' 'lib/**' 'test/**' '*.js' '*.jsx'
# Expected: empty (no .js / .jsx changes)

git diff --stat
# Expected: 3 files: styles/globals.css, docs/DESIGN_TOKENS.md, AGENTS.md

# 2. Confirm the styles/globals.css diff is purely additive (no deletions)
git diff styles/globals.css | grep -E '^-[^-]' | head
# Expected: empty (only the leading 3-dash --- header lines, no deletions)

# 3. Confirm no consumer of the new tokens was added (would be scope creep)
git diff -- 'components/**' 'pages/**' | grep -E 'var\(--glass-|var\(--rim-light|var\(--ember-rim|var\(--elevation|var\(--modal-scrim'
# Expected: empty

# 4. Lint + test + smoke
npm run lint
npm run test:run
# Smoke needs the preview URL — your call whether to run locally vs let CI handle.
```

## Rationale (≤3 sentences)

This brief lands the token foundation for the Liquid Glass redesign
umbrella as a purely additive, zero-rendered-change PR — the most
conservative possible foundation move, designed to let downstream
sub-convoys (#2 modals, #3 forms, #4 layout, #5 cards, #6 public,
#7 motion) consume a stable, documented vocabulary. The "boot-the-brief"
shape was verified against the audit's contrast measurements and the
existing `styles/globals.css` line topology; no dep changes, no .js
touched, no existing rule deleted. Visual diff is expected to be empty
because no consumer of the new tokens is added in this brief — any
pixel-level diff is a bug and must be explained before merge.