deckhearth/.convoys/liquid-glass-redesign.md

---
name: liquid-glass-redesign
classification: epic
success_metric: |
  Deck Hearth's UI reads as a modern, glass-forward fireplace: every surface
  that previously used opaque warm-cream / wood-grain panels now uses a
  tunable glass token system (translucency + backdrop blur + warm gradient
  rim-light); every modal blurs the page behind it; the brand warmth
  (ember / flame / gold) survives as accent and motion, not as a heavy
  panel fill. Eight sub-convoys ship behind the existing visual-diff +
  smoke + vitest gates; no regression in the launch-readiness checklist.
skip: []
status: open
created: 2026-06-03
---

# Liquid Glass Redesign — design-system epic

Umbrella convoy capturing the full pivot from the current "warm panel +
side-highlight + heavy gradient" visual language to a **Liquid Glass**
aesthetic that retains Deck Hearth's fireplace warmth as accent, gradient,
and motion — not as panel fill. Each lettered section below maps to a
dedicated sub-convoy that an architect will refine and an implementer (or
multitask fleet of implementers) will ship.

This convoy is **planning-only**. No source files are touched here. Each
sub-convoy below is a separate, gated, visual-diff-bounded PR (or
multitask group of PRs).

---

## 1. Vision

The product is **Deck Hearth** — a fireplace. Today the UI renders a
fireplace by making every panel look like wood. That is *thematic but
dated*: it gives every surface the same heavy mass, fights the actual
content (cards, decks, lists), and forces motion / glow to do all the
"modern" work alone.

The new direction is the opposite read of "fireplace":

- The **room** is glass — softly translucent, with the page (the actual
  hearth: cards, deck lists, scan frames) glowing through.
- The **fire** is the accent — ember orange / flame / gold reads as
  *light cast onto* the glass, not *paint applied to* the glass.
- The **warmth** comes from gradients and slow motion, not from beige
  panel fills.

Concretely the visual contract is:

| Layer | Before | After |
| --- | --- | --- |
| Panel fill | Opaque `--bg-secondary` / `--bg-tertiary` warm cream | `rgba(bg-secondary, 0.55–0.75)` + `backdrop-filter: blur(20–32px) saturate(140%)` |
| Border | Solid `--border` wood line | Hairline `1px` inner ring + outer hairline; light theme uses warm-white inner highlight (`rgba(255,255,255,0.55)`) |
| Shadow | Single-axis drop shadow | Stacked elevation: ambient soft outer + accent-tinted rim ("ember rim" on hover/focus) |
| Modal backdrop | Dim overlay only | Blur-and-dim: `backdrop-filter: blur(18px)` + `rgba(bg-primary, 0.4)`; ember vignette toward the center to retain hearth warmth |
| Buttons (primary) | Solid flame gradient pill | Glass pill with ember rim-light gradient on top edge + animated micro-glow on hover; matches Apple-style "Liquid Glass" tinted material |
| Cards (TCG cards) | Heavy ember box shadow + opaque container | Container goes glass; rarity glows REMAIN but tightened (one-shadow stack, reduced bloom) so they read against glass |
| Logo / brand | DH monogram in solid gradient pill | Same monogram, glass pill, inner ember gradient ring |

The deliverable is a **reusable token + primitive kit**, not 50 one-off
class names.

---

## 2. Why now

Three things make this the right moment:

