deckhearth/.convoys/cleanup-legacy-design-css.md

name	classification	success_metric	skip	status	created	ci_gates_shipped	depends_on	umbrella
cleanup-legacy-design-css	feature	The legacy gradient-text / glow / accent-blue/purple/pink utility surface is deleted from `styles/globals.css`; no consumer remains (verified by `rg`); hardcoded hex sweep across `components/**` + `pages/**` complete; `.cursor/rules/ui-and-theming.mdc` is updated to make Liquid Glass tokens + primitives the canonical pattern; `forbidden-legacy-design-css` lint / grep gates are wired to prevent regression; lint + vitest + smoke green.	ia ux	ci-gates-shipped-deletion-queued	2026-06-03	2026-06-03	liquid-glass-design-tokens liquid-glass-modal-and-surface-primitive liquid-glass-form-primitives liquid-glass-layout-shell liquid-glass-card-surfaces liquid-glass-public-and-auth motion-system-pass	liquid-glass-redesign

Convoy: cleanup-legacy-design-css

Sub-convoy #8 of the liquid-glass-redesign epic. Strict-deletion convoy — ships last, after every other sub-convoy has migrated off the legacy surface. No new styling. No new components. Only deletions and CI gates to prevent re-introduction.

Why

Without an enforced cleanup at the end, the legacy utility classes (gradient-text-blue, glow-blue, accent-purple, etc. — every one inherited from a pre-Liquid-Glass era) will quietly reappear in future PRs as developers' muscle memory pastes the old patterns. The way to prevent that is:

1. Delete the legacy surface from styles/globals.css.
2. Sweep any remaining hex colors that ought to be tokens.
3. Update .cursor/rules/ui-and-theming.mdc to make the Liquid Glass primitives the canonical pattern.
4. Wire forbidden-* grep gates in CI so the legacy patterns can't land again.

This convoy is predicated on every other sub-convoy having shipped first. If any sub-convoy is still in flight, this convoy waits.

Scope

In scope — deletions from styles/globals.css

• Legacy gradient-text utility classes:
  • .gradient-text-blue (lines ~304–310)
  • .gradient-text-purple (lines ~312–318)
  • .gradient-text-pink — does it exist? rg to confirm.
  • .gradient-text-gold — keep ONLY if still consumed.
  • .gradient-text-flame / .gradient-text-ember — keep ONLY if still consumed; these are brand-aligned.
• Legacy glow utility classes:
  • [data-theme="dark"] .glow-blue (line ~292)
  • [data-theme="dark"] .glow-purple (line ~296)
  • [data-theme="dark"] .glow-pink (line ~300)
• Legacy ad-hoc glow utilities (replaced by --ember-rim-* / --rim-light-* tokens):
  • .fire-glow (line ~209) — confirmed dropped by #5.
  • .ember-glow (line ~213) — confirmed dropped by #5.
• Legacy gradient-bg utility classes — drop if unused post-migration:
  • .gradient-bg-fire (line ~196)
  • .gradient-bg-golden (line ~200)
  • .gradient-bg-ember (line ~204)
• Legacy accent-color mappings:
  • In :root (line ~115–118): --accent-blue, --accent-purple, --accent-pink — delete; no consumer should remain.
  • In [data-theme="dark"] (line ~146–149): same three vars.
• Legacy .btn-* utility classes — drop ONLY if #3 migrated every consumer and operator confirms. Conservative default: keep .btn-* as thin aliases of <Button> styling for backward compatibility; delete in a future polish convoy.
• Legacy .input-field / .search-bar — same treatment as .btn-*.
• Legacy .card (line ~285) — verify usage; likely dropped (replaced by <GlassSurface>).
• Card-hover-panel ad-hoc rules:
  • .card-side-panel / .card-panel-enter / .card-panel-enter-active (lines ~530–565) — drop ONLY if #5 migrated the hover panel to <GlassSurface>.

In scope — hex sweep

rg "#[0-9a-fA-F]{3,6}" components/ pages/ --type js — every match that ISN'T a deliberate brand color in styles/globals.css (i.e. every hex in .js files) must be converted to a theme token. Common culprits:

