@exxatdesignux/ui 0.5.11 → 0.5.13

package/template/docs/token-taxonomy.md

@@ -1,416 +0,0 @@
-# Exxat DS — Token Taxonomy
-
-**Status:** Authoritative · **Audience:** humans + AI agents · **Standard:** WCAG 2.1 AA
-**Machine-readable index:** [`packages/ui/tokens/hooks-index.json`](../../packages/ui/tokens/hooks-index.json) (generated)
-**Defining file (canonical):** [`packages/ui/src/globals.css`](../../packages/ui/src/globals.css). Consumer apps (`apps/web/app/globals.css`, the `create-exxat-app` starter at `packages/ui/template/app/globals.css`) are thin shells that `@import "@exxatdesignux/ui/globals.css"` and only declare their own `@source` directive. The dedicated `packages/ui/src/theme.css` file has been **retired** — see [`docs/migrations/0003-globals-css-canonical.md`](./migrations/0003-globals-css-canonical.md).
-
-This document formalizes the **naming, layering, and ownership** of every CSS
-custom property the design system ships. It is the answer to "what do I name a
-new token?" and "is there already a token for this?". If something here
-disagrees with the CSS, the CSS wins — and this file needs an edit.
-
----
-
-## 1. Layering — where a token lives
-
-Tokens are declared in **four** layers. Higher layers may consume lower ones;
-they MUST NOT redefine names from a higher layer with a different meaning.
-
-| Layer | File | Purpose | Edit when |
-|---|---|---|---|
-| **L0 — Exxat canonical** | `packages/ui/src/globals.css` `:root` (block tagged `Exxat L0 — canonical namespace`) | SLDS-style flat namespace (`--exxat-color-surface-1`, `--exxat-radius-2`, …). The **official** names the DS scales on. Today these are `var()` aliases of L1; the canonical OKLCH will move here over time. | New product surface tokens, broader brand picker, anything you would otherwise put under "L1 with an Exxat brand prefix" |
-| **L1 — shadcn semantic** | `packages/ui/src/globals.css` `:root`/`.dark` | OKLCH literals + back-compat vocabulary (`--background`, `--foreground`, `--brand-color`, …). Required for the upstream shadcn primitives in `components/ui/*`. **Frozen** — do not extend; new tokens go to L0. | Brand color changes, accessibility-driven contrast lifts, new chip/chart slot tied to shadcn names |
-| **L2 — Tailwind bridge** | `packages/ui/src/globals.css` `@theme inline` block | Maps primitives to `--color-*` and `--radius-*` so Tailwind v4 emits utility classes (`bg-brand`, `bg-surface-1`, `text-chip-3`, `rounded-2`, …) | Whenever an L0/L1 token needs a Tailwind utility class |
-| **L3 — Surface override** | Theme blocks (`.theme-one`, `.theme-prism`, `[data-contrast="high"]`, `[data-text-size]`) | Per-brand / per-mode rebindings of L1 names — never new names | New brand, new contrast mode, new density step |
-
-> **Rules:**
-> 1. A token is **introduced exactly once**. New product tokens land in **L0**.
-> 2. L1 (shadcn names) is **frozen** — keep working, do not extend.
-> 3. L2 bridges L0/L1 → Tailwind utilities, exactly once per name.
-> 4. L3 re-binds existing L1 OKLCH values per theme. L0 inherits via `var(L1)` automatically.
-
----
-
-## 2. Namespace map (all current prefixes)
-
-Every prefix below has a clear role. **New tokens MUST land in one of these
-prefixes** — if you cannot place a token, the design system is missing a
-prefix; propose one in a PR and document it here first.
-
-### 2.0 Exxat L0 — canonical namespace (`--exxat-*`)
-
-The **official** name layer. Mirrors the SLDS `--slds-g-*` pattern but flat
-(no `-g-` for "global" yet, since we have a single product namespace). Today
-these resolve to L1 via `var(...)` so every existing theme override flows
-through automatically. New components SHOULD prefer L0 names; the linter will
-not yet *force* this, but `apps/web/docs/migrations/0002-exxat-token-namespace.md`
-tracks the rollout.
-
-| Category | L0 token | Resolves to L1 |
-|---|---|---|
-| Surface | `--exxat-color-surface-1` … `-3` | `--background` / `--card` / `--popover` |
-| Surface | `--exxat-color-surface-muted` / `-accent` / `-secondary` / `-sidebar` / `-input` | `--muted` / `--accent` / `--secondary` / `--sidebar` / `--input-background` |
-| Ink | `--exxat-color-ink-1` / `-2` | `--foreground` / `--muted-foreground` |
-| Ink | `--exxat-color-ink-on-surface-2` / `-on-surface-3` | `--card-foreground` / `--popover-foreground` |
-| Ink | `--exxat-color-ink-on-brand` / `-on-primary` / `-on-secondary` / `-on-accent` / `-on-destructive` | foreground tokens |
-| Brand | `--exxat-color-brand-1` / `-2` / `-3` / `-deep` | `--brand-color` / `-dark` / `-light` / `-deep` |
-| Brand | `--exxat-color-brand-tint-1` / `-2` / `-3` | `--brand-tint` / `-subtle` / `-light` |
-| Action | `--exxat-color-action-primary` / `-secondary` / `-destructive` | `--primary` / `--secondary` / `--destructive` |
-| Border | `--exxat-color-border-1` / `-control-subtle` / `-control-1` / `-control-2` | `--border` ladder (see §6) |
-| Focus | `--exxat-color-focus-ring` | `--ring` |
-| Overlay | `--exxat-color-overlay` | `--overlay` |
-| Chart | `--exxat-color-chart-1` … `-5` | `--chart-1` … `-5` |
-| Chip | `--exxat-color-chip-1` … `-5` / `-destructive` | `--chip-1` … `-5` / `-destructive` |
-| Radius | `--exxat-radius-1` … `-6` | `4px` / `8px` / `12px` / `16px` / `20px` / `24px` |
-| Spacing | `--exxat-spacing-1` / `-2` / `-3` / `-4` / `-5` / `-6` / `-8` / `-12` | Tailwind base scale |
-| Control | `--exxat-control-height-1` / `-2` / `-3` | `--control-height-sm` / `-` / `-touch` |
-
-**Tailwind utilities** are emitted via L2 bridges in `@theme inline`:
-
-| L0 token | Tailwind utility |
-|---|---|
-| `--exxat-color-surface-1` | `bg-surface-1`, `text-surface-1`, `border-surface-1`, … |
-| `--exxat-color-ink-1` / `-2` | `text-ink-1`, `text-ink-2` |
-| `--exxat-color-brand-1` … `-3` | `bg-brand-1`, `bg-brand-2`, `bg-brand-3` |
-| `--exxat-color-brand-tint-1` … `-3` | `bg-brand-tint-1`, … |
-| `--exxat-color-border-1` | `border-1` |
-| `--exxat-color-focus-ring` | `ring-focus-ring` |
-| `--exxat-radius-1` … `-6` | `rounded-1` … `rounded-6` |
-
-> The existing `bg-background`, `bg-brand`, `rounded-md`, etc. are not going
-> away — they alias to the same OKLCH. Both forms work side-by-side; **new code**
-> should reach for the L0 form for clarity and grep-ability (`grep --exxat-`
-> finds every product token without false positives from shadcn names).
-
-### 2.1 Semantic surface (shadcn core, L1 — frozen)
-
-Inherited from shadcn / Radix and treated as the **stable** semantic vocabulary
-across every shadcn component. Do not rename — downstream `components/ui/*`
-expects these.
-
-| Token | Role |
-|---|---|
-| `--background` / `--foreground` | Page canvas + ink |
-| `--card` / `--card-foreground` | Raised card surfaces |
-| `--popover` / `--popover-foreground` | Floating menus, tooltips, dropdowns |
-| `--primary` / `--primary-foreground` | Default CTA color (neutral charcoal, **not** brand — see §3) |
-| `--secondary` / `--secondary-foreground` | Secondary button + de-emphasized surface |
-| `--muted` / `--muted-foreground` | Muted body copy, subtle backgrounds |
-| `--accent` / `--accent-foreground` | Hovered list rows, low-contrast chips |
-| `--destructive` / `--destructive-foreground` | Errors, delete confirms |
-| `--border` | Decorative dividers (no AA requirement) |
-| `--border-control` / `--border-control-3` / `--border-control-35` / `--control-border` | Form-field borders — see §6 for the contrast ladder |
-| `--input` / `--input-background` | Input outline + fill |
-| `--ring` | Focus ring (≥ 3:1, SC 2.4.11) |
-| `--overlay` | Modal / sheet / drawer scrim |
-
-### 2.2 Brand (`--brand-*`)
-
-The **product accent** — different from `--primary` (which is neutral). Exxat
-ships **two** brand themes (Exxat One = lavender 286.1, Exxat Prism = rose 343)
-plus user-picked custom brand.
-
-| Token | Role |
-|---|---|
-| `--brand-color` | Solid brand fill (used on chips, links, charts when product) |
-| `--brand-color-light` / `--brand-color-dark` / `--brand-color-deep` | Brand scale (light / dark / deepest) |
-| `--brand-foreground` | Ink on a solid brand fill |
-| `--brand-tint` / `--brand-tint-light` / `--brand-tint-subtle` | Wash surfaces (sidebar, secondary panel) |
-| `--brand-preview-one` / `--brand-preview-prism` | Fixed swatches for the brand picker — **never change with the active theme** |
-
-### 2.3 Sidebar + secondary panel (`--sidebar-*`, `--secondary-panel-bg`)
-
-Three-level brand chrome stack. See `docs/shell-surface-elevation-pattern.md`.
-
-| Token | Role |
-|---|---|
-| `--sidebar` / `--sidebar-foreground` | Primary sidebar (= `--brand-tint` on product themes) |
-| `--sidebar-primary` / `--sidebar-primary-foreground` | Solid pill / active hint on sidebar |
-| `--sidebar-accent` / `--sidebar-accent-foreground` | Hovered/active row in sidebar |
-| `--sidebar-border` | Inner divider |
-| `--sidebar-ring` | Focus ring inside sidebar |
-| `--sidebar-section-label-foreground` | Section title — mixed against real `--sidebar`, not `--background` |
-| `--secondary-panel-bg` | Nested panel (Library) — level 1 between sidebar and canvas |
-
-### 2.4 Chips / badges (`--chip-*`)
-
-A five-slot **AA-compliant** palette for tags, kanban badges, and small status
-chips. All slots maintain ≥ 4.5:1 against `--background`.
-
-| Token | Hue (light) |
-|---|---|
-| `--chip-1` | indigo (264) |
-| `--chip-2` | teal (184) |
-| `--chip-3` | slate (227) |
-| `--chip-4` | amber (84) |
-| `--chip-5` | orange (70) |
-| `--chip-destructive` | red (25) |
-
-Use through `lib/list-status-badges.ts` (`LIST_HUB_STATUS_TINT_*`). Do not pick a
-chip slot to mean "this entity uses indigo" — pick by **semantic intent**
-(success / warning / neutral / danger / info).
-
-### 2.5 Charts (`--chart-*`)
-
-Five slots scoped for `recharts` series. They are **darker** than chip slots
-because chart areas are larger and need denser pigment.
-
-| Token | Hue |
-|---|---|
-| `--chart-1` | blue (264) |
-| `--chart-2` | green-teal (184) |
-| `--chart-3` | slate (227) |
-| `--chart-4` | amber (84) |
-| `--chart-5` | orange (70) |
-
-Insights derived from charts use `--insight-severity-*-bg` / `-fg` (KPI strip).
-
-### 2.6 Interactive hover (`--interactive-hover-*`)
-
-Single source for ghost-button hover, list-row hover, table chrome hover.
-Replaces ad-hoc `hover:bg-muted` so theming + dark mode flip together.
-
-| Token | Role |
-|---|---|
-| `--interactive-hover` | Default opaque hover fill |
-| `--interactive-hover-foreground` | Ink on hover |
-| `--interactive-hover-subtle` / `-soft` / `-medium` / `-strong` | Opacity ladder (50 / 40 / 60 / 70 mix) |
-| `--interactive-hover-row` | List/table row hover (accent-mixed) |
-
-### 2.7 DataTable (`--dt-*`)
-
-Pinned cells must be **opaque** so they sit above scrolled rows. These tokens
-exist because `var(--muted)` alone gives translucent surfaces in dark mode.
-
-| Token | Role |
-|---|---|
-| `--dt-row-bg` | Base row fill (opaque) |
-| `--dt-row-hover` | Hovered row |
-| `--dt-row-selected` / `--dt-row-selected-fg` | Selection state |
-| `--dt-header-bg` | Header row |
-| `--dt-group-bg` | Group / divider row |
-| `--dt-new-row-bg` / `--dt-new-row-border` | "Just created" highlight |
-
-### 2.8 KPI strip (`--key-metrics-*`, `--insight-severity-*`)
-
-Used by `KeyMetrics` (both `variant="flat"` and `variant="card"`). See
-`docs/kpi-flat-band-pattern.md`.
-
-| Token | Role |
-|---|---|
-| `--key-metrics-flat-cell-bg` | Transparent on `variant="flat"` |
-| `--key-metrics-flat-divider` | Cell-border hairline |
-| `--key-metrics-flat-band-radial` | OKLCH brand glow at bottom |
-| `--key-metrics-flat-band-shadow` | `none` on flat |
-| `--key-metrics-card-glow-radial` | Card-variant glow |
-| `--insight-severity-warning-bg` / `-fg` | Yellow severity (chart-4 mix) |
-| `--insight-severity-info-bg` / `-fg` | Blue severity (chart-1 mix) |
-
-### 2.9 Conditional formatting (`--conditional-rule-*`)
-
-Row backgrounds for table conditional-format rules. Already six slots — adding
-more requires expanding the rule type in `lib/table-conditional-format.ts`.
-
-### 2.10 Icon discs (`--icon-disc-*`)
-
-Soft tinted backgrounds for icon "discs" (KPI cards, banner avatars).
-Bg ≈ 14% mix, fg from `--chip-*` / `--brand-color-dark`.
-
-### 2.11 Avatar (`--avatar-initials-*`)
-
-Bg + fg for initials avatars in `DataTable` cells. Pair brand wash with deep
-brand ink for ≥ 4.5:1 on white rows.
-
-### 2.12 Leo (Ask Leo) (`--leo-*`)
-
-| Token | Role |
-|---|---|
-| `--leo-surface-tint-a` / `-b` | Top / bottom of the AI panel wash |
-| `--leo-surface-gradient` | Full linear wash |
-
-### 2.13 Layout + density (`--header-height`, `--control-*`, `--table-row-height`, `--scaling`)
-
-Sized in **px** so JS can `parseFloat` them. Multiply by `--scaling` for future
-density modes.
-
-### 2.14 Border radius (`--radius`, `--radius-sm`/`-md`/`-lg`/`-xl`/`-2xl`/`-3xl`)
-
-`--radius` is the **base** (8px). The named scale lives at L2 (`@theme inline`)
-so Tailwind emits `rounded-sm`, `rounded-md`, etc.
-
-### 2.15 Shadows + transitions (`--shadow-*`, `--transition-*`)
-
-| Token | Role |
-|---|---|
-| `--shadow-sm` / `-md` / `-lg` | Three-step elevation |
-| `--transition-fast` / `-normal` / `-colors` | Standard durations |
-| `--sticky-edge-fade` | Edge-of-pinned-column gradient |
-
-### 2.16 Promo / banner (`--banner-prism-bg`)
-
-Rose hue 343, used **universally** as the Exxat Prism promo highlight — does
-not flip with the active theme.
-
-### 2.17 OS chrome (`--theme-color-chrome`)
-
-Mirrored into `<meta name="theme-color">` so the browser titlebar matches the
-sidebar. Hex literal here is **intentional** — it is consumed by the browser
-parser, not CSS.
-
----
-
-## 3. Color identity rules
-
-1. **`--primary` is neutral**, not brand. The product accent is `--brand-color`.
-   This matches Exxat's design language (neutral charcoal CTAs, lavender/rose
-   reserved for surfaces and chips). When a button **must** carry the brand,
-   use `bg-brand-color text-brand-foreground` — not `bg-primary`.
-2. **Brand washes (`--brand-tint*`) are surfaces; brand colors
-   (`--brand-color*`) are ink/fills.** Mixing the roles produces low-contrast
-   chips and washed-out sidebars.
-3. **Chip ≠ chart.** Chip tokens are sized for inline chips; chart tokens are
-   sized for filled SVG areas. Re-use a chip color on a chart fill (or vice
-   versa) only when the design explicitly calls for it.
-4. **Every theme MUST keep `--brand-preview-one` and `--brand-preview-prism`
-   fixed.** They drive the brand picker swatch — flipping them with the
-   selected theme defeats the picker.
-
----
-
-## 4. Naming a new token — checklist
-
-Run this list **before** opening `globals.css`:
-
-- [ ] **Does an L0 alias already exist?** (`--exxat-color-surface-1`,
-      `--exxat-color-brand-1`, `--exxat-radius-2`, …) — prefer L0 for new
-      consumers; the L1 shadcn name is the back-compat alias.
-- [ ] If the token is new, **name it at L0 first** (`--exxat-<category>-<slot>`).
-      Add an L1 mirror **only** if a shadcn primitive in `components/ui/*`
-      needs it — that's the only place L1 is still required.
-- [ ] Can it be expressed with an existing semantic token? (`--exxat-color-surface-muted`
-      instead of `--exxat-color-surface-4`, `--brand-color-dark` instead of
-      `--brand-deeper`)
-- [ ] Does it belong to a **scoped surface** (`KeyMetrics`, `DataTable`, Leo,
-      sidebar, secondary panel)? If yes, **prefix with that surface**, e.g.
-      `--key-metrics-*`, `--dt-*`, `--leo-*`. Do **not** drop scoped tokens at
-      the top level.
-- [ ] Is it a **decoration** or a **decision**? Decorations (gradients, fades,
-      shadows) live alongside the surface tokens they decorate. Decisions
-      (semantic intent: warning, info, success) live with chips / charts /
-      insight tokens.
-- [ ] Does it need a Tailwind utility (`bg-*`, `text-*`, `border-*`)? If yes,
-      add the `--color-<name>` bridge in `@theme inline` in **both** globals
-      files.
-- [ ] Does dark mode / high contrast / Prism need different OKLCH? Override at
-      L3 — never branch by emitting a new token name.
-- [ ] Is it derived (e.g. 14% mix of `--brand-color`)? Use `color-mix(in oklch,
-      …)` so theme overrides cascade automatically.
-- [ ] Add the bridge in `packages/ui/src/globals.css` `@theme inline`. App
-      consumers @import that file, so a single edit is enough — no manual
-      mirroring across `apps/web/app/globals.css` / `template/app/globals.css`.
-
-If you tick all the boxes, also:
-
-1. Add an entry to this file (the right §).
-2. Re-run `pnpm --filter @exxatdesignux/ui tokens:index` (see §7) to refresh
-   `packages/ui/tokens/hooks-index.json`.
-
----
-
-## 5. Deprecation policy
-
-Tokens follow the same **add → mark deprecated → remove** lifecycle as code:
-
-1. **Add** the new token; switch components to consume it.
-2. **Mark deprecated** in `packages/ui/src/globals.css` with a comment:
-   ```css
-   /* @deprecated v0.2.18 — use --brand-color-dark; remove in v0.4.0 */
-   --brand-deep: var(--brand-color-dark);
-   ```
-3. **Migrate** consumers (script + grep + manual review). Document in
-   `docs/migrations/<NNNN>-<slug>.md`.
-4. **Remove** in the version named in the deprecation comment. Bump
-   `@exxatdesignux/ui` major or document in `CHANGELOG.md`.
-
-Active deprecations are listed in `docs/migrations/README.md`.
-
----
-
-## 6. Form-field border contrast ladder
-
-Form-field borders are a recurring source of WCAG SC 1.4.11 (3:1 UI contrast)
-failures. Use the right rung — do not guess:
-
-| Token | OKLCH L | Contrast vs `oklch(1 0 0)` | When to use |
-|---|---|---|---|
-| `--border` | 0.92 | < 3:1 | **Decorative only** — card dividers, list separators |
-| `--border-control` | 0.82 | < 3:1 | Layout chrome where contrast is not required |
-| `--border-control-3` | 0.62 | ≈ 3:1 | Form-field border **minimum** — passes AA |
-| `--border-control-35` | 0.25 | > 3.5:1 | Form-field border **recommended** — passes AA + 16% buffer |
-| `--control-border` (alias of `--border-control-3`) | — | — | Default form-field border slot |
-
-If you find yourself reaching for `--border` on an `<input>`, stop — use
-`--control-border`.
-
----
-
-## 7. Machine-readable hooks index
-
-Tooling (linters, codegens, design-tool sync) needs to discover tokens
-programmatically. Run:
-
-```bash
-pnpm --filter @exxatdesignux/ui tokens:index
-```
-
-This regenerates [`packages/ui/tokens/hooks-index.json`](../../packages/ui/tokens/hooks-index.json),
-which mirrors SLDS's `hooks-index.json` shape. The current index contains
-**195 tokens** across **41 namespaces** (including the 12 Exxat L0 sub-namespaces
-`exxat-surface`, `exxat-ink`, `exxat-brand`, `exxat-action`, `exxat-border`,
-`exxat-focus`, `exxat-overlay`, `exxat-chart`, `exxat-chip`, `exxat-radius`,
-`exxat-spacing`, `exxat-control`):
-
-```jsonc
-{
-  "version": "0.2.18",
-  "source": "packages/ui/src/globals.css",
-  "generatedAt": "ISO-8601",
-  "tokens": {
-    "--exxat-color-brand-1": {
-      "namespace": "exxat-brand",
-      "category": "color",
-      "values": { "light": "var(--brand-color)" },
-      "tailwindUtilities": ["bg-brand-1", "text-brand-1", "border-brand-1", "ring-brand-1"],
-      "deprecated": false
-    },
-    "--brand-color": {
-      "namespace": "brand",
-      "category": "color",
-      "values": {
-        "light":           "oklch(0.50 0.14 286.1)",
-        "dark":            "oklch(0.50 0.14 286.1)",
-        "theme-one":       "oklch(0.50 0.14 286.1)",
-        "theme-prism":     "oklch(0.57 0.24 342)",
-        "high-contrast":   "oklch(0.06 0 0)"
-      },
-      "tailwindUtilities": ["bg-brand", "text-brand", "border-brand", "ring-brand"],
-      "deprecated": false
-    }
-  }
-}
-```
-
-CI runs `tokens:index` and fails if the committed JSON is stale.
-
----
-
-## 8. References
-
-- `packages/ui/src/globals.css` — **single source of truth** for L1 / L2 / L3 primitives + Tailwind bridges
-- `apps/web/app/globals.css`, `packages/ui/template/app/globals.css` — thin shells (`@import` + `@source`)
-- `apps/web/docs/shell-surface-elevation-pattern.md` — sidebar / secondary panel
-- `apps/web/docs/kpi-flat-band-pattern.md` — `--key-metrics-flat-*`
-- `apps/web/docs/kpi-trend-pattern.md` — `--insight-severity-*` polarity
-- `.cursor/rules/exxat-token-discipline.mdc` — enforcement rule (don't ship hex
-  literals, don't use deprecated tokens)
-- `docs/migrations/` — token rename + removal history

package/template/docs/voice-and-tone.md

@@ -1,262 +0,0 @@
-# Exxat DS — Voice and tone
-
-> The single biggest driver of "this feels like one product" — or "this feels random" — is **copy**. Empty states, errors, buttons, banners, validation, labels. This doc is the binding reference for all of it.
->
-> **Audience:** designers writing copy, engineers shipping strings, AI agents drafting UI text. Reviewed in PR alongside `.cursor/rules/exxat-accessibility.mdc`.
-
----
-
-## 1. Voice (the constant)
-
-Exxat copy is **clear, direct, and respectful**. We talk to grown professionals (faculty, admins) and to students. We never:
-
-- talk down (no "Oops!" / "Whoops" / "Uh-oh"),
-- over-celebrate ("Awesome!" / "Great job!" / 🎉),
-- guilt-trip ("You haven't… yet" / "Don't forget!"),
-- hide the cause behind metaphor ("Something went wrong" with no detail),
-- shout (sentence case everywhere; ALL CAPS only for system status acronyms).
-
-We **always**:
-
-- name the **thing**: the entity (placement, site, student), the action (Save, Invite, Export), the outcome (saved, sent, downloaded),
-- say what **changed** or what **the user can do next**,
-- use **present tense** (`Saving` / `Saved` / `Try again`), not past-aspirational (`We've saved your changes!`),
-- use **active voice** (`Exxat couldn't save the placement.` not `The placement could not be saved.`).
-
----
-
-## 2. Tone (the variable)
-
-Tone shifts by surface. Same voice, different temperature.
-
-| Surface | Tone | Example |
-|---|---|---|
-| Primary action label | Imperative, 1–3 words | "Save", "Invite people", "Export" |
-| Empty state (filtered) | Helpful, names the filter | "No placements match the current filters. Clear them to see all 247." |
-| Empty state (no data ever) | Welcoming, names the next step | "No placements yet. Add your first one to get started." |
-| Inline validation | Neutral, says the rule | "Use the format MM/DD/YYYY." |
-| Banner (informational) | Calm, explains why | "Read-only — this term has ended." |
-| Banner (warning) | Direct, says the consequence | "Saving will overwrite 3 students' assignments." |
-| Banner (error) | Honest, names the failure + next step | "Exxat couldn't reach the placement service. Try again, or check your network." |
-| Dialog (destructive confirm) | Specific, names the object | "Delete placement P-2026-014? This cannot be undone." |
-| Microcopy (helper, hints) | Brief, format-only | "Out of 4.0", "MM/DD/YYYY" |
-
----
-
-## 3. Buttons
-
-| Pattern | Use | Example |
-|---|---|---|
-| **Sentence case** | Always | `Save`, `Invite people`, `Export selection` |
-| **Title case** | Never | ~~`Save Changes`~~ → `Save changes` |
-| **Verb-first imperative** | Primary actions | `Save`, `Send invite`, `Create placement`, `Download CSV` |
-| **No "Please"** | The button is the request | ~~`Please save`~~ → `Save` |
-| **Don't repeat the field name** | Inline context is enough | ~~`Save changes to placement`~~ → `Save` |
-| **"Cancel" not "Discard"** | Cancel returns to a safe state; Discard is only for destructive draft loss | dialog primary = `Save changes`; cancel = `Cancel` |
-| **Loading verb** | When in-flight, swap to `…` form, preserve width | `Save` → `Saving…` |
-| **Disabled tooltip** | Always say why | "Add at least one collaborator first." |
-
-### Don't
-
-| ❌ Don't | ✅ Do |
-|---|---|
-| `Click here` | `Open placement` |
-| `OK` | `Save`, `Got it`, `Continue` (the actual outcome) |
-| `Submit` | `Send invite`, `Save changes`, `Create placement` |
-| `Yes` / `No` in destructive dialogs | `Delete placement`, `Cancel` |
-| `Loading…` for >2 s with no detail | `Loading placements…` (name the thing) |
-
----
-
-## 4. Empty states
-
-There are **three** kinds. The copy is different for each.
-
-### 4a. Filter-empty ("zero matches")
-
-The dataset has rows; the active filters hide all of them. Tell the user the filters are responsible and offer to clear them.
-
-```
-No placements match the current filters.
-[Clear filters]
-```
-
-Rules:
-
-- Name the entity ("placements", not "items").
-- Mention "the current filters" — not just "no results".
-- Surface a **Clear filters** action if the toolbar has any filters applied.
-- If the search box is the only filter, the message becomes `No placements match "<query>".` (quote the query exactly).
-
-### 4b. True-empty ("no data ever")
-
-The dataset is empty for this user / scope. Tell them what to do next.
-
-```
-No placements yet.
-Add your first one to start tracking student rotations.
-[New placement]
-```
-
-Rules:
-
-- One-line headline + one-line context.
-- The CTA is the same imperative used elsewhere in the app — don't invent "Start now" for an empty state.
-- If creation requires a precursor ("Add at least one site first"), say so and link to the precursor.
-
-### 4c. Permission-empty ("not allowed to see")
-
-The user can't see anything because of access. Don't show counts; don't suggest creating.
-
-```
-You don't have access to this hub.
-Ask a coordinator to invite you with Viewer or higher access.
-```
-
-Rules:
-
-- Name the access level required.
-- Don't show row counts the user can't see.
-- Don't expose the existence of restricted records by mentioning "0 of N hidden".
-
----
-
-## 5. Errors
-
-Errors must answer three questions: **What happened? Why? What can the user do?**
-
-| Element | Required? | Example |
-|---|---|---|
-| Subject | required | `Exxat couldn't save the placement.` |
-| Cause | when knowable | `The site was deleted while you were editing.` |
-| Next step | required | `Choose another site or refresh.` |
-
-### Don't
-
-- `Something went wrong.` — every word is empty. Replace with the subject + cause.
-- `Error 500: Internal Server Error.` — leak the trace ID to logs, not the user. User-facing: "Exxat had a problem. Try again in a moment."
-- Toasts for errors. Use `SystemBanner` (route-level) or inline `FormMessage` (field-level). See [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc).
-
-### Field-level (`FormMessage`)
-
-Match the rule, not the field name. Keep under 60 chars.
-
-| Rule | Message |
-|---|---|
-| Required | `This is required.` |
-| Format (date) | `Use MM/DD/YYYY.` |
-| Format (phone) | `Use +1 (555) 555-0100.` |
-| Range (number) | `Enter a number between 0 and 4.0.` |
-| Unique | `That ID is already in use.` |
-| Server | `Exxat couldn't save this field. Try again.` |
-
----
-
-## 6. Banners
-
-We use **persistent banners** (not toasts) for all product feedback. See [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) and `LocalBanner` / `SystemBanner` in `packages/ui`.
-
-| Variant | Use | Lead with |
-|---|---|---|
-| `info` | Read-only / scope notice / "you're viewing X" | The fact: "Read-only — this term has ended." |
-| `success` | Confirmed state change (long-lived; toasts forbidden) | The outcome: "Invite sent to 3 collaborators." |
-| `warning` | Action will cause consequence | The consequence: "Saving will overwrite 3 students' assignments." |
-| `error` | Recoverable failure | The subject + next step: "Exxat couldn't reach the placement service. Try again." |
-| `destructive` | Pending destructive change | The object + reversibility: "This term will be archived in 7 days. Restore now to keep it." |
-
-Rules:
-
-- One banner per region. If two compete, the higher-severity wins.
-- Pair a banner with an **action** when there's something the user can do (`[Restore]`, `[Try again]`, `[Open log]`).
-- No exclamation marks. The variant color carries the tone.
-
----
-
-## 7. Status badges
-
-Status labels live in [`lib/list-status-badges.ts`](../lib/list-status-badges.ts) and are shared across every surface (table, board card, list row). Don't fork labels per page.
-
-| Type | Conventions | Example |
-|---|---|---|
-| Lifecycle | Title case, single word where possible | `Active`, `Draft`, `Archived`, `Pending` |
-| Outcome | Past-tense verb when an action completed | `Approved`, `Rejected`, `Sent`, `Skipped` |
-| Risk | Plain language, no jargon | `On track`, `At risk`, `Blocked` |
-| Mandatory pairing | Color **AND** icon (WCAG 1.4.1 — never color alone) | green check, amber triangle, red circle-x |
-
-Never: `OK`, `N/A`, `?` as a status label. Show the actual lifecycle state or `Unknown` with a tooltip describing how to resolve it.
-
----
-
-## 8. KPI copy (the highest-stakes copy in the product)
-
-KPIs read top-down: **label → value → trend chip → description**. The reader is scanning, not reading. Each line earns its place.
-
-| Field | Rule | Example |
-|---|---|---|
-| `label` | Sentence case noun phrase. ≤ 24 chars. No "Total" prefix (the value is total by default). | `Active placements`, `New invites`, `Compliance issues` |
-| `value` | The number. Use `tabular-nums`. Round to a sensible precision. Suffix unit (`%`, `hrs`) without space when natural. | `247`, `12 %`, `38 hrs` |
-| `delta` | The **count** of change. Empty (`""` or `0`) hides the chip entirely. Never prose. | `+12`, `-3`, `+8 %` |
-| `description` | The caption beneath the value row. Prose explaining what the number is or how it splits. Never the delta. | `vs last week`, `across 4 sites`, `left + right` |
-
-See [`exxat-kpi-trends.mdc`](../../../.cursor/rules/exxat-kpi-trends.mdc) for the trend-polarity rules (when up means bad, set `trendPolarity: "lower_is_better"`).
-
-### Don't
-
-- `Total: 247` — drop "Total".
-- `247 placements` in `value` — put `247` in `value`, `placements` is in `label`.
-- `+5 (up 12 % from last week)` in `delta` — `delta = "+5"`, `description = "vs last week"`.
-
----
-
-## 9. Form labels and helper text
-
-| Element | Rule | Example |
-|---|---|---|
-| Label | Sentence case, no colon, no "*" — pair `*` decoration with `aria-required` only. | `Date of birth` |
-| Required marker | Visible `*` (`aria-hidden`), programmatic `aria-required="true"`. | `Date of birth *` |
-| Helper text | Persistent, format-first. Use `FormDescription`. Never placeholder-only. | `MM/DD/YYYY` |
-| Placeholder | May mirror the format. Never the sole carrier. | `MM/DD/YYYY` |
-| Inline error | Replaces helper while active. Match the rule, not the field name. | `Use MM/DD/YYYY.` |
-| Unit in label vs description | Units go in description when context-dependent (`Out of 4.0` under "GPA"), in label when fixed (`Hours per week`). | — |
-
-See [`exxat-accessibility.mdc`](../../../.cursor/rules/exxat-accessibility.mdc) §"Form fields — format hints MUST be persistent".
-
----
-
-## 10. Dates, times, numbers
-
-| Type | Format | Example |
-|---|---|---|
-| Date (UI) | Locale-aware, defaults to `MM/DD/YYYY` for en-US | `12/14/2025` |
-| Date range | Same format, en-dash with hair-thin spaces (or hyphen-minus in mono) | `12/14/2025 – 12/20/2025` |
-| Time | 12-hour with am/pm in lowercase | `2:30 pm` |
-| Relative time | Use sparingly; pair with absolute on hover/tooltip | `Updated 3 hours ago` (tip: `12/15/2025, 11:14 am`) |
-| Numbers | `tabular-nums`. Use thousands separator (`12,547`) for ≥ 4 digits | `12,547` |
-| Currency | Symbol-first, no space (`$1,200.00`) | `$1,200.00` |
-| Percent | No space (`12 %` is wrong, use `12%`) | `12%` |
-| Duration | Short form (`38 hrs`, `2 wks`) | `38 hrs` |
-
----
-
-## 11. Reviewer checklist (paste into PRs that touch copy)
-
-- [ ] Sentence case (not title case) everywhere.
-- [ ] No `Click here`, `Submit`, `OK`, `Loading…` without a noun.
-- [ ] No toasts; banners or inline status instead.
-- [ ] Empty state names the entity and surfaces a next action or "Clear filters".
-- [ ] Errors answer: what / why / what now.
-- [ ] Status labels come from `lib/list-status-badges.ts`, not new strings.
-- [ ] KPI `delta` is a count; KPI `description` is prose. Polarity matches the metric.
-- [ ] Form helper text is `FormDescription`, not placeholder-only.
-- [ ] No exclamation marks outside `success` banners (and even those rarely).
-- [ ] No emoji unless explicitly approved for that surface.
-
----
-
-## See also
-
-- [`HANDBOOK.md`](./HANDBOOK.md) — where this fits in the docs map
-- [`glossary.md`](./glossary.md) — vocabulary
-- [`.cursor/rules/exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) — why banners, not toasts
-- [`.cursor/rules/exxat-kpi-trends.mdc`](../../../.cursor/rules/exxat-kpi-trends.mdc) — KPI delta vs description
-- [`.cursor/rules/exxat-accessibility.mdc`](../../../.cursor/rules/exxat-accessibility.mdc) — format-hint persistence rule