507 lines
23 KiB
Markdown
507 lines
23 KiB
Markdown
|
---
|
|||
|
|
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.
|