@exxatdesignux/ui 0.2.19 → 0.4.0

package/template/docs/HANDBOOK.md

@@ -0,0 +1,187 @@
+# Exxat DS — Handbook
+
+> **Start here.** One page. Read in 10 minutes. Links out to everything else.
+>
+> **Audience:** designers, engineers, contributors, AI agents — anyone shipping UI in the Exxat product.
+>
+> **Working with an AI assistant?** Read [`.cursor/skills/exxat-token-economy/SKILL.md`](../../.cursor/skills/exxat-token-economy/SKILL.md) **first** (or `.claude/skills/exxat-token-economy/SKILL.md` for Claude Code). It's a one-page pre-flight that cuts token usage by ~50%: a task → minimum-file-set table, the five-question rule check, and tiny scaffolds that mean the assistant never has to re-read this handbook for the common case.
+
+---
+
+## 1. Five principles
+
+Every screen, primitive, and pattern in this design system serves one or more of these. When in doubt, the principle wins over the convenience.
+
+1. **Clarity over decoration.** Users see one product, one shell, one rhythm. Surprise (mystery icons, hidden states, novel layouts) is a tax on attention.
+2. **Progressive disclosure.** Beginners see what they need. Power users reach what they want. Default to the simpler surface; expose density on opt-in (Properties drawer, view tabs, secondary panel).
+3. **Same-shaped tools.** A hub looks like a hub. A drawer looks like a drawer. A KPI looks like a KPI. Pick the canonical primitive (§5 reference pages) before composing your own.
+4. **Accessibility is non-negotiable.** WCAG 2.1 AA is the **floor**, not the goal. Keyboard, screen-reader, contrast, touch-target, format hints — all enforced by rules, lints, and a checklist.
+5. **The data drives the chrome.** KPIs, status, trend polarity, descriptions — they come from the dataset (or the product) and are honest. No spin arrows, no decorative placeholders.
+
+---
+
+## 2. How to build a hub in 6 steps
+
+This is the **happy path** for the most common task: "I have an entity (records, library items, tokens, …); ship a hub for it." Follow these in order and the page lands at "best UX/UI", not "random design".
+
+| Step | What to do | Where it lives | Rule |
+|---|---|---|---|
+| 1 | Add typed mock rows in `lib/mock/<entity>.ts`. Aim for ~12 realistic records. | `apps/web/lib/mock/` | `.cursor/rules/exxat-centralized-list-dataset.mdc` |
+| 2 | Write **one** KPI helper `lib/mock/<entity>-kpi.ts` returning `MetricItem[]` (≤ 4 tiles). | same | `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` |
+| 3 | Build the column defs (`ColumnDef[]`). Set `filter:` per column to get filter chips automatically. | `apps/web/components/<entity>-table.tsx` | `exxat-data-tables.mdc` |
+| 4 | Mount **`HubTable`** (NOT raw `<DataTable>`) inside `ListPageTemplate.renderContent`. `HubTable` wires `useTableState`, toolbar (search + filter chips + sort), and the **Properties drawer** in one place. | `apps/web/components/<entity>-table.tsx` | `exxat-data-tables.mdc` |
+| 5 | Compose the page client with `PrimaryPageTemplate` → `ListPageTemplate` (KPIs in `metrics`, view tabs in `defaultTabs`, the `HubTable` in `renderContent`). | `apps/web/components/<entity>-client.tsx` | `exxat-list-page-connected-views.mdc` |
+| 6 | Add to nav (`lib/mock/navigation.tsx`). If the hub needs scoped sub-navigation (e.g. categories), declare `secondaryPanel: "<id>"` and register the panel. | `apps/web/lib/mock/navigation.tsx`, `apps/web/components/sidebar/secondary-panel.tsx` | `exxat-primary-nav-secondary-panel.mdc` |
+
+**Reference pages to copy:** `apps/web/components/columns-showcase.tsx` (single-view catalog hub composing every reusable cell), `apps/web/components/tokens-themes-client.tsx` (hub with a secondary panel + URL-driven scope), or `apps/web/components/library-table.tsx` (full hub: table / board / dashboard + conditional rules).
+
+> **Stop signs.** If you find yourself building a parallel table stack, a second metrics strip, a custom filter row, or pasting raw `<DataTable>` into `renderContent` — **stop and re-read** `.cursor/rules/exxat-reuse-before-custom.mdc`.
+
+---
+
+## 3. Where everything lives
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ PRINCIPLES + HANDBOOK   →  docs/HANDBOOK.md (this file)             │
+│                                                                     │
+│ FOUNDATIONS                                                         │
+│   tokens                →  docs/token-taxonomy.md                   │
+│   icons (Font Awesome)  →  .cursor/rules/exxat-fontawesome-icons    │
+│   typography            →  docs/token-taxonomy.md (font-* tokens)   │
+│   spacing / radius      →  docs/token-taxonomy.md (--exxat-*)       │
+│   color & themes        →  apps/web/components/tokens-themes-*      │
+│   voice & tone          →  docs/voice-and-tone.md                   │
+│   glossary              →  docs/glossary.md                         │
+│   reference pages       →  docs/reference-implementations.md        │
+│                                                                     │
+│ DECIDING (selection guides)                                         │
+│   which component?      →  docs/component-selection-guide.md        │
+│   page vs drawer vs     →  docs/drawer-vs-dialog-pattern.md         │
+│     dialog vs route        + .cursor/rules/exxat-{drawer-vs-dialog, │
+│                              page-vs-drawer}.mdc                    │
+│   card vs row vs list   →  docs/card-vs-rows-pattern.md             │
+│                                                                     │
+│ BLUEPRINTS  (framework-agnostic specs — one per pattern)            │
+│                         →  docs/blueprints/                         │
+│                            page-header · data-table ·               │
+│                            list-page-template · board-card ·        │
+│                            key-metrics                              │
+│                                                                     │
+│ PATTERNS  (long-form narrative — the "why" + the "how")             │
+│                         →  docs/*.md (data-views-pattern,           │
+│                            kpi-trend-pattern, drawer-vs-dialog-     │
+│                            pattern, dedicated-search,               │
+│                            command-menu, …)                         │
+│                                                                     │
+│ RULES  (binding MUST / MUST NOT — for AI agents + reviewers)        │
+│                         →  .cursor/rules/*.mdc                      │
+│                                                                     │
+│ SKILLS  (workflows + checklists — for AI agents doing a task)       │
+│                         →  .cursor/skills/  +  .claude/skills/      │
+│                                                                     │
+│ MIGRATIONS  (deprecation history, every breaking change)            │
+│                         →  docs/migrations/                         │
+│                                                                     │
+│ AGENT HANDBOOK  (authoritative §-numbered manual)                   │
+│                         →  apps/web/AGENTS.md                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Quick "which file should I open?" cheat-sheet
+
+| You want to… | Open this |
+|---|---|
+| Pick the right component for a job | [`docs/component-selection-guide.md`](./component-selection-guide.md) |
+| Know what "hub" / "view tab" / "KPI band" mean | [`docs/glossary.md`](./glossary.md) |
+| Write empty-state / error / button copy | [`docs/voice-and-tone.md`](./voice-and-tone.md) |
+| Find the canonical reference page to copy | [`docs/reference-implementations.md`](./reference-implementations.md) |
+| Know the spec for a pattern | [`docs/blueprints/`](./blueprints/) |
+| Understand the "why" of a pattern | [`docs/<pattern>-pattern.md`](.) |
+| Know the binding MUST / MUST NOT | [`.cursor/rules/`](../../../.cursor/rules/) |
+| Run a recurring agent workflow | [`.cursor/skills/`](../../../.cursor/skills/) or [`.claude/skills/`](../../../.claude/skills/) |
+| Token name & semantics | [`docs/token-taxonomy.md`](./token-taxonomy.md) |
+| Full authoritative handbook | [`apps/web/AGENTS.md`](../AGENTS.md) |
+
+---
+
+## 4. Rule precedence (when sources conflict)
+
+If two docs say different things, **the higher row wins**:
+
+1. **`.cursor/rules/*.mdc`** — these are MUST / MUST NOT; they bind the AI agent and the reviewer.
+2. **`apps/web/AGENTS.md`** — authoritative §-numbered handbook. The rules above are summaries of this.
+3. **`docs/blueprints/*.md`** — framework-agnostic specs for a single pattern.
+4. **`docs/*-pattern.md`** — long-form narrative for a pattern.
+5. **Reference page in code** (`apps/web/components/<reference>.tsx`) — the working implementation.
+6. **This handbook** — orientation only. If it conflicts with rules or AGENTS, the rules/AGENTS win.
+
+> **Found a conflict?** Open a PR that updates the *binding* layer (rule or AGENTS section) first, then propagate down. Don't fork the truth.
+
+---
+
+## 5. The canonical primitives (memorize these)
+
+These are the ones you'll use on >90% of screens. If a screen needs something else, it almost certainly already exists — search `components/` before building.
+
+| Need | Primitive | Lives in |
+|---|---|---|
+| Page chrome (breadcrumbs, site header, max-width content rail) | `PrimaryPageTemplate` | `apps/web/components/templates/primary-page-template.tsx` |
+| Hub frame (header + metrics + view tabs + content) | `ListPageTemplate` | `packages/ui` |
+| **Hub view body** (table + search + filters + Properties drawer + bulk-actions) | **`HubTable`** | `packages/ui` (re-exported from `@/components/data-views`) |
+| Page header (title + subtitle + actions + collaborators rail) | `PageHeader` | `apps/web/components/page-header.tsx` |
+| KPI strip / band | `KeyMetrics` (`variant="flat"` on hubs) | `packages/ui` |
+| Status chip + icon | `ListHubStatusBadge` + `lib/list-status-badges.ts` | `apps/web/components/` |
+| Board / kanban card | `ListPageBoardCard` + primitives | `packages/ui` |
+| Side overlay | `Sheet` / `Drawer` (NOT toast — `exxat-no-toast.mdc`) | `packages/ui` |
+| Persistent banner | `LocalBanner` / `SystemBanner` | `packages/ui` |
+| Inline status / format hint | `FormDescription`, inline `<small>` | `packages/ui` |
+| Tooltip | `Tip` / `Tooltip` | `packages/ui` |
+| Keyboard shortcut hint | `Kbd` (`variant="bare"` inside buttons) | `packages/ui` |
+| Global search | `CommandMenu` (⌘K) | `apps/web/components/command-menu.tsx` |
+| AI assistant chrome | Ask Leo side panel (⌘⌥K) | `apps/web/components/` |
+
+For a fuller decision tree see [`docs/component-selection-guide.md`](./component-selection-guide.md).
+
+---
+
+## 6. The shortest accessibility checklist
+
+Run this on every PR. If you can't tick every box, the change isn't ready. (Full list: `.cursor/skills/exxat-accessibility/SKILL.md` and [`AGENTS.md` §8](../AGENTS.md).)
+
+- [ ] **Keyboard.** Every interactive thing reachable via Tab + activatable via Enter / Space. Focus ring visible (≥ 3:1).
+- [ ] **Touch target ≥ 24×24 CSS px** (or 24 px spacing) per WCAG 2.5.8.
+- [ ] **Icons that mean something** have a text alt — either adjacent label (Case A, `aria-hidden`), or `role="img" + aria-label + Tooltip` (Case B), or `aria-label + Tooltip` on the button (Case C). No silent icons.
+- [ ] **Contrast.** Text ≥ 4.5:1; UI components ≥ 3:1. Don't encode state with color alone — pair with icon or label.
+- [ ] **Format hints are persistent**, never placeholder-only. Use `FormDescription`.
+- [ ] **Dialogs / drawers / sheets** have a `Title` (use `sr-only` if visually hidden).
+- [ ] **Tabs** use `role="tablist"` correctly (no mixed children); composite switchers use `role="toolbar"` instead.
+- [ ] **No toast.** Use banners, inline status, or dialogs (`exxat-no-toast.mdc`).
+- [ ] **HC modes.** Forced-colors and `data-contrast="high"` covered for any fill-only state (progress, gauge, pill).
+
+---
+
+## 7. The "you're done" definition
+
+A hub or screen is **done** when:
+
+1. It uses `PrimaryPageTemplate` + `ListPageTemplate` (or another canonical template).
+2. The data surface is `HubTable` (or, for non-hubs, the right primitive from §5).
+3. KPIs use `KeyMetrics` with `delta` for counts, `description` for prose, ≤ 4 tiles, polarity set correctly.
+4. The §6 accessibility checklist is green.
+5. Copy passes [`docs/voice-and-tone.md`](./voice-and-tone.md).
+6. No new shared primitives were added without `.cursor/rules/exxat-reuse-before-custom.mdc` approval.
+7. The §13 PR-review checklist in [`AGENTS.md`](../AGENTS.md#section-13) is green.
+
+---
+
+## 8. Where to ask for help
+
+- **Code-level questions** — open the file referenced in a rule's "See also" section.
+- **Pattern-level questions** — open the matching `docs/*-pattern.md`.
+- **"Is this the right approach?"** — read [`.cursor/rules/exxat-reuse-before-custom.mdc`](../../../.cursor/rules/exxat-reuse-before-custom.mdc). If still unsure, ask before building.
+- **AGENTS.md is too long** — that's why this handbook exists. Bring the §-number you're stuck on; we'll split it out.
+
+---
+
+*This file is intentionally short. If you want to add something, ask whether it belongs in a rule, a pattern, a blueprint, or the glossary instead.*

package/template/docs/blueprints/README.md

@@ -0,0 +1,86 @@
+# Exxat DS — Blueprints
+
+**Audience:** humans + AI agents.
+**Inspired by:** [SLDS Component Blueprints](https://www.lightningdesignsystem.com/components).
+
+A **blueprint** is a **framework-agnostic spec** for a UI pattern. It says
+*what* the pattern is, *what it must do*, and *what tokens it consumes* —
+**without committing to any one implementation**.
+
+A **component** is the React + Tailwind implementation that satisfies the
+blueprint inside this app.
+
+| Blueprint says… | Component does… |
+|---|---|
+| "A page header has a title, optional icon, optional meta line, optional action slot, optional `+ N collaborators` rail" | `PageHeader` renders that with `variant="object-home" / "record-home" / "collaboration"` etc. |
+| "A data list is a sortable, filterable, columnable grid of records with search, properties drawer, and view tabs" | `DataTable` + `ListPageTemplate` + `TablePropertiesDrawer` compose to satisfy this |
+
+---
+
+## Why blueprints exist
+
+1. **They survive framework changes.** If we ever ship a second consumer
+   (mobile, embed widget, design-token export to Figma), the blueprint stays
+   true; only the implementation changes.
+2. **They make the design language explicit.** New contributors can read a
+   single page that says "this is what a page header **is** at Exxat" without
+   spelunking through React props.
+3. **They let designers, engineers, and AI agents share one vocabulary.** The
+   blueprint is the contract; the React component is the receipt.
+
+---
+
+## Anatomy of a blueprint doc
+
+Each blueprint follows the same template. Copy it from
+[`_template.md`](./_template.md) when adding a new one.
+
+```
+# <Blueprint name>
+
+## 1. Intent          → What user need does this solve? When NOT to use it.
+## 2. Anatomy         → Required + optional slots, with an ASCII or markdown sketch.
+## 3. States          → Default, hover, active, disabled, loading, empty, error, RTL.
+## 4. Tokens consumed → Exact token names from `docs/token-taxonomy.md`.
+## 5. Accessibility   → Roles, focus order, keyboard, screen-reader.
+## 6. Variants        → Named families that share anatomy but swap layout/density.
+## 7. Implementation  → Table of frameworks → component(s); React is required.
+## 8. Do / Don't      → Anti-patterns + correct alternatives.
+## 9. References      → Linked AGENTS.md sections, cursor rules, related blueprints.
+```
+
+The React row in §7 is **required**; other frameworks are listed as `—` until
+they ship.
+
+---
+
+## Authoritative file pointers
+
+For most patterns, the blueprint complements an existing narrative doc — it
+does **not** replace it. The blueprint is the spec; the narrative is the deep
+dive.
+
+| Blueprint | Narrative doc | Cursor rule(s) | React component(s) |
+|---|---|---|---|
+| [page-header](./page-header.md) | `apps/web/docs/data-views-pattern.md` (Page header section) | `exxat-collaboration-access.mdc` (variant), `exxat-mono-ids.mdc` (subtitle IDs) | `PageHeader`, `PlacementsPageHeader`, `TeamPageHeader`, `LibraryPageHeader` |
+| [data-table](./data-table.md) | `apps/web/docs/data-views-pattern.md` | `exxat-data-tables.mdc`, `exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc` | `DataTable`, `DataTablePaginated`, `useTableState`, `TablePropertiesDrawer` |
+| [list-page-template](./list-page-template.md) | `apps/web/docs/data-views-pattern.md`, `kpi-flat-band-pattern.md` | `exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc`, `exxat-list-page-view-shells.mdc` | `ListPageTemplate`, `HubTable`, `useTableState`, `TablePropertiesDrawer` |
+| [board-card](./board-card.md) | `apps/web/docs/data-views-pattern.md` (board UI section) | `exxat-board-cards.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-card-vs-list-rows.mdc` | `ListPageBoardCard`, `ListPageBoardCardTitleRow`, `ListPageBoardCardBadgeRow`, `BoardCardTwoLineBlock`, `BoardCardIconRow`, `ListHubStatusBadge` |
+| [key-metrics](./key-metrics.md) | `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md` | `exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` | `KeyMetrics`, `MetricItem`, `MetricInsight`, `KeyMetricsProvider` |
+
+Future blueprints to write (open a PR when adding one):
+
+- `drawer-vs-dialog.md` — overlay decision (already in `docs/drawer-vs-dialog-pattern.md`, formalize as blueprint)
+- `command-menu.md` — global ⌘K palette + Ask Leo split
+- `dedicated-search.md` — landing vs results
+- `sidebar.md` — primary nav + secondary panel + product switcher
+- `coach-mark.md` — onboarding tours
+- `status-badge.md` — `ListHubStatusBadge` + `lib/list-status-badges.ts`
+
+---
+
+## See also
+
+- [`apps/web/docs/token-taxonomy.md`](../token-taxonomy.md) — the design-token namespace these blueprints reference
+- [`apps/web/docs/component-selection-guide.md`](../component-selection-guide.md) — decision tree across blueprints
+- [`apps/web/AGENTS.md`](../../AGENTS.md) §9 architecture pointers (component reuse table)

package/template/docs/blueprints/_template.md

@@ -0,0 +1,91 @@
+# Blueprint: <Name>
+
+> **Status:** Draft / Stable. **Owner:** <team or person>. **Implements:** <SC refs>.
+
+## 1. Intent
+
+What user need does this pattern solve? In one paragraph.
+
+**Use when:**
+- Bullet
+- Bullet
+
+**Do NOT use when:**
+- Bullet
+
+## 2. Anatomy
+
+ASCII / markdown sketch with labelled slots. List every named slot and whether
+it is required, optional, or conditional.
+
+```
+┌──────────────────────────────────────────┐
+│ [icon]  Title                  [actions] │  ← slot: title-row (required)
+│ ───────────────────────────────────────  │
+│ subtitle · ID · meta                     │  ← slot: meta (optional)
+└──────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `title` | required | Single H1 string |
+| `icon` | optional | FA glyph or product mark |
+| `actions` | optional | Primary CTA + optional `⋯` overflow |
+| `meta` | optional | Count · freshness · sort summary |
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Default | … |
+| Loading | … |
+| Empty | … |
+| Error | … |
+| RTL | … |
+
+## 4. Tokens consumed
+
+List every token the blueprint references from
+[`docs/token-taxonomy.md`](../token-taxonomy.md). Be precise — no "a brand
+color"; name `--brand-color`.
+
+| Token | Used for |
+|---|---|
+| `--background` / `--foreground` | Surface + ink |
+| … | … |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.1.1 Non-text content | Icons are decorative (Case A) when adjacent to text; standalone icons follow Case B (label + tooltip) |
+| 1.3.1 Info & relationships | … |
+| 2.1.1 Keyboard | Tab order: … |
+| 2.4.6 Headings / labels | The title slot is the `<h1>` for the route |
+| 2.4.11 Focus visible | Inherits `:focus-visible` ring (≥ 3:1) |
+
+## 6. Variants
+
+| Variant | When to use | Differences from default |
+|---|---|---|
+| `base` | … | — |
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `PrimaryComponent` + `RelatedComponent` | `apps/web/components/<file>.tsx` |
+| Mobile | — | — |
+| Figma | — | — |
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Bullet | Bullet |
+
+## 9. References
+
+- `apps/web/docs/<related-narrative>.md`
+- `.cursor/rules/<related-rule>.mdc`
+- `apps/web/AGENTS.md` §<section>

package/template/docs/blueprints/board-card.md

@@ -0,0 +1,123 @@
+# Blueprint: Board card
+
+> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.1.1, 1.3.1, 2.5.8, 4.1.2.
+
+## 1. Intent
+
+A **board card** is the kanban-tile presentation of a single hub record (e.g.
+one Placement, one Team member, one Question-bank item) when the active view
+is `board`. The card surfaces the most-scannable summary fields — title, owner
+avatar, status chip, 1-3 meta lines — and is sized so a column holds 6-10
+cards on a 1280-wide viewport.
+
+**Use when:**
+
+- The hub's `board` view tab is active.
+- The record has a **status** (or equivalent grouping) that drives column placement.
+- Users compare ~6-30 records side-by-side and would benefit from owner / status visibility.
+
+**Do NOT use when:**
+
+- The record needs ≥ 4 fields to be useful at a glance (use list / table).
+- The dataset has > ~100 records per column (board UX collapses; use table + filters).
+- The hub does not model status / lifecycle (use folder grid or list).
+
+## 2. Anatomy
+
+```
+┌──────────────────────────────────────────────┐
+│  Title row                       [avatar]    │  ← slot: title (required) + trailing (optional)
+│ ──────────────────────────────────────────── │
+│  [status chip]                               │  ← slot: badgeRow (optional, when status exists)
+│ ──────────────────────────────────────────── │
+│  Body — primary stat (large) + sub label     │  ← slot: body (optional)
+│  ▣ row icon · meta label · meta value        │
+│  ▣ row icon · meta label · meta value        │
+└──────────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `title` | required | `ListPageBoardCardTitleRow` — single-line truncated title |
+| `trailing` | optional | `ListPageBoardCardAvatar` (owner) or another single glyph |
+| `badgeRow` | optional | `ListPageBoardCardBadgeRow` + `ListHubStatusBadge surface="board"` |
+| `body` | optional | `ListPageBoardCardBody` containing `BoardCardTwoLineBlock` / `BoardCardIconRow` |
+| `footer` | optional | Counts, freshness, or a small CTA — kept low-emphasis |
+
+The shell is `ListPageBoardCard` (`Card size="sm"` treatment) — do NOT compose
+a bespoke `<button>` + border-class wrapper for the same pattern.
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Default | Surface 2 background, hairline border, no shadow |
+| Hover | Border deepens; subtle elevation shift (matches `Card size="sm"`) |
+| Focused | `:focus-visible` ring on the outer element (≥ 3:1) |
+| Selected (drag source / active drag target) | `data-selected` border + brand tint |
+| Loading | Skeleton shell mirroring title row + badge row + body |
+| Empty column | Column footer shows "+ Add" affordance with `aria-label` per column |
+| RTL | All trailing slots flip; status chip flips alignment |
+
+## 4. Tokens consumed
+
+| Token | Used for |
+|---|---|
+| `--exxat-color-surface-2` / `--card` | Card background |
+| `--exxat-color-border-1` / `--border` | Card hairline |
+| `--exxat-color-ink-1` / `--foreground` | Title text |
+| `--exxat-color-ink-2` / `--muted-foreground` | Meta label text |
+| `--exxat-color-focus-ring` / `--ring` | `:focus-visible` ring |
+| `--exxat-radius-2` / `--radius-md` | Card corners |
+| Status-tint variables (`LIST_HUB_STATUS_TINT_*`) | Status chip background + text |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.1.1 Non-text content | Icons in `BoardCardIconRow` are decorative when paired with a visible label (Case A); standalone glyphs get Case B label + tooltip |
+| 1.3.1 Info & relationships | The card is one `<article>` (or `role="listitem"` inside the column's `role="list"`); status, owner, and meta rows are programmatically related to the title |
+| 2.5.8 Target size | The whole card is the primary click target — ≥ 24×24 CSS px; small icon controls inside use `size-6` (≥ 24px) |
+| 4.1.2 Name / role / value | If the card is interactive (opens detail) it is rendered as `<button>` with an accessible name combining title + status |
+
+## 6. Variants
+
+| Variant | When to use | Differences from default |
+|---|---|---|
+| `base` | Most hubs | Title + status badge + body |
+| `no-status` | Hubs without lifecycle (Library items) | Omit `badgeRow`; body carries the differentiator |
+| `compact` | Dense boards (10+ cards visible) | Drop body; show title + status + avatar only |
+| `with-progress` | Workflow boards with completion bar | Add a `<Progress>` row in the body slot |
+
+## 6.1 List-row counterpart
+
+`ListPageBoardCard layout="row"` is the same component shape rendered as a
+horizontal row for the `list` view tab. Use one renderer for both views so the
+**title / status / owner / meta** mapping stays consistent — never define two
+parallel components for "card" and "row" of the same hub.
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `ListPageBoardCard` + `ListPageBoardCardTitleRow` + `ListPageBoardCardBadgeRow` + `ListPageBoardCardBody` + `BoardCardTwoLineBlock` + `BoardCardIconRow` + `ListHubStatusBadge` | `@exxatdesignux/ui/components/data-views` + `apps/web/lib/list-status-badges.ts` |
+| Board template | `ListPageBoardTemplate` (column shells + `renderCard`) | `@exxatdesignux/ui/components/data-views/list-page-board-template` |
+| Mobile | — | — |
+| Figma | "Board card – hub" component in DS library | — |
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Use `ListPageBoardCard` as the shell; compose primitives inside | Wrap a bespoke `<button>` with border / padding utility classes for the same pattern |
+| Status: `ListHubStatusBadge surface="board"` + entity-specific map from `lib/list-status-badges.ts` | Show status as plain body text when the hub uses `ListHubStatusBadge` elsewhere |
+| Pull rows from `tableState.rows` so board honors filters / search | Hydrate cards from a separate `BOARD_MOCK[]` array |
+| Match list-row + table-row + card field choices via one mapper per hub | Define a card-only field projection that diverges from the table |
+| Use `Tip` on any icon-only control inside the card | Rely on `aria-label` alone for icon-only affordances inside the card |
+
+## 9. References
+
+- `apps/web/docs/data-views-pattern.md` — board UI section
+- `.cursor/rules/exxat-board-cards.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-card-vs-list-rows.mdc`
+- `apps/web/AGENTS.md` §4.4 (board cards), §13 (checklist)
+- `apps/web/lib/list-status-badges.ts` — `LIST_HUB_STATUS_TINT_*` + entity maps

package/template/docs/blueprints/data-table.md

@@ -0,0 +1,139 @@
+# Blueprint: Data Table
+
+> **Status:** Stable. **Owner:** Exxat DS core. **Implements:** WCAG 2.1 AA. **References:** SC 1.3.1, 2.1.1, 2.4.3, 2.4.6, 2.5.8, 4.1.2.
+
+## 1. Intent
+
+A **data table** is the canonical Exxat surface for browsing a homogeneous,
+comparable dataset (placements, team members, questions, compliance records).
+It pairs a **sortable / filterable / columnable grid** with a single state
+object (`useTableState`) that **every connected view** — list, board,
+dashboard, folder, panel — reads from.
+
+**Use when:**
+- The hub shows ≥ ~10 comparable records.
+- Users need to sort, filter, pin columns, change density, or export the data.
+- The hub is a primary nav destination.
+
+**Do NOT use when:**
+- The hub is **visual browse** (kanban, gallery, finder) — use
+  `ListPageBoardCard` + `data-views/` primitives. See
+  [`card-vs-rows-pattern.md`](../card-vs-rows-pattern.md).
+- The data is < ~10 rows and never grows — a simple list (or `<dl>`) suffices.
+- The view is read-only inside an analytics card — that may use minimal markup
+  per [`AGENTS.md` §3](../../AGENTS.md).
+
+## 2. Anatomy
+
+```
+┌─ ListPageTemplate ────────────────────────────────────────────────────┐
+│ [view tabs] [Add view +]                       [metrics slot]         │
+│  ├ DataTableToolbar ──────────────────────────────────────────────┐   │
+│  │ [search] [filter chips] [sort] [columns] [⋯ properties]        │   │
+│  ├ DataTable header ──────────────────────────────────────────────┤   │
+│  │  Col A ↕ │ Col B │ Col C │ …                                   │   │
+│  ├ DataTable body  ───────────────────────────────────────────────┤   │
+│  │  …rows from `tableState.rows`…                                 │   │
+│  ├ DataTablePaginated footer (optional) ──────────────────────────┤   │
+│  │  ‹ 1 / N ›                                                     │   │
+│  └────────────────────────────────────────────────────────────────┘   │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `view tabs` | required when ≥ 1 view type | `table / list / board / dashboard` per `ListPageTemplate` |
+| `toolbar.search` | required | `⌘K` / `Ctrl K` find-in-list |
+| `toolbar.filter` | required when entity has filterable fields | Shared `FilterFieldDef` chips |
+| `toolbar.sort` | optional (column headers also sort) | Multi-column sort summary |
+| `toolbar.columns` | required | Column visibility / order chooser |
+| `toolbar.overflow` | required | `⋯` → `TablePropertiesDrawer` |
+| `header` | required | One row of column heads; sortable cells expose `aria-sort` |
+| `body` | required | Rows from **`tableState.rows`** — no parallel data source |
+| `pagination` | optional | When the result set exceeds the virtualization budget |
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Empty result | Inline empty-state row (icon + 1 sentence + clear filters action) |
+| Empty entity | Empty-state card (no rows in entity) |
+| Loading | Skeleton header + 5 skeleton rows; toolbar still interactable |
+| Sorted | Active column shows ↑ / ↓ with `aria-sort`; multi-sort shows index pill |
+| Filtered | Chips in toolbar; "X of Y" indicator |
+| Selected rows | Row check + bulk-action bar above toolbar |
+| Pinned cells | Opaque using `--dt-row-bg` / `--dt-header-bg` (never translucent) |
+| New row (just created) | `--dt-new-row-bg` + `--dt-new-row-border` (fades after N seconds) |
+| RTL | Header sort arrows and column resize handles mirror |
+
+## 4. Tokens consumed
+
+| Token | Used for |
+|---|---|
+| `--dt-row-bg`, `--dt-row-hover`, `--dt-row-selected`, `--dt-row-selected-fg` | Row chrome (must be **opaque** for pinned cells) |
+| `--dt-header-bg`, `--dt-group-bg` | Header + group rows |
+| `--dt-new-row-bg`, `--dt-new-row-border` | "Just created" highlight |
+| `--sticky-edge-fade` | Edge-of-pinned-column gradient |
+| `--border` | Hairlines between rows / columns |
+| `--ring` | Focus ring on cells, sort headers, row actions |
+| `--interactive-hover-row` | Hover-row tint |
+| `--avatar-initials-bg`, `--avatar-initials-fg` | Initials cells |
+| `--font-mono` (via `font-mono tabular-nums` class) | System IDs in cells |
+| `--table-row-height` | Default row height (`48px * --scaling`) |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.3.1 Info & relationships | `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th scope="col">` semantics preserved through TanStack Table renderers |
+| 1.4.3 Contrast | Row hover + selection tints stay ≥ 4.5:1 against `--foreground` |
+| 1.4.11 UI contrast | Cell borders use `--border`; focus uses `--ring` (≥ 3:1) |
+| 2.1.1 Keyboard | Cells reachable by `Tab`; arrow-key cell nav inside the body; `Esc` clears active filter chip |
+| 2.4.3 Focus order | Header → toolbar → body → pagination; never traps |
+| 2.4.6 Headings & labels | Column heads are `<th>` with visible text labels; icon-only sort affordance carries `aria-label` + `Tooltip` (SC 1.1.1 Case C) |
+| 2.5.8 Target size | Sort handles, sort/filter chips, row checkboxes ≥ 24×24 CSS px |
+| 4.1.2 Name, role, value | Sortable headers expose `aria-sort`; row selection checkboxes expose checked state |
+
+## 6. Variants
+
+| Variant | When to use | Differences |
+|---|---|---|
+| `DataTable` | Default — virtualized, sticky header | All features above |
+| `DataTablePaginated` | Server-paginated result sets where virtualization is wrong | Page footer + page-size selector |
+| `DataTable size="compact"` | Dense data (admin tools, reconciliation views) | Reduced `--table-row-height` |
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `DataTable`, `DataTablePaginated`, `useTableState`, `DataTableToolbar`, `TablePropertiesDrawer`, **importable cell renderers** in `components/data-views/table-cells.tsx` (`ProgressCell`, `CurrencyCell`, `RatingCell`, `RowActionsCell<TRow>`, …) | [`packages/ui/src/components/data-table/`](../../../../packages/ui/src/components/data-table/), [`apps/web/components/data-views/table-cells.tsx`](../../components/data-views/table-cells.tsx), [`packages/ui/src/components/table-properties/`](../../../../packages/ui/src/components/table-properties/) |
+| Mobile | — | — |
+| Figma | — | — |
+
+Reference compositions:
+
+- **Placements** — `PlacementsClient` + `PlacementsTable` (most complete reference)
+- **Team** — `TeamClient` + `TeamTable`
+- **Compliance** — `ComplianceClient` + `ComplianceTable`
+- **Library** — `LibraryClient` + `LibraryTable` (adds folder
+  scope from URL)
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Use **one** `useTableState` per logical table; pass `tableState.rows` to every connected view (list/board/dashboard) | Hydrate a board / list view from a parallel mock array — the count will diverge from the table |
+| Wrap the table in `ListPageTemplate` so view tabs exist | Render `DataTable` directly under `PageHeader` for a primary hub |
+| Pass `currentView` + `onViewChange` to `TablePropertiesDrawer` so Properties matches the active tab | Mount `TablePropertiesDrawer` on a multi-view page without `currentView` — it defaults to "Table display" copy on Board |
+| Use `font-mono tabular-nums` on system IDs only | Apply `font-mono` to names, statuses, or dates |
+| Mark sort headers with `aria-sort` and visible direction glyph | Use color alone to communicate sort direction |
+| Search keyboard hint shows `⌘K` (no Alt) | Use `⌘⌥K` for the table search — that chord is Ask Leo |
+
+## 9. References
+
+- [`apps/web/docs/data-views-pattern.md`](../data-views-pattern.md) — architecture narrative
+- [`.cursor/rules/exxat-data-tables.mdc`](../../../.cursor/rules/exxat-data-tables.mdc) — the mandatory stack
+- [`.cursor/rules/exxat-list-page-connected-views.mdc`](../../../.cursor/rules/exxat-list-page-connected-views.mdc) — `tableState.rows` across views
+- [`.cursor/rules/exxat-centralized-list-dataset.mdc`](../../../.cursor/rules/exxat-centralized-list-dataset.mdc) — one dataset rule
+- [`.cursor/rules/exxat-table-properties-drawer.mdc`](../../../.cursor/rules/exxat-table-properties-drawer.mdc) — Properties drawer + active view
+- [`apps/web/AGENTS.md`](../../AGENTS.md) §3, §4, §5