@exxatdesignux/ui 0.5.10 → 0.5.12

package/template-vite/.cursor/rules/exxat-ux-discovery-protocol.mdc

@@ -0,0 +1,202 @@
+---
+description: Exxat DS — STOP before code on any surface design (new, rebuild, redesign, replace); output a design brief and WAIT for user go-ahead
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — UX discovery protocol
+
+## STOP — read before you write any file
+
+If the user's prompt asks you to **design, create, build, rebuild, redesign,
+replace, redo, refresh, modernize, re-imagine, or "make a new version of"**
+any **page, route, screen, hub, detail view, wizard, settings section,
+dashboard, dialog, sheet, drawer, panel, layout, or significant component**:
+
+1. **Do NOT write code, do NOT edit files, do NOT call edit tools yet.**
+2. **Output the design brief** (template below) in chat.
+3. **Wait for the user to reply** with `yes` / `proceed` / `ship it` / edits.
+4. **Only then** move to implementation.
+
+If your next tool call would be `write_file`, `str_replace`, `create_file`,
+or any code-mutating action **and** you have not posted a brief and received
+go-ahead, you are violating this rule. **Stop and post the brief.**
+
+## When this gate fires (and when it doesn't)
+
+This gate fires on **any task that decides what a surface should look like
+or how it works** — whether the surface exists today or not. Treat
+"replace what we have" and "create from scratch" identically — both need a
+brief, because both make a design decision.
+
+**Fires (brief required):**
+
+- "Create a new student detail page."
+- "Rebuild the dashboard."
+- "Redesign the settings screen instead of what we have."
+- "Make a new version of the placements table."
+- "Replace the current onboarding flow."
+- "Build a wizard for adding a site."
+- "Design a sheet for inviting collaborators."
+- User attaches a screenshot / mockup / Figma link and asks to "build this".
+
+**Does NOT fire (brief not required, edit freely):**
+
+- Single-class restyle of an existing surface that already follows DS rules.
+- Copy / label edits.
+- Bug fixes (a11y violation, broken state, wrong data).
+- Dependency bumps, ESLint passes, type fixes, test-only changes.
+- Adding a new column / filter to an *existing* `HubTable` that doesn't
+  change the page's IA.
+
+When in doubt, ask: **"Am I deciding what this surface should be?"** Yes →
+brief. No → edit.
+
+## MUST
+
+0. **Output the brief, then WAIT.** The brief is a checkpoint, not a
+   preamble. Do not bundle the brief and the first file edit in the same
+   turn. After posting the brief, end your turn with an explicit
+   "Ready to build — confirm or edit." prompt. Resume only on the user's
+   next message.
+1. **No code without a confirmed brief.** "Confirmed" means the user wrote
+   `yes`, `proceed`, `ship it`, `LGTM`, `build it`, accepted edits, or asked
+   a follow-up that implies acceptance. Silence is not consent.
+2. **Cite a reference.** Every brief names **one repo reference** + **two
+   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel /
+   Linear / Airtable / Coda / Height / etc.) that solve the same
+   **job-to-be-done**. Cite the SaaS analogues by product name + pattern
+   codes from `apps/web/docs/modern-saas-patterns.md` (e.g.
+   `Linear issue detail (M1, M4, M7)`).
+3. **Name principles + breaks.** Brief lists the principles applied
+   (`exxat-ux-principles.mdc`) and any deviations with one-sentence reasons.
+   **Never-break** principles (P1–P8) cannot be deviated from.
+4. **One assumption per gap.** If the user can't or won't answer, state the
+   assumption inline; never invent silently.
+5. **Sync the brief to the implementation.** PR / commit message references
+   the job doc (`apps/web/docs/jobs/`) and any principle break.
+
+## MUST NOT
+
+- **Skip the brief because the prompt sounds like a refactor.** "Rebuild",
+  "redesign", "replace", "instead of what we have", and "from scratch" are
+  design decisions, not refactors. Brief required.
+- **Post a brief and then write 8 files in the same turn.** That's not a
+  brief — that's a press release. End the turn after the brief.
+- Generate files before the brief.
+- Ask more than **3** questions in one batch.
+- Ask questions whose answer is already in the prompt, the file tree, or
+  `apps/web/docs/jobs/`.
+- Use uploaded screenshots as the implementation spec
+  (`exxat-no-image-pixel-copy.mdc`).
+- Treat a feature list as a job. Ask: *what decision does this enable?*
+
+## Question bank by surface type
+
+Pick **at most 3** questions whose answers change the design. Skip the rest.
+
+### Record / entity detail
+1. Who reads this most — power admin (dense, keyboard-first) or occasional
+   user (cozy, guided)?
+2. How is it reached — list, deep link, notification, search? (Drives
+   breadcrumb + back-affordance model.)
+3. Section tabs needed, or single-scroll page? (Field count > ~20 or rich
+   children → tabs.)
+
+### Hub / list page
+1. Dense comparison (table) or visual browse (board / gallery)?
+2. Per-record actions, bulk actions, or both?
+3. Will users filter / sort / customize columns, or is the view fixed?
+
+### Wizard / compose flow
+1. One screen with sections, or multi-step (>3 decisions)?
+2. Are intermediate steps savable as drafts?
+3. Submit is destructive, or always reversible?
+
+### Settings / preferences
+1. User scope (personal), workspace (shared), or both?
+2. Search needed (>20 settings) or flat list?
+3. Apply-on-change or explicit Save?
+
+### Dashboard / analytics
+1. One critical KPI or a comparison set (≤4)?
+2. Read at a glance, or drill into details?
+3. Time range fixed, or user-controlled?
+
+### Overlay (drawer / dialog / sheet)
+1. Does the user need the hub visible behind them? (Yes → sheet; no → route.)
+2. Blocking confirmation, or reversible? (Blocking → dialog; reversible → sheet.)
+3. Will it grow to ≥3 steps? (Yes → consider route instead.)
+
+## Brief template (copy verbatim)
+
+```
+Problem:            <one sentence — the user's pain, not the feature>
+User & frequency:   <persona, frequency, expertise>
+Job-to-be-done:     <the decision or action this enables>
+Pattern:            <route | sheet | dialog | inline> + IA shape
+Reference (repo):   <file path>
+Reference (modern): <product 1 + Mx>, <product 2 + Mx>
+Principles applied: <P-codes from exxat-ux-principles>
+Deviations:         <principle + one-sentence reason, or "none">
+Out of scope:       <what this does not do, deliberately>
+Open questions:     <max 2; ideally 0>
+```
+
+## Examples
+
+**Good:**
+> Problem: Coordinators can't tell at a glance which students are
+> non-compliant before placement.
+> User & frequency: Program coordinator, daily, keyboard-first.
+> Job-to-be-done: Identify and act on at-risk students in < 30s per record.
+> Pattern: route `/students/[id]` + identity row + status row + 2×2 card grid.
+> Reference (repo): `components/library-table.tsx` for IA cadence.
+> Reference (modern): Linear issue detail (M1, M4, M7); Stripe customer
+> record (M4, M11).
+> Principles applied: P1, P2, P3, P5, P6, P13, P19.
+> Deviations: none.
+> Out of scope: inline editing (v2), bulk message (lives on list).
+> Open questions: none.
+
+**Bad (silent generate):**
+> *Agent writes 4 files without explanation.*
+
+**Bad (vague prompt accepted):**
+> User: "make a settings page". *Agent writes generic form.* Should have
+> asked: scope (personal/workspace), search needed, apply-on-change vs Save.
+
+## Closing artifact: the design → engineering handoff
+
+When the build is complete (files written, surface working in dev), produce
+**one filled-in handoff document** before declaring the task done.
+
+**Template** lives at:
+
+- Workspace: `apps/web/docs/templates/handoff.md` (or workspace root if not yet copied — copy from `packages/ui/consumer-extras/templates/handoff.md`)
+- Consumer apps (after `exxat-ui sync-extras`): `docs/exxat-ds/templates/handoff.md`
+
+**Fill it in** with the actual primitives, tokens, icons, and shortcuts the
+build used. Save the filled copy at:
+
+- `apps/web/docs/handoff/<surface-slug>.md` (workspace)
+- `docs/exxat-ds/handoff/<surface-slug>.md` (consumer)
+
+Attach the filled handoff to the PR description (or paste inline). The
+engineer reads it once, runs `exxat-ui audit <generated-file>` to verify
+the floor, and is done.
+
+**MUST sections:** 1 (job-to-be-done), 3 (pattern + IA), 5 (DS components
+used), 6 (tokens), 8 (a11y checklist — every box ticked), 11 (keyboard map),
+12 (any deviations from P9–P20).
+
+If the handoff is incomplete or hand-wavy, the design task is not finished.
+
+## See also
+
+- `.cursor/skills/exxat-senior-ux/SKILL.md` — the persona + full protocol
+- `.cursor/rules/exxat-ux-principles.mdc` — principles + when to break
+- `apps/web/docs/jobs/` — canonical references per job type
+- `apps/web/docs/modern-saas-patterns.md` — pattern codes (M1–M12)
+- `.cursor/rules/exxat-no-image-pixel-copy.mdc` — IA from screenshots only
+- **Closing artifact:** `packages/ui/consumer-extras/templates/handoff.md`

