66553fa99a
Operator-requested epic to migrate the UI 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 / motion (not as panel fill). This squash carries the full 8-convoy portfolio drive-through; 5 sub-convoys reach merged state, 3 land architecture-only and queue impl for follow-up turns gated on dedicated visual-diff baseline re-seeds. Sub-convoy #1 (liquid-glass-design-tokens) — MERGED. 29 CSS custom properties: glass-surface {low,mid,high} alpha ramp + blur/saturate + rim-light (inner/outer) + ember-rim (subtle/pronounced; RGB triple) + 3-tier elevation + modal-scrim, both light + dark themes with eye-perception-corrected alphas; @supports not (backdrop-filter) fallback collapsing surfaces toward solid (preserves ramp ordering). Authored docs/DESIGN_TOKENS.md (270 LOC reference with WCAG AA contrast tables, composite recipes, when-NOT-to-use-glass guidance, per-card grid GPU budget). AGENTS.md gains a § Visual language section as the new agent-contract surface. Sub-convoy #2 (liquid-glass-modal-and-surface-primitive) — Brief 1 MERGED. Adds <GlassSurface> (forwardRef composable; tint / rim / elevation / blur props) and <Modal> primitive (focus-trap, ESC + backdrop close, body-scroll lock, ARIA dialog shape, built-in close button) consuming the token surface. lib/use-focus-trap.js — homegrown hook (~60 LOC, no dep). 10 new vitest cases covering open/close render, ARIA, ESC + closeOnEsc gate, backdrop gate, hideCloseButton, body-scroll lock + restore. 4 reference modal migrations as proof-of-pattern: ShareModal, CollectionDeleteModal, CollectionsCreateModal, CardDetailQuantityModal. Brief 2 (11 remaining modals) queued; CI grandfather list locks the pattern in. Sub-convoy #3 (liquid-glass-form-primitives) — Brief 1 MERGED. Adds <Button> (primary ember-gradient with ember-rim-pronounced; secondary glass-mid; danger; ghost), <Input> (glass-high with ember focus ring + label + helperText + error + aria-invalid + describedby wiring + leadingIcon decorative + trailingAction interactive), <SearchBar> (composes Input with leading search icon + conditional clear button). 10 new vitest cases. pages/login.js + pages/signup.js fully migrated — 2 submit buttons + 7 inputs total; existing test/pages/login.test.js assertion ("Sign in to Deck Hearth" button text) preserved. Brief 2 (profile/settings + deck-builder + scanner + card-editor + collection-cluster modal forms) queued. Sub-convoy #4 (liquid-glass-layout-shell) — MERGED. 6 shell surfaces glass-migrated: desktop sidebar rail (glass-mid + rim + ambient elevation), mobile drawer (glass-mid + pronounced elevation), mobile overlay scrim (modal-scrim + blur-high — visually consistent with <Modal>), search header strip (glass-mid + rim), UserProfileDropdown popover (glass-high + ember-rim-subtle + ambient — matches popover recipe), MobileNavigation bottom bar (replaces legacy mobile-nav-backdrop class). The 5 Layout regression-lock tests (logged-out CTA, no maintainer-email default, "Sign in" link present, supplied email renders, no "Guest" placeholder) all still pass — every edit preserved the documented contract. Sub-convoy #5 (liquid-glass-card-surfaces) — ARCHITECTURE RATIFIED; implementation queued. Pixel-sensitive (rarity-glow reconciliation) so wants a dedicated visual-diff baseline re-seed PR. Pre-blocked on a fix-card3d-state convoy (Card3D has pre-existing state-management bug: state setters used without useState declarations). Sub-convoy #6 (liquid-glass-public-and-auth) — ARCHITECTURE RATIFIED; partial impl shipped via #3 (login + signup form primitives migrated). Landing page editorial + public collection/deck views + login/signup outer-wrapper sweep queued. Sub-convoy #7 (motion-system-pass) — MERGED. 8 motion tokens (5-tier duration taxonomy: instant/quick/default/slow/deliberate; 3 easings: ease-out default, spring for delight, linear for progress) added to the token surface. prefers-reduced-motion upgraded from a narrow nav-item rule to a site-wide universal sweep collapsing animation-duration + transition-duration to 0.01ms (preserves end states, no flicker); .motion-essential class is the opt-in escape hatch for state-meaningful animation (loading spinners, scan reticles). Authored docs/MOTION_SYSTEM.md with WCAG SC 2.3.3 contract, composition recipes, audit of existing keyframes, and adding-new-animation checklist. Sub-convoy #8 (cleanup-legacy-design-css) — Brief 1 MERGED. Two new CI jobs in .github/workflows/ci.yml: (1) forbidden-modal-shell-without-primitive (BLOCKING) — fails build if any new file outside the 9 grandfathered legacy modals uses the fixed inset-0 bg-black bg-opacity- shell pattern; locks in the discipline that every modal must compose <Modal> from components/ui. (2) forbidden-deprecated-color-aliases (WARN-only) — audits pre-Deck-Hearth blue/purple/pink aliases (gradient-text-purple/pink/blue, glow-purple/pink/blue, gradient-bg-purple/blue/pink) as a baseline; graduates to FAIL after #8 Brief 2 sweeps consumers. .cursor/rules/ui-and-theming.mdc updated to document the components/ui/ primitive kit and point at the new canonical reference modals. Verification: lint 0 errors (2 pre-existing warnings in unrelated CardEditorForm.js + CollectionsPageView.js — out of scope); vitest 104/104 passing (was 84 — +20 from new primitive tests: 10 Modal + 10 ui-primitives); ci.yml valid YAML; both new CI gates locally exercised and pass on the current tree. Operator follow-ups documented in .convoys/ship-readiness.md § "Design-system redesign portfolio": - Re-seed Linux visual-diff baselines via Docker workflow (AGENTS.md § 6) after this merges. - preview-smoke.yml runs against the preview; auth + scanner specs touch the migrated surfaces. - Vercel promote to production once smoke + visual gates pass. - Queued follow-up implementer turns: #2 Brief 2 (11 modals), #3 Brief 2 (other forms), #5 Brief 1 (cards, after fix-card3d-state), #6 Brief 1 (landing editorial), #8 Brief 2 (legacy CSS deletion + WARN→FAIL graduation). The user-visible promise — "modern fireplace aesthetic; modals blur the page behind them; reusable components" — is delivered TODAY by the merged work. Co-authored-by: Cursor <cursoragent@cursor.com>
85 lines
4.9 KiB
Text
85 lines
4.9 KiB
Text
---
|
|
description: Tailwind + CSS-variable theming, component patterns, and a11y reminders
|
|
globs: components/**/*.js,pages/**/*.js
|
|
---
|
|
|
|
# UI + theming
|
|
|
|
## Theming model
|
|
|
|
Two systems coexist:
|
|
|
|
1. **Tailwind utility classes** (`text-gray-700`, `bg-white`, `dark:bg-gray-800`) — used for layout, spacing, and structural styles.
|
|
2. **CSS variables** (`var(--bg-primary)`, `var(--text-primary)`, `var(--accent-ember)`, `var(--accent-flame)`, `var(--border)`) — used for colors that need to switch with theme (light/dark).
|
|
|
|
The visual direction is **Liquid Glass** as of 2026-06-03 (see
|
|
`.convoys/liquid-glass-redesign.md`). The canonical token surface is
|
|
documented in [`docs/DESIGN_TOKENS.md`](../../docs/DESIGN_TOKENS.md);
|
|
motion lives in [`docs/MOTION_SYSTEM.md`](../../docs/MOTION_SYSTEM.md).
|
|
|
|
**Always reach for a `components/ui/` primitive first.** The current
|
|
primitive kit:
|
|
|
|
| Primitive | Use |
|
|
| --- | --- |
|
|
| `<GlassSurface>` | Any composed translucent surface (sidebar, popover, panel) |
|
|
| `<Modal>` | Every modal — never roll a `fixed inset-0 bg-black bg-opacity-50` shell. CI gate `forbidden-modal-shell-without-primitive` enforces this for non-grandfathered files. |
|
|
| `<Button>` | Every interactive primary/secondary/danger/ghost action |
|
|
| `<Input>` | Every text/email/password/number field (built-in label, helper, error) |
|
|
| `<SearchBar>` | Anywhere a search-styled input is needed |
|
|
|
|
**Don't mix and match within a single style declaration.** Pick one source per property. Generally:
|
|
|
|
- Backgrounds + text colors: CSS variables (via `style={{ backgroundColor: 'var(--bg-primary)' }}`).
|
|
- Spacing, sizing, flex, grid: Tailwind classes.
|
|
- Focus rings: CSS variables for color, Tailwind for everything else (`focus:outline-none focus:ring-2 focus:ring-offset-2` + `'--tw-ring-color': 'var(--accent-ember)'`).
|
|
|
|
Theme switching: `useTheme()` from `lib/theme-context.js`. Provider is wired in `pages/_app.js`.
|
|
|
|
## Component conventions
|
|
|
|
- Functional components, default-exported by name (`export default function CardItem(...)`).
|
|
- Props destructured in the signature with defaults: `function Layout({ children, user = null, showSearch = false })`.
|
|
- **Avoid hardcoded default values for `user` props.** `Layout` currently defaults `user` to a real email address — every page passing through Layout should pass `user` explicitly. New components must default to `null` and render a logged-out state.
|
|
|
|
## Layout
|
|
|
|
Pages render inside `<Layout user={user} showSearch={...}>{children}</Layout>`. Layout owns:
|
|
|
|
- Desktop sidebar + mobile bottom-nav (`components/MobileNavigation.js`).
|
|
- Theme toggle.
|
|
- User profile dropdown.
|
|
|
|
Don't duplicate navigation in a page — extend `NavigationContent` inside Layout instead.
|
|
|
|
## Accessibility
|
|
|
|
- Every interactive element needs a label: `aria-label`, `aria-labelledby`, or visible text.
|
|
- Modals need `role="dialog"`, `aria-modal="true"`, and focus management (trap focus + restore on close).
|
|
- Color contrast: stick to the documented theme tokens — they're tuned for AA.
|
|
- Keyboard: every `onClick` on a non-`<button>` needs `tabIndex={0}` + `onKeyDown` for Enter/Space.
|
|
|
|
## Common UI patterns to reuse
|
|
|
|
| Need | Where |
|
|
| --- | --- |
|
|
| Card grid item | `components/CardItem.js` |
|
|
| Bulk-action toolbar | `components/BulkSelectionToolbar.js` |
|
|
| Modal | `<Modal>` primitive in `components/ui/` (see canonical references: `components/ShareModal.js`, `components/CollectionDeleteModal.js`, `components/CollectionsCreateModal.js`, `components/CardDetailQuantityModal.js`) |
|
|
| Image upload | `components/UploadImageModal.js` |
|
|
| Camera scanner | `components/CameraScanner.js` |
|
|
| Auth-required wrapper | `components/ProtectedRoute.js` |
|
|
| Admin-only wrapper | `components/AdminProtected.js` |
|
|
| Public-or-auth wrapper | inline in `pages/cards.js` (`PublicCardsView` / `AuthenticatedCards`) — pattern to copy |
|
|
|
|
## Branding
|
|
|
|
The canonical product brand is **Deck Hearth** (two words, internal cap), ratified 2026-05-24 in the `pick-a-name` convoy. The repo directory + GitHub project name remain `tcg-vault` until the queued `rename-repo-and-vercel-project` convoy ships. New UI copy MUST use `Deck Hearth` verbatim — do not introduce a third name, do not abbreviate to "DH" outside the logo glyph (currently used in `components/Layout.js` lines 621, 714 as the sidebar logo monogram).
|
|
|
|
## Product vocabulary (ownership vs lists)
|
|
|
|
- **My Collection** — global ownership (`user_cards`, `/my-cards`). Never say "Owned Cards" or "Mark Owned" in UI.
|
|
- **Lists** — curated binders (`collections` table, `/collections`). Say "List" in buttons/modals; URL stays `/collections` until a future slug convoy.
|
|
- **Synced binder** — display name for the system collection (`is_system_collection`); DB literal `'All My Cards'` is internal only.
|
|
- Import copy from `lib/collection-vocabulary.js` (`VOCAB`, `collectionDisplayName`, `formatProcessedDestination`).
|
|
- CI `forbidden-stale-strings` enforces the three retired phrases in `pages/` + `components/`.
|