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

name	classification	success_metric	skip	status	created
liquid-glass-redesign	epic	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.		open	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.