@exxatdesignux/ui 0.1.0 → 0.2.7

package/bin/cli.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Primary CLI for `@exxatdesignux/ui`.
+ *
+ * Usage (after publish) — prefer **scoped** install so you always run this package’s binary
+ * (plain `npx exxat-ui` would fetch a different npm package named `exxat-ui` if it exists):
+ *   npx --package=@exxatdesignux/ui@latest exxat-ui init
+ *   npx --package=@exxatdesignux/ui@latest exxat-ui update
+ *
+ * `npm create exxat-app` still maps to `bin/init.mjs` for empty-folder scaffolding.
+ */
+
+import { execFileSync } from "child_process"
+import { readFileSync } from "fs"
+import { dirname, resolve } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const cmd = process.argv[2] ?? "help"
+
+function runInitScript() {
+  execFileSync(process.execPath, [resolve(__dirname, "init.mjs")], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  })
+}
+
+function runSyncExtras() {
+  execFileSync(process.execPath, [resolve(__dirname, "sync-extras.mjs")], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  })
+}
+
+/** @returns {number} negative if a < b, 0 if equal, positive if a > b (x.y.z only) */
+function compareSemver(a, b) {
+  const pa = a.split(".").map(n => parseInt(n, 10) || 0)
+  const pb = b.split(".").map(n => parseInt(n, 10) || 0)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] ?? 0
+    const db = pb[i] ?? 0
+    if (da !== db) return da - db
+  }
+  return 0
+}
+
+function printHelp() {
+  console.log(`
+@exxatdesignux/ui — CLI
+
+Commands:
+  init         Scaffold the Exxat DS starter app (must run in an empty directory).
+  sync-extras  Copy packaged Cursor skills + pattern docs into this repo (DS-only paths).
+  update       How to upgrade an existing project that depends on this package.
+  doctor       Compare this CLI version vs npm registry "latest" (diagnose stale installs).
+
+Do NOT use plain npx @exxatdesignux/ui — use the scoped form below.
+
+Examples:
+  npx --package=@exxatdesignux/ui@latest exxat-ui init
+  npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+  npx --package=@exxatdesignux/ui@latest exxat-ui doctor
+  npx --package=@exxatdesignux/ui@latest exxat-ui update
+
+Legacy (npm create):
+  npm create exxat-app@latest
+`)
+}
+
+function printUpdate() {
+  console.log(`
+Update @exxatdesignux/ui in your application:
+
+  npm install @exxatdesignux/ui@latest
+
+  # If the lockfile still pins an old release, force the resolver:
+  npm install @exxatdesignux/ui@latest --save --prefer-online
+
+  # or (pnpm)
+  pnpm add @exxatdesignux/ui@latest
+
+  # or (yarn)
+  yarn add @exxatdesignux/ui@latest
+
+That refreshes **components / hooks / tokens** under node_modules only — your app
+routes and product copy are unchanged.
+
+**Still seeing old code?** Run **exxat-ui doctor** — the npm "latest" tag often lags
+this Git repo until maintainers publish (git tag **ui-v<version>**).
+
+To also refresh **bundled Cursor skills** and **pattern reference docs** from the
+same package version (overwrites only .cursor/skills/exxat-* and docs/exxat-ds/):
+
+  npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+
+CLI (always pulls this scope): npx --package=@exxatdesignux/ui@latest exxat-ui <init|sync-extras|update|doctor|help>
+
+Monorepo / design-system contributors (this workspace): pull latest Git and run
+  pnpm install
+from the repository root — apps use "workspace:*" for the local package.
+
+Scaffold: exxat-ui init pins @exxatdesignux/ui in the new app to the same semver as
+this CLI tarball so npm does not resolve a stale "latest" from cache.
+`)
+}
+
+function printDoctor() {
+  const pkgPath = resolve(__dirname, "../package.json")
+  let cliVersion = "unknown"
+  try {
+    cliVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version
+  } catch {
+    /* ignore */
+  }
+  console.log(`This exxat-ui CLI (package on disk / npx extract): ${cliVersion}`)
+  try {
+    const reg = execFileSync("npm", ["view", "@exxatdesignux/ui", "version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim()
+    console.log(`npm registry dist-tag "latest":              ${reg || "(no response)"}`)
+    if (reg && reg !== cliVersion) {
+      console.log("")
+      if (compareSemver(reg, cliVersion) < 0) {
+        console.log(
+          "The registry is **behind** this CLI package: Git has a newer version that has not been published to npm yet.",
+        )
+        console.log(
+          "Running `npm install @exxatdesignux/ui@latest` only installs **" + reg + "** until maintainers publish (push tag **ui-v" + cliVersion + "**).",
+        )
+      } else {
+        console.log(
+          "The registry reports a **newer** version than this CLI — refresh npx/npm cache or run `npx --package=@exxatdesignux/ui@" +
+            reg +
+            " exxat-ui …` so the CLI matches the registry.",
+        )
+      }
+      console.log("")
+      console.log("Options:")
+      console.log("  • Install the latest **published** build: npm install @exxatdesignux/ui@" + reg)
+      console.log("  • Or pack from a Git checkout: cd packages/ui && npm pack && npm i ../exxatdesignux-ui-*.tgz")
+    } else if (reg === cliVersion) {
+      console.log("")
+      console.log("Registry matches this CLI — @latest should resolve to the same release.")
+    }
+  } catch (e) {
+    console.log("")
+    console.log("Could not run `npm view` (offline or npm not in PATH). Error:", (e && e.message) || e)
+  }
+  console.log("")
+}
+
+switch (cmd) {
+  case "init":
+    runInitScript()
+    break
+  case "sync-extras":
+    runSyncExtras()
+    break
+  case "update":
+    printUpdate()
+    break
+  case "doctor":
+    printDoctor()
+    break
+  case "help":
+  case "--help":
+  case "-h":
+    printHelp()
+    break
+  default:
+    console.error(`Unknown command: ${cmd}\n`)
+    printHelp()
+    process.exitCode = 1
+}

package/bin/init.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { cpSync, existsSync, readdirSync } from 'fs'
+import { cpSync, readFileSync, readdirSync, writeFileSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
 import { execSync } from 'child_process'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const templateDir = resolve(__dirname, '../template')
+const selfPkgPath = resolve(__dirname, '../package.json')
 const targetDir = process.cwd()
 
 const files = readdirSync(targetDir)
@@ -19,6 +20,16 @@ if (!isEmpty) {
 console.log('📦  Copying Exxat DS starter app...')
 cpSync(templateDir, targetDir, { recursive: true })
 
+/** Pin DS to this CLI tarball version so `npm install` does not resolve a stale `latest` from cache. */
+const selfVersion = JSON.parse(readFileSync(selfPkgPath, 'utf8')).version
+const targetPkgPath = resolve(targetDir, 'package.json')
+const targetPkg = JSON.parse(readFileSync(targetPkgPath, 'utf8'))
+if (targetPkg.dependencies?.['@exxatdesignux/ui']) {
+  targetPkg.dependencies['@exxatdesignux/ui'] = `^${selfVersion}`
+  writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`)
+  console.log(`📌  Pinned @exxatdesignux/ui to ^${selfVersion} (matches this scaffold).`)
+}
+
 console.log('📥  Installing dependencies...')
 execSync('npm install', { stdio: 'inherit', cwd: targetDir })
 
@@ -27,3 +38,6 @@ console.log('✅  Done! Your Exxat DS app is ready.')
 console.log('')
 console.log('   npm run dev   → start dev server')
 console.log('')
+console.log('   Optional — refresh Cursor skills + pattern docs from the same package:')
+console.log(`   npx --package=@exxatdesignux/ui@${selfVersion} exxat-ui sync-extras`)
+console.log('')

package/bin/sync-extras.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Consumer: copy packaged design-system extras into the app repo.
+ *
+ * Overwrites ONLY:
+ *   - `.cursor/skills/<bundled exxat-* skill folders>/`
+ *   - `docs/exxat-ds/*.md` (pattern reference docs from the package)
+ *
+ * Does NOT touch `app/`, `pages/`, `src/` product code, or npm dependencies.
+ * Run after `npm install @exxatdesignux/ui@…` / `pnpm update @exxatdesignux/ui`.
+ *
+ *   npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = resolve(__dirname, "..")
+const cwd = process.cwd()
+
+const skillsSrc = join(pkgRoot, "consumer-extras", "cursor-skills")
+const skillsDest = join(cwd, ".cursor", "skills")
+
+const patternsSrc = join(pkgRoot, "consumer-extras", "patterns")
+const patternsDest = join(cwd, "docs", "exxat-ds")
+
+function syncSkills() {
+  if (!existsSync(skillsSrc)) {
+    console.error(
+      "[sync-extras] Missing packaged skills. Is @exxatdesignux/ui installed? Expected:",
+      skillsSrc,
+    )
+    process.exit(1)
+  }
+  mkdirSync(skillsDest, { recursive: true })
+  for (const name of readdirSync(skillsSrc)) {
+    const src = join(skillsSrc, name)
+    if (!statSync(src).isDirectory()) continue
+    if (!name.startsWith("exxat-")) continue
+    const dest = join(skillsDest, name)
+    if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+    cpSync(src, dest, { recursive: true })
+    console.log(`[sync-extras] wrote .cursor/skills/${name}/`)
+  }
+}
+
+function syncPatterns() {
+  if (!existsSync(patternsSrc)) {
+    console.warn("[sync-extras] no packaged patterns (optional).")
+    return
+  }
+  mkdirSync(patternsDest, { recursive: true })
+  for (const name of readdirSync(patternsSrc)) {
+    const src = join(patternsSrc, name)
+    if (!statSync(src).isFile()) continue
+    cpSync(src, join(patternsDest, name))
+    console.log(`[sync-extras] wrote docs/exxat-ds/${name}`)
+  }
+}
+
+syncSkills()
+syncPatterns()
+console.log("[sync-extras] Done. Product routes and app content were not modified.")

package/consumer-extras/README.md

@@ -0,0 +1,21 @@
+# Consumer extras (ships with `@exxatdesignux/ui`)
+
+These folders are **not** application content. They are design-system reference
+material that other repositories can **refresh from the npm package** without
+touching product routes or pages.
+
+| Path in this tarball | After `exxat-ui sync-extras` in your repo |
+|----------------------|-------------------------------------------|
+| `cursor-skills/exxat-*` | `.cursor/skills/exxat-*` (replaced) |
+| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) |
+
+**Components and hooks** still come only from `node_modules/@exxatdesignux/ui`
+via normal semver installs — `sync-extras` does not copy TS source into your app.
+
+**Maintainers** (this monorepo): when skills or web docs change, run:
+
+```bash
+pnpm --filter @exxatdesignux/ui vendor:consumer-extras
+```
+
+…then bump `packages/ui` version and publish so consumers get the new bundle.

package/consumer-extras/cursor-skills/exxat-accessibility/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: exxat-accessibility
+description: WCAG 2.x / ARIA checklist for Exxat DS — tablists, touch targets, contrast, and audit follow-ups. Use when fixing axe/Deque issues, building nav or tab UIs, or reviewing accessibility.
+user-invocable: true
+---
+
+# Exxat DS — accessibility checklist
+
+Standard target: **WCAG 2.1 Level AA** (and 2.2 where noted).
+
+**Canonical for agents (MUST/MUST NOT, checklist):** `exxat-ds/AGENTS.md` **§8** in the repo (same content summarized there; this skill stays the detailed checklist + product tokens).
+
+## ARIA roles & structure (SC 1.3.1)
+
+- **`role="tablist"`** may only contain **`role="tab"`** (or elements that resolve to tabs). Do **not** place `role="button"`, menus (`aria-haspopup`), or ad-hoc controls **inside** the same `tablist` container.
+- **Composite view switchers** (tabs + per-tab settings menu + remove control): use **`role="toolbar"`** with **`aria-label`**, and **`aria-pressed`** on view toggle buttons instead of misusing `tab`/`tablist`.
+- Prefer **`<button type="button">`** over **`span role="button"`** for clickable icons (keyboard + AT).
+
+## Touch targets (WCAG 2.2 AA — 2.5.8 Target Size Minimum)
+
+- Interactive controls (including icon-only chevrons and close icons) should be at least **24×24 CSS pixels**, or have **24px** spacing so their **24px** hit circles do not overlap adjacent targets.
+- Use **`min-h-6 min-w-6`** (or `size-6`) with centered icons; avoid `size-4` (16px) for sole click targets.
+
+## Icons that communicate information — always have a text alternative (SC 1.1.1, 3.3.2, 2.4.6)
+
+This rule covers **every icon that carries meaning**, not only icon-only buttons. FA glyphs, inline SVGs, avatar placeholders, trend arrows, status dots, chart-legend squares, calendar/clock/pin icons in cells — if the icon **tells the user something**, that something MUST be reachable by screen readers AND discoverable to sighted users who don't recognise the glyph.
+
+There are three cases. Pick the one that matches the icon's context:
+
+### Case A — Decorative icon next to text that already names it
+
+When the icon sits adjacent to a visible text label that already carries the meaning, the icon is **decorative**. It MUST be `aria-hidden` and MUST NOT carry `aria-label` (screen readers would announce the meaning twice).
+
+```tsx
+<span className="flex items-center gap-1.5">
+  <i className="fa-light fa-calendar-days" aria-hidden />
+  <span>12/14/2025 – 12/20/2025</span>
+</span>
+
+<Button>
+  <i className="fa-light fa-plus" aria-hidden />
+  <span>New placement</span>
+</Button>
+```
+
+No tooltip needed — the text is the alt. This is the default in table cells, buttons with text labels, breadcrumbs, badges, menu items.
+
+### Case B — Informational icon standing alone (no adjacent label)
+
+When the icon is the **only visible carrier** of the information — e.g.:
+
+- `fa-calendar-days` in a compact table column header meaning "date range"
+- `fa-clock` meaning "updated at" or "time remaining"
+- `fa-location-dot` meaning "site" / "location"
+- `fa-graduation-cap` meaning "student"
+- trending arrow in a KPI card (↑ / ↓)
+- status dot (a coloured circle meaning "on track / at risk / blocked")
+- icon-only legend key on a chart
+- `fa-paperclip` meaning "has attachments"
+- `fa-lock` meaning "restricted"
+
+…the icon MUST:
+
+1. Announce itself to AT via **`role="img"` + `aria-label`** on a wrapping element (span/div), OR inherit the name from a labelled ancestor via `aria-labelledby`.
+2. Expose a visible **`Tooltip`** so sighted mouse/keyboard users who don't recognise the glyph learn the meaning.
+
+```tsx
+<Tooltip>
+  <TooltipTrigger asChild>
+    {/* Non-interactive: wrap in a span with role="img".
+        tabIndex={0} so the tooltip opens on keyboard focus, not just hover. */}
+    <span
+      role="img"
+      aria-label="Placement date range"
+      tabIndex={0}
+      className="inline-flex size-6 items-center justify-center rounded-md text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <i className="fa-light fa-calendar-days" aria-hidden />
+    </span>
+  </TooltipTrigger>
+  <TooltipContent side="top">Placement date range</TooltipContent>
+</Tooltip>
+```
+
+Rules:
+1. `TooltipContent` text MUST match the `aria-label`.
+2. The inner `<i>` / `<svg>` is always `aria-hidden`; the accessible name lives on the wrapper.
+3. If a visible text label could fit, **prefer Case A** (add the label) over tooltip-only.
+4. Target/focus size still **≥ 24×24 CSS px** so keyboard users can focus the icon reliably.
+5. Status dots MUST additionally carry a **text or shape cue** (not colour alone — SC 1.4.1). E.g. pair a coloured dot with a status label nearby, or differentiate by icon shape (`circle-check` vs `triangle-exclamation` vs `circle-xmark`).
+
+### Case C — Interactive icon-only button / link
+
+Any button or link whose visible content is a **single icon** — close (`×`), chevron, overflow (`⋯`), sort direction, filter chip dismiss, copy-to-clipboard, Ask Leo toggle, expand/collapse, row actions — MUST carry BOTH:
+
+1. **`aria-label`** on the `<button>` / `<a>` (programmatic name for AT and axe).
+2. A wrapping **`Tooltip`** whose content repeats the same name (plus a `Kbd` when a shortcut exists).
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"
+import { Kbd } from "@/components/ui/kbd"
+
+<Tooltip>
+  <TooltipTrigger asChild>
+    <button
+      type="button"
+      aria-label="Close insight"
+      onClick={onClose}
+      className="inline-flex size-7 min-h-7 min-w-7 items-center justify-center rounded-md …"
+    >
+      <i className="fa-solid fa-xmark" aria-hidden />
+    </button>
+  </TooltipTrigger>
+  <TooltipContent side="top" className="flex items-center gap-1.5">
+    <span>Close</span>
+    <Kbd>Esc</Kbd>
+  </TooltipContent>
+</Tooltip>
+```
+
+Rules:
+1. `TooltipContent` MUST match or extend the `aria-label`.
+2. Inside the tooltip use the **default tile** `<Kbd>` (NOT `variant="bare"`).
+3. The inner `<i>` / `<svg>` MUST have `aria-hidden`.
+4. Click target **≥ 24×24 CSS px** (see Touch targets section).
+
+### Narrow exceptions (all cases)
+
+- A chevron inside a labelled composite (`Select`, `Combobox`, `Breadcrumb` separator) where the parent already names the whole control or the glyph is purely structural — mark it `aria-hidden`.
+- Drag handles inside a `dnd-kit` listener that reference a labelled ancestor via `aria-describedby`.
+- Decorative icons that purely decorate (e.g. the Leo star next to an already-named "Ask Leo" button) — `aria-hidden`, no tooltip.
+
+### Decision tree
+
+```
+Icon appears somewhere →
+  Is there adjacent visible text that already names the meaning?
+    YES → Case A: aria-hidden, no tooltip. Done.
+    NO  → Is the icon the visible content of a button/link?
+            YES → Case C: aria-label on the control + Tooltip.
+            NO  → Case B: span[role="img", aria-label, tabIndex=0] + Tooltip.
+```
+
+**When in doubt: add the accessible name + tooltip.** Silence is never correct for an icon that means something.
+
+## Keyboard shortcuts inside buttons — `<Kbd variant="bare">` only
+
+The `Kbd` primitive (`@/components/ui/kbd`) has two variants:
+
+| Variant | Where it goes | Chrome |
+|---------|---------------|--------|
+| `tile` (default) | Inside `TooltipContent`, menu `shortcut=` slots, standalone surfaces | Background + border, fixed contrast |
+| `bare` | Inline **inside** a `Button` (primary, secondary, wizard Next/Back/Submit) | No background, no border, inherits `currentColor` at 70 % opacity |
+
+Inside a filled/solid button the `tile` variant looks like a pasted-on patch (wrong background color against the button fill). Always glue multi-key chords into **one** bare kbd:
+
+```tsx
+// ✅ correct — bare inside a button
+<Button>
+  <span>Ask Leo</span>
+  <KbdGroup className="ml-1.5">
+    <Kbd variant="bare">⌘⌥K</Kbd>
+  </KbdGroup>
+</Button>
+
+// ❌ wrong — tile variant on a primary button
+<Button>
+  <span>Ask Leo</span>
+  <KbdGroup className="ml-1.5">
+    <Kbd>⌘</Kbd><Kbd>⌥</Kbd><Kbd>K</Kbd>
+  </KbdGroup>
+</Button>
+```
+
+Reference pattern: `components/new-placement-form.tsx` (Next = `<Kbd variant="bare">{mod}⏎</Kbd>`, Back = `<Kbd variant="bare">{mod}{alt}←</Kbd>`). See `.cursor/rules/exxat-kbd-shortcuts.mdc` for the full shortcut table.
+
+## Color (SC 1.4.3 / 1.4.11)
+
+- **Normal text** (including small badge labels): **≥ 4.5:1** against its background.
+- **UI components** (borders, focus rings): **≥ 3:1** where required by 1.4.11.
+- **Muted text on tinted surfaces** (e.g. sidebar): use tokens mixed against **`--sidebar`**, not only against `--background` (see `--sidebar-section-label-foreground`).
+
+## Sidebar badges (design tokens)
+
+- **Count / numeric (sidebar):** **red** (`bg-red-600` + white). Placement toolbar counts use **status colors** (see below).
+- **“New”:** use **brand** (`bg-brand` + `text-brand-foreground`).
+- **“Beta”:** bright yellow fill + **dark** text (`bg-yellow-400` + `text-yellow-950`) for contrast.
+
+## Placements toolbar count pills (`filterId`)
+
+- **`all`:** slate  
+- **`upcoming`:** amber  
+- **`ongoing`:** blue  
+- **`completed`:** emerald  
+- Unknown `filterId` falls back to **all** (slate).
+
+## Form fields — format hints MUST be persistent (SC 3.3.2, 1.3.1)
+
+Placeholder text disappears on focus, is low-contrast by default, and is not reliably announced by assistive tech. For any field with a **required format**, render the format as **persistent helper text** tied to the input via `aria-describedby` — never rely on the placeholder alone.
+
+**When this applies (non-exhaustive):**
+
+- Dates, times, date ranges (even when a picker is present — the typed-format fallback must show the mask).
+- Phone / fax, country-specific formats.
+- Currency, GPA, percentages, hours, durations, unit-bearing numbers ("hrs/wk", "USD").
+- IDs with a pattern (Student ID `STU-YYYY-####`, NPI, license #).
+- Email / URL where a domain or protocol is required.
+- Credit hours, scores, weights — anything whose scale is not obvious from the label.
+
+**Pattern — use `FormDescription` from shadcn `Form`:**
+
+```tsx
+<FormField name="dob" render={({ field }) => (
+  <FormItem>
+    <FormLabel>Date of birth<span aria-hidden="true"> *</span></FormLabel>
+    <FormControl>
+      <Input {...field} inputMode="numeric" placeholder="MM/DD/YYYY" />
+    </FormControl>
+    {/* Persistent — announced via aria-describedby, survives focus */}
+    <FormDescription>MM/DD/YYYY</FormDescription>
+    <FormMessage />
+  </FormItem>
+)} />
+```
+
+**Rules:**
+
+1. The format MUST appear as visible text **outside** the placeholder — `FormDescription`, a helper `<p>` with `id` referenced by `aria-describedby`, or an adjacent `<small>`.
+2. Placeholder MAY mirror the format as extra affordance, but is never the sole source.
+3. Prefer a **picker primitive** over free-text where one exists: `DatePickerField` for dates, `Select` for enumerated values, masked input for phone/IDs.
+4. Required marker (`*`) is decorative — always pair with `aria-required="true"` on the input.
+5. Error messages (`FormMessage`) replace description announcement while active; keep the description concise so the combined `aria-describedby` string stays readable.
+6. Units belong in the description, not the label suffix, when they vary by context (e.g. "Out of 4.0" under GPA rather than in the label).
+
+## High-Contrast modes
+
+There are **two** HC paths in this app. Fix both or the bar will still look broken in one of them:
+
+1. **App HC theme — `html[data-contrast="high"]`** (user toggle in Settings). Use the **`hc:`** Tailwind variant defined in `globals.css` (line 22: `@custom-variant hc (&:is([data-contrast="high"] *));`). This is what the user sees when they switch to High Contrast in-app.
+2. **OS / browser forced-colors** — Windows High Contrast, some Linux DEs, `prefers-contrast: more`. Use `forced-colors:` variants mapping to system colors (`Canvas`, `CanvasText`, `Highlight`, `HighlightText`, `GrayText`).
+
+### Why tokens collapse in HC
+
+In HC themes many surfaces resolve to near-identical values (e.g. `bg-muted` ≈ `bg-background` in HC dark, `bg-brand` gets desaturated). Any UI encoding state **only via fill/track color** (progress bars, quota gauges, chart ranges, meter pills, dashed reference lines, status pills) flattens into a single rectangle. The fix is to force distinct contrast in HC:
+
+- **Track / container:** `hc:border hc:border-border hc:bg-background` + `forced-colors:border-[CanvasText] forced-colors:bg-[Canvas]`
+- **Active fill / progress:** `hc:bg-foreground` + `forced-colors:bg-[Highlight]`
+- **Dashed marker / divider:** `hc:border-foreground` + `forced-colors:border-[CanvasText]`
+- **Pill on colored bg:** invert to `hc:bg-background hc:text-foreground hc:border hc:border-foreground` + `forced-colors:bg-[Canvas] forced-colors:text-[CanvasText] forced-colors:border-[CanvasText]`
+- **Disabled state:** `forced-colors:text-[GrayText]`
+
+Never rely on `box-shadow` alone for separation in HC — shadows are suppressed; pair with a border.
+
+Windows HC mode (and the CSS `forced-colors: active` media query) strips every custom `background-color`, `border-color`, and `box-shadow` and remaps text/icons to a small palette of system colors. Progress bars, pills, chart legends, avg-markers, and any "color-only" indicator collapse into a single flat rectangle if you rely purely on tokens like `bg-brand` or `bg-muted`.
+
+**Rule:** for every UI that encodes state **via fill / track color** (progress bars, quota gauges, chart ranges, meter pills, status pills, dashed reference lines):
+
+1. Keep the default `bg-*` tokens for light/dark themes.
+2. Add `forced-colors:` variants mapping to system colors:
+   - **Track / container:** `forced-colors:bg-[Canvas] forced-colors:border forced-colors:border-[CanvasText]`
+   - **Active fill / progress:** `forced-colors:bg-[Highlight]` (text on it → `forced-colors:text-[HighlightText]`)
+   - **Dashed marker / divider:** `forced-colors:border-[CanvasText]`
+   - **Tooltip / pill on colored bg:** `forced-colors:bg-[Canvas] forced-colors:text-[CanvasText] forced-colors:border forced-colors:border-[CanvasText]`
+   - **Disabled state:** `forced-colors:text-[GrayText]`
+3. Never rely on `box-shadow` alone for separation in HC — shadows are suppressed; pair with a border.
+
+Reference fix: `components/dashboard-quota-progress-card.tsx` `StudentScoreProgressRow` — track → `Canvas`, fill → `Highlight`, avg-marker pill → `Canvas` + `CanvasText` border.
+
+## Audit rules to track (examples)
+
+| Severity | Rule | Criterion |
+|----------|------|-----------|
+| Critical | Certain ARIA roles must contain particular children | 1.3.1 |
+| Serious | Touch targets must be ≥24px or spaced accordingly | 2.5.8 |
+
+When fixing, re-run **axe** or your preferred checker on the **Placements** page after changing the Views toolbar.
+
+## Charts (keyboard exploration)
+
+- **Chart region:** Product charts that support arrow-key exploration use **`ChartFigure`** (`role="application"`, focus ring on the chart container, click-or-Tab to focus per `charts-overview`).
+- **Selected datum:** Prefer **visible** feedback that matches the **`/dashboard` gallery** — Recharts **`activeBar`** + **`activeIndex`** for bars, **`activeShape`** + **`activeIndex`** for pies — via **`@/lib/chart-keyboard-selection`**. Avoid relying on **opacity-only** dimming as the only “selected” indicator; pair with ring/stroke so focus is perceivable (WCAG **2.4.7 Focus Visible** where applicable).
+- **Tables under charts:** **`ChartDataTable`** (`sr-only`) provides an equivalent programmatic structure for screen-reader users.

package/consumer-extras/cursor-skills/exxat-board-cards/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: exxat-board-cards
+description: >-
+  Build and maintain kanban board cards in Exxat DS — ListPageBoardCard shell, title/avatar/badge/body hierarchy, BoardCardTwoLineBlock, list-status-badges, ListPageBoardTemplate. Use when adding board view, Team/Compliance/Placements cards, or status chips on cards.
+user-invocable: true
+---
+
+# Exxat DS — board (kanban) cards
+
+**Canonical MUST/MUST NOT:** **`exxat-ds/AGENTS.md` §4.4** (or **`./AGENTS.md`** when the workspace is the `exxat-ds` app folder only). **Claude:** **`.claude/skills/exxat-board-cards/SKILL.md`** (repo root) or **`exxat-ds/.claude/skills/exxat-board-cards/SKILL.md`** (app-only workspace) — same body as this file. This skill is the **how-to**; the handbook stays the contract.
+
+## When to use this skill
+
+- Adding or changing **`viewType === "board"`** on a **`ListPageTemplate`** hub.
+- Building a new **`EntityBoardView`** or **`renderCard`** for **`ListPageBoardTemplate`**.
+- Aligning **Team** / **Compliance** board cards with **Placements**.
+- Wiring **status** on cards so it matches **table** and **list** views.
+
+## Shell: `ListPageBoardCard`
+
+Import from **`@/components/data-views/list-page-board-card`**:
+
+| Part | Component | Role |
+|------|-----------|------|
+| Outer | **`ListPageBoardCard`** | **`Card` `size="sm"`**; pass **`onClick`**, **`isNew`**, **`style`** (e.g. conditional row bg) like **`BoardPlacementCard`**. |
+| Header wrapper | **`ListPageBoardCardHeader`** | Vertical rhythm inside the card. |
+| Title row | **`ListPageBoardCardTitleRow`** | **`title`** + optional **`trailing`** + **`titleClassName`** (`truncate`, `line-clamp-2`, **`lineClampClass`**). |
+| Avatar | **`ListPageBoardCardAvatar`** | **`initials`** string; **`size-7`**, **`--avatar-initials-bg` / `--avatar-initials-fg`**. |
+| Status / tags | **`ListPageBoardCardBadgeRow`** | **`ListHubStatusBadge`** **`surface="board"`** (+ maps from **`lib/list-status-badges.ts`**) — **not** raw status text or one-off **`Badge`** markup in the body. |
+| Body | **`ListPageBoardCardBody`** | Icon rows and two-line blocks (facts). |
+| Hint | **`ListPageBoardCardSecondary`** | Empty states / helper copy. |
+
+## Primitives: `board-card-primitives.tsx`
+
+- **`BoardCardTwoLineBlock`** — icon + **primary** line (`font-medium text-foreground`) + optional **secondary** (muted). Omit **`line2`** for a single-line fact row.
+- **`BoardCardIconRow`** — when mirroring rich **table cells** (see **`BoardPlacementCard`**).
+- **`lineClampClass`** — pass into title or cell wrappers when density options apply.
+- **`BoardNewCardPlaceholder`** — column chrome for **`ListPageBoardTemplate`**.
+
+Prefer **two-line blocks** for stacked **primary / secondary** facts so cards match Placements’ visual rhythm.
+
+## Status badges (list hubs: Team, Compliance, Question bank, …)
+
+- **Maps (single source):** **`lib/list-status-badges.ts`** — per-entity `*_STATUS_LABEL`, `*_STATUS_BADGE_CLASS`, `*_STATUS_ICON`, plus semantic **`LIST_HUB_STATUS_TINT_*`** (success / warning / neutral / danger) for new domains.
+- **Component:** **`ListHubStatusBadge`** from **`@/components/list-hub-status-badge`** — **`surface="table"`** for **DataTable** cells and **list** rows; **`surface="board"`** inside **`ListPageBoardCardBadgeRow`**. Do not duplicate the shell classes on each page.
+- Use the **same** maps everywhere for that entity so copy and colors never drift.
+- **Do not** add **`uppercase`** or **`tracking-wide`** — **sentence / title case**, consistent with **`BoardStatusBadge`** on Placements (`placement-board-card.tsx`).
+- **Placements** lifecycle uses **`StatusBadge`** in **`data-list-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Question bank).
+
+## Avatar when mock has no `initials`
+
+Use **`initialsFromDisplayName`** from **`lib/initials-from-name.ts`** (e.g. compliance **owner** name).
+
+## Column template (simple hubs)
+
+**`ListPageBoardTemplate`** (`list-page-board-template.tsx`) — define **`ListPageBoardColumnDef<T>`** (`id`, `label`, `description`, **`filter`**, **`renderCard`**). Placements uses a **custom** board with richer headers; new hubs usually start here.
+
+## Placements
+
+**`BoardPlacementCard`** (`placement-board-card.tsx`) — domain-specific (lifecycle tabs, **`ColumnDef`**, conditional background). It **still** composes **`ListPageBoardCard`** parts and primitives; copy that structure for new dense entities.
+
+## Checklist
+
+- [ ] **`ListPageBoardCard`** (not one-off button/card markup).
+- [ ] Title row; avatar when product shows a person/owner chip.
+- [ ] Status in **`ListPageBoardCardBadgeRow`** with **`ListHubStatusBadge`** **`surface="board"`** + **`list-status-badges`** (if entity has status).
+- [ ] Body facts via **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`**.
+- [ ] No **`uppercase`** on status **`Badge`** labels.