• bg-[#xxx] Tailwind arbitrary-value classes.
• style={{ backgroundColor: '#xxx' }} inline.
• stroke="#xxx" / fill="#xxx" on SVG paths (these may be intentional and untokened — architect's call per-SVG).

In scope — rule + doc updates

• .cursor/rules/ui-and-theming.mdc:
  • Drop the "Two systems coexist" warning paragraph (no longer true post-migration).
  • Make <GlassSurface>, <Modal>, <Button>, <Input>, <SearchBar> the canonical primitives in the "Common UI patterns to reuse" table.
  • Add a "Forbidden patterns" section listing the deleted utility classes + the new grep gate names.
• AGENTS.md § "Branding":
  • Update the Liquid Glass paragraph from #1 with the as-shipped convoy series + pointers at docs/DESIGN_TOKENS.md and docs/MOTION_SYSTEM.md.
• docs/DESIGN_TOKENS.md:
  • Final audit — every token documented; every contrast measurement re-checked.
• docs/MOTION_SYSTEM.md:
  • Final audit.

In scope — CI gates

Add grep gates to .github/workflows/ci.yml mirroring the existing forbidden-endpoints + forbidden-stale-strings + forbidden-client- side-llm-keys pattern:

• forbidden-legacy-color-tokens — fails the build if any of --accent-blue, --accent-purple, --accent-pink, gradient-text-(blue|purple|pink), glow-(blue|purple|pink) appear in components/**, pages/**, styles/**.
• forbidden-hex-in-jsx — fails the build if #[0-9a-fA-F]{3,6} appears in components/**/*.js or pages/**/*.js (with a curated allowlist for legitimate SVG paths if any remain).
• forbidden-legacy-utility-classes (optional, architect ratifies) — fails the build if btn-(flame|ember|gold) / input-field / search-bar classNames appear post-migration.

Out of scope

• Any new design work.
• Any new component.
• Any structural change.

Roles invoked

1. role-architect — sweep inventory + brief.
2. role-design-system-auditor — verify zero design regressions.
3. role-doc-writer — .cursor/rules/ui-and-theming.mdc, AGENTS.md.
4. role-implementer — single brief; cleanup-only.
5. role-reviewer — single post-PR review.

Brief 1 (shipped 2026-06-03) — CI grep gates only

The disciplined-discipline work: lock in the design-system rules that the sub-convoys established, so future PRs can't regress.

Two new CI jobs added to .github/workflows/ci.yml:

1. forbidden-modal-shell-without-primitive — FAIL (blocking). Greps pages/ + components/ for fixed inset-0 bg-black bg-opacity- and FAILS if any match is found outside the grandfathered legacy list (the 9 modals still queued for #2 Brief 2: CollectionsSuccessModal, CollectionsEditModal, CollectionEditModal, CardDetailDeckModal, ScannerPageView, UploadImageModal, CollectionSelectionModal, OCRSettings, pages/decks.js). New modal files MUST use the <Modal> primitive from components/ui/. As sub-convoy #2 Brief 2 lands migrations, entries delete from the grandfathered list — never silently.
2. forbidden-deprecated-color-aliases — WARN-only (audit baseline). Greps pages/ + components/ for the legacy pre-Deck-Hearth aliases (gradient-text-purple/pink/blue, glow-purple/pink/blue, gradient-bg-purple/blue/pink). Currently warning-only with a baseline count; graduates to FAIL once #8 Brief 2 sweeps all known consumers (see § Brief 2 below).

Rule updates in .cursor/rules/ui-and-theming.mdc:

• Documented the components/ui/ primitive kit (<GlassSurface>, <Modal>, <Button>, <Input>, <SearchBar>).
• Pointed at docs/DESIGN_TOKENS.md + docs/MOTION_SYSTEM.md as canonical surfaces.
• Updated "Common UI patterns to reuse" table — Modal row now points at the primitive + canonical references.

Brief 2 (queued for follow-up) — actual deletion

Only run AFTER:

1. liquid-glass-modal-and-surface-primitive Brief 2 (the 11 remaining modal migrations) is merged.
2. liquid-glass-form-primitives Brief 2 (form sweep) is merged.
3. liquid-glass-card-surfaces Brief 1 (card surface migration) is merged.
4. liquid-glass-public-and-auth Brief 1 (public-view editorial) is merged.

Targets:

• Delete --accent-blue / --accent-purple / --accent-pink aliases from styles/globals.css.
• Delete .gradient-text-blue / .gradient-text-purple / .gradient-text-pink / .glow-blue / .glow-purple / .glow-pink / .gradient-bg-purple / .gradient-bg-blue / .gradient-bg-pink utility classes.
• Delete .fire-glow / .ember-glow utility classes (replaced by --ember-rim-{subtle,pronounced}).
• Delete the page-level fire-glow-bg background animation (replaced by localized ember-float on landing hero only via #6).
• Delete mobile-nav-backdrop legacy class (Layout's MobileNavigation now uses --glass-surface-mid directly via #4).
• Graduate forbidden-deprecated-color-aliases job from WARN to FAIL (exit 1 instead of exit 0).

Todos

• Architect: full deletion inventory + grep-confirm zero consumers
• Design-system auditor: zero-regression sign-off
• Doc-writer: rule + AGENTS.md + token-doc updates
• Brief 1 — deletions + sweep + CI gates + doc updates
• Post-PR review

Decisions to ratify

1. Keep .btn-* and .input-field / .search-bar as thin aliases or delete? Conservative: keep as aliases; delete in a future polish convoy. Aggressive: delete now (cleaner end state). Operator ratifies.
2. forbidden-hex-in-jsx SVG allowlist — how to handle legitimate inline SVG hex (e.g. mana-symbol SVGs in components/ManaSymbols.js). Recommended: per-file allowlist via // eslint-disable-next-line or a path-based exclusion in the grep gate.
3. Should gradient-text-gold, gradient-text-flame, gradient-text-ember survive? These are brand-aligned. Likely: keep, but document in docs/DESIGN_TOKENS.md.
4. .fire-glow-bg already dropped by #7 — confirm.

Acceptance criteria

1. Every deletion in § Scope is executed; no consumer remains (rg verifies).
2. Hex sweep complete; forbidden-hex-in-jsx passes.
3. Rule + AGENTS.md + docs updated.
4. CI gates added and verified by negative test (introduce a forbidden pattern in a scratch commit; verify CI fails; revert).
5. Lint + vitest + smoke green.
6. Visual-diff baselines unchanged (cleanup should not affect render).

CI impact

Workflow / job	Behavior
preview-smoke.yml	Fires.
visual-diff.yml	Fires — should show zero diff (cleanup is non-visual). Any diff is a bug.
lint	Fires + new grep gates.
test: (vitest)	Fires.
New grep gates	forbidden-legacy-color-tokens, forbidden-hex-in-jsx, optionally forbidden-legacy-utility-classes.

Known constraints

• Zero net design change. This convoy is deletion-only. Visual diff MUST be empty. Any pixel change is a sign that #1–#7 left work on the table; back out and address.
• No-go zones honoured — components/Layout.js.backup, scripts/add-*.js / fix-*.js / seed-*.js graveyard untouched.

Multitask dispatch

slice_dependencies:
  - brief: 1
    depends_on: []
    files:
      - styles/globals.css
      - .github/workflows/ci.yml
      - .cursor/rules/ui-and-theming.mdc
      - AGENTS.md
      - docs/DESIGN_TOKENS.md
      - docs/MOTION_SYSTEM.md
      # ... and any .js files where hex sweep finds consumers

Single brief. No multitask.

Out of scope follow-ups

• delete-btn-utility-aliases — if Decision 1 keeps the legacy .btn-* aliases here, delete them in a small polish convoy 3-6 months post-redesign.
• storybook-adoption — natural next step once the primitive set is stable.
• design-tokens-as-tailwind-theme — if Tailwind composition shape converges on the same patterns repeatedly. P3 DX.