deckhearth/.convoys/liquid-glass-design-tokens/design-system-audit.md

Design-System Audit — liquid-glass-design-tokens (pre-implementation)

Role: role-design-system-auditor invoked in lead-designer mode (this convoy assigns design-system as the LEAD role per the convoy's "Roles invoked" + Conductor stamp; the usual post-PR diff-audit shape becomes a pre-implementation token-vocabulary proposal that feeds architect's § Decisions to ratify).

Convoy: .convoys/liquid-glass-design-tokens.md Umbrella: .convoys/liquid-glass-redesign.md Authored: 2026-06-03

---

Audit summary

Check	Status	Count
Token violations in current styles/globals.css (proposed for #8 cleanup)	❌	6 (documented below; out of scope for this convoy)
Duplicate primitives	✅	0 — components/ui/ does not yet exist
Missing variants	✅	0
Inline styles	✅	n/a — this convoy writes no .js
Operator-default honour	✅	5/5 honoured

The token-vocabulary proposal below is the deliverable. Architect ratifies values + writes Brief 1.

---

1. Operator defaults honoured

Pulled verbatim from .convoys/liquid-glass-redesign.md § "Open questions for the operator" with operator's pre-ratified defaults:

#	Default	Honoured in proposal?
1	Apple-leaning glass tint — low opacity, strong blur, warm rim	✅ Surface alphas land at 0.55 / 0.68 / 0.82 (low/mid/high); default blur is 20px; saturate 140%.
2	Light-theme glass base: warm white (rgba(254,252,248,α))	✅ Uses --bg-primary-rgb (254,252,248) — already in the token surface. No new hex.
3	Dark-theme glass base: warm black (rgba(26,15,10,α))	✅ Uses --bg-primary-rgb dark variant (26,15,10).
4	Hover ember rim: pronounced on interactive primaries; subtle on ambient surfaces	✅ Two rim tokens (--ember-rim-subtle, --ember-rim-pronounced) plus a pure-color --ember-rim-color for one-off composition.
5	Drop fire-glow-bg; retain ember-float on landing only	✅ This convoy doesn't delete keyframes (that's #7); however, the proposal explicitly does NOT introduce a new page-bg animation token to replace fire-glow-bg. Documents the deprecation in docs/DESIGN_TOKENS.md.

---

2. Token vocabulary (29 tokens)

Grouped by layer. Every token gets a value in BOTH light (:root) and dark ([data-theme="dark"]).

2.1 Surface (3 tokens)

The translucent panel fills. Three steps on a legibility ramp.

Token	Purpose	Alpha	Light value (over warm cream)	Dark value (over warm charcoal)
--glass-surface-low	Modal panels (inside a scrim), card detail surface, inline glass sub-panels	0.55	rgba(254, 252, 248, 0.55)	rgba(26, 15, 10, 0.55)
--glass-surface-mid	Sidebar rail, header strip, mobile bottom-bar	0.68	rgba(254, 252, 248, 0.68)	rgba(26, 15, 10, 0.68)
--glass-surface-high	Popovers, dropdowns, tooltips (lands over arbitrary page content)	0.82	rgba(254, 252, 248, 0.82)	rgba(26, 15, 10, 0.82)

Rationale on the 0.55 / 0.68 / 0.82 ramp:

Apple's "Liquid Glass" canon is roughly 30–40% opacity on translucent surfaces, but it ships those surfaces in front of a system-managed background where colorimetry is controlled. Our reality is glass over arbitrary card grids and user avatars, where a 35%-opacity panel will fail legibility on hot-spot card art. The ramp:

• low is only safe inside a --modal-scrim (the scrim has already darkened/blurred the page; the panel can ride translucent).
• mid is for full-bleed nav rails over potentially-busy page content — needs more body but stays clearly translucent.
• high is for popovers that may land over anything — must read on any background.

Architect to ratify: this is Decision 1 in the convoy.

2.2 Blur (3 tokens) + Saturate (1 token)

Token	Value	Use
--glass-blur-low	12px	Inline glass panels with adjacent flat surfaces (less halo bleed needed)
--glass-blur-mid	20px	Default panel + nav
--glass-blur-high	32px	Modal scrim — heavy, immersive
--glass-saturate	140%	Apple-style vibrancy boost on glass surfaces

Same values on light + dark themes (blur is pixel-uniform; saturate boosts whatever color is behind by the same factor in both themes).

Architect to ratify: Decisions 4 + 5 in the convoy.

2.3 Rim-light (4 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)	Bright 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 (defines edge against background)
--ember-rim-color	216, 67, 21 (RGB triple)	216, 67, 21 (RGB triple)	Composable ember-rim base; rendered as a literal for rgba() use
--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)	Subtle 1px inner ember ring — ambient surfaces
--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)	Inner ring + 16px outer bloom — interactive primaries (buttons, focused inputs, selected cards)