1. **Brand is settled.** `pick-a-name` (PR #21, 2026-05-24) ratified
   Deck Hearth as the canonical name. No more rebranding noise mid-design.
2. **Test infrastructure is in place.** `Screenshot diff` workflow
   (`visual-diff.yml`) fires on every PR touching `pages/**` /
   `components/**` / `styles/**` / `tailwind.config.js` / `postcss.config.js`,
   and `seed-visual-baselines-on-linux` (PR #58, 2026-06-02) shipped the
   first Linux baseline. Smoke (3/3, 2.9s) defends auth + page-render on
   every PR. Vitest (21/21) defends Layout's logged-out branch. A
   design-system redesign without these gates would be reckless; with
   them, it's tractable.
3. **The component fleet is small enough to enumerate.** 42 components in
   `components/`, ~15 modals, 1 Layout, 1 MobileNavigation. The full
   design migration is bounded — not a year-long redesign treadmill.

This convoy does **NOT** ship before the eight P0 ship-blockers (already
**8/8 RESOLVED**, 2026-05-24) and **does** ship in parallel with the
queued P2/P3 polish convoys listed in `.convoys/ship-readiness.md` §
Queued convoys. It does not block launch — but it dramatically raises
the launch-day quality bar.

---

## 3. Hard scoping rules

- **No new third-party CSS framework.** Tailwind + CSS variables stays.
  Liquid Glass is implemented as new tokens + a small primitive set.
- **No TypeScript adoption.** Files stay `.js`. See `AGENTS.md` Gotcha #9.
- **Theme tokens, not hex.** Every new color reads from a CSS variable.
  The hex sweep is a dedicated sub-convoy (#8 below).
- **Both themes ship together.** Light and dark each get their own glass
  recipe — the light theme uses a warm-white inner highlight, dark uses
  a black-glass with ember-rim. Never ship one theme without the other.
- **Brand warmth survives.** Ember (`#d84315` RGB `216,67,21`) and Flame
  (`#ff6f00`) remain the canonical accents. Gold (`#ffab40`) remains for
  rarity / celebration. No new accent hues without operator ratification.
- **Reduced-motion is mandatory.** Every animation introduced honours
  `prefers-reduced-motion`. Existing `fire-glow-bg` and `ember-float`
  animations get audited under #7.
- **Accessibility is non-negotiable.** Glass + warm-cream backgrounds
  often fail AA. Every token comes with a documented contrast measurement
  vs `--text-primary` AND `--text-secondary` in both themes.
- **Browser support.** `backdrop-filter` is supported in all evergreen
  browsers (Safari 18+, Chrome 76+, Firefox 103+). Fallback in
  `@supports not (backdrop-filter: blur(20px)) { ... }` per the existing
  pattern in `styles/globals.css` lines 815–819 — use a solid-with-alpha
  fallback, never a hard-opaque revert.
- **Performance budget.** Stacked `backdrop-filter` on long scroll lists
  is expensive. Card grids may NOT use glass on every card item — glass
  is for the *container*, not every card. The per-card surface stays
  cheap (solid + cheap shadow). The card detail VIEW gets glass.
- **No flag rollout needed.** The repo has no feature-flag wrapper.
  Migration is incremental by sub-convoy; visual diff catches breakage
  per PR; a bad sub-convoy can be reverted independently.
- **One sub-convoy per PR (or per multitask group).** Do not bundle
  primitives + layout + cards into a single PR — visual diff becomes
  unreadable and rollback impossible.

---

## 4. Dependency graph

```
                  ┌────────────────────────────────────────┐
                  │ 1. liquid-glass-design-tokens          │
                  │    (CSS vars + docs; no UI change)     │
                  └──────────────────┬─────────────────────┘
                                     │
                ┌────────────────────┼────────────────────┐
                │                    │                    │
                ▼                    ▼                    ▼
   ┌────────────────────┐  ┌────────────────────┐  ┌──────────────────────┐
   │ 2. modal-and-      │  │ 3. form-primitives │  │ 7. motion-system     │
   │    surface-        │  │    <Button>        │  │    audit + reduced-  │
   │    primitive       │  │    <Input>         │  │    motion sweep      │
   │    <GlassSurface>  │  │    <SearchBar>     │  │                      │
   │    <Modal>         │  │    + sweep         │  │                      │
   │    + modal sweep   │  └─────────┬──────────┘  └──────────┬───────────┘
   └─────────┬──────────┘            │                         │
             │                       │                         │
             ▼                       ▼                         │
   ┌────────────────────┐  ┌────────────────────┐              │
   │ 4. layout-shell    │  │ 5. card-surfaces   │              │
   │    Layout +        │  │    CardItem,       │              │
   │    MobileNav +     │  │    CardDetailView, │              │
   │    header          │  │    Card3D, rarity  │              │
   └─────────┬──────────┘  └─────────┬──────────┘              │
             │                       │                         │
             └──────────┬────────────┘                         │
                        ▼                                      │
              ┌────────────────────┐                           │
              │ 6. public-and-auth │                           │
              │    /, /login,      │                           │
              │    /signup, public │                           │
              │    collection/deck │                           │
              └─────────┬──────────┘                           │
                        │                                      │
                        └──────────┬───────────────────────────┘
                                   ▼
                       ┌────────────────────┐
                       │ 8. cleanup-legacy- │
                       │    design-css      │
                       │    (delete dead    │
                       │    utilities; hex  │
                       │    sweep)          │
                       └────────────────────┘
```

**Strict-blockers:**

- #1 blocks all other sub-convoys (they consume the tokens).
- #2 blocks #4 (Layout consumes `<GlassSurface>`) and #5 (`CardDetailView` modal-like surfaces).
- #4 + #5 block #6 (public + auth pages compose Layout + cards).
- #7 can run in parallel with anything after #1 (it audits motion, not surfaces).
- #8 ships last — it deletes utilities the previous sub-convoys must have stopped using.

**Multitask opportunities:**

- After #1 merges: `/multitask` #2, #3, #7 (disjoint file sets).
- After #2 merges: the **modal sweep** inside #2 itself fans out via
  `/multitask` — one brief per ~3 modals (see #2's seed convoy file).
- After #4 + #5 merge: `/multitask` per-page in #6 (`index`, `login`,
  `signup`, `community/collections`, `community/decks` are file-disjoint).

---

## 5. Sub-convoy summaries

Each sub-convoy has its own `.convoys/<slug>.md` seed file (open status,
awaiting role-conductor refinement when picked up). Brief shape:

### 1. `liquid-glass-design-tokens` (foundation — no UI change)

**File**: `.convoys/liquid-glass-design-tokens.md`. Adds the new token
layer to `styles/globals.css` (`--glass-surface-*`, `--glass-blur-*`,
`--rim-light-*`, `--ember-rim-*`, `--elevation-*`) for both themes, plus
a `docs/DESIGN_TOKENS.md` reference page with contrast measurements.
**Zero component changes** — this is plumbing. Visual diff is expected
to be a no-op (or trivially noisy from CSS reordering). Unblocks
everything else.

### 2. `liquid-glass-modal-and-surface-primitive`

**File**: `.convoys/liquid-glass-modal-and-surface-primitive.md`.
Extracts `<GlassSurface>` (the panel primitive) + `<Modal>` (the
backdrop + dialog primitive with focus trap, ESC-to-close, ARIA-correct
shape). Migrates **all ~15 modals** in `components/*Modal.js` +
`ScanDisambiguationDialog.js` + `OCRSettings.js` to the new primitive.
Inner multitask fan-out: one brief per ~3 modals (see seed for slice
list). Closes the "Modal patterns" finding from `ship-readiness.md`
role-design-system-auditor.

### 3. `liquid-glass-form-primitives`

**File**: `.convoys/liquid-glass-form-primitives.md`. Extracts
`<Button>` (variants: primary glass, ghost glass, ember rim, gold
celebrate), `<Input>` (glass input field with floating focus rim),
`<SearchBar>`. Replaces the existing `.btn-primary` / `.btn-flame` /
`.btn-ember` / `.btn-gold` / `.input-field` / `.search-bar` utility
classes incrementally — utility classes stay aliased to the new tokens
until #8 sweeps them. **No** new global utility classes are introduced.

### 4. `liquid-glass-layout-shell`

**File**: `.convoys/liquid-glass-layout-shell.md`. `components/Layout.js`
(826 lines — the sidebar + header + theme toggle + profile dropdown) and
`components/MobileNavigation.js` (bottom-bar + mobile drawer) move to
glass surfaces. The sidebar becomes a glass rail; the header becomes a
glass top-bar with subtle ember rim under the page edge; the mobile
bottom-bar's existing `backdrop-filter: blur(16px)` (`styles/globals.css`
line 807) is upgraded to the canonical token + rim. **Highest-blast PR**
in the portfolio because Layout is on every authenticated page — visual
diff for this PR will be loud; baselines must be re-seeded on Linux
post-merge (see `seed-visual-baselines-on-linux` precedent).

### 5. `liquid-glass-card-surfaces`

**File**: `.convoys/liquid-glass-card-surfaces.md`. `components/CardItem.js`
(card grid item), `components/CardDetailView.js`, `components/Card3D.js`,
plus rarity FX reconciliation. The existing rarity-glow stack
(`rarity-glow-mythic` / `rare` / `uncommon` / `enchanted` in
`styles/globals.css` lines 568–697) is **tightened** — collapsed from a
3-layer shadow stack to a 2-layer shadow stack, then re-tuned against
the new glass container so the glow reads against translucency. **Per-card
performance budget**: card grid items stay cheap (no `backdrop-filter`
on the grid item itself); glass goes on the *container* and the *detail
view*.

### 6. `liquid-glass-public-and-auth`

**File**: `.convoys/liquid-glass-public-and-auth.md`. `pages/index.js`
(316-line landing), `pages/login.js`, `pages/signup.js`, public
collection/deck views (`pages/cards.js` `PublicCardsView`,
`pages/collection/[id].js` public branch, `pages/deck/[id].js` public
branch). These pages are the **first impression** — they get the most
polish budget. Multitask-friendly: per-page briefs, file-disjoint.

### 7. `motion-system-pass`

**File**: `.convoys/motion-system-pass.md`. Audits and consolidates the
existing motion vocabulary (`pulse`, `float`, `sparkle`, `aura`,
`edgeFloat`, `edgeGlow`, `mythic-sparkle`, `rare-shimmer`,
`uncommon-twinkle`, `enchanted-rainbow`, `fire-glow`, `ember-float`).
Defines a four-tier motion taxonomy (ambient / accent / hover-feedback /
celebration), enforces `prefers-reduced-motion` on every tier, and
documents a per-page motion budget. Drops unused animations. Can run in
parallel with #2–#5.

### 8. `cleanup-legacy-design-css`

**File**: `.convoys/cleanup-legacy-design-css.md`. After every other
sub-convoy has migrated off the legacy utility classes, this sub-convoy
deletes them. In scope: `.gradient-text-blue`, `.gradient-text-purple`,
`.gradient-text-pink`, `.glow-blue`, `.glow-purple`, `.glow-pink`,
`.gradient-bg-fire`, `.gradient-bg-golden`, `.gradient-bg-ember` (if
unused post-migration), the legacy color mappings (`--accent-blue`,
`--accent-purple`, `--accent-pink` in both themes), hardcoded hex sweep
across `components/**` + `pages/**`. Strict-deletion convoy — no new
styling.

---

## 6. CI impact summary

| Sub-convoy | `preview-smoke` | `visual-diff` | `lint` | `vitest` |
| --- | --- | --- | --- | --- |
| 1. design-tokens | Fires | **Fires** (CSS change) — baselines stable | Fires | Fires |
| 2. modal-and-surface | Fires | **Fires + LOUD** — modals change shape | Fires | Fires (Layout tests stable) |
| 3. form-primitives | Fires | **Fires + LOUD** — buttons everywhere | Fires | Fires |
| 4. layout-shell | Fires | **Fires + LOUDEST** — Layout on every page | Fires | Fires + 5 Layout assertions defended |
| 5. card-surfaces | Fires | **Fires + LOUD** — card grids change | Fires | Fires |
| 6. public-and-auth | Fires | **Fires** — landing + auth pages | Fires | Fires + smoke "sign-in page renders" asserts post-migration |
| 7. motion-system | Fires | **Fires** — animations re-tuned | Fires | Fires |
| 8. cleanup | Fires | Fires (should be no-op visually) | Fires | Fires |

**Post-merge per sub-convoy**: re-seed Linux baselines for the affected
surfaces (the `seed-visual-baselines-on-linux` Docker workflow already
documented in `AGENTS.md` § 6 is the canonical path).

**No new CI gates** are required by this epic. Existing gates carry it.

---

## 7. Risk register

| Risk | Mitigation |
| --- | --- |
| `backdrop-filter` performance on long card grids | Per-card surface stays solid; glass only on container + detail view (Hard scoping rule). |
| Light-theme contrast fail when text overlays glass | Every token ships with documented contrast measurements (#1's deliverable). |
| Visual diff floods every PR with noise | One sub-convoy per PR (Hard scoping rule); re-seed baselines on merge. |
| Brand drift (someone introduces purple/blue glass) | #8 keeps the legacy `accent-blue/purple/pink` aliases alive until the last moment, then deletes them in one PR — making accidental reintroduction visible at lint time post-cleanup. |
| Mobile bottom-nav already has glass; PR #4 may double-stack it | #4's architect note: respect the existing `.mobile-nav-backdrop` rule (`styles/globals.css` line 807); upgrade to the canonical token, do not re-implement on top. |
| Modal focus-trap regressions | `<Modal>` primitive in #2 lands with focus-trap + ESC-to-close + ARIA — the role-a11y-auditor findings in `ship-readiness.md` § Role-a11y-auditor are closed by #2. |
| Animation count explodes | #7 enforces the four-tier motion taxonomy with a per-page budget. |
| TypeScript adoption pressure | Hard scoping rule: NO `.ts` files. JavaScript-only per `AGENTS.md` Gotcha #9. |
| Sub-convoys block each other indefinitely | Dependency graph is explicit; #1 → fan-out; multitask after #1 → multitask after #4+#5 → cleanup. |
| User pushback on lost warmth | Vision contract makes warmth survive as accent + motion. Hold the ember/flame/gold token names; just change how they're applied. |

---

## 8. Acceptance criteria (epic-level)

The epic is "done" when:

1. All eight sub-convoys are merged (`status: merged` or `shipped` in
   each `.convoys/<slug>.md`).
2. `docs/DESIGN_TOKENS.md` reflects the as-shipped token surface (kept
   fresh by #1, audited by every subsequent sub-convoy).
3. `npm run lint` and `npm run test:run` and `npm run test:smoke` all
   green on `main` post-merge of #8.
4. Linux visual baselines re-seeded for every UI surface touched
   (`seed-visual-baselines-on-linux` workflow run logged).
5. AGENTS.md § "Branding" section updated with one paragraph naming the
   Liquid Glass direction + pointer at `docs/DESIGN_TOKENS.md`.
6. `.cursor/rules/ui-and-theming.mdc` updated to make the new tokens +
   primitives the canonical pattern (the existing "Two systems coexist"
   note becomes obsolete after #8).
7. Lighthouse mobile + desktop scores on `pages/index.js` no worse than
   the pre-redesign baseline (Performance, Accessibility).

---

## 9. Roles invoked (epic-level)

This umbrella does NOT itself invoke roles — each sub-convoy invokes its
own role chain. The typical chain per sub-convoy is:

1. `role-conductor` — writes the sub-convoy from its seed.
2. `role-ux-reviewer` — for sub-convoys #2, #4, #5, #6.
3. `role-design-system-auditor` — for sub-convoys #1, #2, #3, #5, #7.
4. `role-a11y-auditor` — for sub-convoys #2, #3, #4.
5. `role-architect` — every sub-convoy (decides brief boundaries +
   multitask shape).
6. `role-implementer` — one or more per sub-convoy.
7. Post-PR audit fleet (`/multitask role-reviewer +
   role-design-system-auditor + role-a11y-auditor`) on every visual PR.
8. `role-doc-writer` — updates `docs/DESIGN_TOKENS.md` after #1; updates
   `AGENTS.md` + `.cursor/rules/ui-and-theming.mdc` after #8.

---

## 10. Open questions for the operator

These need ratification before #1's architect starts. They are NOT
re-litigations of the design vision — they are precise tuning calls:

1. **Glass tint strength.** Two reference points:
   - **Apple Liquid Glass** (iOS 19) — very translucent (~30–40% surface
     opacity), strong blur (~30px), tinted vibrancy.
   - **Linear / Vercel / Arc Browser** — less translucent (~70–85%),
     softer blur (~12–20px), borderline frosted.
   Where on this spectrum does Deck Hearth sit? Recommended default:
   **Apple-leaning** (lower opacity, stronger blur, warmer rim) — the
   product is a personal hearth, not an enterprise tool.

2. **Light-theme glass base.** Two options:
   - **Warm white** (`rgba(254, 252, 248, 0.55)` — the existing
     `--bg-primary-light` with alpha) — keeps the cream warmth.
   - **Cool white** (`rgba(255, 255, 255, 0.6)`) — true Apple-style
     glass; reads more "modern" but loses warmth on flat panels.
   Recommended default: **warm white**, with ember-rim doing the
   warmth lifting.

3. **Dark-theme glass base.**
   - **Warm black** (`rgba(26, 15, 10, 0.55)` — existing
     `--bg-primary-dark` with alpha) — matches the wood-charcoal floor.
   - **Cool black** (`rgba(0, 0, 0, 0.6)`) — true Apple style.
   Recommended default: **warm black**.

4. **Hover ember rim intensity.** Glow on hover is core to the vibe.
   How "alive" should it be?
   - **Subtle** — `box-shadow: 0 0 0 1px rgba(216, 67, 21, 0.4) inset`
     (1px ring on top edge only).
   - **Pronounced** — adds an outer 8–12px `rgba(216, 67, 21, 0.25)`
     bloom.
   Recommended default: **pronounced on interactive primaries** (buttons,
   focused inputs, selected cards); **subtle on ambient surfaces** (nav
   rail, header).

5. **Drop the current `fire-glow-bg` page-background animation?** It
   currently animates the whole-page background `filter: hue-rotate(...)`
   — expensive on long scrolls and visually fights the glass aesthetic.
   Recommended: **drop**, retain `ember-float` as a localized accent on
   the landing hero only.

6. **Sub-convoy sequencing under launch pressure.** If the operator
   wants to launch publicly before the epic completes, ship #1 → #2 →
   #4 (modals + Layout) as the minimum-viable redesign, then ship #3,
   #5, #6, #7, #8 post-launch. Confirm.

These six are tabled for sub-convoy #1's architect gate.

---

## 11. How to start

Per `.cursor/agents/role-conductor.md`, start the first sub-convoy with:

> *"Run role-conductor: start a new convoy `liquid-glass-design-tokens`
> from the seed `.convoys/liquid-glass-design-tokens.md`. Success =
> tokens + docs ship; zero component changes; visual-diff baselines
> stable; lint + vitest + smoke green."*

The Conductor will set classification, skip flags, and hand off to
`role-design-system-auditor` + `role-architect`.

After #1 merges, the operator can dispatch #2, #3, #7 in parallel via
`/multitask`. Track per-sub-convoy status in the frontmatter of each
seed file; mirror the rolling state into the "Design system redesign
portfolio" section of `.convoys/ship-readiness.md`.