a6d72e19b7
Replace stale ownership/list labels across pages and components, add lib/collection-vocabulary.js as the single copy source, document the taxonomy in AGENTS.md, and gate retired strings in CI. Co-authored-by: Cursor <cursoragent@cursor.com>
69 lines
3.9 KiB
Text
69 lines
3.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).
|
|
|
|
**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 | `components/CollectionSelectionModal.js`, `components/ShareModal.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/`.
|