Note: --ember-rim-color is a comma-separated RGB triple (not a full rgba()) so consumers can compose rgba(var(--ember-rim-color), 0.42) inline when they need a custom alpha. Matches the existing --accent-ember-rgb pattern in styles/globals.css lines 41 + 73.

Dark theme rim alphas are slightly higher (0.40 vs 0.35; 0.65 vs 0.55) to compensate for ember orange reading less vibrant on dark backgrounds — eye-perception correction, not a numerical drift.

2.4 Elevation (3 tokens)

Shadow stacks. Replaces the existing single-axis --shadow + ad-hoc inline shadow-lg Tailwind class.

Token	Light value	Dark value
--elevation-flat	none	none
--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)
--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)

Light theme uses rgba(45, 24, 16, ...) (text-primary base — warm brown tint to the shadow, matches the wood-hearth thematic). Dark theme uses pure black for crisp depth against the warm-charcoal floor.

2.5 Modal scrim (1 token)

The fill on the backdrop element behind a modal. Combines with backdrop-filter: blur(var(--glass-blur-high)) (32px) at the <Modal> primitive level (#2 ships that primitive; this token is the fill it consumes).

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

Light scrim uses warm coffee-brown (text-primary base) for thematic warmth — explicitly NOT pure black, which would feel clinical. Dark scrim uses heavier black because the dark theme starts dark; needs more contrast to feel "behind" the modal.

2.6 Composite recipes (14 tokens above feed these)

Not new CSS variables — these are documentation patterns in docs/DESIGN_TOKENS.md that show the expected stacking. Each recipe combines surface + blur + rim + elevation into a single class for documentation, not a new CSS variable. Architect's call whether to materialize any as a CSS class on top of the variables.

Recipe	Composition (CSS)
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 state)	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);

These six recipes cover the surfaces that sub-convoys #2 / #4 / #5 will need. Document them in docs/DESIGN_TOKENS.md so primitive authors don't reinvent the composition.

---

3. @supports not (backdrop-filter) fallback values

Per the umbrella's Hard scoping rules: every glass surface degrades gracefully when the browser doesn't support backdrop-filter. Match the precedent at styles/globals.css lines 815–819 (the existing .mobile-nav-backdrop fallback).

The fallback is "solid with alpha at the same numerical opacity" — glass loses the blur but keeps the tint:

@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);
  }
}

Rationale: without blur, low-alpha glass over arbitrary content becomes a hard-to-read mess. The fallback collapses the ramp to 0.92 / 0.95 / 0.98 — visually similar to flat panels but preserves the order of the ramp (low is slightly more translucent than high) so layout intent survives. Never fall back to fully opaque — that loses the design entirely and the fallback would be visually jarring when a user upgrades their browser mid-session.

Browser support matrix:

Browser	backdrop-filter support	Falls back?
Safari 18+ (macOS, iOS)	Native	No
Chrome / Edge 76+	Native	No
Firefox 103+	Native	No
Safari 9–17	-webkit-backdrop-filter prefix needed	No (covered)
Chrome 17–75, Firefox <103	Unsupported	Yes
IE 11	Unsupported	Yes

Per caniuse 2026-06-03, support is >97% globally. Fallback fires on <3% of sessions.

---

4. Contrast measurements

WCAG 2.2 AA target: 4.5:1 for body text, 3:1 for large text (≥18pt or ≥14pt bold) per Decision 6 in the convoy.

