@exxatdesignux/ui 0.2.19 → 0.4.0

package/consumer-extras/handbook/reference-implementations.md

@@ -0,0 +1,153 @@
+# Exxat DS — Reference implementations
+
+> When a rule says "see Placements" or "see Team", **this is the index**. Open the file. Copy. Don't reinvent.
+
+Reference pages are the **canonical working implementations** of a pattern. They're the source of truth that rules + blueprints summarize. If a rule conflicts with a reference page, the bug is in the rule — open a PR.
+
+---
+
+## How to use this page
+
+1. Find the row that matches the pattern you're building.
+2. Open the **Reference page** column — that file is the template.
+3. Read the linked **Blueprint** for the framework-agnostic spec.
+4. Read the linked **Rule** for the binding MUST / MUST NOT.
+5. Read the linked **Pattern** for the long-form "why".
+
+If you find yourself diverging from the reference page, ask **why** before shipping.
+
+---
+
+## Primary hubs
+
+| Pattern | Reference page | Blueprint | Rule(s) | Pattern doc |
+|---|---|---|---|---|
+| Full hub: table + board + dashboard + list + paginated + conditional rules + dashboard customize | `apps/web/components/placements-table.tsx` + `placements-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md), [`data-table`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/data-table.md), [`board-card`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/board-card.md), [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc), [`exxat-list-page-connected-views`](../../../.cursor/rules/exxat-list-page-connected-views.mdc), [`exxat-centralized-list-dataset`](../../../.cursor/rules/exxat-centralized-list-dataset.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+| Hub with dashboard customize (canvas layout edit) | `apps/web/components/team-table.tsx` + `team-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md), [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-list-page-connected-views`](../../../.cursor/rules/exxat-list-page-connected-views.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+| Hub with finder / split-panel view | `apps/web/components/sites-table.tsx` + `sites-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md) | [`exxat-list-page-view-shells`](../../../.cursor/rules/exxat-list-page-view-shells.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+| Hub with secondary panel scope (folder rail) | `apps/web/components/library-table.tsx` + `library-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md) | [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc), [`exxat-library-hub-header`](../../../.cursor/rules/exxat-library-hub-header.mdc) | [`library-hub-header-pattern`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/library-hub-header-pattern.md) |
+| Hub with secondary panel scope (token categories) — **smallest** secondary-panel reference | `apps/web/components/tokens-themes-client.tsx` + `tokens-secondary-nav.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md) | [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc) | [`shell-surface-elevation-pattern`](../shell-surface-elevation-pattern.md) |
+| Single-view showcase hub (table only) — **18 SaaS cell patterns**, each rendered by an **importable named cell** from `@/components/data-views` (see "Cell primitives" table below). Categories: select, primary identity + ID + favorite, avatar + name + email, avatar group +N, type pill, difficulty signal, status chip, inline toggle, tag list, rating stars, progress bar, currency, numeric, attachment count, external link, relative time, absolute date, row actions overflow. | `apps/web/components/columns-showcase.tsx` + `columns-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md), [`data-table`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/data-table.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc) | — |
+
+> **First-time hub builder:** start with `sites-table.tsx` (smallest complete hub) or `columns-showcase.tsx` (single-view, easiest).
+
+---
+
+## Cell primitives (importable)
+
+Every cell renderer below is exported from `@/components/data-views` (re-exported from `apps/web/components/data-views/table-cells.tsx`). The live catalog page is `/columns`. **Do not re-implement these inside a `ColumnDef['cell']`** — import the name.
+
+| Cell | Renders | Import |
+|------|---------|--------|
+| `ProgressCell` | Track + filled bar with auto-tone in thirds; `value`, `max`, `tone`, `label` | `@/components/data-views` |
+| `CurrencyCell` | Right-aligned `tabular-nums`; `value`, `currency` (USD), `locale`, `maximumFractionDigits` | same |
+| `NumericCell` | Right-aligned plain count; `value`, `fractionDigits` | same |
+| `RatingCell` | N of `max` FA stars + value; color + glyph paired (WCAG 1.4.1) | same |
+| `SignalBarsCell` | Wi-Fi-style ordinal bars; `level`, `max`, `tone`, `label` (required) | same |
+| `BooleanToggleCell` | Inline `ToggleSwitch` with `checked` + `onChange(next)`; stops row click propagation | same |
+| `AttachmentCountCell` | Paperclip + count chip; muted dash on `0` | same |
+| `ExternalLinkCell` | Truncated host + new-tab icon; `url`, `label?`; `Tip` shows full URL | same |
+| `RelativeTimeCell` | "3 hours ago" with `Tip(absolute)`; `iso`, `now?` (deterministic snapshots) | same |
+| `PeopleAvatarRailCell` | Face rail with `+N` overflow; `people: PersonStub[]`, **non-overlapping** | same |
+| `PillCell` | Outlined badge + leading FA icon; `label`, `icon?` | same |
+| `TagListCell` | Soft badges with `+N` overflow; `tags`, `visibleMax?`, `formatLabel?` | same |
+| `RowActionsCell<TRow>` | `⋯` overflow dropdown; `row`, `actions: RowActionDef<TRow>[]` (label, icon, onSelect, variant, shortcut, disabled) | same |
+| `EMPTY_DASH` | Aria-hidden `—` placeholder for null/undefined cells | same |
+
+**Anti-references** (do NOT copy):
+- ❌ Inlining `Intl.NumberFormat`, `[1,2,3,4,5].map(s => …)` star loops, raw `<a target="_blank">`, `new URL(…).hostname`, or `Intl.RelativeTimeFormat` inside a `cell:`. Import the named cell.
+- ❌ Re-implementing `RowActionsCell` per hub with a custom `DropdownMenu`. The generic `RowActionsCell<TRow>` covers `Open / Edit / Duplicate / Archive`-style menus.
+
+---
+
+## Hub chrome
+
+| Pattern | Reference page | Blueprint | Rule(s) |
+|---|---|---|---|
+| Page header — primary hub | `apps/web/components/placements-page-header.tsx` | [`page-header`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/page-header.md) | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc), [`exxat-mono-ids`](../../../.cursor/rules/exxat-mono-ids.mdc) |
+| Page header — collaboration variant (face rail + invite) | `apps/web/components/library-page-header.tsx` | [`page-header`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/page-header.md) | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc) |
+| Page header — entity / record (no view tabs) | `apps/web/components/page-header.tsx` (variants) | [`page-header`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/page-header.md) | — |
+| KPI flat band on a hub | `apps/web/components/placements-client.tsx` | [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-kpi-flat-band`](../../../.cursor/rules/exxat-kpi-flat-band.mdc), [`exxat-kpi-max-four`](../../../.cursor/rules/exxat-kpi-max-four.mdc), [`exxat-kpi-trends`](../../../.cursor/rules/exxat-kpi-trends.mdc) |
+| Properties drawer wiring | `apps/web/components/placements-table.tsx` | — | [`exxat-table-properties-drawer`](../../../.cursor/rules/exxat-table-properties-drawer.mdc) |
+| Export drawer + ⋯ menu | `apps/web/components/placements-page-header.tsx` + `export-drawer.tsx` | — | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc) |
+
+---
+
+## Board, list, dashboard views
+
+| Pattern | Reference page | Blueprint | Rule(s) |
+|---|---|---|---|
+| Board card (kanban) | `apps/web/components/placements-board-view.tsx`, `team-table.tsx` (`renderListRow`) | [`board-card`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/board-card.md) | [`exxat-board-cards`](../../../.cursor/rules/exxat-board-cards.mdc), [`exxat-card-vs-list-rows`](../../../.cursor/rules/exxat-card-vs-list-rows.mdc) |
+| List row (single-column) | `apps/web/components/team-table.tsx` `renderListRow` | [`board-card`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/board-card.md) (row layout) | [`exxat-card-vs-list-rows`](../../../.cursor/rules/exxat-card-vs-list-rows.mdc) |
+| Dashboard view with charts + KPI band | `apps/web/components/placements-dashboard-charts-section.tsx` | [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-dashboard-view-charts`](../../../.cursor/rules/exxat-dashboard-view-charts.mdc) |
+| Folder / finder split view | `apps/web/components/data-views/finder-panel-view.tsx` (used in `sites-table.tsx`) | — | [`exxat-list-page-view-shells`](../../../.cursor/rules/exxat-list-page-view-shells.mdc) |
+
+---
+
+## Search
+
+| Pattern | Reference page | Rule(s) | Pattern doc |
+|---|---|---|---|
+| Global command palette (⌘K) | `apps/web/components/command-menu.tsx` + `lib/command-menu-config.ts` | [`exxat-command-menu`](../../../.cursor/rules/exxat-command-menu.mdc) | [`command-menu-pattern`](../command-menu-pattern.md) |
+| Dedicated search (landing + results) | `apps/web/components/dedicated-search-*.tsx` | [`exxat-dedicated-search-surfaces`](../../../.cursor/rules/exxat-dedicated-search-surfaces.mdc) | — |
+| In-table search (toolbar) | wired by `HubTable` automatically | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+
+---
+
+## Collaboration
+
+| Pattern | Reference page | Rule(s) | Pattern doc |
+|---|---|---|---|
+| Face rail + invite drawer | `apps/web/components/collaboration-access-flow.tsx`, `invite-collaborators-drawer.tsx` | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc) | [`collaboration-access-pattern`](../collaboration-access-pattern.md) |
+
+---
+
+## Overlays and confirmations
+
+| Pattern | Reference page | Rule(s) | Pattern doc |
+|---|---|---|---|
+| Side drawer (long auxiliary flow) | `apps/web/components/export-drawer.tsx`, `invite-collaborators-drawer.tsx`, `apps/web/components/table-properties/drawer.tsx` | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc), [`exxat-page-vs-drawer`](../../../.cursor/rules/exxat-page-vs-drawer.mdc) | [`drawer-vs-dialog-pattern`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/drawer-vs-dialog-pattern.md) |
+| Dialog (blocking short confirm / destructive) | `apps/web/components/ui/alert-dialog.tsx` consumers (search `<AlertDialog`) | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc) | [`drawer-vs-dialog-pattern`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/drawer-vs-dialog-pattern.md) |
+| Coach mark / onboarding | `apps/web/lib/coach-mark-registry.ts` consumers (Placements dashboard customize) | — | — |
+
+---
+
+## Settings, tokens, themes
+
+| Pattern | Reference page | Rule(s) |
+|---|---|---|
+| Settings page (preferences + sections) | `apps/web/app/(app)/settings/page.tsx` | — |
+| Tokens & themes hub (secondary panel + categories + visualizers) | `apps/web/components/tokens-themes-client.tsx`, `tokens-themes-section.tsx`, `tokens-secondary-nav.tsx` | [`exxat-token-discipline`](../../../.cursor/rules/exxat-token-discipline.mdc), [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc) |
+
+---
+
+## Anti-references (what NOT to copy)
+
+These exist but are **not** canonical. They predate a rule, are scoped to a one-off, or use a legacy primitive. **Don't copy from them.**
+
+| Anti-reference | Why not | What to use instead |
+|---|---|---|
+| Raw `<DataTable>` mounted directly in `ListPageTemplate.renderContent` (historical) | Loses filter chips + Properties drawer; users lose discoverability | `HubTable` (see Sites / Placements / Tokens / Columns refs) |
+| Custom search input above a `DataTable` | `HubTable`'s toolbar already does this; duplicating leads to drift | Configure `ColumnDef.filter` + use `HubTable` |
+| `toast()` / Sonner / snackbar | Forbidden — see [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) | `LocalBanner` / `SystemBanner` or inline status |
+| Negative-margin overlapping avatars | Forbidden — see [`exxat-person-identity-display.mdc`](../../../.cursor/rules/exxat-person-identity-display.mdc) | `AvatarGroup` (gapped by default) |
+
+---
+
+## Adding a new reference page
+
+If you build a pattern that **other hubs will copy**, list it here. A reference page is canonical when:
+
+1. It satisfies the matching blueprint or rule end-to-end.
+2. It passes the §13 PR-review checklist in [`AGENTS.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md).
+3. The file has a top-level doc comment that names what it's the reference for (e.g. *"Sites hub — thin wrapper around `<HubTable>`. Owns only the column defs, renderers for non-table views, and the mock-data wiring."*).
+4. The matching rule's "Reference implementations" list points back to it.
+
+---
+
+## See also
+
+- [`HANDBOOK.md`](./HANDBOOK.md) — start-here doc map
+- [`blueprints/README.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/README.md) — what a blueprint is
+- [`component-selection-guide.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/component-selection-guide.md) — decision tree across blueprints
+- [`apps/web/AGENTS.md` §13](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md) — full PR-review checklist

