@exxatdesignux/ui 0.3.0 → 0.4.1

package/template/components/tokens-themes-section.tsx

@@ -0,0 +1,386 @@
+"use client"
+
+/**
+ * Tokens & themes — visualizer primitives + token index.
+ *
+ * This module exports the building blocks consumed by `tokens-themes-client.tsx`
+ * (which wires them into `PrimaryPageTemplate` + `ListPageTemplate`). It does
+ * NOT render the page shell.
+ *
+ * Each category gets a representation that matches the token's nature:
+ *
+ *   | Tab          | Renders tokens as…                                            |
+ *   |--------------|---------------------------------------------------------------|
+ *   | Colors       | 56-px swatch (`background: var(--name)`)                      |
+ *   | Gradients    | 96×40 fill swatch (paint-based, value usually multi-line)     |
+ *   | Radius       | 64×64 muted box with `border-radius: var(--name)`             |
+ *   | Size         | bar with `height: var(--name)` (scaled visually)              |
+ *   | Shadow       | floating mini-card with `box-shadow: var(--name)`             |
+ *   | Typography   | "Aa Sample" in `font-family: var(--name)`                     |
+ *   | Motion       | a dot that translates on hover using `transition: var(--name)`|
+ *   | Aliases      | `name → var(--target)` row (resolves the indirection)         |
+ *   | Other        | raw text value                                                |
+ *
+ * All tiles share click-to-copy on the `var(--name)` reference. The token
+ * index is the single source of truth: `packages/ui/tokens/hooks-index.json`.
+ */
+
+import * as React from "react"
+import { useTheme } from "next-themes"
+import tokensIndex from "@exxatdesignux/ui/tokens/hooks-index.json"
+import { Button } from "@/components/ui/button"
+import { Badge } from "@/components/ui/badge"
+import { Tip } from "@/components/ui/tip"
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
+import { cn } from "@/lib/utils"
+
+/* ── Token index types ────────────────────────────────────────────────── */
+
+export type TokenCategory =
+  | "color"
+  | "gradient"
+  | "radius"
+  | "size"
+  | "shadow"
+  | "typography"
+  | "transition"
+  | "alias"
+  | "other"
+
+export type TokenRecord = {
+  namespace: string
+  category: TokenCategory | string
+  values: Record<string, string>
+  tailwindUtilities?: string[]
+  deprecated?: boolean
+  deprecatedMessage?: string | null
+}
+
+type TokensIndex = {
+  version: string
+  tokenCount: number
+  namespaces: string[]
+  themeKeys: string[]
+  tokens: Record<string, TokenRecord>
+}
+
+export const TOKENS_INDEX = tokensIndex as unknown as TokensIndex
+
+/** First available theme value — used for the "raw value" text under each tile. */
+export function primaryValueText(t: TokenRecord): string {
+  return t.values.light ?? Object.values(t.values)[0] ?? ""
+}
+
+/* ── Category tab catalogue ────────────────────────────────────────────── */
+
+export interface CategoryTabDef {
+  id: TokenCategory
+  label: string
+  icon: string
+  matches: (cat: string) => boolean
+}
+
+export const CATEGORY_TABS: CategoryTabDef[] = [
+  { id: "color",      label: "Colors",     icon: "fa-palette",                matches: (c) => c === "color" },
+  { id: "gradient",   label: "Gradients",  icon: "fa-circle-half-stroke",     matches: (c) => c === "gradient" },
+  { id: "radius",     label: "Radius",     icon: "fa-rectangle-vertical",     matches: (c) => c === "radius" },
+  { id: "size",       label: "Size",       icon: "fa-ruler-horizontal",       matches: (c) => c === "size" },
+  { id: "shadow",     label: "Shadow",     icon: "fa-clone",                  matches: (c) => c === "shadow" },
+  { id: "typography", label: "Typography", icon: "fa-text-size",              matches: (c) => c === "typography" },
+  { id: "transition", label: "Motion",     icon: "fa-wave-sine",              matches: (c) => c === "transition" },
+  { id: "alias",      label: "Aliases",    icon: "fa-link",                   matches: (c) => c === "alias" },
+  { id: "other",      label: "Other",      icon: "fa-hashtag",                matches: (c) => c === "other" },
+]
+
+/** Pre-compute counts per category — same shape `getTabCount(filterId)` expects. */
+export const CATEGORY_COUNTS: Record<TokenCategory, number> = CATEGORY_TABS.reduce(
+  (acc, tab) => { acc[tab.id] = 0; return acc },
+  {} as Record<TokenCategory, number>,
+)
+export const DEPRECATED_COUNT = (() => {
+  let n = 0
+  for (const t of Object.values(TOKENS_INDEX.tokens)) {
+    if (t.deprecated) n += 1
+    for (const tab of CATEGORY_TABS) {
+      if (tab.matches(t.category)) {
+        CATEGORY_COUNTS[tab.id] += 1
+        break
+      }
+    }
+  }
+  return n
+})()
+
+/* ── Theme switcher ────────────────────────────────────────────────────── */
+
+export function TokensThemeSwitcher({ className }: { className?: string }) {
+  const { theme = "system", setTheme } = useTheme()
+  const [mounted, setMounted] = React.useState(false)
+  React.useEffect(() => setMounted(true), [])
+  const value = mounted ? theme : "system"
+  return (
+    <RadioGroup
+      value={value}
+      onValueChange={setTheme}
+      className={cn("inline-flex items-center gap-1 rounded-md border border-border bg-card p-1", className)}
+      aria-label="Theme preview"
+    >
+      {(["light", "dark", "system"] as const).map((t) => (
+        <label
+          key={t}
+          htmlFor={`theme-${t}`}
+          className={cn(
+            "flex cursor-pointer items-center gap-1.5 rounded px-2.5 py-1 text-xs transition-colors",
+            "hover:bg-foreground/[0.04]",
+            value === t && "bg-foreground/[0.06] text-foreground",
+          )}
+        >
+          <RadioGroupItem value={t} id={`theme-${t}`} className="sr-only" />
+          <i
+            className={cn(
+              "fa-light text-xs",
+              t === "light" && "fa-sun",
+              t === "dark" && "fa-moon",
+              t === "system" && "fa-desktop",
+            )}
+            aria-hidden="true"
+          />
+          <span className="capitalize">{t}</span>
+        </label>
+      ))}
+    </RadioGroup>
+  )
+}
+
+/* ── Clipboard hook ────────────────────────────────────────────────────── */
+
+export function useTokenClipboard() {
+  const [copied, setCopied] = React.useState<string | null>(null)
+  const copy = React.useCallback((text: string) => {
+    if (typeof navigator === "undefined" || !navigator.clipboard) return
+    navigator.clipboard.writeText(text).then(() => {
+      setCopied(text)
+      window.setTimeout(() => setCopied((c) => (c === text ? null : c)), 1200)
+    }).catch(() => {})
+  }, [])
+  return { copied, copy }
+}
+
+/* ── Tile shell ────────────────────────────────────────────────────────── */
+
+interface TokenTileProps {
+  name: string
+  record: TokenRecord
+  onCopy: (text: string) => void
+  preview: React.ReactNode
+  valueText?: string
+  density?: "tight" | "wide"
+}
+
+function TokenTile({ name, record, onCopy, preview, valueText, density = "wide" }: TokenTileProps) {
+  const cssRef = `var(${name})`
+  const raw = valueText ?? primaryValueText(record)
+  return (
+    <div
+      className={cn(
+        "group flex items-stretch gap-3 rounded-md border border-border bg-card p-3 transition-colors",
+        "hover:border-brand/40 hover:bg-interactive-hover-soft",
+      )}
+    >
+      <div className={cn("shrink-0", density === "tight" ? "w-14" : "w-20")}>{preview}</div>
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center gap-2 min-w-0">
+          <code className="font-mono text-xs text-foreground truncate tabular-nums">{name}</code>
+          {record.deprecated && (
+            <Badge variant="destructive" className="text-[10px] h-4 px-1.5 shrink-0">
+              deprecated
+            </Badge>
+          )}
+        </div>
+        <div className="mt-0.5 flex items-center gap-1.5 text-[11px] text-muted-foreground">
+          <span className="rounded-sm bg-muted/60 px-1.5 py-0.5">{record.namespace}</span>
+        </div>
+        <div className="mt-1 truncate font-mono text-[11px] text-muted-foreground" title={raw}>
+          {raw || "—"}
+        </div>
+      </div>
+      <Tip side="left" label={`Copy ${cssRef}`}>
+        <Button
+          type="button"
+          size="icon"
+          variant="ghost"
+          className="size-7 shrink-0 self-center opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+          onClick={() => onCopy(cssRef)}
+          aria-label={`Copy ${cssRef}`}
+        >
+          <i className="fa-light fa-copy text-sm" aria-hidden="true" />
+        </Button>
+      </Tip>
+    </div>
+  )
+}
+
+/* ── Category-specific previews ───────────────────────────────────────── */
+
+function ColorPreview({ name }: { name: string }) {
+  return (
+    <div
+      className="h-14 w-14 rounded-md border border-border"
+      style={{ backgroundColor: `var(${name})` }}
+      aria-hidden="true"
+    />
+  )
+}
+function GradientPreview({ name }: { name: string }) {
+  return (
+    <div
+      className="h-14 w-20 rounded-md border border-border"
+      style={{ background: `var(${name})` }}
+      aria-hidden="true"
+    />
+  )
+}
+function RadiusPreview({ name }: { name: string }) {
+  return (
+    <div
+      className="h-14 w-14 border border-border bg-muted/50"
+      style={{ borderRadius: `var(${name})` }}
+      aria-hidden="true"
+    />
+  )
+}
+function SizePreview({ name, record }: { name: string; record: TokenRecord }) {
+  const raw = primaryValueText(record)
+  return (
+    <div className="flex h-14 w-20 items-center justify-center" aria-hidden="true">
+      <div
+        className="w-full bg-brand rounded-sm"
+        style={{ height: `min(56px, var(${name}))` }}
+        title={raw}
+      />
+    </div>
+  )
+}
+function ShadowPreview({ name }: { name: string }) {
+  return (
+    <div
+      className="m-1 h-12 w-12 rounded-md bg-card"
+      style={{ boxShadow: `var(${name})` }}
+      aria-hidden="true"
+    />
+  )
+}
+function TypographyPreview({ name }: { name: string }) {
+  return (
+    <div
+      className="flex h-14 w-20 items-center justify-center rounded-md border border-border bg-muted/30"
+      style={{ fontFamily: `var(${name})` }}
+      aria-hidden="true"
+    >
+      <span className="text-2xl text-foreground">Aa</span>
+    </div>
+  )
+}
+function MotionPreview({ name }: { name: string }) {
+  return (
+    <div className="relative h-14 w-20 overflow-hidden rounded-md border border-border bg-muted/30" aria-hidden="true">
+      <div
+        className="absolute left-2 top-1/2 size-3 -translate-y-1/2 rounded-full bg-brand group-hover:translate-x-12"
+        style={{ transition: `var(${name})` }}
+      />
+    </div>
+  )
+}
+function AliasPreview({ record }: { record: TokenRecord }) {
+  const v = primaryValueText(record)
+  const targetMatch = v.match(/var\((--[a-z0-9-]+)\)/i)
+  const target = targetMatch?.[1]
+  return (
+    <div className="flex h-14 w-20 flex-col items-center justify-center rounded-md border border-border bg-muted/30 text-center" aria-hidden="true">
+      <i className="fa-light fa-link text-base text-muted-foreground" />
+      {target && (
+        <code className="mt-0.5 truncate max-w-full px-1 font-mono text-[9px] text-muted-foreground">{target}</code>
+      )}
+    </div>
+  )
+}
+function OtherPreview() {
+  return (
+    <div className="flex h-14 w-20 items-center justify-center rounded-md border border-dashed border-border text-muted-foreground" aria-hidden="true">
+      <i className="fa-light fa-hashtag text-base" />
+    </div>
+  )
+}
+
+/**
+ * Pick the right visualizer for a token. Used both by the legacy `TokensCategoryGrid`
+ * and by the DataTable Preview cell in `tokens-themes-client.tsx`.
+ */
+export function categoryPreview(name: string, record: TokenRecord): React.ReactNode {
+  switch (record.category) {
+    case "color":      return <ColorPreview name={name} />
+    case "gradient":   return <GradientPreview name={name} />
+    case "radius":     return <RadiusPreview name={name} />
+    case "size":       return <SizePreview name={name} record={record} />
+    case "shadow":     return <ShadowPreview name={name} />
+    case "typography": return <TypographyPreview name={name} />
+    case "transition": return <MotionPreview name={name} />
+    case "alias":      return <AliasPreview record={record} />
+    default:           return <OtherPreview />
+  }
+}
+
+/* ── Category grid (the page body for one view tab) ───────────────────── */
+
+export interface TokensCategoryGridProps {
+  query: string
+  showDeprecated: boolean
+  category: CategoryTabDef
+  onCopy: (text: string) => void
+}
+
+export function TokensCategoryGrid({ query, showDeprecated, category, onCopy }: TokensCategoryGridProps) {
+  const filtered = React.useMemo(() => {
+    const q = query.trim().toLowerCase()
+    const out: Array<[string, TokenRecord]> = []
+    for (const [name, record] of Object.entries(TOKENS_INDEX.tokens)) {
+      if (!category.matches(record.category)) continue
+      if (!showDeprecated && record.deprecated) continue
+      if (q && !(name.toLowerCase().includes(q) || record.namespace.toLowerCase().includes(q))) continue
+      out.push([name, record])
+    }
+    return out.sort(([a], [b]) => a.localeCompare(b))
+  }, [query, showDeprecated, category])
+
+  if (filtered.length === 0) {
+    return (
+      <div className="rounded-md border border-dashed border-border bg-muted/20 p-8 text-center text-sm text-muted-foreground">
+        No {category.label.toLowerCase()} tokens match your filter.
+      </div>
+    )
+  }
+
+  /** Colors are dense (100+ tokens) → 3-column on wide. Other categories 1–2 col. */
+  const isDense = category.id === "color"
+  return (
+    <div
+      className={cn(
+        "grid gap-2",
+        isDense
+          ? "grid-cols-1 md:grid-cols-2 xl:grid-cols-3"
+          : "grid-cols-1 md:grid-cols-2",
+      )}
+    >
+      {filtered.map(([name, record]) => (
+        <TokenTile
+          key={name}
+          name={name}
+          record={record}
+          onCopy={onCopy}
+          density={isDense ? "tight" : "wide"}
+          preview={categoryPreview(name, record)}
+        />
+      ))}
+    </div>
+  )
+}

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