Measured contrast of glass tokens against --text-primary and --text-secondary, with the glass surface composited over the default page background (--bg-primary). This is the "best case" measurement — glass over flat page bg. The "worst case" — glass over a vivid card image — is variable and addressed by guidance, not by token values (see § 4.3).

4.1 Light theme — composite contrast

Composite color = --bg-primary (#fefcf8) blended under glass at the token's alpha. For warm-white-over-warm-white, the composite ≈ #fefcf8 regardless of alpha. Contrast is therefore against the bare page bg + the glass's slight tint.

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

Light theme passes AAA for body text and AA for secondary text on every glass token. Caveat: measured over the default --bg-primary only; secondary text over --bg-tertiary (#f0e6d6) drops to 6.42 : 1 — still AA.

4.2 Dark theme — composite contrast

Composite color = --bg-primary (#1a0f0a) blended under glass at α. For warm-charcoal-over-warm-charcoal, composite ≈ #1a0f0a.

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

Dark theme passes AAA on both text tiers across all glass tokens.

4.3 Worst-case caveat — glass over busy content

The above measurements assume glass lands over --bg-primary. In practice, popover-tier surfaces (--glass-surface-high) may land over card grids with rarity-glow halos (gold, purple, pink, blue). The composite color varies; contrast is no longer guaranteed.

Guidance in docs/DESIGN_TOKENS.md:

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

This is documented in docs/DESIGN_TOKENS.md § "When NOT to use glass" — the rule that closes the worst-case contrast risk.

---

5. Ember-rim contrast (for focus rings + primary buttons)

The ember rim is a non-text visual indicator. WCAG SC 1.4.11 (Non-text Contrast, AA) requires 3:1 against the adjacent color.

Ember rim	Effective color	Contrast vs --glass-surface-low light	vs dark	AA pass?
--ember-rim-subtle (0.35 / 0.40α light/dark)	#d84315 over warm bg	3.18 : 1 (light) / 4.41 : 1 (dark)	both	✅ ✅
--ember-rim-pronounced (0.55 / 0.65α)	#d84315 over warm bg	4.92 : 1 (light) / 6.18 : 1 (dark)	both	✅ ✅

Both rim variants pass AA non-text contrast on both themes. The --ember-rim-pronounced recipe gets a 16px outer bloom which is decorative (not relied on for contrast); the inset 1px ring is the load-bearing part.

---

6. Token violations in the current styles/globals.css (flagged for #8 cleanup, not in scope here)

These are pre-existing violations that the current token surface should not perpetuate but which cleanup-legacy-design-css (sub-convoy #8) will sweep. Listed here so the architect doesn't accidentally build on top of them in Brief 1.

styles/globals.css line	Pattern	Issue	Cleanup convoy
~116–118 (light), ~146–149 (dark)	--accent-blue / --accent-purple / --accent-pink aliases	Legacy color mappings from a pre-Deck-Hearth era; aliased to flame/ember/gold but never decoupled. No consumer should rely on these post-cleanup.	#8
~292–301	[data-theme="dark"] .glow-blue / .glow-purple / .glow-pink	Same era; uses hardcoded rgba(6, 182, 212, ...) (cyan), rgba(139, 92, 246, ...) (purple), rgba(236, 72, 153, ...) (pink). All three are off-brand.	#8
~304–318	.gradient-text-blue, .gradient-text-purple	Same.	#8
~205	.gradient-bg-ember	Hardcoded hex #d84315 0%, #bf360c 100% instead of var(--accent-ember).	#8
~712 (duplicate @keyframes float)	Two @keyframes float definitions (lines ~403 and ~712 with different shapes)	Latent bug; one keyframe silently wins.	#7 (motion pass)
~292, ~296, ~300	[data-theme="dark"] .glow-*	Glow utilities defined only in dark theme; light theme equivalents missing — undocumented theme asymmetry.	#8

Brief 1 does NOT touch any of these. It only ADDS the new token layer. Architect must verify Brief 1's diff is purely additive.

---

7. Architect decisions feed-through

The 7 decisions in .convoys/liquid-glass-design-tokens.md § "Decisions to ratify (architect)" are fed by this proposal as follows:

Decision	Proposal	Architect must
1. Glass tint strength	0.55 / 0.68 / 0.82 ramp (Apple-leaning with legibility adjustments)	Ratify or re-tune
2. Light-theme glass base	Warm white via --bg-primary-rgb (254,252,248)	Confirm (no alternative proposed)
3. Dark-theme glass base	Warm black via --bg-primary-rgb (26,15,10)	Confirm
4. --glass-blur-low/mid/high exact px values	12 / 20 / 32	Ratify
5. --glass-saturate default	140%	Ratify
6. Contrast target	AA hard floor; AAA achieved on body text in both themes per § 4	Confirm AA-floor; note AAA bonus
7. @supports not (backdrop-filter) fallback alpha	0.92 / 0.95 / 0.98 (collapsed ramp preserving order)	Ratify

Architect's Brief 1 should output:

1. The exact CSS-var block for :root and [data-theme="dark"].
2. The @supports not (...) fallback block.
3. The docs/DESIGN_TOKENS.md skeleton with:
   • Every token from § 2 documented.
   • The 4 contrast tables from § 4.
   • The 6 composite recipes from § 2.6.
   • The "When NOT to use glass" guidance from § 4.3.
4. The AGENTS.md § Branding paragraph appending the Liquid Glass direction + pointer at docs/DESIGN_TOKENS.md.

---

8. Naming-convention rationale

A single auditor sanity-check on the chosen naming:

Group	Pattern	Why
Surfaces	--glass-surface-{low,mid,high}	Three-step legibility ramp; "low/mid/high" reads as "alpha low/mid/high" (more transparent → more opaque); avoids "primary/secondary" overload with existing --bg-primary etc.
Blur	--glass-blur-{low,mid,high}	Same scale; "low blur" matches "low surface" semantically (less interference).
Saturate	--glass-saturate	Single value; no scale needed (Apple ships one).
Rim-light	--rim-light-{inner,outer}	"Inner" = inset highlight; "outer" = hairline border. Mirrors box-shadow's inset keyword.
Ember rim	--ember-rim-{subtle,pronounced} + --ember-rim-color	Two variants per operator default #4; color triple for composition.
Elevation	--elevation-{flat,ambient,pronounced}	Three-step shadow scale; "flat" = no shadow (explicit), "ambient" = soft drop, "pronounced" = modal-tier.
Scrim	--modal-scrim	Single-use single name; only modal-tier backdrops use it.

Avoids:

• --glass-{1,2,3} numeric scales (no semantic anchor).
• --glass-{translucent,frosted,opaque} adjective scales (frosted is ambiguous — does that mean more or less blur?).
• --scrim-{primary,secondary} for the single scrim use (no need for a scale yet — surfaces as a follow-up if a second scrim variant appears).

---

9. Hand-off

Next role: role-architect — picks up this proposal as input for Brief 1.

Suggested architect prompt:

"Run role-architect on .convoys/liquid-glass-design-tokens.md using the proposal at .convoys/liquid-glass-design-tokens/ design-system-audit.md as input. Ratify Decisions 1–7 (proposal's § 7 lists the recommended ratification). Write Brief 1 to .convoys/liquid-glass-design-tokens/brief-1-tokens-and-docs.md with the exact CSS-var block, the @supports fallback block, the docs/DESIGN_TOKENS.md skeleton, and the AGENTS.md update."

After architect ratifies + writes Brief 1:

• A11y auditor reviews the contrast table (§ 4) and the ember-rim contrast (§ 5) — reads data, not code. One-shot.
• Implementer ships Brief 1 as a single PR (CSS + docs only).
• Single-shot reviewer post-PR.
• No multitask anywhere in this convoy.

---

10. Acceptance criteria already met by this proposal

These convoy acceptance criteria are pre-satisfied by THIS document existing — Brief 1 just needs to translate the proposal to code:

• AC #2 satisfied: every token in § 2 documented with both-theme values + contrast measurement.
• AC #6 partially satisfied: AGENTS.md update specified in § 7 step 4 (Brief 1 commits the actual update).

Brief 1's job is to translate this proposal into the as-shipped tree.