@exxatdesignux/ui 0.2.19 → 0.4.0

package/consumer-extras/cursor-skills/exxat-primary-nav-secondary-panel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exxat-primary-nav-secondary-panel
-description: Exxat DS pattern — one primary sidebar row opens a nested SecondaryPanel (Question bank). NavLinkItem.secondaryPanel id, PANELS registry, useAutoPanel on hub, URL scope + same useTableState rows. Use when adding hub scoped nav (All/My/tree) beside content.
+description: Exxat DS pattern — one primary sidebar row opens a nested SecondaryPanel (Library). NavLinkItem.secondaryPanel id, PANELS registry, useAutoPanel on hub, URL scope + same useTableState rows. Use when adding hub scoped nav (All/My/tree) beside content.
 user-invocable: true
 ---
 
@@ -12,11 +12,11 @@ user-invocable: true
 ## Wiring checklist
 
 1. **`lib/mock/navigation.tsx`** — set **`secondaryPanel: "<id>"`** on the primary **`NavLinkItem`**; **`url`** = hub route.
-2. **`components/secondary-panels/registry.tsx`** — add **`SECONDARY_PANELS["<id>"]`** → panel shell (title) + hub-specific nav component (e.g. **`list-hub-panel.tsx`**, **`question-bank-panel.tsx`**). Do not add new hubs inside **`question-bank-*.tsx`**.
-3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `QuestionBankPanelActivator`).
-4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/question-bank-nav.ts`**).
-5. **Folder-scoped hub header (Question bank library)** — When **`scope === "folder"`** in the URL, **`QuestionBankPageHeader`** **⋯ More** includes **Customize folder**; mount **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** so it works on **all** **`ListPageTemplate`** view tabs — **`.cursor/rules/exxat-question-bank-hub-header.mdc`**, **`docs/question-bank-hub-header-pattern.md`**.
-6. **Collapse control** — the nested rail header uses **`collapseActiveSecondaryPanel()`** (angles-left icon), not “close”, so the panel stays dismissed until **`openPanel`** runs again (nav, scope hook, or hub re-entry). Layout effects that auto-call **`openPanel`** must respect **`secondaryPanelAutoReopenSuppressed`** (see **`app/(app)/question-bank/layout.tsx`** + **`SecondaryPanelProvider`**).
+2. **`components/secondary-panel.tsx`** — add **`PANELS["<id>"]`** → panel shell (title, optional search) + secondary nav component.
+3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `LibraryPanelActivator`).
+4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/library-nav.ts`**).
+5. **Folder-scoped hub header (Library library)** — When **`scope === "folder"`** in the URL, **`LibraryPageHeader`** **⋯ More** includes **Customize folder**; mount **`LibraryNewFolderSheet`** on **`LibraryClient`** so it works on **all** **`ListPageTemplate`** view tabs — **`.cursor/rules/exxat-library-hub-header.mdc`**, **`docs/library-hub-header-pattern.md`**.
+6. **Collapse control** — the nested rail header uses **`collapseActiveSecondaryPanel()`** (angles-left icon), not “close”, so the panel stays dismissed until **`openPanel`** runs again (nav, scope hook, or hub re-entry). Layout effects that auto-call **`openPanel`** must respect **`secondaryPanelAutoReopenSuppressed`** (see **`app/(app)/library/layout.tsx`** + **`SecondaryPanelProvider`**).
 7. **Surface elevation** — secondary panel = **level 1** (lighter than sidebar, darker than page). Use **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`**; derive from **`--brand-tint*`** per active product (**One** indigo, **Prism** rose). See **`docs/shell-surface-elevation-pattern.md`**.
 
 ## MUST NOT
@@ -30,7 +30,7 @@ user-invocable: true
 
 `SecondaryPanelProvider` reads **`useSidebarReflowZoom()`** (zoom ≥ 200% or very short viewport — same WCAG 1.4.10 signal the primary sidebar uses). On entering high zoom it sets `secondaryPanelCompact = true` so the 16 rem rail drops to the 3 rem icon variant and frees up content space. The user can still re-expand manually (via the icon rail's "Show labels" affordance or any `openPanel` trigger); the next zoom-out → zoom-in cycle re-collapses it. `openPanel` itself opens directly in compact mode when high zoom is already active so newly-navigated panels don't flash expanded.
 
-Custom panel content (anything you register under `PANELS[id]`) should **read `secondaryPanelCompact` from the provider context** and render an icon-only layout in that branch — `QuestionBankPanel` / `QuestionBankSecondaryNav` are the reference.
+Custom panel content (anything you register under `PANELS[id]`) should **read `secondaryPanelCompact` from the provider context** and render an icon-only layout in that branch — `LibraryPanel` / `LibrarySecondaryNav` are the reference.
 
 ## Pair with
 
@@ -39,13 +39,11 @@ Custom panel content (anything you register under `PANELS[id]`) should **read `s
 ## Reference
 
 - `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
-- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, **high-zoom auto-collapse**.
-- `components/secondary-panels/registry.tsx` — **`SECONDARY_PANELS`** map (`question-bank`, `list-hub`, …).
-- `lib/list-hub-nav.ts` + `components/list-hub-secondary-nav.tsx` — second hub reference implementation.
+- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, `PANELS` registry, **high-zoom auto-collapse**.
 - `hooks/use-sidebar-reflow-zoom.ts` — shared zoom / reflow signal.
 - `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths; **`bg-[var(--secondary-panel-bg)]`**.
 - `app/globals.css` — `--secondary-panel-bg`, `--sidebar`, product **`theme-one`** / **`theme-prism`** blocks.
 - `contexts/product-context.tsx` — `accentOverrideActive`, theme class on `<html>`.
 - **`docs/shell-surface-elevation-pattern.md`**
