12.1: Design Token System

[steilerDev]

As a developer, I want a centralized design token system using CSS custom properties so that all visual values are defined in one place and support theming.

Parent Epic: #115
Priority: Must Have

Acceptance Criteria

• 1. client/src/styles/tokens.css exists with Layer 1 (palette: gray, blue, red, green scales) and Layer 2 (semantic: bg, text, border, primary, danger, success, focus, shadow, spacing) on :root
• 2. index.css imports tokens.css at the top and uses semantic tokens for body styles
• 3. App renders identically to before (zero visual changes)
• 4. All quality gates pass (lint, typecheck, test, format:check, build, npm audit)

Notes

• No dependencies on other stories — can start immediately
• Blocks Story 12.3 (Migrate CSS Modules to Design Tokens)
• Layer 1 tokens define the raw color palette; Layer 2 tokens map semantic meanings to palette values
• This story only creates the token file and updates body styles — it does NOT migrate existing CSS Module files (that is Story 12.3)

[steilerDev]

[uat-validator]

UAT Scenarios: Story 12.1 — Design Token System

Preconditions

• The repository is checked out and npm install has been run
• The app can be started locally with npm run dev (server on port 3000, client dev server on port 5173)
• A browser is open to http://localhost:5173
• An admin account is available to log in (or the setup flow can be used to create one)

---

Scenario UAT-12.1-01: Token file exists at the correct path (Critical)

• Given: The story has been implemented
• When: A developer inspects the file system at client/src/styles/tokens.css
• Then: The file exists at exactly client/src/styles/tokens.css
• Verification Method: Automated (file-system check in integration test or CI lint step)

---