@@ -62,7 +62,7 @@ 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`, `QuestionBankPageHeader` |
+| [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` |

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

@@ -85,7 +85,7 @@ a bespoke `<button>` + border-class wrapper for the same pattern.
 | Variant | When to use | Differences from default |
 |---|---|---|
 | `base` | Most hubs | Title + status badge + body |
-| `no-status` | Hubs without lifecycle (Question bank items) | Omit `badgeRow`; body carries the differentiator |
+| `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 |
 

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

@@ -106,7 +106,7 @@ dashboard, folder, panel — reads from.
 
 | Framework | Component(s) | File |
 |---|---|---|
-| **React (this app)** | `DataTable`, `DataTablePaginated`, `useTableState`, `DataTableToolbar`, `TablePropertiesDrawer`, column-cell helpers in `placements-table-cells.tsx` | [`apps/web/components/data-table/`](../../components/data-table/), [`apps/web/components/placements-table-cells.tsx`](../../components/placements-table-cells.tsx), `@/components/table-properties` |
+| **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 | — | — |
 
@@ -115,7 +115,7 @@ Reference compositions:
 - **Placements** — `PlacementsClient` + `PlacementsTable` (most complete reference)
 - **Team** — `TeamClient` + `TeamTable`
 - **Compliance** — `ComplianceClient` + `ComplianceTable`
-- **Question bank** — `QuestionBankClient` + `QuestionBankTable` (adds folder
+- **Library** — `LibraryClient` + `LibraryTable` (adds folder
   scope from URL)
 
 ## 8. Do / Don't

package/template/docs/blueprints/list-page-template.md

@@ -5,7 +5,7 @@
 ## 1. Intent
 
 A **list page** is the canonical hub surface for browsing a homogeneous
-collection of records (Placements, Team, Compliance, Question bank items, …).
+collection of records (Placements, Team, Compliance, Library items, …).
 It pairs a single `DataTable` with view-tab variants (table · list · board ·
 dashboard · folder · panel · tree), one shared filter / sort / column model,
 and a metric strip that consumes the same filtered row bag.
@@ -93,9 +93,9 @@ The view body is rendered by `HubTable` (or a custom non-table view) and
 | Variant | When to use | Differences from default |
 |---|---|---|
 | `base` | Most hubs | Header + metrics + tabs + view body |
-| `no-metrics` | Hubs where KPI summary adds noise (e.g. Question bank: too many heterogeneous folders) | Omit `metrics` prop |
+| `no-metrics` | Hubs where KPI summary adds noise (e.g. Library: too many heterogeneous folders) | Omit `metrics` prop |
 | `with-banner` | Pages that need a promo or alert above the header | Use `beforeSiteHeader` slot |
-| `secondary-panel-hub` | Hubs scoped by a sidebar panel (Question bank) | Wrap in `SecondaryPanelHubTemplate`; same `useTableState` |
+| `secondary-panel-hub` | Hubs scoped by a sidebar panel (Library) | Wrap in `SecondaryPanelHubTemplate`; same `useTableState` |
 
 ## 7. Implementation