-- `components/question-bank-secondary-nav.tsx` + `lib/question-bank-nav.ts`.
-- **Folder-scoped header customize:** `components/question-bank-page-header.tsx`, `components/question-bank-client.tsx` — **`docs/question-bank-hub-header-pattern.md`**, **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+- `components/library-secondary-nav.tsx` + `lib/library-nav.ts`.
+- **Folder-scoped header customize:** `components/library-page-header.tsx`, `components/library-client.tsx` — **`docs/library-hub-header-pattern.md`**, **`.cursor/rules/exxat-library-hub-header.mdc`**.

package/consumer-extras/cursor-skills/exxat-token-economy/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: exxat-token-economy
+description: >-
+  Cut AI token usage by ~50% on Exxat DS work — task → minimum-file-set table,
+  five-question pre-flight that catches the top rule violations before
+  generation, canonical primitive aliases (no grep needed), tiny scaffolds
+  for hub client / column def / KPI item, and a deny-list of files the
+  assistant should NOT open. Read this BEFORE opening any other DS doc.
+user-invocable: true
+---
+
+# Exxat DS — token economy (read this first)
+
+**Why this exists.** Every other DS skill / rule / pattern doc is a deep dive on
+one concern. When the user just wants to build a screen, the assistant tends to:
+
+1. Re-read `AGENTS.md` (~80 KB) on every turn.
+2. `grep` to "find the Button" when the import path is already known.
+3. Regenerate hub scaffolding it could copy from a reference page.
+4. Read 6 rule files speculatively when only 2 apply.
+5. Re-explain "we use HubTable because…" in 200 tokens.
+
+This skill is the **pre-flight** for any DS work. Read it first; load other docs
+only when this skill explicitly points to one. **Target: ≥ 50% fewer input
+tokens per design turn vs. the naive "open AGENTS.md and grep" loop.**
+
+## When to use this skill
+
+- **First** turn of any new DS feature, hub, or design change.
+- Any time the assistant is about to open `AGENTS.md` or a `*-pattern.md` doc — read this skill instead and follow §1's file-set table.
+- Whenever the user complains about cost, latency, or "you keep re-reading the same files".
+
+---
+
+## §1 — Task → minimum file set
+
+Open **only** these files. Skip everything else unless one of these files cites it.
+
+| Task | Read (minimum) | Skip (do not open) |
+|------|----------------|--------------------|
+| **Build a new hub page** (table + KPIs + view tabs) | `apps/web/components/columns-showcase.tsx` (or any reference hub), `docs/exxat-ds/handbook/HANDBOOK.md` §"How to build a hub" | `AGENTS.md`, `hub-table.tsx` source, all `*-pattern.md` |
+| **Add a column / cell pattern** | `apps/web/components/columns-showcase.tsx` (the live catalog) | `data-table/index.tsx`, the whole `types.ts` |
+| **Add a board / kanban view** | `apps/web/components/placements-board-card.tsx`, `exxat-board-cards.mdc` only | All other rules |
+| **Add a KPI strip** | `docs/exxat-ds/handbook/reference-implementations.md` § KPI flat band, `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` | `key-metrics.tsx` source |
+| **Write empty-state / error / button copy** | `docs/exxat-ds/handbook/voice-and-tone.md` | All rules |
+| **Theme / token tweak** | `apps/web/app/globals.css`, `packages/ui/tokens/hooks-index.json` | All pattern docs |
+| **Status chip color/icon** | `apps/web/lib/list-status-badges.ts` | Accessibility rule (already covered by the map) |
+| **Bug fix** | `rg` for the symbol, read only the matching file | Everything else |
+| **Architectural change** (only when the user explicitly says so) | `AGENTS.md`, `HANDBOOK.md` | — |
+
+**Heuristic.** If a file is over 25 KB and you're not modifying that exact file,
+don't read it. Use this skill body + the reference page in `columns-showcase.tsx`
+instead.
+
+---
+
+## §2 — Five-question pre-flight (before you generate code)
+
+Answer **yes / no / N/A** to each. A **no** means re-plan; you'll save a regeneration cycle.
+
+1. **`HubTable`, not raw `<table>`?** — every hub-style grid in `ListPageTemplate.renderContent` uses `HubTable<TRow>` from `@/components/data-views`. Filters + Properties drawer + view-type tiles + bulk actions come free.
+2. **`view` + `onViewChange` plumbed?** — if the page has view tabs, pass both through `client → table → drawer toolbar → TablePropertiesDrawer`. Otherwise the drawer ships table-only copy on a Board tab.
+3. **Color + icon on every status chip?** — `ListHubStatusBadge` + a tint from `lib/list-status-badges.ts` + an FA icon. Color alone fails WCAG 1.4.1.
+4. **≤ 4 KPIs on the primary strip?** — `KEY_METRICS_KPI_COUNT_MAX = 4`. A fifth becomes a `MetricInsight` or a chart.
+5. **No toasts for product feedback?** — use `LocalBanner` / `SystemBanner` / inline status. Toasts are reserved for build-tool messages.
+
+If all five are **yes**, generate. If any is **no**, either narrow the requirements
+with **one** clarifying question or fix the gap silently and note it in your response.
+
+---
+
+## §3 — Canonical primitive aliases (no grep needed)
+
+When the user says "X", reach for "Y". Save the search.
+
+### Page chrome & overlays
+
+| User says | Use | Path |
+|----------|-----|------|
+| button, action, CTA | `Button` | `@/components/ui/button` |
+| input, text field, form field | `Input`, `FormField` | `@/components/ui/{input,form}` |
+| avatar | `AvatarInitials` | `@/components/ui/avatar` |
+| chip, badge, status, tag | `Badge`, `ListHubStatusBadge`, `StatusBadge` | `@/components/{ui/badge,list-hub-status-badge}` |
+| dropdown, menu, ⋯ | `DropdownMenu` family | `@/components/ui/dropdown-menu` |
+| tooltip, hint | `Tip` (or `Tooltip`) | `@/components/ui/tip` |
+| sheet, drawer | `Sheet` family, `ExportDrawer`, `TablePropertiesDrawer` | `@/components/ui/sheet` |
+| dialog, modal, confirm | `Dialog` family | `@/components/ui/dialog` |
+| table, list, grid (product data) | `HubTable` inside `ListPageTemplate` | `@/components/data-views` |
+| KPI, metric, stat | `KeyMetrics` + `MetricItem` | `@/components/key-metrics` |
+| board, kanban | `ListPageBoardCard`, `ListPageBoardTemplate` | `@/components/data-views/list-page-board-card` |
+| icon | FA `<i class="fa-light fa-{name}" aria-hidden />` | (Kit script in `app/layout.tsx`) |
+| keyboard shortcut hint | `Kbd variant="bare"` inside buttons; `tile` in tooltips | `@/components/ui/kbd` |
+| toggle, switch | `ToggleSwitch` | `@/components/ui/toggle-switch` |
+
+### Table cell renderers (ALL importable — do NOT re-implement)
+
+Every cell renderer below is exported from **`@/components/data-views`** (re-exported from `apps/web/components/data-views/table-cells.tsx`). Live catalog: `apps/web/components/columns-showcase.tsx` at route `/columns`.
+
+| User says | Use | Notes |
+|----------|-----|-------|
+| progress bar, % complete, weeks done | `ProgressCell` | `value`, `max?`, `tone?: "auto" \| "success" \| "warning" \| "danger" \| "info"`, `label?` |
+| currency, money, price, cost | `CurrencyCell` | `value`, `currency?` (default USD), `locale?`, right-aligned `tabular-nums` |
+| numeric count, attempts, downloads | `NumericCell` | `value`, `fractionDigits?`, right-aligned |
+| rating, stars, score | `RatingCell` | `value`, `max?` (5), `showValue?` — color **and** glyph (WCAG 1.4.1) |
+| signal bars, low/med/high, difficulty | `SignalBarsCell` | `level`, `max?` (3), `tone?`, `label` (required, accessible) |
+| toggle, published/draft, enabled/disabled | `BooleanToggleCell` | `checked`, `onChange(next)`, `labelOn?`, `labelOff?`; stops row click propagation |
+| attachments, files count, paperclip | `AttachmentCountCell` | `count` — muted dash on `0` |
+| external link, source, view in new tab | `ExternalLinkCell` | `url`, `label?` — host extracted; `Tip` shows full URL |
+| relative time, "3 hours ago", recency | `RelativeTimeCell` | `iso`, `now?` (override for deterministic snapshots) |
+| face rail, reviewers, assignees +N | `PeopleAvatarRailCell` | `people: PersonStub[]`, `visibleMax?` (3), `size?: "sm" \| "md"`; **non-overlapping** avatars |
+| type pill, category, kind with icon | `PillCell` | `label`, `icon?: "fa-..."` — outlined, single-line |
+| tag list +N, keywords, labels | `TagListCell` | `tags: string[]`, `visibleMax?` (2), `formatLabel?` (default `#${tag}`) |
+| row actions, ⋯, overflow menu | `RowActionsCell<TRow>` | `row`, `actions: RowActionDef<TRow>[]` (`label`, `icon`, `onSelect`, `variant?`, `shortcut?`, `disabled?`) |
+
+### Out of band — only when none of the above fits
+
+If the user asks for **anything outside this list**: first scan `columns-showcase.tsx`
++ the `reference-implementations.md` index — both name every existing primitive.
+Only propose a new shared component if neither covers it AND the user has approved
+bespoke work (`exxat-reuse-before-custom.mdc`).
+
+**Hard rule.** Do NOT inline-implement a progress bar, currency formatter, rating,
+relative-time, attachment chip, external link, face rail, type pill, tag list, or
+row-actions menu inside a `ColumnDef['cell']`. Import the named cell. If you find
+yourself writing `Intl.NumberFormat`, `<a target="_blank">`, or a `[1,2,3,4,5].map(…)` star
+loop inside a `cell:`, stop — you're re-deriving a shipped primitive.
+
+---
+
+## §4 — Tiny scaffolds (copy verbatim, don't re-derive)
+
+The boilerplate shapes you'd otherwise regenerate.
+
+### Hub client (replace `Entity`, KPIs, columns)
+
+```tsx
+"use client"
+import * as React from "react"
+import { PrimaryPageTemplate } from "@/components/templates/primary-page-template"
+import { PageHeader } from "@/components/page-header"
+import { KeyMetrics, type MetricItem } from "@/components/key-metrics"
+import { ListPageTemplate, type ViewTab, HubTable } from "@/components/data-views"
+
+const ENTITY_TABS: ViewTab[] = [{ id: "all", label: "All", viewType: "table", icon: "fa-table", filterId: "all" }]
+const ENTITY_SUPPORTED_VIEWS = ["table", "list", "board"] as const
+
+export function EntityClient({ rows }) {
+  const [tabs, setTabs] = React.useState<ViewTab[]>(ENTITY_TABS)
+  const [activeTabId, setActiveTabId] = React.useState(ENTITY_TABS[0].id)
+  return (
+    <PrimaryPageTemplate siteHeader={{ title: "Entity" }}>
+      <ListPageTemplate
+        defaultTabs={ENTITY_TABS} tabs={tabs} onTabsChange={setTabs}
+        activeTabId={activeTabId} onActiveTabChange={setActiveTabId}
+        supportedViewTypes={ENTITY_SUPPORTED_VIEWS}
+        getTabCount={() => rows.length}
+        header={<PageHeader title="Entity" subtitle="…" />}
+        metrics={<KeyMetrics variant="flat" metrics={ENTITY_KPIS} showHeader={false} metricsSingleRow />}
+        renderContent={(tab, updateTab) => (
+          <HubTable rows={rows} columns={useColumns()}
+            view={tab.viewType} onViewChange={v => updateTab({ viewType: v })}
+            supportedViewTypes={ENTITY_SUPPORTED_VIEWS}
+            hubLabel="Entity" lifecycleTabLabel="Entity"
+            getRowId={r => r.id} getRowSelectionLabel={r => r.name}
+            defaultSort={{ key: "name", dir: "asc" }}
+            renderers={{}}
+          />
+        )}
+      />
+    </PrimaryPageTemplate>
+  )
+}
+```
+
+### `MetricItem` shape (KPI strip cell)
+
+```ts
+{ id: "active", label: "Active", value: 142, delta: "+8 vs last week",
+  trend: "up", trendPolarity: "higher_is_better",
+  metricVariant: "hero", description: "currently in placement" }
+```
+
+- `trend: "neutral"` + empty `delta` → no trend chip renders. Don't fake a `+0`.
+- `trendPolarity: "lower_is_better"` for error counts, defects, overdue.
+- `metricVariant: "hero"` for **one** cell per strip — the headline number.
+- Max **4 cells**.
+
+### `ColumnDef<TRow>` shape
+
+```ts
+{ key: "name", label: "Name", width: 240, minWidth: 180,
+  defaultPin: "left", sortable: true, sortKey: "name",
+  filter: { type: "text", icon: "fa-user", operators: ["contains"] },
+  cell: row => <span className="truncate">{row.name}</span> }
+```
+
+- `key: "select"` + `defaultPin: "left"` + `lockPin: true` → checkbox column.
+- `key: "actions"` + `defaultPin: "right"` + `lockPin: true` → ⋯ overflow column.
+- `filter: { type: "select", options }` for categorical columns.
+
+### Default `cell:` should call a named primitive
+
+The right `cell:` body for the common patterns is **one import + one component**, not an inline JSX block:
+
+```ts
+import { ProgressCell, CurrencyCell, RatingCell, BooleanToggleCell,
+         RelativeTimeCell, AttachmentCountCell, ExternalLinkCell,
+         PeopleAvatarRailCell, PillCell, TagListCell, NumericCell,
+         RowActionsCell, type RowActionDef } from "@/components/data-views"
+
+// Examples — cell:'s body is one call.
+cell: row => <ProgressCell value={row.completion} />
+cell: row => <CurrencyCell value={row.cost} />
+cell: row => <RatingCell value={row.rating} />
+cell: row => <BooleanToggleCell checked={row.published} onChange={next => onTogglePublished(row, next)} />
+cell: row => <RelativeTimeCell iso={row.lastActivityAt} />
+cell: row => <AttachmentCountCell count={row.attachmentCount} />
+cell: row => <ExternalLinkCell url={row.sourceUrl} />
+cell: row => <PeopleAvatarRailCell people={row.reviewers} />
+cell: row => <PillCell label={TYPE_LABEL[row.type]} icon={TYPE_ICON[row.type]} />
+cell: row => <TagListCell tags={row.tags} />
+cell: row => <NumericCell value={row.attempts} />
+cell: row => <RowActionsCell row={row} actions={ROW_ACTIONS} />
+```
+
+If `cell:` exceeds **one line** for any pattern above, you're re-deriving — go back and import.
+
+---
+
+## §5 — Deny list (do NOT open unless asked)
+
+Treat these as expensive — skip unless the user explicitly names them or this skill points to them:
+
+- `AGENTS.md` — only when the task is "change the architecture or the rules themselves".
+- `packages/ui/src/components/data-views/hub-table.tsx` — the API is documented; don't read the implementation.
+- `apps/web/.next/`, `.turbo/`, `node_modules/` — never.
+- All 29 `.cursor/rules/exxat-*.mdc` at once — §1 already points to the 1-2 that apply.
+- Test files (`*.test.*`, `__tests__/`) — irrelevant for design.
+- Build configs (`tsup.config.ts`, `next.config.ts`, `turbo.json`) — irrelevant for design.
+- `packages/ui/tokens/hooks-index.json` (~163 KB) — only when the task is a token rename / audit.
+
+---
+
+## §6 — When to ask vs. when to assume
+
+One clarifying question costs ~50 tokens. A wrong implementation costs hundreds (read, generate, user feedback, regenerate). Ask when:
+
+1. The task name is ambiguous between two patterns (e.g. "add a panel" → drawer or split panel?).
+2. Two existing reference hubs handle the same concern differently (use the user's existing precedent if they have one).
+3. The user mentions a screen that doesn't have a clear primitive in §3.
+
+Don't ask when:
+
+- The user has cited a specific file or component — go.
+- The pre-flight (§2) all answers yes — go.
+- The task fits exactly one row in §1's task map — go.
+
+---
+
+## §7 — Output discipline (your turn budget)
+
+Your **response** also costs tokens. Keep it lean:
+
+- **No "let me explain the design system" preambles.** The user has the package installed; they know.
+- **No reading-aloud of file paths.** Cite with `code` ticks; don't re-narrate.
+- **No restating the prompt.** Jump straight to the action.
+- **Group tool calls in parallel** when independent (reading 3 files = 1 message, not 3).
+- **Stop generating** as soon as the pre-flight (§2) says you have what you need. Don't gold-plate.
+
+---
+
+## See also
+
+- **Handbook** — `docs/exxat-ds/handbook/HANDBOOK.md` (5 principles + how-to-build-a-hub)
+- **Reference implementations** — `docs/exxat-ds/handbook/reference-implementations.md` (find the file to copy)
+- **Voice & tone** — `docs/exxat-ds/handbook/voice-and-tone.md` (user-facing copy)
+- **Cell patterns catalog** — `apps/web/components/columns-showcase.tsx` (live at `/columns`)

package/consumer-extras/handbook/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 (placements, sites, columns, 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 page to copy:** `apps/web/components/sites-table.tsx` (the smallest complete hub) or `apps/web/components/columns-showcase.tsx` (single-view hub with a `HubTable`).
+
+> **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`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/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/`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/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`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/token-taxonomy.md) |
+| Full authoritative handbook | [`apps/web/AGENTS.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/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`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/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](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/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`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/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/consumer-extras/handbook/glossary.md

@@ -0,0 +1,58 @@
+# Exxat DS — Glossary
+
+> Shared vocabulary. When a rule or pattern uses a term in **bold**, it's defined here. Add a term when you find yourself explaining the same word twice in PR review.
+
+| Term | Definition | See also |
+|---|---|---|
+| **Active view** | The currently selected view tab on a hub (table, list, board, dashboard, …). Drives which `HubTableRenderers` entry mounts and what the **Properties drawer** shows in its view-type tile grid. | `exxat-table-properties-drawer.mdc` |
+| **Bare Kbd** | The `<Kbd variant="bare">` rendering — no background, no border, inherits `currentColor` at 70 %. Used inline **inside** a button so the chord doesn't look pasted on. The default `tile` variant is reserved for tooltips and menu shortcut slots. | `exxat-kbd-shortcuts.mdc` |
+| **Blueprint** | Framework-agnostic spec for one UI pattern. Says *what* the pattern is and *what* it must do without committing to React. See `docs/blueprints/`. | `docs/blueprints/README.md` |
+| **Board card** | The kanban-style card surface on a board view. Composed of `ListPageBoardCard` (shell), `ListPageBoardCardTitleRow`, optional `ListPageBoardCardAvatar`, optional badge row with `ListHubStatusBadge` (`surface="board"`), and a body using `BoardCardTwoLineBlock` / `BoardCardIconRow`. | `exxat-board-cards.mdc` |
+| **Brand glow** | The OKLCH-mixed brand tint applied as a soft halo behind a surface (KPI flat band, secondary panel). Not a hard background — the tint **adds**, the underlying surface still reads. | `docs/kpi-flat-band-pattern.md`, `docs/shell-surface-elevation-pattern.md` |
+| **Bulk-actions slot** | The floating action bar that appears when one or more rows are selected in a `HubTable`. Wired via `bulkActionsSlot={(selected) => …}`. | `packages/ui/src/components/data-views/hub-table.tsx` |
+| **Cell pattern** | One column's rendering recipe — built by composing existing primitives (`Badge`, `AvatarInitials`, `ListHubStatusBadge`, `ToggleSwitch`, FA glyphs, `Tip`, `Tooltip`, `DropdownMenu`). The canonical catalog of patterns lives in `apps/web/components/columns-showcase.tsx`; the live demo is at `/columns`. | `docs/reference-implementations.md` |
+| **Cell primitive** | One of the named, importable `ColumnDef['cell']` renderers exported from `@/components/data-views` (re-exported from `apps/web/components/data-views/table-cells.tsx`): `ProgressCell`, `CurrencyCell`, `NumericCell`, `RatingCell`, `SignalBarsCell`, `BooleanToggleCell`, `AttachmentCountCell`, `ExternalLinkCell`, `RelativeTimeCell`, `PeopleAvatarRailCell`, `PillCell`, `TagListCell`, `RowActionsCell`. Every cell renderer in the showcase comes from this module; new hubs **must** import these instead of inlining the same JSX. | `.cursor/skills/exxat-token-economy/SKILL.md` §3, `exxat-data-tables.mdc` |
+| **Centralized list dataset** | The rule that **one** `useTableState` row bag drives **every** view (table, list, board, dashboard, panel, tree, …) on a given hub. No parallel mock arrays per view. | `exxat-centralized-list-dataset.mdc` |
+| **Coach mark** | The onboarding overlay that highlights a UI element and explains it. State managed by `useCoachMark`. Dismissals stick per flow id. | `apps/web/lib/coach-mark-registry.ts` |
+| **Collaboration variant** | The `PageHeader` flavor that exposes the face rail + Invite-people overflow item for shared hubs. | `exxat-collaboration-access.mdc` |
+| **Column def (`ColumnDef`)** | The typed column shape consumed by `DataTable` / `HubTable`. Adding `filter:` to a column auto-generates a filter chip and toolbar dropdown entry. | `packages/ui/src/components/data-table/types.ts` |
+| **Conditional rule** | A `ColumnDef`-level rule that applies a background tint to a cell when its value matches an operator + value (e.g. "score < 60 → red"). Authored in the **Properties drawer**. | `packages/ui/src/components/table-properties/` |
+| **Content rail** | The centered, max-width column the `PrimaryPageTemplate` reserves for primary content. Width comes from the template, not the page; don't override per-page. | `apps/web/components/templates/primary-page-template.tsx` |
+| **DataTable** | The low-level table primitive in `packages/ui`. Mount this **only** outside a hub (drawer-body mini-grids, modal sub-tables). Inside `ListPageTemplate`, use `HubTable`. | `exxat-data-tables.mdc` |
+| **`delta`** | The KPI **count** of change (e.g. `"+5"`, `-3`, `"+12 %"`) on a `MetricItem`. Pass `""` or `0` to suppress the trend chip. Never prose. | `exxat-kpi-trends.mdc` |
+| **`description`** | The KPI **caption** beneath the value and trend row on a `MetricItem`. Use this for prose like `"left + right"` or `"vs last week"`. Never a delta count. | `exxat-kpi-trends.mdc` |
+| **Display options** | Per-table preferences (toolbar search visibility, density, gridlines, pagination toggle, …) that flow through `DataListDisplayOptions`. `HubTable` owns the state by default; the hub client can take it over with `displayOptions` + `onDisplayOptionsChange`. | `packages/ui/src/components/table-properties/` |
+| **Empty state** | The text + icon + (optional) action shown when a view body has zero rows after filters. Distinct from "no data ever" (use `EmptyTableState`) vs "no matches" (filter-aware copy). | `docs/voice-and-tone.md` |
+| **Face rail** | The small overlapping-faces row on a `PageHeader` (collaboration variant) showing collaborators. Click to open the invite drawer. | `exxat-collaboration-access.mdc` |
+| **Filter chip** | The dismissible chip rendered above a `HubTable` body for each active filter. Auto-generated from `ColumnDef.filter`. | `exxat-data-tables.mdc` |
+| **Flat band (KPI)** | `KeyMetrics variant="flat"` — transparent cell, brand glow only, hairline cell borders. The shape used on every primary hub metrics strip. | `exxat-kpi-flat-band.mdc` |
+| **Hairline** | A 1 px border at exactly `--border` color used to separate KPI cells, table cells, surface divisions. Never thicker for hierarchy — use spacing or color instead. | `docs/kpi-flat-band-pattern.md` |
+| **HubTable** | The canonical hub view body. Wraps `useTableState`, the toolbar (search + filter chips + filter dropdown + sort), `TablePropertiesDrawerButton`, view-type tiles, bulk-actions, and conditional rules. Always use this inside `ListPageTemplate.renderContent`. | `exxat-data-tables.mdc` |
+| **Hub primitive** | Synonym for `HubTable` — the single primitive that produces a "hub-shaped" view body. | same |
+| **Inspector** | A side-anchored drawer that shows a single record's details without leaving the hub. Resolved against the same `tableState.rows` as the grid. | `exxat-centralized-list-dataset.mdc` |
+| **`KeyMetrics`** | The KPI strip / band component. Accepts `MetricItem[]` (≤ 4) and a single `MetricInsight`. Use `variant="flat"` on hubs; `variant="card"` for embedded analytics cards. | `exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc` |
+| **KPI strip** | The horizontal KPI row at the top of a hub. ≤ 4 tiles. | `exxat-kpi-max-four.mdc` |
+| **Lifecycle tab label** | The string shown under "Properties" in the drawer header (e.g. "Placements", "Team"). Set on `HubTable.lifecycleTabLabel`. | `packages/ui/src/components/table-properties/drawer-button.tsx` |
+| **List hub status badge** | The shared status chip + icon used everywhere status appears (table rows, board cards, list rows). Colors and icons live in `lib/list-status-badges.ts`. `surface="table"` for grid; `surface="board"` for cards. | `exxat-board-cards.mdc` |
+| **List page template** | The hub frame component. Owns the page header slot, metrics strip slot, view-tabs row, and the `renderContent(tab, updateTab)` body callback. | `packages/ui/src/components/templates/list-page.tsx` |
+| **Mono ID** | A system-generated identifier shown in `font-mono tabular-nums` so digits align and the ID is visibly distinct from prose. Mono **only** the ID token in a mixed line. | `exxat-mono-ids.mdc` |
+| **OKLCH** | The perceptually uniform color space used by the brand-tint mix and the glow tokens. Surfaces stack: page → secondary panel → sidebar. | `docs/shell-surface-elevation-pattern.md` |
+| **Pattern** | Long-form narrative that explains a UI behavior in prose: when to use it, how it composes, anti-patterns, references. Lives in `docs/*-pattern.md`. Complements (but doesn't replace) a blueprint or rule. | `docs/HANDBOOK.md` |
+| **`PrimaryPageTemplate`** | The page chrome: breadcrumbs, site header, content rail with the project's standard max-width. Wrap every primary route in this. | `apps/web/components/templates/primary-page-template.tsx` |
+| **Progressive disclosure** | The principle that complexity is exposed only when the user opts into it. KPIs default visible, filters default folded into the toolbar, conditional rules live in the Properties drawer, etc. | `docs/HANDBOOK.md` §1 |
+| **Properties drawer** | The right-side `Sheet` opened from the table toolbar, hosting view-type tiles, column visibility, density, sort, group-by, filters, conditional rules, and pagination toggle. Mounted automatically by `HubTable`. | `exxat-table-properties-drawer.mdc` |
+| **Reference page** | A canonical full implementation of a hub or pattern in `apps/web/components/<entity>-*.tsx`. Listed in `docs/reference-implementations.md`. Copy from these before inventing. | `docs/reference-implementations.md` |
+| **Rule (binding)** | A `.cursor/rules/*.mdc` doc with MUST / MUST NOT. Binds the AI agent and the human reviewer. Wins over patterns and narratives. | `docs/HANDBOOK.md` §4 |
+| **Secondary panel** | A scoped navigation rail (e.g. "Library → All / Mine / Tree", "Tokens & themes → Colors / Radius / Motion / …") that sits between the main sidebar and the page. Opening one collapses the main sidebar; closing one restores the previous sidebar state. | `exxat-primary-nav-secondary-panel.mdc` |
+| **Site header** | The top bar on a primary route (org/product switcher + breadcrumbs + actions). Owned by `PrimaryPageTemplate`. | `apps/web/components/templates/primary-page-template.tsx` |
+| **Skill** | A `.cursor/skills/<name>/SKILL.md` (mirrored in `.claude/skills/`) workflow + checklist for a recurring agent task. Use a skill when the same checklist would be repeated across many sessions. | `apps/web/AGENTS.md` |
+| **`supportedViewTypes`** | The allowlist of `DataListViewType` values a hub implements. Passed to `HubTable.supportedViewTypes` so the Properties drawer never offers a view the hub can't render. | `packages/ui/src/components/data-views/hub-table.tsx` |
+| **Trend polarity** | `MetricItem.trendPolarity` says whether "up" is good (`higher_is_better`, default), bad (`lower_is_better`), or value-neutral (`informational`). The arrow's tint follows the polarity, not the sign. | `exxat-kpi-trends.mdc` |
+| **`useTableState`** | The state hook that owns rows, filters, search, sort, pagination, group-by, and column visibility. Always one instance per hub. | `exxat-centralized-list-dataset.mdc` |
+| **View tab** | A tab on `ListPageTemplate` representing one view of the same dataset (table, list, board, dashboard, folder, panel, tree, …). Each tab carries a `viewType` and the `renderContent` callback receives it. | `exxat-list-page-connected-views.mdc` |
+| **View type (`DataListViewType`)** | The enum of view shapes the design system supports — `"table" \| "list" \| "board" \| "dashboard" \| "folder" \| "panel" \| "tree"`. Each tab declares one. | `apps/web/lib/data-list-view.ts` |
+| **Voice & tone** | The microcopy rules for the product: empty states, errors, banners, buttons, validation. See `docs/voice-and-tone.md`. | `docs/voice-and-tone.md` |
+
+---
+
+*Missing a term? Add it. Glossary entries are short — link to the rule or pattern for depth, don't restate it here.*