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

---
name: cleanup-legacy-design-css
classification: feature
success_metric: |
  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.
skip:
  - ia
  - ux
status: ci-gates-shipped-deletion-queued
created: 2026-06-03
ci_gates_shipped: 2026-06-03
depends_on:
  - 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
umbrella: 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

```yaml
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.