package/consumer-extras/handbook/voice-and-tone.md

@@ -0,0 +1,262 @@
+# 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`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/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

package/consumer-extras/patterns/collaboration-access-pattern.md

@@ -1,8 +1,8 @@
 # Collaboration & access pattern
 
-Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Question bank — `QuestionBankPageHeader`, `QuestionBankClient`, `InviteCollaboratorsDrawer`.
+Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Library — `LibraryPageHeader`, `LibraryClient`, `InviteCollaboratorsDrawer`.
 
-**Folder-scoped question bank:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`QuestionBankNewFolderSheet`** mounted on **`QuestionBankClient`** so it works on every view tab. See **`docs/question-bank-hub-header-pattern.md`** and **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+**Folder-scoped library:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`LibraryNewFolderSheet`** mounted on **`LibraryClient`** so it works on every view tab. See **`docs/library-hub-header-pattern.md`** and **`.cursor/rules/exxat-library-hub-header.mdc`**.
 
 ## When to use
 
@@ -33,11 +33,11 @@ Shared UI for **who can access a hub** (face stack in the header) and **inviting
 
 ```tsx
 <CollaborationAccessFlow
-  initialCollaborators={QUESTION_BANK_HEADER_COLLABORATORS}
+  initialCollaborators={LIBRARY_HEADER_COLLABORATORS}
   resourceLabel={hubHeader.title}
 >
   {({ collaborators, openInvite }) => (
-    <QuestionBankPageHeader
+    <LibraryPageHeader
       variant="collaboration"
       title={hubHeader.title}
       questionCount={count}
@@ -100,9 +100,9 @@ Row order:
 | Hub flow | `components/collaboration-access-flow.tsx` |
 | Collaborator type | `components/page-header.tsx` (`PageHeaderCollaborator`) |
 | Invite sheet | `components/invite-collaborators-drawer.tsx` |
-| Entity header | `components/question-bank-page-header.tsx` |
-| Hub wiring | `components/question-bank-client.tsx` |
-| Demo roster | `lib/mock/question-bank-header-collaborators.ts` |
+| Entity header | `components/library-page-header.tsx` |
+| Hub wiring | `components/library-client.tsx` |
+| Demo roster | `lib/mock/library-header-collaborators.ts` |
 
 ## Checklist (new hub)
 

package/consumer-extras/patterns/command-menu-pattern.md

@@ -42,4 +42,4 @@ The command menu is the app’s **global search and AI entry**—one place to ju
 
 ---
 
-Keep this document aligned with **`exxat-ds/AGENTS.md` §7.1** when behavior or copy changes.
+Keep this document aligned with **`apps/web/AGENTS.md` §7.1** when behavior or copy changes.

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -25,26 +25,6 @@ The npm package includes a full Next.js reference under:
 
 Use it when you need to know **what files exist**, **how shims re-export** `@exxatdesignux/ui`, or **what AGENTS / layout** patterns look like for the current release. Porting is manual: diff template vs your repo and apply intentional changes (imports, new components, CSS entrypoints).
 
-### List-page view registry (required for data hubs)
-
-After upgrading, confirm each hub table uses **`ListPageConnectedViewBody`** (not long **`if (view === …)`** chains) and that these stay aligned:
-
-| File | Purpose |
-|------|---------|
-| `lib/data-list-view-registry.ts` | Render kinds + hub KPI strip rules |
-| `lib/<hub>-supported-views.ts` | What the hub can add/switch to |
-| `components/templates/list-page.tsx` | `supportedViewTypes` on Add view + shortcuts |
-| `components/data-views/list-page-connected-view-body.tsx` | View router |
-| `lib/hub-connected-view-renderers.ts` | **`defineHubViewRenderers(supported, { … })`** — dev warnings when a supported view has no body |
-| `components/data-views/list-page-folder-columns-panel.tsx` | Generic Miller columns for **panel** view (hub wrapper for QB colors/actions) |
-
-Pass the **same** `supportedViewTypes` array to **`ListPageTemplate`** and **`TablePropertiesDrawerButton`**. Wrap hub renderers with **`defineHubViewRenderers`**. Import **question-bank-only** tree/folder nav from hub files, not the generic **`data-views`** barrel. See **`docs/exxat-ds/data-views-pattern.md`** § “View registry and connected bodies” and **`consumer-app-pattern.md`** for the full consumer-app checklist.
-
-### Shell + sidebar (after DS token changes)
-
-- [ ] Dark mode **secondary panel** uses **`--secondary-panel-bg`** from DS globals (sidebar-accent mix) — spot-check Question bank **Library** rail.
-- [ ] Collapsed **product switcher** — **`SidebarMenuButton` `tooltip=`** + **`DropdownMenuTrigger`** only (no outer **`Tooltip`** wrapping the trigger).
-
 ## 4. Dependency and Node
 
 - Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.