From 9ed8c97c249c57eaf03c9ff02a7d63a223327c6e Mon Sep 17 00:00:00 2001 From: weeihan Date: Thu, 1 Oct 2026 09:21:28 +0800 Subject: [PATCH] docs: add IMS Admin refresh slice 1 implementation plan Co-Authored-By: Claude Haiku 4.5 --- .../2026-10-01-ims-admin-refresh-slice-1.md | 3126 +++++++++++++++++ 1 file changed, 3126 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-01-ims-admin-refresh-slice-1.md diff --git a/docs/superpowers/plans/2026-10-01-ims-admin-refresh-slice-1.md b/docs/superpowers/plans/2026-10-01-ims-admin-refresh-slice-1.md new file mode 100644 index 0000000..8554002 --- /dev/null +++ b/docs/superpowers/plans/2026-10-01-ims-admin-refresh-slice-1.md @@ -0,0 +1,3126 @@ +# IMS Admin Refresh, Slice 1 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the Modernist look with the IMS Admin refresh for the foundation (tokens, gate, primitives, `TableCard`, shells) and migrate the Incidents list (screens 01 and 10) as the first full screen. + +**Architecture:** New tokens go in `app/globals.css` (`@theme static`). The old Modernist class names (`gray-*`, `blue-*`, `red-*`, `accent-100..900`, `neutral-*`, `border-divider`) stay defined but re-valued, so the ~60 unmigrated files keep rendering until later slices. New primitives live in `components/ui/`. The Incidents list becomes a `TableCard` fed by a shared server loader. + +**Tech Stack:** Next.js 16.3.7 (App Router, Turbopack), React 19, Tailwind CSS v4 (`@theme static`), `lucide-react`, Geist and Geist Mono via `next/font/google`, vitest 4 + jsdom + `@testing-library/react`. + +**Spec:** `design-system/design.md` (§2 tokens, §3 shells, §4 components, §8 build order). References: `design-system/IMS Admin Spec.dc.html`, `design-system/IMS Admin.dc.html`. + +## Global Constraints + +- Source of truth is `design-system/design.md`. The Modernist system under `design-system/_ds/` is retired. +- Colours, type, radius, shadows exactly as design.md §2: ink `#1f1f1f`, ground `#f1f1f1`, surface `#ffffff`, surface-2 `#f7f7f7`, one teal accent `#0f766e`, danger `#b3261e`, top bar `#1a1a1a`. +- Rules are 1px. Never `border-2` or `border-{t,b,l,r}-2`. +- Radius scale: `rounded-md` = 8 (buttons, chips, inputs, pills), `rounded-xl` = 12 (cards), `rounded-[5px]` checkbox, `rounded-[6px]` avatar, 999 only for badges. +- Status and priority colours only through `StatusTag` and `PriorityTag` (design.md §4.2): dark text on a light tint, text label always present. +- Every list is a `TableCard` (design.md §4.9). Do not hand-build tables. +- Never write `*/` inside a CSS comment in `app/globals.css`; it ends the comment and silently swallows the `@theme` block (this broke production builds once). +- Do not run `next dev` while verifying a production build in the same `.next`. Verify CSS with `rm -rf .next && npm run build` and inspect `.next/static/chunks/*.css`. +- Baseline: 7 tests already fail before this work (missing `DEEPSEEK_API_KEY`, `BREVO_API_KEY`, and a `cookies()` scope error): `lib/incidents/bulk-import.test.ts` (2), `tests/api/incidents/quality-check.test.ts` (2), `rca-draft.test.ts` (1), `triage-suggest.test.ts` (1), `tests/lib/notifications/email.test.ts` (1). "No new failures" means exactly these 7 and no others. +- No database, API, auth or routing changes. Do not deploy; deploying needs the owner's go-ahead. +- Work on branch `feat/admin-refresh-slice-1`. Stage only named paths; never `git add -A`. Leave the untracked `Modern table UI mockups.zip` files and the deleted `design-system/ims-admin/MASTER.md` alone. + +## File Structure + +**Create** +- `components/ui/checkbox.tsx`, `filter-chip.tsx`, `segmented.tsx`, `avatar.tsx`, `drawer.tsx`, `table-card.tsx` +- `components/layout/app-shell.tsx`, `components/layout/mobile-shell.tsx`, `components/layout/nav-items.ts` +- `components/incidents/incident-table.tsx` +- `lib/incidents/list-params.ts` (pure URL-param parsing), `lib/incidents/list-query.ts` (DB loader) +- `tests/**` for each of the above + +**Modify** +- `app/globals.css`, `app/layout.tsx`, `scripts/check-design-gates.mjs`, `tests/design/tokens.test.ts`, `tests/scripts/check-design-gates.test.ts` +- `components/ui/button.tsx`, `status-tag.tsx`, `field.tsx`, `card.tsx`, `modal.tsx` +- `components/notifications/bell.tsx`, `components/incidents/incident-filters.tsx` +- `app/(protected)/layout.tsx`, `app/(protected)/hse/incidents/page.tsx`, `app/(protected)/supervisor/incidents/page.tsx` +- `CLAUDE.md`, memory `ims-design-system.md` + +**Delete** +- `components/ui/tag.tsx`, `components/ui/table-styles.ts`, `components/layout/sidebar.tsx`, `components/incidents/incident-list.tsx` (replaced; callers are updated in the same tasks) + +--- + +### Task 1: Gate, tokens and Geist + +**Files:** +- Modify: `scripts/check-design-gates.mjs` (full rewrite), `tests/scripts/check-design-gates.test.ts` (full rewrite), `app/globals.css` (full rewrite), `tests/design/tokens.test.ts` (full rewrite), `app/layout.tsx`, `tests/components/layout/sidebar.test.tsx`, `tests/components/ui/modal.test.tsx` +- Modify (mechanical sweep): every `.tsx` under `app/` and `components/` containing `border-2` or `border-{t,b,l,r}-2` + +**Interfaces:** +- Consumes: nothing. +- Produces: Tailwind utilities `bg-ground`, `bg-surface`, `bg-surface-2`, `text-ink`, `text-ink-2`, `text-ink-3`, `text-muted`, `text-faint`, `border-rule`, `border-rule-2`, `border-ring`, `bg-accent`, `text-accent`, `bg-accent-tint`, `bg-accent-tint-2`, `text-danger`, `bg-topbar`, `shadow-card`, `shadow-float`, `shadow-drawer`, `shadow-primary`, `shadow-secondary`, `shadow-input`, `shadow-chip`, `shadow-chip-set`, `font-sans`, `font-mono`, and the status pairs `bg-st--bg` / `text-st--fg` for hue in `amber blue violet orange indigo green grey red`; gate command `npm run check:design` with `findViolations(src, file)`. + +- [ ] **Step 1: Branch and baseline** + +```bash +cd /Users/yapweeihan/Projects/IMS.nosync +git checkout main && git pull --ff-only 2>/dev/null; git checkout -b feat/admin-refresh-slice-1 +npx vitest run 2>&1 | grep -E "Test Files|Tests " +``` + +Expected: `Tests 7 failed | 239 passed` (the 7 baseline failures). If the counts differ, stop and report. + +- [ ] **Step 2: Write the failing gate tests** + +Replace `tests/scripts/check-design-gates.test.ts`: + +```ts +import { describe, it, expect } from 'vitest' +import { findViolations } from '../../scripts/check-design-gates.mjs' + +const rules = (src: string, file = 'components/x.tsx'): string[] => + (findViolations(src, file) as Array<{ rule: string }>).map(v => v.rule) + +describe('design gates (IMS Admin refresh)', () => { + it('allows the radius scale, including rounded-full', () => { + expect(rules('
')).toEqual([]) + }) + + it.each(['border-2', 'border-b-2', 'border-t-2', 'border-l-2', 'border-r-2'])('flags %s', cls => { + expect(rules(`
`)).toContain('no-2px-border') + }) + + it('accepts 1px rules', () => { + expect(rules('
')).toEqual([]) + }) + + it('flags the retired Archivo font', () => { + expect(rules("import { Archivo } from 'next/font/google'")).toContain('no-archivo') + }) + + it('flags off-palette colors but accepts remapped gray, blue and red', () => { + expect(rules('

')).toContain('off-palette') + expect(rules('

')).toContain('off-palette') + expect(rules('

')).toEqual([]) + }) + + it('accepts the status token classes', () => { + expect(rules('')).toEqual([]) + }) + + it('flags hard-coded hex colors, including the retired Modernist red', () => { + expect(rules('

')).toContain('no-hex') + expect(rules('

'quoted'

')).not.toContain('no-hex') + }) + + it('flags centered button labels', () => { + expect(rules('')).toContain('no-centered-button') + }) + + it('flags leftovers the codemod should have replaced', () => { + expect(rules('
')).toEqual(expect.arrayContaining(['no-bg-white', 'no-heavy-shadow'])) + }) + + it('reports file and 1-based line numbers', () => { + const v = findViolations('a\n
', 'components/y.tsx') + expect(v[0]).toMatchObject({ file: 'components/y.tsx', line: 2, rule: 'no-2px-border' }) + }) + + it('accepts clean on-system markup', () => { + expect(rules('
')).toEqual([]) + }) +}) +``` + +- [ ] **Step 3: Write the failing token test** + +Replace `tests/design/tokens.test.ts`: + +```ts +import { describe, it, expect } from 'vitest' +import { readFileSync } from 'fs' +import path from 'path' + +const css = readFileSync(path.resolve(__dirname, '../../app/globals.css'), 'utf8') + +describe('IMS Admin tokens in globals.css', () => { + it.each([ + ['--color-ink', '#1f1f1f'], + ['--color-ink-2', '#303030'], + ['--color-ink-3', '#4a4a4a'], + ['--color-muted', '#616161'], + ['--color-faint', '#8a8a8a'], + ['--color-rule', '#ebebeb'], + ['--color-rule-2', '#e3e3e3'], + ['--color-ring', '#d4d4d4'], + ['--color-surface', '#ffffff'], + ['--color-surface-2', '#f7f7f7'], + ['--color-ground', '#f1f1f1'], + ['--color-accent', '#0f766e'], + ['--color-accent-tint', '#f2f7f6'], + ['--color-accent-tint-2', '#e6f4f1'], + ['--color-danger', '#b3261e'], + ['--color-topbar', '#1a1a1a'], + ])('declares %s as %s', (name, value) => { + expect(css).toMatch(new RegExp(`${name}:\\s*${value}\\b`, 'i')) + }) + + it.each([ + ['amber', '#fff1c2', '#6b4a00'], + ['blue', '#e0efff', '#00527c'], + ['violet', '#ede7ff', '#4b2e99'], + ['orange', '#ffe6cf', '#7a3a00'], + ['indigo', '#e3e8ff', '#2c3e8f'], + ['green', '#d7f4e3', '#0c5132'], + ['grey', '#ebebeb', '#4a4a4a'], + ['red', '#fee3e0', '#8e1f0b'], + ])('declares the %s status pair', (hue, bg, fg) => { + expect(css).toMatch(new RegExp(`--color-st-${hue}-bg:\\s*${bg}`, 'i')) + expect(css).toMatch(new RegExp(`--color-st-${hue}-fg:\\s*${fg}`, 'i')) + }) + + it('sets the radius scale: md 8, xl 12', () => { + expect(css).toMatch(/--radius-md:\s*8px/) + expect(css).toMatch(/--radius-xl:\s*12px/) + }) + + it('declares the card and floating shadows', () => { + expect(css).toMatch(/--shadow-card:\s*0 0 0 1px rgba\(0, ?0, ?0, ?\.08\), 0 1px 2px rgba\(0, ?0, ?0, ?\.06\)/) + expect(css).toMatch(/--shadow-float:\s*0 0 0 1px rgba\(0, ?0, ?0, ?\.1\), 0 12px 32px rgba\(0, ?0, ?0, ?\.18\)/) + }) + + it('declares the component shadows', () => { + for (const name of ['drawer', 'primary', 'secondary', 'input', 'chip', 'chip-set']) { + expect(css).toMatch(new RegExp(`--shadow-${name}:`)) + } + }) + + it('uses Geist through the next/font variables', () => { + expect(css).toMatch(/--font-sans:\s*var\(--font-geist\)/) + expect(css).toMatch(/--font-mono:\s*var\(--font-geist-mono\)/) + }) + + it('keeps the legacy remaps so unmigrated pages still render', () => { + expect(css).toMatch(/--color-gray-100:\s*var\(--color-neutral-200\)/) + expect(css).toMatch(/--color-blue-600:\s*var\(--color-accent\)/) + expect(css).toMatch(/--color-red-600:\s*var\(--color-danger\)/) + expect(css).toMatch(/--color-divider:/) + }) + + it('styles keyboard focus with the 2px accent ring', () => { + expect(css).toMatch(/:focus-visible\s*\{[^}]*outline:\s*2px solid var\(--color-accent\)/) + }) + + it('has no dark mode block and no Modernist leftovers', () => { + expect(css).not.toContain('prefers-color-scheme') + expect(css).not.toMatch(/ec3013/i) + expect(css).not.toMatch(/archivo/i) + }) + + it('has no stray comment terminator before @theme', () => { + const head = css.slice(0, css.indexOf('@theme')) + expect(head.match(/\*\//g)?.length).toBe(head.match(/\/\*/g)?.length) + }) +}) +``` + +- [ ] **Step 4: Run both to verify they fail** + +Run: `npx vitest run tests/scripts/check-design-gates.test.ts tests/design/tokens.test.ts 2>&1 | grep -E "Test Files|Tests "` +Expected: FAIL (both files have failing tests). + +- [ ] **Step 5: Rewrite the gate** + +Replace `scripts/check-design-gates.mjs`: + +```js +import { readdirSync, readFileSync, statSync } from 'node:fs' +import path from 'node:path' +import { fileURLToPath } from 'node:url' + +const RULES = [ + { rule: 'no-2px-border', re: /(?]*className=[^>]*(? { + for (const { rule, re } of RULES) { + if (re.test(text)) out.push({ file, line: i + 1, rule, text: text.trim() }) + } + }) + return out +} + +function walk(dir, files = []) { + for (const name of readdirSync(dir)) { + const full = path.join(dir, name) + if (statSync(full).isDirectory()) walk(full, files) + else if (full.endsWith('.tsx')) files.push(full) + } + return files +} + +function main() { + const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..') + const all = [] + for (const dir of ['app', 'components']) { + for (const abs of walk(path.join(root, dir))) { + const rel = path.relative(root, abs).split(path.sep).join('/') + all.push(...findViolations(readFileSync(abs, 'utf8'), rel)) + } + } + for (const v of all) console.log(`${v.file}:${v.line} [${v.rule}] ${v.text}`) + console.log(all.length === 0 ? 'design gates: clean' : `design gates: ${all.length} violation(s)`) + process.exit(all.length === 0 ? 0 : 1) +} + +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main() +``` + +- [ ] **Step 6: Rewrite `app/globals.css`** + +Read the file first (the harness requires it), then replace it entirely: + +```css +@import "tailwindcss"; + +/* IMS Admin refresh tokens. Source of truth: design-system/design.md section 2. + Static emits every variable so plain CSS can use var(--color-*) too. */ +@theme static { + --color-ink: #1f1f1f; + --color-ink-2: #303030; + --color-ink-3: #4a4a4a; + --color-muted: #616161; + --color-faint: #8a8a8a; + --color-rule: #ebebeb; + --color-rule-2: #e3e3e3; + --color-ring: #d4d4d4; + --color-surface: #ffffff; + --color-surface-2: #f7f7f7; + --color-ground: #f1f1f1; + --color-accent: #0f766e; + --color-accent-tint: #f2f7f6; + --color-accent-tint-2: #e6f4f1; + --color-danger: #b3261e; + --color-topbar: #1a1a1a; + + /* Status pills: a dark step on a light tint, one pair per hue. */ + --color-st-amber-bg: #fff1c2; + --color-st-amber-fg: #6b4a00; + --color-st-blue-bg: #e0efff; + --color-st-blue-fg: #00527c; + --color-st-violet-bg: #ede7ff; + --color-st-violet-fg: #4b2e99; + --color-st-orange-bg: #ffe6cf; + --color-st-orange-fg: #7a3a00; + --color-st-indigo-bg: #e3e8ff; + --color-st-indigo-fg: #2c3e8f; + --color-st-green-bg: #d7f4e3; + --color-st-green-fg: #0c5132; + --color-st-grey-bg: #ebebeb; + --color-st-grey-fg: #4a4a4a; + --color-st-red-bg: #fee3e0; + --color-st-red-fg: #8e1f0b; + + /* Legacy names kept, re-valued, until every page is migrated. */ + --color-divider: #e3e3e3; + --color-neutral-100: #f7f7f7; + --color-neutral-200: #ebebeb; + --color-neutral-300: #d4d4d4; + --color-neutral-400: #c4c4c4; + --color-neutral-500: #8a8a8a; + --color-neutral-600: #616161; + --color-neutral-700: #4a4a4a; + --color-neutral-800: #303030; + --color-neutral-900: #1f1f1f; + + --color-accent-100: #e6f4f1; + --color-accent-200: #c5e8e0; + --color-accent-300: #9fd3c7; + --color-accent-400: #5fb3a5; + --color-accent-500: #2b9488; + --color-accent-600: #0c615a; + --color-accent-700: #0b4f47; + --color-accent-800: #083b36; + --color-accent-900: #052a26; + + --color-gray-50: var(--color-neutral-100); + --color-gray-100: var(--color-neutral-200); + --color-gray-200: var(--color-neutral-300); + --color-gray-300: var(--color-neutral-400); + --color-gray-400: var(--color-neutral-500); + --color-gray-500: var(--color-neutral-600); + --color-gray-600: var(--color-neutral-700); + --color-gray-700: var(--color-neutral-800); + --color-gray-800: var(--color-neutral-900); + --color-gray-900: var(--color-ink); + --color-gray-950: var(--color-ink); + + --color-blue-50: var(--color-accent-100); + --color-blue-100: var(--color-accent-100); + --color-blue-200: var(--color-accent-200); + --color-blue-300: var(--color-accent-300); + --color-blue-400: var(--color-accent-400); + --color-blue-500: var(--color-accent-500); + --color-blue-600: var(--color-accent); + --color-blue-700: var(--color-accent-700); + --color-blue-800: var(--color-accent-800); + --color-blue-900: var(--color-accent-900); + --color-blue-950: var(--color-accent-900); + + --color-red-50: #fee3e0; + --color-red-100: #fee3e0; + --color-red-200: #f9c4bd; + --color-red-300: #f2a198; + --color-red-400: #e06a5a; + --color-red-500: #c9382a; + --color-red-600: var(--color-danger); + --color-red-700: #8e1f0b; + --color-red-800: #6b1708; + --color-red-900: #4a1005; + + /* Radius scale: 8 buttons, chips, inputs, pills; 12 cards; 14 drawer. */ + --radius: 8px; + --radius-xs: 4px; + --radius-sm: 6px; + --radius-md: 8px; + --radius-lg: 8px; + --radius-xl: 12px; + --radius-2xl: 14px; + --radius-3xl: 14px; + --radius-4xl: 14px; + + --shadow-card: 0 0 0 1px rgba(0,0,0,.08), 0 1px 2px rgba(0,0,0,.06); + --shadow-float: 0 0 0 1px rgba(0,0,0,.1), 0 12px 32px rgba(0,0,0,.18); + --shadow-drawer: 0 0 0 1px rgba(0,0,0,.1), 0 24px 60px rgba(0,0,0,.24); + --shadow-primary: inset 0 -1px 0 #000, inset 0 1px 0 rgba(255,255,255,.18), 0 1px 2px rgba(0,0,0,.2); + --shadow-secondary: inset 0 0 0 1px var(--color-ring), 0 1px 0 rgba(0,0,0,.05); + --shadow-input: inset 0 0 0 1px var(--color-faint); + --shadow-chip: inset 0 0 0 1px var(--color-ring); + --shadow-chip-set: inset 0 0 0 1px var(--color-accent-300); + --shadow-sm: 0 1px 2px rgba(0,0,0,.06); + --shadow-md: 0 3px 10px rgba(0,0,0,.12); + --shadow-lg: var(--shadow-float); + --shadow-xl: var(--shadow-float); + --shadow-2xl: var(--shadow-float); + + --font-sans: var(--font-geist), system-ui, sans-serif; + --font-mono: var(--font-geist-mono), ui-monospace, SFMono-Regular, Menlo, monospace; +} + +@layer base { + html { + background: var(--color-ground); + } + + body { + background: var(--color-ground); + color: var(--color-ink); + font-family: var(--font-sans); + font-size: 13px; + line-height: 1.5; + } + + h1, h2, h3, h4, h5, h6 { + font-weight: 650; + line-height: 1.25; + letter-spacing: -0.01em; + } + + :focus { + outline: none; + } + + :focus-visible { + outline: 2px solid var(--color-accent); + outline-offset: 2px; + } + + ::selection { + background: color-mix(in srgb, var(--color-accent) 25%, transparent); + } + + input, + textarea, + select { + color: var(--color-ink); + } + + input::placeholder, + textarea::placeholder { + color: var(--color-faint); + } + + button:disabled, + input:disabled, + select:disabled, + textarea:disabled { + opacity: 0.45; + cursor: not-allowed; + } +} +``` + +- [ ] **Step 7: Switch the font in `app/layout.tsx`** + +Read the file, then replace the import, the font constants and the `` className: + +```tsx +import { Geist, Geist_Mono } from 'next/font/google' +``` + +```tsx +const geist = Geist({ + variable: '--font-geist', + subsets: ['latin'], +}) + +const geistMono = Geist_Mono({ + variable: '--font-geist-mono', + subsets: ['latin'], +}) +``` + +```tsx + className={`${geist.variable} ${geistMono.variable} h-full antialiased`} +``` + +Remove the Archivo import, constant and usage. Confirm: `grep -n Archivo app/layout.tsx` prints nothing. + +- [ ] **Step 8: Sweep 2px borders to 1px and fix the two tests that asserted them** + +```bash +python3 - <<'EOF' +import re, glob +tok1 = re.compile(r'(?&1 | grep -E "Test Files|Tests " +npm run check:design 2>&1 | tail -3 +npx tsc --noEmit 2>&1 | head -5; echo "tsc done" +npx vitest run 2>&1 | grep -E "Test Files|Tests " +rm -rf .next && npm run build > /tmp/ims-build.log 2>&1; echo "build exit=$?" +f=$(ls .next/static/chunks/*.css | head -1) +echo "accent: $(grep -ho '\-\-color-accent:[^;}]*' $f | head -1) | md radius: $(grep -ho '\-\-radius-md:[^;}]*' $f | head -1) | st-green-bg: $(grep -ho '\-\-color-st-green-bg:[^;}]*' $f | head -1) | font: $(grep -ho '\-\-font-sans:[^;}]*' $f | head -1)" +``` + +Expected: token and gate tests all pass; `design gates: clean`; `tsc` prints nothing; the full suite shows exactly the 7 baseline failures; build exit 0; the CSS line shows `#0f766e`, `8px`, `#d7f4e3` and `var(--font-geist)`. If the CSS line is empty or shows Tailwind defaults, the `@theme` block is not being compiled: check for a stray `*/` in comments before anything else. + +- [ ] **Step 10: Commit** + +```bash +git add scripts/check-design-gates.mjs tests/scripts/check-design-gates.test.ts app/globals.css app/layout.tsx tests/design/tokens.test.ts tests/components/layout/sidebar.test.tsx tests/components/ui/modal.test.tsx app components +git commit -m "feat(design): switch to IMS Admin tokens, Geist and the 1px-rule gate + +Co-Authored-By: Claude Haiku 4.5 " +``` + +--- + +### Task 2: UI primitives + +**Files:** +- Modify: `components/ui/button.tsx`, `components/ui/status-tag.tsx`, `components/ui/field.tsx`, `components/ui/card.tsx`, `components/ui/modal.tsx` +- Create: `components/ui/checkbox.tsx`, `components/ui/filter-chip.tsx`, `components/ui/segmented.tsx`, `components/ui/avatar.tsx`, `components/ui/drawer.tsx` +- Delete: `components/ui/tag.tsx`, `components/ui/table-styles.ts` +- Test: `tests/components/ui/primitives.test.tsx` (full rewrite), `tests/components/ui/modal.test.tsx` (rewrite) + +**Interfaces:** +- Consumes: Task 1 utilities. +- Produces (later tasks import exactly these): + - `cx(...parts)` from `./cx` (unchanged) + - `Button({ variant?: 'primary'|'secondary'|'icon', block?: boolean, mobile?: boolean } & ButtonHTMLAttributes)`; default `type="button"` + - `StatusTag({ status: string, children?: ReactNode })`, `PriorityTag({ priority: string, children?: ReactNode })`, `statusHue(key: string): StatusHue` where `StatusHue = 'amber'|'blue'|'violet'|'orange'|'indigo'|'green'|'grey'|'red'` + - `Checkbox({ checked: boolean, indeterminate?: boolean, onChange: (next: boolean) => void, label: string })` + - `FilterChip({ label: string, value: string, options: Array<{ value: string, label: string }>, onChange: (value: string) => void })` + - `Segmented({ value: string, onChange: (v: string) => void, options: Array<{ value: string, label: ReactNode }> })` + - `Avatar({ name: string })` + - `Drawer({ open: boolean, onClose: () => void, title: string, actions?: ReactNode, children: ReactNode })` + - `Field`, `Input`, `Textarea`, `Select`, `INPUT_CLASS` from `./field`; `Card({ kicker?, title?, meta?, children? })`; `Modal` (same props as today) + +- [ ] **Step 1: Write the failing primitives test** + +Replace `tests/components/ui/primitives.test.tsx`: + +```tsx +import { describe, it, expect, vi } from 'vitest' +import { render, screen, fireEvent } from '@testing-library/react' +import { Button } from '@/components/ui/button' +import { StatusTag, PriorityTag, statusHue } from '@/components/ui/status-tag' +import { Checkbox } from '@/components/ui/checkbox' +import { FilterChip } from '@/components/ui/filter-chip' +import { Segmented } from '@/components/ui/segmented' +import { Avatar } from '@/components/ui/avatar' +import { Drawer } from '@/components/ui/drawer' +import { Field, Input } from '@/components/ui/field' +import { Card } from '@/components/ui/card' + +describe('Button', () => { + it('primary is the dark 32px button, type=button by default', () => { + render() + const b = screen.getByRole('button', { name: 'Report incident' }) + expect(b.getAttribute('type')).toBe('button') + expect(b.className).toContain('bg-ink-2') + expect(b.className).toContain('h-8') + expect(b.className).toContain('rounded-md') + expect(b.className).toContain('shadow-primary') + }) + + it('secondary is white with a ring', () => { + render() + const b = screen.getByRole('button', { name: 'Export' }) + expect(b.className).toContain('bg-surface') + expect(b.className).toContain('shadow-secondary') + }) + + it('icon is a 28px ghost button', () => { + render() + const b = screen.getByRole('button', { name: 'Submit' }) + expect(b.className).toContain('w-full') + expect(b.className).toContain('h-12') + expect(b.className).toContain('rounded-xl') + }) +}) + +describe('StatusTag and PriorityTag', () => { + it.each([ + ['reported', 'amber'], ['triaged', 'blue'], ['investigating', 'violet'], ['capa_pending', 'orange'], + ['verification', 'indigo'], ['closed', 'green'], ['open', 'grey'], ['in_progress', 'blue'], + ['overdue', 'red'], ['pending_verification', 'indigo'], ['verified', 'green'], ['reopened', 'red'], + ['high', 'orange'], ['med', 'amber'], ['low', 'grey'], ['nonsense', 'grey'], + ])('%s uses the %s pair', (key, hue) => { + expect(statusHue(key)).toBe(hue) + }) + + it('renders a dark-on-tint pill with a text label', () => { + render() + const el = screen.getByText('CAPA pending') + expect(el.className).toContain('bg-st-orange-bg') + expect(el.className).toContain('text-st-orange-fg') + expect(el.className).toContain('rounded-md') + }) + + it('accepts a label override', () => { + render(Late) + expect(screen.getByText('Late').className).toContain('bg-st-red-bg') + }) + + it('priority med reads Medium on the amber pair', () => { + render() + expect(screen.getByText('Medium').className).toContain('bg-st-amber-bg') + }) + + it('never uses white text on a saturated fill', () => { + const { container } = render() + expect(container.innerHTML).not.toContain('text-white') + }) +}) + +describe('Checkbox', () => { + it('toggles and reports the next value', () => { + const onChange = vi.fn() + render() + const cb = screen.getByRole('checkbox', { name: 'Select row' }) + expect(cb.getAttribute('aria-checked')).toBe('false') + fireEvent.click(cb) + expect(onChange).toHaveBeenCalledWith(true) + }) + + it('shows checked and indeterminate states', () => { + const { rerender } = render( {}} label="a" />) + expect(screen.getByRole('checkbox').getAttribute('aria-checked')).toBe('true') + expect(screen.getByRole('checkbox').className).toContain('bg-accent') + rerender( {}} label="a" />) + expect(screen.getByRole('checkbox').getAttribute('aria-checked')).toBe('mixed') + }) +}) + +describe('FilterChip', () => { + const options = [{ value: 'open', label: 'Open' }, { value: 'closed', label: 'Closed' }] + + it('unset shows the label and a select with an empty option', () => { + render( {}} />) + expect(screen.getByText('Status')).toBeTruthy() + expect((screen.getByLabelText('Status') as HTMLSelectElement).value).toBe('') + }) + + it('changes through the select', () => { + const onChange = vi.fn() + render() + fireEvent.change(screen.getByLabelText('Status'), { target: { value: 'closed' } }) + expect(onChange).toHaveBeenCalledWith('closed') + }) + + it('set shows Label: value in the teal tint with a clear button', () => { + const onChange = vi.fn() + render() + expect(screen.getByText('Status: Closed').closest('label')?.className).toContain('bg-accent-tint-2') + fireEvent.click(screen.getByRole('button', { name: 'Clear Status' })) + expect(onChange).toHaveBeenCalledWith('') + }) +}) + +describe('Segmented', () => { + it('marks the active option and reports changes', () => { + const onChange = vi.fn() + render() + expect(screen.getByRole('button', { name: 'List' }).getAttribute('aria-pressed')).toBe('true') + fireEvent.click(screen.getByRole('button', { name: 'Board' })) + expect(onChange).toHaveBeenCalledWith('board') + }) +}) + +describe('Avatar', () => { + it('shows up to two initials on the teal tile', () => { + render() + const el = screen.getByText('AL') + expect(el.className).toContain('bg-accent-200') + expect(el.className).toContain('rounded-[6px]') + }) +}) + +describe('Drawer', () => { + it('renders nothing when closed', () => { + const { container } = render( {}} title="Notifications">x) + expect(container.firstChild).toBeNull() + }) + + it('renders a labelled dialog, closes on the X button and on Escape', () => { + const onClose = vi.fn() + render(Mark all read}>body) + expect(screen.getByRole('dialog', { name: 'Notifications' })).toBeTruthy() + expect(screen.getByText('Mark all read')).toBeTruthy() + fireEvent.click(screen.getByRole('button', { name: 'Close' })) + fireEvent.keyDown(document, { key: 'Escape' }) + expect(onClose).toHaveBeenCalledTimes(2) + }) +}) + +describe('Field, Input, Card', () => { + it('Input is 36px with the faint ring and is labelled', () => { + render() + const input = screen.getByLabelText('Email') + expect(input.className).toContain('h-9') + expect(input.className).toContain('shadow-input') + expect(input.className).toContain('rounded-md') + }) + + it('Card is a white 12px card with the card shadow', () => { + const { container } = render(Body) + expect(container.firstElementChild?.className).toContain('rounded-xl') + expect(container.firstElementChild?.className).toContain('shadow-card') + expect(screen.getByText('Forklift')).toBeTruthy() + }) +}) +``` + +- [ ] **Step 2: Rewrite the modal test** + +Replace `tests/components/ui/modal.test.tsx`: + +```tsx +import { describe, it, expect, vi } from 'vitest' +import { render, screen, fireEvent } from '@testing-library/react' +import { Modal } from '@/components/ui/modal' + +describe('Modal', () => { + it('renders nothing when closed', () => { + const { container } = render( {}} title="T">body) + expect(container.firstChild).toBeNull() + }) + + it('renders a 12px card dialog with the floating shadow and a 1px header rule', () => { + render( {}} title="Confirm" footer={actions}>body text) + const dialog = screen.getByRole('dialog') + expect(screen.getByText('Confirm')).toBeTruthy() + expect(screen.getByText('body text')).toBeTruthy() + expect(screen.getByText('actions')).toBeTruthy() + expect(dialog.innerHTML).toContain('rounded-xl') + expect(dialog.innerHTML).toContain('shadow-float') + expect(dialog.innerHTML).toContain('border-b border-rule') + expect(dialog.innerHTML).not.toContain('border-b-2') + }) + + it('closes from the X button and on Escape', () => { + const onClose = vi.fn() + render(x) + fireEvent.click(screen.getByRole('button', { name: 'Close' })) + fireEvent.keyDown(document, { key: 'Escape' }) + expect(onClose).toHaveBeenCalledTimes(2) + }) +}) +``` + +- [ ] **Step 3: Run to verify they fail** + +Run: `npx vitest run tests/components/ui 2>&1 | grep -E "Test Files|Tests |Failed to resolve" | head -5` +Expected: FAIL (modules such as `@/components/ui/checkbox` not found, old assertions failing). + +- [ ] **Step 4: Write the primitives** + +`components/ui/button.tsx`: + +```tsx +import type { ButtonHTMLAttributes } from 'react' +import { cx } from './cx' + +type Variant = 'primary' | 'secondary' | 'icon' + +const BASE = + 'inline-flex items-center justify-center gap-1.5 whitespace-nowrap transition-colors cursor-pointer ' + + 'disabled:opacity-45 disabled:cursor-not-allowed' + +const VARIANTS: Record = { + primary: 'h-8 px-3 rounded-md bg-ink-2 text-white text-[13px] font-semibold shadow-primary hover:bg-ink active:bg-black', + secondary: 'h-8 px-3 rounded-md bg-surface text-ink text-[13px] font-medium shadow-secondary hover:bg-surface-2 active:bg-rule', + icon: 'w-7 h-7 rounded-md text-ink-3 hover:bg-rule', +} + +type Props = ButtonHTMLAttributes & { + variant?: Variant + block?: boolean + mobile?: boolean +} + +export function Button({ variant = 'primary', block = false, mobile = false, className, type = 'button', ...rest }: Props) { + return ( + + ) +} +``` + +`components/ui/filter-chip.tsx`: + +```tsx +import { ChevronDown, X } from 'lucide-react' +import { cx } from './cx' + +export function FilterChip({ + label, + value, + options, + onChange, +}: { + label: string + value: string + options: Array<{ value: string; label: string }> + onChange: (value: string) => void +}) { + const selected = options.find(o => o.value === value) + const set = Boolean(value && selected) + return ( + + ) +} +``` + +`components/ui/segmented.tsx`: + +```tsx +import type { ReactNode } from 'react' +import { cx } from './cx' + +export function Segmented({ + value, + onChange, + options, +}: { + value: string + onChange: (v: string) => void + options: Array<{ value: string; label: ReactNode }> +}) { + return ( +
+ {options.map(o => ( + + ))} +
+ ) +} +``` + +`components/ui/avatar.tsx`: + +```tsx +export function initials(name: string): string { + return name + .split(' ') + .map(w => w[0] ?? '') + .join('') + .toUpperCase() + .slice(0, 2) +} + +export function Avatar({ name }: { name: string }) { + return ( + + {initials(name)} + + ) +} +``` + +`components/ui/drawer.tsx`: + +```tsx +'use client' + +import { useEffect } from 'react' +import { X } from 'lucide-react' +import { Button } from './button' + +export function Drawer({ + open, + onClose, + title, + actions, + children, +}: { + open: boolean + onClose: () => void + title: string + actions?: React.ReactNode + children: React.ReactNode +}) { + useEffect(() => { + if (!open) return + const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose() } + document.addEventListener('keydown', onKey) + return () => document.removeEventListener('keydown', onKey) + }, [open, onClose]) + + if (!open) return null + + return ( +
+
+ +
+ ) +} +``` + +`components/ui/field.tsx` (keep exports; restyle): + +```tsx +import type { InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from 'react' +import { cx } from './cx' + +export const INPUT_CLASS = + 'w-full h-9 px-3 rounded-md bg-surface text-[13px] text-ink caret-accent shadow-input ' + + 'placeholder:text-faint disabled:opacity-45 disabled:cursor-not-allowed' + +export function Field({ label, htmlFor, children }: { label: string; htmlFor: string; children: ReactNode }) { + return ( +
+ + {children} +
+ ) +} + +export function Input({ className, ...rest }: InputHTMLAttributes) { + return +} + +export function Textarea({ className, ...rest }: TextareaHTMLAttributes) { + return