package/template-vite/.cursor/rules/exxat-ux-principles.mdc

@@ -0,0 +1,187 @@
+---
+description: Exxat DS UX principles — what to follow, when to break, why
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — UX principles (and when to break them)
+
+Principles are the senior designer's spine. They make most decisions cheap.
+**Break deliberately, not accidentally** — and say so in the design brief
+(`exxat-ux-discovery-protocol.mdc`). If you can't write the deviation reason
+in one sentence, you shouldn't be breaking the principle.
+
+Each principle below has: **what it says**, **why**, **when to break**, and
+the **anti-pattern**.
+
+---
+
+## Always-follow (P1–P8) — no exceptions
+
+### P1. Way back is obvious, and exactly once
+Breadcrumb in `SiteHeader` OR explicit back affordance — **never both**.
+- **Why:** Two paths back create cognitive overhead and a redundant UI.
+- **When to break:** Never.
+- **Anti-pattern:** Breadcrumb "Dashboard › Students › Jordan Lee" + a
+  separate "Back to roster" button in the body.
+- **Reference:** `exxat-breadcrumbs-no-back.mdc`.
+
+### P2. One H1 per page; no duplicated identity
+The record name appears in exactly one carrier — typically `PageHeader.title`
++ ancestors-only breadcrumb. Not also as an `<h1>` in the body.
+- **Why:** Screen readers and scan-reading rely on a single page title.
+- **When to break:** Never.
+- **Anti-pattern:** Name in breadcrumb leaf + `PageHeader title` + body `<h1>`.
+
+### P3. One primary action per surface
+Exactly one filled `Button`; everything else `outline` / `ghost` / `link`.
+- **Why:** Two primaries = no primary.
+- **When to break:** Never. Symmetric pairs ("Approve" + "Reject") are both
+  *outline* — neither is the styled "primary".
+- **Anti-pattern:** Two filled buttons in the header.
+
+### P4. Don't pixel-copy
+Extract IA from screenshots and competitor references; never copy chrome,
+colors, or bespoke widgets.
+- **Why:** Pixels carry decisions made in another product's context.
+- **When to break:** Never.
+- **Reference:** `exxat-no-image-pixel-copy.mdc`.
+
+### P5. Every list / detail / action ships empty + error + loading
+- **Why:** Real users hit all three; afterthoughts ship as bugs.
+- **When to break:** Never.
+- **Anti-pattern:** "Loading…" text and no skeleton; missing 404 / empty.
+
+### P6. Keyboard parity
+Every mouse action has a keyboard equivalent; focus is always visible.
+- **Why:** Power users, motor-disabled users, screen-reader users all rely
+  on this.
+- **When to break:** Never.
+- **Reference:** `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc`.
+
+### P7. WCAG 2.1 AA minimum
+Contrast ≥ 4.5:1 (text) / ≥ 3:1 (UI), targets ≥ 24×24, labels on icon-only.
+- **Why:** Floor for shipping. Not negotiable.
+- **When to break:** Never.
+- **Reference:** `exxat-accessibility.mdc`.
+
+### P8. Reuse before invent
+Compose from DS primitives first. New shared primitives require user approval
+after a real, repeated need (≥ 2 use cases).
+- **Why:** Forked stacks divide the team; the DS is the vocabulary.
+- **When to break:** Never silently. Ask the user.
+- **Reference:** `exxat-reuse-before-custom.mdc`.
+
+---
+
+## Default-follow (P9–P20) — break only with stated reason
+
+### P9. Clarity over cleverness
+Direct labels, recognizable patterns. "Save" beats "Persist". "Send" beats
+"Beam".
+- **Why:** Decisions cost less when the label states the action.
+- **Break when:** Intentional brand voice in low-stakes surfaces (onboarding
+  celebration, marketing splash). Never in core flows.
+- **Anti-pattern:** "Materialize this configuration" instead of "Save".
+
+### P10. Recognition over recall
+Surface what the user needs; don't make them remember.
+- **Why:** Working memory is the most expensive resource on a screen.
+- **Break when:** Daily power users where keyboard shortcuts replace visible
+  chrome (Cron, Linear, Raycast). Provide a discoverable hint.
+- **Anti-pattern:** Hiding a frequent action behind a chord with no UI.
+
+### P11. One job per surface
+A screen optimizes for one primary user decision.
+- **Why:** Splits attention, splits metrics, splits design quality.
+- **Break when:** Workspace surfaces (Notion-style pages, Linear-style issue
+  views) deliberately compose multiple jobs. Even then, one job is **primary**.
+- **Anti-pattern:** Settings page that also includes a dashboard.
+
+### P12. Progressive disclosure
+Show core first; depth on demand (popovers, sheets, expand).
+- **Why:** Most users do the common thing most of the time.
+- **Break when:** Compliance / legal / audit surfaces where everything must
+  be visible.
+- **Anti-pattern:** 30-field form on first load with no grouping.
+
+### P13. Status visible without scroll
+Status signals that drive decisions (compliance, errors, urgency) appear
+above the fold.
+- **Why:** Status hidden = ignored.
+- **Break when:** Privacy / discretion contexts (e.g. HR records where peer
+  visibility is undesirable).
+- **Anti-pattern:** Compliance status on tab #3 of a record detail.
+
+### P14. Density follows frequency
+Daily power users get compact / dense; occasional users get cozy / spacious.
+- **Why:** Different audiences scan differently.
+- **Break when:** Accessibility (low-vision, motor) mandates generous
+  spacing. Offer a density toggle if both audiences share a surface.
+- **Anti-pattern:** Sparse table for a coordinator viewing 200 students/day.
+
+### P15. Inline editing where data is read
+Modern SaaS (Notion, Linear, Airtable) edits in place. Don't bounce users
+to a form for a single-field change.
+- **Why:** Mode-switch friction kills throughput.
+- **Break when:** Bulk operations, multi-field validation, audit-logged
+  fields, destructive edits — use a focused form / drawer.
+- **Anti-pattern:** "Edit" page just to change a phone number.
+
+### P16. Optimistic UI for low-risk actions
+Favorite, archive, status flip, reorder — feel instant; reconcile on error.
+- **Why:** Speed of feedback is a quality signal.
+- **Break when:** Financial / irreversible / regulated actions — show progress
+  and confirmation.
+- **Anti-pattern:** Spinner overlay for a star-favorite toggle.
+
+### P17. Search is global and fast
+`⌘K` opens command + search; everything addressable is searchable.
+- **Why:** Modern users navigate by typing.
+- **Break when:** Never for modern SaaS at this scale.
+- **Reference:** `exxat-command-menu.mdc`.
+
+### P18. Content first, chrome last
+Data is the star. Sidebars collapse to icons. Headers stay ~48–56px.
+Surfaces are generous.
+- **Why:** Chrome competes with the work.
+- **Break when:** Heavily configurable admin consoles where chrome **is** the
+  content. Prefer collapsing over crowding.
+- **Anti-pattern:** Purple gradient hero bar above a data table.
+
+### P19. Type carries hierarchy
+Weight, size, color do the heavy lifting before borders, boxes, or color
+tints.
+- **Why:** Ornament dates fast; type ages well.
+- **Break when:** Status surfaces where color is encoding meaning (chips,
+  alerts).
+- **Anti-pattern:** Every value wrapped in a tinted card.
+
+### P20. AI is a sidecar, not the primary path
+Ask Leo / inline AI — opt-in, contextual, cancellable. Never auto-runs on a
+record. Never the only way to do something.
+- **Why:** AI is a feature; the core product must work without it.
+- **Break when:** Surfaces explicitly built around AI (e.g. an AI-only
+  composer). Even then, expose the deterministic path.
+- **Reference:** `exxat-command-menu.mdc` (⌘K vs ⌘⌥K split).
+
+---
+
+## How to declare a deviation
+
+In the design brief, list the broken principle + the reason on one line:
+
+```
+Deviations: P14 (density) — broke "follows frequency" because the primary
+            user here is occasional but the same surface also serves daily
+            admins; resolved with a density toggle, default cozy.
+```
+
+If the reason doesn't fit on one line, the deviation isn't justified yet.
+
+## See also
+
+- `.cursor/skills/exxat-senior-ux/SKILL.md` — the persona
+- `.cursor/rules/exxat-ux-discovery-protocol.mdc` — gating + brief
+- `apps/web/docs/modern-saas-patterns.md` — the modern canon (M1–M12)
+- All `exxat-*.mdc` rules — concrete enforcement per pattern

package/template-vite/.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):** `apps/web/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.