Scenario UAT-12.1-02: Layer 1 — Gray palette is defined on :root (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer opens the file and searches for gray palette tokens
• Then: The :root block contains a gray scale with at least the following stops: --color-gray-50, --color-gray-100, --color-gray-200, --color-gray-300, --color-gray-400, --color-gray-500, --color-gray-600, --color-gray-700, --color-gray-800, --color-gray-900, --color-gray-950 (exact stop count may vary; a full scale from near-white to near-black is required)
• Then: Each value is a valid CSS color (hex or hsl())
• Verification Method: Automated (CSS parse + token name check)

---

Scenario UAT-12.1-03: Layer 1 — Blue palette is defined on :root (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for blue palette tokens
• Then: Tokens named --color-blue-* cover a full scale (at minimum light, mid, and dark values, e.g., --color-blue-100, --color-blue-400, --color-blue-500, --color-blue-600, --color-blue-700)
• Then: All values are valid CSS colors
• Verification Method: Automated (CSS parse + token name check)

---

Scenario UAT-12.1-04: Layer 1 — Red and Green palettes are defined on :root (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for red and green palette tokens
• Then: Tokens named --color-red-* and --color-green-* each cover a full scale
• Then: All values are valid CSS colors
• Verification Method: Automated (CSS parse + token name check)

---

Scenario UAT-12.1-05: Layer 2 — Semantic background tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for semantic background tokens
• Then: At minimum the following semantic tokens are present and map to Layer 1 palette values: --color-bg-page (or equivalent), --color-bg-surface (or equivalent), --color-bg-subtle (or equivalent)
• Then: Each value references a Layer 1 palette token using var(--color-gray-*) or similar (not a hardcoded hex value)
• Verification Method: Automated (CSS parse; check that Layer 2 values use var() references to Layer 1 tokens)

---

Scenario UAT-12.1-06: Layer 2 — Semantic text tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for semantic text color tokens
• Then: At minimum the following are present: a primary text token (e.g., --color-text-primary), a secondary/muted text token (e.g., --color-text-secondary), and a disabled/placeholder text token
• Then: Each value uses var() to reference a Layer 1 palette token
• Verification Method: Automated

---

Scenario UAT-12.1-07: Layer 2 — Semantic border tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for border tokens
• Then: At minimum one border color token (e.g., --color-border-default) is present and references a Layer 1 gray value
• Verification Method: Automated

---

Scenario UAT-12.1-08: Layer 2 — Primary (blue) action tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for primary/interactive tokens
• Then: Tokens covering the primary action color family are present (e.g., --color-primary-* or --color-interactive-*) including at least a base, hover, and focus-ring value, all referencing blue palette tokens
• Verification Method: Automated

---

Scenario UAT-12.1-09: Layer 2 — Danger (red) tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for danger/error tokens
• Then: At minimum --color-danger-* tokens (or equivalent) are present covering a background, border, and text variant (e.g., used for error banners and validation messages), all referencing red palette tokens
• Verification Method: Automated

---

Scenario UAT-12.1-10: Layer 2 — Success (green) tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for success tokens
• Then: At minimum --color-success-* tokens are present covering background, border, and text, all referencing green palette tokens
• Verification Method: Automated

---

Scenario UAT-12.1-11: Layer 2 — Focus ring token is defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block
• Then: A focus ring token (e.g., --shadow-focus or --color-focus-ring) is defined that corresponds to the blue-tinted box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.*) pattern currently used in the existing CSS Modules
• Verification Method: Automated

---

Scenario UAT-12.1-12: Layer 2 — Shadow tokens are defined (Critical)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block
• Then: At minimum one card/surface shadow token (e.g., --shadow-sm or --shadow-card) is present that matches the box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06) pattern used on the login/setup card today
• Verification Method: Automated

---

Scenario UAT-12.1-13: Layer 2 — Spacing tokens are defined (Nice-to-have for this story)

• Given: client/src/styles/tokens.css exists
• When: A developer inspects the :root block for spacing tokens
• Then: A spacing scale is present (e.g., --spacing-1 through --spacing-8 or --space-xs through --space-2xl) matching the rem-based values in use across the app
• Verification Method: Automated

---

Scenario UAT-12.1-14: index.css imports tokens.css as its first statement (Critical)

• Given: Story implementation is complete
• When: A developer opens client/src/styles/index.css
• Then: The very first non-comment line is @import './tokens.css'; (or equivalent relative path @import 'tokens.css';)
• Then: The import appears before any rule blocks (the *, html, body selectors follow after)
• Verification Method: Automated (lint rule or file content check)

---

Scenario UAT-12.1-15: body styles in index.css use semantic tokens (Critical)

• Given: index.css has been updated as part of this story
• When: A developer opens client/src/styles/index.css and reads the body rule
• Then: Any color or background-color applied to body uses var(--color-*) references to semantic tokens rather than hardcoded hex values
• Then: The font-family stack remains unchanged (system-ui, -apple-system, sans-serif) since typography tokens are not in scope for this story
• Verification Method: Manual (code review) + Automated (CSS parser grep for hardcoded hex in body selector)

---

Scenario UAT-12.1-16: No hardcoded hex values remain in tokens.css Layer 2 declarations (Critical)

• Given: tokens.css exists with both Layer 1 and Layer 2 tokens
• When: A developer inspects all Layer 2 (semantic) token declarations in the :root block
• Then: Every Layer 2 token value is expressed as var(--color-<palette>-<stop>) — no raw hex codes appear in Layer 2 declarations
• Then: Layer 1 (palette) tokens may use raw hex codes — this is expected and correct
• Verification Method: Automated (CSS parse; grep Layer 2 properties for non-var() values)

---

Scenario UAT-12.1-17: App renders with no visible change after implementation — login page (Critical)

• Given: The app is running locally (npm run dev) after the story is implemented
• When: A user navigates to http://localhost:5173 and is redirected to the login page
• Then: The login page displays a centered white card on a light gray background — identical in appearance to before the change
• Then: The "Sign In" heading appears in dark text
• Then: Username and password fields have a light gray border (#d1d5db equivalent)
• Then: The "Sign in" button is blue (#3b82f6 equivalent)
• Then: No elements appear with missing colors, invisible text, or layout shifts
• Verification Method: Manual (visual inspection) + Both (Playwright screenshot comparison if baseline exists)

---

Scenario UAT-12.1-18: App renders with no visible change — dashboard (Critical)

• Given: A user is logged in and on the Dashboard page
• When: The user views the main content area and sidebar
• Then: The sidebar background remains the dark navy/slate color (#1f2937 equivalent)
• Then: Sidebar text and navigation links are white/near-white
• Then: The active navigation link has a blue background (#3b82f6 equivalent)
• Then: The main content area background is light gray (#f9fafb equivalent)
• Then: The header is white with a bottom border
• Verification Method: Manual (visual inspection) + Both (Playwright screenshot comparison)

---

Scenario UAT-12.1-19: CSS custom properties are accessible in browser DevTools (Nice-to-have)

• Given: The app is running locally and a browser DevTools window is open
• When: A user opens DevTools, selects the html or :root element in the Elements panel, and inspects its computed styles
• Then: Custom properties named --color-gray-*, --color-blue-*, --color-bg-*, --color-text-* etc. appear in the computed styles panel
• Then: Their values resolve to the expected hex/hsl colors
• Verification Method: Manual (DevTools inspection)

---

Scenario UAT-12.1-20: Build succeeds with no errors after token introduction (Critical)

• Given: The story is implemented
• When: A developer runs npm run build from the repository root
• Then: The build completes without errors (exit code 0)
• Then: client/dist/ contains the compiled output including the CSS bundle
• Verification Method: Automated (CI quality gate — build step)

---

Scenario UAT-12.1-21: All quality gates pass (Critical)

• Given: The story is implemented
• When: A developer runs each of the following commands: npm run lint, npm run format:check, npm run typecheck, npm test, npm run build, npm audit
• Then: Every command exits with code 0
• Then: npm audit reports 0 vulnerabilities
• Then: npm test reports all existing tests pass (no regressions introduced by adding a CSS file)
• Verification Method: Automated (CI quality gates pipeline)

---

Scenario UAT-12.1-22: No existing CSS Module files are modified (Boundary check)

• Given: The story scope is limited to creating tokens.css and updating index.css
• When: A developer runs git diff --name-only after implementation
• Then: The diff contains client/src/styles/tokens.css (new file) and client/src/styles/index.css (modified)
• Then: No CSS Module files (*.module.css) appear in the diff — migrating those is Story 12.3's responsibility
• Verification Method: Manual (git diff inspection)

---

Edge Cases

• Empty :root block: If tokens.css exists but has an empty :root block, the app should still build and render correctly (CSS custom properties simply have no values, but the file is syntactically valid)
• Import order matters: If tokens.css is imported after other CSS that references its tokens, the tokens will not resolve — the import at the top of index.css is critical
• Token name collisions: If a token name matches an existing browser-reserved custom property or a future CSS standard property, it could cause unexpected behavior — names should use the --color-, --shadow-, --spacing- prefixes to avoid this
• var() with no fallback in Layer 2: If a Layer 2 token references a Layer 1 token that doesn't exist (e.g., a typo), the property resolves to its initial value (usually transparent/invisible) — this is a silent failure. The absence of any visual regression is a strong signal that all var() references are valid

---

Automated Test Mapping

• CSS token file validation: client/src/styles/tokens.css — file existence + token name/value checks (owned by qa-integration-tester, Jest or a dedicated CSS-lint rule)
• index.css import check: static analysis confirming import is first statement (owned by qa-integration-tester)
• Visual regression (no change): Playwright screenshot baseline comparison for login page and dashboard (owned by e2e-test-engineer, e2e/tests/visual/design-tokens.spec.ts or within existing page tests)
• Quality gates: CI pipeline (ci.yml) covers lint, typecheck, test, build, audit automatically