@exxatdesignux/ui 0.5.11 → 0.5.13

package/consumer-extras/templates/handoff.md

@@ -0,0 +1,190 @@
+# Design → Engineering Handoff
+
+This template is the **single artifact** the agent produces at the end of any
+design task that creates or rebuilds a surface (page, hub, detail view,
+wizard, drawer, sheet). It is the contract between the designer who shaped
+the work in the brief and the engineer who ships it.
+
+The agent fills this in as part of the `exxat-ux-discovery-protocol` flow.
+The engineer reads it once, runs `exxat-ui audit <file>` against the
+generated files, and is done.
+
+---
+
+## 1. Job-to-be-done
+
+> Single sentence. The decision or action this surface enables for the user.
+> Copy from the design brief — do not invent.
+
+(example) *Coordinator identifies and acts on at-risk students before placement.*
+
+## 2. Audience & frequency
+
+> Persona (admin / coordinator / faculty / student / preceptor) + how often
+> they hit this surface (daily / weekly / occasional).
+
+(example) *Program coordinator, daily, keyboard-first.*
+
+## 3. Pattern + IA
+
+> The DS pattern this surface uses + the information architecture shape.
+> Should match the brief.
+
+- **Surface kind**: route | sheet | dialog | inline (one of the four)
+- **Layout**: page-header + ?? (single column / split / data-table grid / …)
+- **Navigation**: breadcrumb? back affordance? anchor sub-nav?
+- **Header tier**: identity, status, KPI, ⋯ overflow, primary CTA
+
+## 4. Reference implementations
+
+> One **repo** reference + two **modern SaaS** analogues (cite by product
+> name + Mx codes from `docs/exxat-ds/modern-saas-patterns.md`).
+
+- **Repo**: `apps/web/components/<file>.tsx`
+- **Modern**: `<Product 1>` (Mx, Mx); `<Product 2>` (Mx, Mx)
+
+## 5. Components used (DS inventory)
+
+> Every DS primitive consumed. The agent fills this in by inspecting its
+> own diff. No new bespoke widgets unless approved in the brief.
+
+| Primitive | From | Why |
+|-----------|------|-----|
+| `PageHeader` | `@exxatdesignux/ui/page-header` | Identity + actions row |
+| `HubTable` | `@/components/data-views` | Rows + filters + properties |
+| … | … | … |
+
+## 6. Tokens consumed
+
+> Every CSS custom property the agent referenced. No hex literals — see
+> `exxat-token-discipline`.
+
+- Colors: `--exxat-color-bg-app`, `--exxat-color-text-primary`, …
+- Spacing: `--exxat-spacing-*`
+- Radii: `--exxat-radius-*`
+- Shadow / elevation: `--exxat-shadow-*`
+
+## 7. Icons used
+
+> Font Awesome Pro classes. Add to the subset audit (`fa:subset-audit`)
+> if any are new to the kit.
+
+- `fa-light fa-graduation-cap` — student identity
+- `fa-light fa-shield-check` — compliance status
+- …
+
+## 8. Accessibility floor
+
+> Filled by the agent automatically (the universal a11y rule is on). Engineer
+> verifies by running axe / Deque on the deployed surface.
+
+- [x] One H1 per page; record name in `PageHeader.title` only
+- [x] Single primary CTA; everything else is outline / ghost / link
+- [x] `Tablist` semantics correct (no buttons inside `role=tablist`)
+- [x] All interactive targets ≥ 24 × 24 CSS px
+- [x] Contrast ≥ 4.5 : 1 for text, ≥ 3 : 1 for UI / focus
+- [x] Every icon has either `aria-hidden` (decorative) or `aria-label` + tooltip (informational)
+- [x] Format hints rendered as `FormDescription`, not placeholder
+- [x] Every primary action has an `Enter` shortcut + visible Kbd hint
+- [x] Every cancel action accepts `Esc`
+
+## 9. Data shape
+
+> What rows / records / fields this surface reads from. Engineer wires the
+> real API; the agent uses `lib/mock/<entity>.ts` for the demo dataset.
+
+- **Mock**: `apps/web/lib/mock/<entity>.ts`
+- **API contract** (when known): `<endpoint>` returns `<RowShape>`
+- **State container**: `useTableState({ data, columns })`
+
+## 10. Empty / loading / error
+
+> Every list, detail, and action ships all three states. Filled in by the
+> agent; engineer verifies the copy.
+
+- **Loading**: skeleton (`<HubTableSkeleton />` or matched shape)
+- **Empty**: copy + primary CTA to start the flow
+- **Error**: copy + retry affordance + Ask Leo entry point
+
+## 11. Keyboard map
+
+> Every shortcut bound on this surface. The agent must declare these so the
+> engineer can write a Playwright test against them.
+
+| Action | Shortcut |
+|--------|----------|
+| Open Add view | `1..9` |
+| Submit primary form | `Enter` |
+| Cancel | `Esc` |
+| Search | `⌘K` / `Ctrl+K` |
+| Ask Leo | `⌘⌥K` / `Ctrl+Alt+K` |
+| New record | `⌘⌥N` |
+
+## 12. Deviations from principles
+
+> Any P9–P20 principle the design intentionally breaks, and the one-sentence
+> reason. P1–P8 cannot be deviated from. If this section has rows, the
+> engineer must include them in the PR description.
+
+| Principle | Reason |
+|-----------|--------|
+| P14 (density) | Mixed audience — added density toggle, default cozy |
+
+## 13. Out of scope
+
+> What this surface deliberately does **not** do. Helps the engineer decide
+> what tickets *not* to file.
+
+(example)
+- Inline editing of student name (v2)
+- Bulk message (lives on the list hub, not on the detail)
+
+## 14. Open questions
+
+> Things the brief could not answer. Engineer pings the designer or product.
+
+- (example) Should the compliance badge link out to the source document or open in a side panel?
+
+## 15. Designer-stack → engineering-stack port (delete if same stack)
+
+> **Skip this section** if your designer prototype and your production app
+> are on the same framework (both Vite, both Next.js).
+>
+> **Fill this in** if the designer prototyped on the **Vite scaffold**
+> (`create-exxat-app`, the lightweight default) but the production app
+> still runs on **Next.js**. The agent or engineer maps each Vite-specific
+> import to its Next equivalent before merging the work into prod.
+
+| Vite scaffold (designer) | Next.js prod (engineer) | Notes |
+|---|---|---|
+| `import { Link } from "@/lib/next-compat"` → `<Link to="…">` | `import Link from "next/link"` → `<Link href="…">` | Drop the shim re-export; rename `to` → `href` |
+| `import { useNavigate } from "react-router-dom"` | `import { useRouter } from "next/navigation"` + `router.push(...)` | One-line swap |
+| `import { useLocation } from "react-router-dom"` → `useLocation().pathname` | `import { usePathname } from "next/navigation"` | Direct equivalent |
+| `import { useSearchParams } from "react-router-dom"` returns `[params, setParams]` | `import { useSearchParams } from "next/navigation"` returns `ReadonlyURLSearchParams` | Drop the destructure, accept readonly shape |
+| `import { Navigate } from "react-router-dom"` (JSX redirect) | `import { redirect } from "next/navigation"` (function call) | Move from JSX to component body |
+| `React.lazy(() => import(...))` + `<Suspense>` | `dynamic(() => import(...), { loading, ssr: false })` | Functionally equivalent — pick whichever the surrounding file already uses |
+| `vite.config.ts` aliases | `next.config.mjs` `experimental.turbopack.resolveAlias` or `tsconfig.json` `paths` | Rare — most aliases live in `tsconfig.json` already |
+| `index.html` `<meta>` tags + `<title>` | `app/layout.tsx` `metadata` export | Move static meta into the route's `metadata`; dynamic meta moves into `generateMetadata` |
+| `document.cookie` reads in client components | `cookies()` from `next/headers` (server) | Most cases are client-only; only swap if the value must be SSR-rendered |
+| `@fontsource-variable/inter` import in `main.tsx` | `Inter()` from `next/font/google` in `app/layout.tsx` | Both produce zero-CLS variable fonts; Next has the edge on hashed asset names |
+
+The agent runs this map as a codemod — see
+`packages/ui/template-vite/scripts/port-next-imports.mjs` (template-vite
+internal use) for the inverse direction (Next → Vite, used during PR-2).
+Engineers porting **Vite → Next** can copy that script and reverse the
+regexes; the patterns are symmetric.
+
+---
+
+## How the engineer uses this file
+
+1. Read sections 1–3 to understand intent.
+2. Skim sections 4–7 to confirm the agent reused DS primitives + tokens (no surprises).
+3. Run `npx --package=@exxatdesignux/ui exxat-ui audit <generated-file>.tsx` to validate the floor automatically.
+4. Wire real data per section 9.
+5. Verify section 10 states render with real API data (not just mocks).
+6. Add section 11 shortcuts to the route's e2e test.
+7. Surface section 12 deviations + section 14 open questions in the PR description.
+
+If any section is missing or hand-wavy, the handoff is incomplete. Push it
+back to the designer / agent before merging.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "license": "UNLICENSED",
   "author": "Exxat Design",
@@ -97,7 +97,7 @@
     "dist",
     "src",
     "bin",
-    "template",
+    "template-vite",
     "consumer-extras",
     "tokens"
   ],
@@ -155,7 +155,6 @@
     "lint": "eslint src/",
     "test": "vitest run",
     "test:watch": "vitest",
-    "sync-template": "node ./scripts/sync-template-from-web.mjs",
     "vendor:consumer-extras": "node ./scripts/vendor-consumer-extras.mjs",
     "tokens:index": "node ./scripts/build-tokens-index.mjs",
     "tokens:check": "node ./scripts/build-tokens-index.mjs --check"

package/{template → template-vite}/.claude/skills/exxat-ds-skill/SKILL.md

@@ -19,9 +19,11 @@ description: >
 ## 1. Project Overview
 
 - **Stack:** Next.js 16 (App Router), React, TypeScript, Tailwind CSS, shadcn/ui primitives, Font Awesome icons
-- **App root:** `exxat-ds/app/(app)/` — route group that wraps all authenticated pages
-- **Single source of truth:** `exxat-ds/AGENTS.md` for full prose explanations; this skill is the actionable summary
+- **App root:** `apps/web/app/(app)/` — route group that wraps all authenticated pages
+- **Single source of truth:** `apps/web/AGENTS.md` for full prose explanations; this skill is the actionable summary
 - **Companion skills (narrow topics):** `exxat-fontawesome-icons`, `exxat-mono-ids`, `exxat-primary-nav-secondary-panel`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-dedicated-search-surfaces`, `exxat-accessibility`, `exxat-board-cards`, `exxat-collaboration-access` — live under `.cursor/skills/`; vetted copies ship with **`@exxatdesignux/ui`** in `consumer-extras/cursor-skills/` after **`pnpm --filter @exxatdesignux/ui vendor:consumer-extras`**.
+- **Library folder-scoped header (rule + doc):** **`.cursor/rules/exxat-library-hub-header.mdc`** and **`docs/library-hub-header-pattern.md`** — pair with **`exxat-primary-nav-secondary-panel`** when URL **`scope=folder`** drives the hub title.
+- **Consumer repos (npm install of `@exxatdesignux/ui`):** After a version bump, read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`**, run **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** so **`docs/exxat-ds/consumer-upgrade-checklist.md`** and Cursor skills match the tarball, and diff the host app against **`node_modules/@exxatdesignux/ui/template/`** for anything new to port (routes, re-exports, AGENTS). Use **`exxat-ui changelog`**, **`exxat-ui update`**, and **`exxat-ui doctor`** for CLI guidance.
 
 ---
 
@@ -87,16 +89,161 @@ To add a primary nav item, append to `NAV_PRIMARY`:
 
 | Concern | Pattern |
 |--------|---------|
-| **Product (One / Prism)** | **`ExxatProductLogo`** (`components/exxat-product-logo.tsx`) for the header control and **`ProductSwitcher`** — **not** logo.dev rasters unless product explicitly changes that. |
+| **Product (One / Prism)** | **`ExxatProductLogo`** (`components/exxat-product-logo.tsx`) for the header control and **`ProductSwitcher`** — **not** logo.dev rasters unless product explicitly changes that. The logo is now **generated from a config**, not hand-built SVG paths — see **§3.4** to add a new product. |
 | **School/program menu width** | **`DropdownMenuContent`** defaults to **intrinsic width** (**`min-w-52 w-max max-w-[min(24rem,calc(100vw-2rem))]`** via **`DROPDOWN_MENU_CONTENT_SURFACE_CLASS`** in **`@exxatdesignux/ui/lib/dropdown-menu-surface`**) — pure CSS, no **`ResizeObserver`**. The **school / program** switcher still uses an explicit wider surface (**`!w-max min-w-72 max-w-[min(100vw-2rem,28rem)]`**) so dense rows stay readable. |
 | **School/program copy** | **Do not truncate** school or program names in the switcher; wrap (**`break-words`**, **`whitespace-normal`**, **`items-start`** on multi-line rows). The selected-school summary shows **school name + current program**. |
 | **Team switcher trigger** | **`SidebarMenuButton` `size="lg"`** uses **`h-12`** + **`overflow-hidden`**, which **clips** a second line (program). When the sidebar is **expanded** or **mobile**, add **`h-auto min-h-12`** and **`overflow-x-clip overflow-y-visible`**. On **icon rail**, hide label rows with **`group-data-[collapsible=icon]:hidden`** (tooltip still exposes the full string). Icon mode defaults **`size-8` + `p-2`** (~16px inner) **clips** school logos — override **`!size-9`**, **`!p-0`**, **`overflow-visible`**. Omit header **chevrons** next to logos if they look like stray chrome. |
 | **Motion / Animate UI** | [Animate UI](https://animate-ui.com/docs) — open **copy-first** animated components (Motion + Tailwind). This repo uses **`motion/react`** + **`lib/motion-ui.ts`** presets; pull more animations from their registry into `components/` when needed. |
-| **Nav items with children** | **Expanded:** **`Collapsible`**. **Desktop icon rail:** **`Popover`** listing child links. **Do not** pass **`tooltip={…}`** on **`SidebarMenuButton`** that is the **direct** child of **`CollapsibleTrigger asChild`** — the tooltip wrapper inserts an extra **`Tooltip` root** and breaks Radix **`Slot`** (**`React.Children.only`**). Compose **`Tooltip` > `TooltipTrigger` > `CollapsibleTrigger` > `SidebarMenuButton`** without the **`tooltip` prop**, or use the popover branch only. |
+| **Nav items with children** | See **§3.2** below for the full parent ↔ children pattern (collapsible vs popover, active-state rules, chevron + slide animation, reduced motion). |
 | **Profile (mock)** | **`stockPortraitUrl()`** from **`lib/stock-portrait.ts`**; **`AvatarImage`** **`referrerPolicy="no-referrer"`** for external URLs. |
 
 **Reference:** `components/app-sidebar.tsx`, `components/nav-user.tsx`, `components/product-switcher.tsx`.
 
+### 3.2 Parent ↔ children nav (collapsible vs popover vs secondary panel)
+
+A primary nav row that owns sub-routes has **three possible shapes** — pick exactly one per item:
+
+| Shape | When to use | Where it lives |
+|---|---|---|
+| **A. Collapsible children** (e.g. Library → All / My / Favorites / Folders) | Small finite child list that benefits from inline browsing (≤ 40 items, no extra page chrome). | `NavLinkItem.children` rendered by **`CollapsibleNavItem`** in `app-sidebar.tsx`. |
+| **B. Secondary panel** (separate nested rail) | Same nav row needs **scoped search / tree / metrics** alongside the hub content. | `NavLinkItem.secondaryPanel = "<id>"` + `PANELS[id]` — see companion skill `exxat-primary-nav-secondary-panel`. |
+| **C. Both A + B on one row** (Library does this) | Most cases when a hub has a sub-list AND a rich rail. The sidebar still shows the collapsible children; clicking the parent route also opens the secondary panel via `useAutoPanel`. | Combine A + B; the active-state and animation rules in §3.2 still apply to the sidebar children. |
+
+#### Active-state rules — **the single biggest mistake to avoid**
+
+1. **Expanded sidebar (full rail):** parent stays **visually neutral** when a child is active — **never double-highlight**. `isCollapsibleParentMenuButtonActive` returns `false` if `anyChildActive` so the active child row carries `data-active` alone.
+2. **Collapsed sidebar (icon rail):** the parent icon is the **only** affordance, so it lights up when **any child** route is active. Implementation: `iconRailActive = isAnyChildActive` is fed into `SidebarMenuButton.isActive` and selects `item.iconActive` (`fa-solid`) over `item.icon` (`fa-light`).
+3. **Tooltip / aria copy** in icon mode names the parent (e.g. "Library — open subpages"); the **popover** content lists children with their own active state so users see which sub-route is selected.
+
+```tsx
+// Inside CollapsibleNavItem
+const isAnyChildActive = item.children?.some(c => isCollapsibleChildActive(...))
+const parentMenuButtonActive = isCollapsibleParentMenuButtonActive(pathname, item) // false when anyChildActive
+const iconRailActive = isAnyChildActive
+```
+
+#### Chevron + content animation (shadcn / Radix collapsible)
+
+The collapsible rotates a chevron and slides the children in/out, mirroring shadcn's `Accordion`/`Collapsible` motion. **Three pieces wired together:**
+
+1. **`group/collapsible`** on the **`SidebarMenuItem`** that wraps the trigger — opts the chevron into `group-data-[state=open]/collapsible:rotate-90` (or whatever direction the icon needs). Without `group/collapsible` the chevron never rotates.
+2. **`CollapsibleContent`** uses Radix's `--radix-collapsible-content-height` CSS var via the shared keyframes:
+   ```tsx
+   <CollapsibleContent className="overflow-hidden
+     data-[state=open]:[animation:collapsible-down_200ms_ease-out]
+     data-[state=closed]:[animation:collapsible-up_200ms_ease-out]
+     motion-reduce:animate-none
+     group-data-[collapsible=icon]:hidden">
+     <SidebarMenuSub>...</SidebarMenuSub>
+   </CollapsibleContent>
+   ```
+   `overflow-hidden` is **required** so the height clip is visible during the animation. `motion-reduce:animate-none` honours `prefers-reduced-motion` (WCAG 2.3.3).
+3. **Keyframes in `app/globals.css`** (shared, reused by `Accordion` too):
+   ```css
+   @keyframes collapsible-down { from { height: 0 } to { height: var(--radix-collapsible-content-height) } }
+   @keyframes collapsible-up   { from { height: var(--radix-collapsible-content-height) } to { height: 0 } }
+   ```
+
+#### Icon-rail popover (collapsed sidebar)
+
+When `state === "collapsed"` (or `isMobile === false` on a tablet icon rail), `CollapsibleNavItem` renders a **`Popover`** anchored to the parent icon, listing children as full rows. **Do not** pass `tooltip={…}` to a `SidebarMenuButton` that is the **direct** child of `CollapsibleTrigger asChild` — the tooltip wrapper inserts an extra `Tooltip` root and breaks Radix `Slot` (`React.Children.only`). Compose `Tooltip > TooltipTrigger > CollapsibleTrigger > SidebarMenuButton` without the `tooltip` prop, or use the popover branch only.
+
+#### Hydration
+
+`CollapsibleNavItem` is an isolated component with its own controlled `open` state initialised in `useEffect`. **Do not** pass `defaultOpen` based on pathname at render time — server and client resolve it differently and Radix throws a hydration mismatch.
+
+#### Cap
+
+The data shape supports any number of children, but the collapsible variant is rendered only when `childCount <= 40`. Beyond that, model the children as a **secondary panel** (shape B) so the user gets search + scroll.
+
+**Reference:** `components/app-sidebar.tsx` (`CollapsibleNavItem`, `isCollapsibleParentMenuButtonActive`, `isCollapsibleChildActive`), `app/globals.css` (`@keyframes collapsible-down/up`), `lib/mock/navigation.tsx` (`NavLinkItem.children`).
+
+### 3.3 Secondary panel auto-collapse on high zoom
+
+`SecondaryPanelProvider` (`components/secondary-panel.tsx`) reads **`useSidebarReflowZoom()`** (browser zoom ≥ 200% **or** very short viewport — same WCAG 1.4.10 signal the primary sidebar uses) and **auto-collapses the nested rail to its icon variant on entering high zoom**. The user can re-expand once collapsed; the next zoom-out → zoom-in cycle re-collapses. `openPanel` also opens directly in compact mode when high zoom is active so freshly-navigated panels don't briefly flash expanded.
+
+Any future secondary-panel-like rail should reuse `useSidebarReflowZoom` rather than inventing a parallel zoom hook.
+
+**Reference:** `components/secondary-panel.tsx` (`SecondaryPanelProvider`), `hooks/use-sidebar-reflow-zoom.ts`.
+
+### 3.4 Product wordmark + brand registry
+
+The product logo ("**Exxat** *One*" / "**Exxat** *Prism*") is **generated from a `ProductBrandConfig`** in `lib/product-brand.ts`, not from hand-built SVG paths. The suffix word renders as real **Ivy Presto** italic text (`var(--font-heading)`, Adobe Fonts kit `wuk5wqn` preloaded in `app/layout.tsx`); the circular mark is the same Exxat "E" geometry, recolored from the brand's gradient.
+
+**To add a new product:**
+
+```ts
+// lib/my-product-brand.ts
+import { defineProductBrand, registerProductBrand } from "@/lib/product-brand"
+
+export const EXXAT_PULSE = defineProductBrand({
+  id: "exxat-pulse",
+  prefix: "Exxat",                          // optional, defaults to "Exxat"
+  suffix: "Pulse",                          // rendered in Ivy Presto italic
+  brandColor: "#00A8E8",                    // any CSS color — drives suffix text + mark fill
+  markGradient: ["#0083C7", "#3FC6FF"],     // optional 2-stop linear gradient on the mark
+  markShadow: "#006FAA",                    // optional inner shadow behind the "E" cut-out
+})
+
+registerProductBrand(EXXAT_PULSE)
+```
+
+Then render anywhere via either the **generic** primitives or the **Exxat** convenience wrappers:
+
+```tsx
+import { ProductWordmark, ProductMark, ProductLogo } from "@/components/product-wordmark"
+import { ExxatProductLogo, ExxatProductMark } from "@/components/exxat-product-logo"
+
+// Generic — works for any registered brand
+<ProductLogo config={EXXAT_PULSE} className="h-7" variant="mutedSuffix" />
+<ProductMark config={EXXAT_PULSE} className="size-7" />
+<ProductWordmark config={EXXAT_PULSE} className="h-7" />
+
+// Existing Exxat call-sites unchanged
+<ExxatProductLogo product="exxat-one" variant="mutedSuffix" className="h-7" />
+<ExxatProductMark product="exxat-prism" className="size-7" />
+```
+
+**Visual contract (so new brands look like real logos, not styled text):**
+
+1. **Prefix** uses Inter `font-extrabold` (800) `tracking-tight` in deep slate (`#273441`) / soft grey on dark (`#A8B2BA`). Always.
+2. **Suffix** — **official Exxat brand spec from Figma** — `var(--font-heading)` (IvyPresto Text), **upright `font-semibold` (600)** with `tracking-[-0.03em]` (Figma "letter spacing -3 %"), tinted with `brandColor`. **Not italic**, **not Bold/ExtraBold** — IvyPresto's Bodoni-lineage SemiBold already has the thick verticals that read as a logo, and pushing to 700/800 makes the letterforms visually heavier than the brand asset (`ExxatOne_WordmarkLogo_WithMinClearSpace.png`). Avoid `medium` (500) / `regular` (400) — those read as inline text, not as a wordmark.
+3. **Size relationship** — the `ExxatProductLogo` outer span pins `text-base leading-none` (16 px inherited) so the wordmark's `text-[1.78em]` resolves to ~28 px font / ~20 px cap-height regardless of host surface (sidebar `text-sm`, dropdown `text-base`, etc.). The mark renders at **`h-full`** of the outer height — the original hand-built `viewBox="0 0 766 164"` already bakes breathing room around the circle artwork, so giving the mark the full outer height reproduces the brand asset's 1.56:1 mark-to-cap ratio (caps ≈ 20 px against a 32 px mark at `h-8`). Shrinking the mark (e.g. `h-[88%]`) makes it visually smaller than the wordmark span and inverts the intended hierarchy. Use **`h-8`** (32 px) as the default sidebar / dropdown / switcher height; `h-7` is too tight for the new wordmark scale and produces a sub-30 px mark.
+4. **Cap-to-mark centring** — the wordmark adds `translate-y-[0.09em]` to compensate for the cap-midpoint vs em-box-midpoint offset (Inter / Ivy Presto put cap glyphs in the upper portion of the line box). Without this, `items-center` aligns the *spans* but not the *visible cap* and mark — the wordmark visually rides ~3 px above the mark. Keep the translate when forking.
+5. **`variant="mutedSuffix"`** (sidebar / switcher) keeps the brand color in **light** mode and only tints to `--muted-foreground` in **dark** mode. Don't mute the suffix in light mode — it loses brand recognition.
+6. **Mark** stays the canonical Exxat "E" geometry so existing pixel-aligned layouts (sidebar header avatar slot, switcher dropdown rows) keep working when you swap brands; only colors change.
+7. **Host span** uses `overflow-visible` because the wordmark's `1.78em` line-box can overshoot the parent `h-X` by ~1 px — let it render, don't clip.
+8. **Don't pass `object-*` classes** to the logo `className` — `ExxatProductLogo` is a `<span>`, not a replaced element, so `object-contain` / `object-left` are silently dropped. Use width / max-width constraints instead.
+9. **`ProductMark` has no size default** — callers MUST set explicit dimensions (`size-7`, `h-full w-auto`, etc.). A `size-*` default would silently lose against a downstream `h-full / w-auto` whenever `tailwind-merge` failed to recognise the shorthand-to-pair equivalence, and the mark would render at the default size (28 px) instead of the parent height (32 px in h-8). `ExxatProductLogo` passes `h-full w-auto`; the icon-rail / collapsed-sidebar usages pass `size-7`. Keep the explicit size.
+
+**Where to extend the registry:** brand configs live alongside `lib/product-brand.ts` for the two built-ins. Co-locate new product configs near their feature (e.g. `app/(app)/<product>/_lib/brand.ts`) and call `registerProductBrand` at module import time so `ProductSwitcher` / `getProductBrand(id)` resolve it without ordering issues.
+
+**MUST NOT:** add new hand-traced SVG paths for an additional product. Author a `ProductBrandConfig` instead.
+
+**Reference:** `lib/product-brand.ts`, `components/product-wordmark.tsx`, `components/exxat-product-logo.tsx`, `components/product-switcher.tsx`.
+
+### 3.5 Appearance preview tiles (Theme / Contrast)
+
+`components/settings-appearance-card.tsx` renders the Theme (Light / Dark / System) and Contrast (Normal / High / Windows / System) pickers using a shared **`ChromeIllustration`** SVG helper — a polished mini browser window (Mac-style traffic lights, sidebar with brand-tinted mark + 5 nav rows, header bar with search pill + avatar, KPI card + mini bar-chart card + list rows).
+
+Two knobs to make new variants without forking the geometry:
+
+- **`tokens: ChromeTokens`** — palette per labeled mode. Override individual fills via `{...CHROME_LIGHT, shellStroke: "..."}`. Don't reach for `var(--background)` — preview tiles must show their target mode regardless of the active theme so users can compare before committing.
+- **`strokeBoost: number`** — multiplier applied to every border weight. `1.8` is the high-contrast value used by both **High** and **Windows** tiles.
+
+For "System" variants, use the **`SplitSystemSvg`** helper. It renders `ChromeIllustration` twice in the **same** 96 × 56 viewBox, each clipped to a triangular half (top-left triangle = "light", bottom-right triangle = "dark") via SVG `<clipPath>` polygons. The result is **one window with a diagonal theme split** — the macOS / iOS "Auto" pattern — not two adjacent windows.
+
+```tsx
+<SplitSystemSvg
+  light={{ tokens: CHROME_LIGHT, sidebar: split.light, sidebarMark: split.markLight }}
+  dark={{ tokens: CHROME_DARK, sidebar: split.dark, sidebarMark: split.markDark }}
+/>
+```
+
+**MUST NOT** invent ad-hoc rect-stacks for new appearance options, or render two side-by-side mini-windows for a single "System" tile — extend `ChromeIllustration` or compose `SplitSystemSvg`.
+
+**Reference:** `components/settings-appearance-card.tsx` (`ChromeIllustration`, `SplitSystemSvg`, `CHROME_LIGHT`, `CHROME_DARK`, `SPLIT_SIDEBAR`).
+
 ---
 
 ## 4. Primary Hub Pages — Mandatory Pattern
@@ -104,37 +251,41 @@ To add a primary nav item, append to `NAV_PRIMARY`:
 Any **primary nav destination** that shows a list of records **must** use this composition (same as Placements / Team):
 
 ```
-ListPageTemplate
+ListPageTemplate  (supportedViewTypes = FULL_HUB_SUPPORTED_VIEWS — seven views)
   ├── PageHeader (title, subtitle with count, primary CTA, ⋯ more menu)
   ├── KeyMetrics (flat variant, single row)
   └── renderContent()
-        └── DataTable + useTableState + TablePropertiesDrawer
+        └── HubTable + useTableState + TablePropertiesDrawer + renderers per view
 ```
 
+**Add view parity (binding):** `.cursor/rules/exxat-hub-supported-views.mdc`, `apps/web/docs/hub-supported-views-pattern.md`. **MUST NOT** use `supportedViewTypes={["table"]}` or four-view-only allowlists without a documented exception. List view **MUST** use **`ListPageBoardCard`** (`library-table.tsx`).
+
 **Reference implementations:**
-- `components/library-table.tsx` + `library-client.tsx` — canonical seven-view hub (start here)
-- `components/columns-showcase.tsx` — cell catalog via `LibraryTable` (custom `columnDefs`, same Add view as Library)
-- `components/tokens-themes-client.tsx` + `components/tokens-secondary-nav.tsx` — hub with secondary panel + URL-driven scope + built-in pagination chrome
-- `components/library-table.tsx` + `components/library-hub-client.tsx` — full multi-view hub (table, board, dashboard)
+- `components/library-client.tsx` + `components/library-table.tsx` — **canonical seven-view hub** (All questions)
+- `components/columns-showcase.tsx` — custom table via **`LibraryTable`** + same seven views
+- `components/tokens-themes-client.tsx` + `components/tokens-hub-auxiliary-views.tsx`
+- `components/team-client.tsx` + `components/team-table.tsx` — entity hub pattern
+- `components/placements-client.tsx` + `components/placements-table.tsx` — Placements (most complete)
 
 **Files to create for a new hub page `Foo`:**
 | File | Purpose |
 |------|---------|
 | `lib/mock/foo.ts` | Mock data + TypeScript interface (12+ rows) |
-| `lib/mock/foo-kpi.ts` | `fooKpiMetrics()` (≤ 4 `MetricItem`s, each with `onClick` or `href`) + `fooKpiInsight()` returning a single `MetricInsight` |
+| `lib/mock/foo-kpi.ts` | `fooKpiMetrics()` + `fooKpiInsight()` |
 | `components/foo-page-header.tsx` | `PageHeader` + primary CTA + ⋯ menu |
-| `components/foo-showcase.tsx` *or* `components/foo-table.tsx` | `HubTable` (NOT raw `DataTable`) — pass `pagination` / `onPaginationChange` if the hub needs pagination chrome |
-| `components/foo-client.tsx` | `ListPageTemplate` orchestrator, mounts `KeyMetrics` with `items` + `insight` |
+| `components/foo-table.tsx` | `DataTable` + `useTableState` + `TablePropertiesDrawer` |
+| `components/foo-client.tsx` | `ListPageTemplate` orchestrator |
 | `app/(app)/foo/page.tsx` | Thin server component |
 
-**Do not** ship a **nav-linked hub** as an **empty page** or a single “replace this later” paragraph. If the route appears in **`lib/mock/navigation.tsx`**, implement the full hub (mock rows, **`ListPageTemplate`**, connected views per **`exxat-ds/AGENTS.md` §4.1**) unless the product explicitly defines a non-data shell.
+**Do not** ship a **nav-linked hub** as an **empty page** or a single “replace this later” paragraph. If the route appears in **`lib/mock/navigation.tsx`**, implement the full hub (mock rows, **`ListPageTemplate`**, connected views per **`apps/web/AGENTS.md` §4.1**) unless the product explicitly defines a non-data shell.
 
 ### Page vs drawer (actions)
 
 - **Drawer / sheet** — Use when the user needs **the current page behind them** *and* a **quick view**, **quick actions**, or a **short step** (e.g. properties, export, glance at a row).
+- **Dialog** — **Blocking** confirm/alert/short choice — **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 - **New page** — Use **otherwise**: **primary**, **long-form**, **multi-step**, or flows that need their **own URL** without the hub visible.
 
-Align with **`exxat-ds/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**.
+Align with **`apps/web/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 
 ---
 
@@ -150,7 +301,7 @@ Align with **`exxat-ds/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`
 | `ColumnDef` from `@/components/data-table/types` | Column type |
 | `FilterFieldDef`, `FilterOperator`, `ConditionalRule` from `@/components/table-properties/types` | Filter types |
 
-**Board (kanban) cards:** Use **`ListPageBoardCard`** and related parts from **`components/data-views/list-page-board-card.tsx`**; **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** from **`board-card-primitives.tsx`**. **List hub** status (Team, Compliance, Library, …): maps in **`lib/list-status-badges.ts`**; render with **`ListHubStatusBadge`** (**`surface="table"`** in table/list, **`surface="board"`** on cards); semantic tints **`LIST_HUB_STATUS_TINT_*`** for new domains; no **`uppercase`**. **Placements** uses **`StatusBadge`** in **`data-list-table-cells.tsx`** (wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`**). **Full rules:** **`exxat-ds/AGENTS.md` §4.4**, **`.cursor/rules/exxat-board-cards.mdc`**, **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+**Board (kanban) cards:** Use **`ListPageBoardCard`** and related parts from **`components/data-views/list-page-board-card.tsx`**; **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** from **`board-card-primitives.tsx`**. **List hub** status (Team, Compliance, Library, …): maps in **`lib/list-status-badges.ts`**; render with **`ListHubStatusBadge`** (**`surface="table"`** in table/list, **`surface="board"`** on cards); semantic tints **`LIST_HUB_STATUS_TINT_*`** for new domains; no **`uppercase`**. **Placements** uses **`StatusBadge`** in **`placements-table-cells.tsx`** (wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`**). **Full rules:** **`apps/web/AGENTS.md` §4.4**, **`.cursor/rules/exxat-board-cards.mdc`**, **`.cursor/skills/exxat-board-cards/SKILL.md`**.
 
 **Minimum required features on any data list page:**
 - Search (wire `searchable={displayOptions.showToolbarSearch}`)
@@ -192,6 +343,14 @@ Align with **`exxat-ds/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`
 
 **`MetricItem.trend`** must match the **signed change** (arrow direction = truth). **`trendPolarity`** (`higher_is_better` default, **`lower_is_better`**, **`informational`**) controls **tints** and **`aria-label`** — e.g. **low PBI / review flags** rising → `trend: "up"` + **`lower_is_better`** → unfavourable (red), not green. **Doc:** **`docs/kpi-trend-pattern.md`** · **Rule:** **`.cursor/rules/exxat-kpi-trends.mdc`** · **Skill:** **`.cursor/skills/exxat-kpi-trends/SKILL.md`**.
 
+### 5.3 KPI count (max four)
+
+**`ListPageTemplate`** metrics and **Data tab** key-metrics cards: **≤ 4** `MetricItem` — **`docs/kpi-strip-max-four-pattern.md`**, **`lib/dashboard-layout-merge.ts`**, **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**.
+
+### 5.4 Cards vs table rows
+
+Dense comparable hub → **`DataTable`**. Boards / folders / visual browse → **`ListPageBoardCard`** + **`ListPageViewFrame`**. **Doc:** **`docs/card-vs-rows-pattern.md`** · **Rule:** **`.cursor/rules/exxat-card-vs-list-rows.mdc`**.
+
 **DataTable must wrap in `<div className="pb-6">`.**
 
 ---
@@ -247,6 +406,8 @@ Use `PageHeader` from `@/components/page-header` for the content-area header (be
 
 When a hub is **shared**, use **`PageHeader` `variant="collaboration"`**: **empty roster** → outline **Add collaborator**; **non-empty** → face rail (faces / **`+N`** open the invite sheet). **Invite people** also lives under the entity header **⋯ More** and opens **`InviteCollaboratorsDrawer`** via **`CollaborationAccessFlow`** when possible. Library access (Owner / Editor / Commenter / Viewer) comes from **`lib/collaborator-access.ts`**; directory tags (Faculty, Program coordinator, Director) use **`PageHeaderCollaborator.roles`**.
 
+**Library library — folder URL scope:** When **`?scope=folder&folderId=`** applies, **⋯ More** must also offer **Customize folder** (**`LibraryPageHeader`** **`onCustomizeFolder`**) and the **`LibraryNewFolderSheet`** must be mounted on **`LibraryClient`** so it works on every **`ListPageTemplate`** view tab. **`.cursor/rules/exxat-library-hub-header.mdc`** · **`docs/library-hub-header-pattern.md`** (app: **`apps/web/docs/...`**).
+
 **Handbook:** `apps/web/AGENTS.md` §4.7 · **Doc:** `docs/collaboration-access-pattern.md` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md` · **Reference:** Library header + client.
 
 ---
@@ -300,7 +461,7 @@ Never install new packages or create parallel components. Always use what exists
 | Color | CSS design tokens only — no hardcoded hex/rgb |
 | Minimum font size | **`text-xs`** (11px at 16px root via `--text-xs`) or larger — never arbitrary classes below 11px (`AGENTS.md` §8.3) |
 
-Before adding any component: search `components/ui/` first. Add a prop/variant to an existing component rather than creating a parallel one.
+Before adding any component: search `components/ui/` first. Add a prop/variant to an existing component rather than creating a parallel one. **If nothing fits** and you need a **new shared primitive or large bespoke widget**, **ask the user** before new files — **`.cursor/rules/exxat-reuse-before-custom.mdc`** (unless the task already approved greenfield).
 
 ---
 
@@ -395,7 +556,7 @@ import { DropdownMenuItem, Shortcut } from "@/components/ui/dropdown-menu"
 | Duplicate | ⌘/Ctrl + D |
 | Review / Info | ⌘/Ctrl + I |
 | Remove / Delete item | ⌘/Ctrl + ⌫ |
-| Add view (1..n) | ⌘/Ctrl + ⇧/Shift + 1..9 |
+| Add view (1..n) | **1..9** (plain digit; `dataListViewAddShortcut`) |
 | **Submit a workflow** (Create, Save, Export, Apply) | **Enter** ⏎ — scoped to the open form/drawer/dialog |
 | **Cancel / dismiss** a workflow | **Esc** (Radix Dialog/Sheet/AlertDialog already bind this) |
 | **Advance a multi-step wizard** | ⌘/Ctrl + Enter (plain Enter must not submit mid-flow) |
@@ -450,7 +611,7 @@ Reference implementations: `new-placement-form.tsx` (Create placement = Enter on
 - **Natural language / AI:** Product **SHOULD** show **quick results in the palette** when the response fits; use **Ask Leo** (**⌘⌥K**) for **longer or complex** answers.
 - **Do not** treat the palette as a static link list only—leave room for inline AI results as they ship.
 
-**Details:** `exxat-ds/docs/command-menu-pattern.md`, **`exxat-ds/AGENTS.md` §7.1** (or `./` when the app folder is the workspace root).
+**Details:** `apps/web/docs/command-menu-pattern.md`, **`apps/web/AGENTS.md` §7.1** (or `./` when the app folder is the workspace root).
 
 ---
 
@@ -461,7 +622,7 @@ Full checklist in `references/accessibility.md`. Summary of the most-violated ru
 ### Structure
 - One `<main id="main-content" tabIndex={-1}>` per page
 - One `<h1>` per page (via `PageHeader`) — `SiteHeader` title is NOT an h1
-- `DialogTitle` / `SheetTitle` / `DrawerTitle` always present (use `className="sr-only"` if visually hidden)
+- `DialogTitle` / `SheetTitle` always present (use `className="sr-only"` if visually hidden)
 
 ### ARIA roles
 - `role="tablist"` → only `role="tab"` children. **Never** put buttons, menus, or other controls inside `tablist`
@@ -705,8 +866,8 @@ Copy and complete for every list/table/hub page:
 - [ ] Sidebar item added to `lib/mock/navigation.tsx` with light/solid icon pair
 - [ ] **Shell sidebar:** Product header uses **`ExxatProductLogo`**; school **`logoDevUrl`** + **`lib/logo-dev`**; team switcher menu **`!w-max`** (not trigger-width-only); expanded switcher **`h-auto min-h-12`** so school + program lines are not clipped; no **`CollapsibleTrigger` → `SidebarMenuButton` with `tooltip` prop**; child nav uses **popover** on icon rail per **§3.1**
 - [ ] Hub pages: `ListPageTemplate` + `DataTable` + `useTableState` + `TablePropertiesDrawer`
-- [ ] Board view: `ListPageBoardCard` shell + `ListHubStatusBadge` + `list-status-badges` when applicable (`exxat-ds/AGENTS.md` §4.4)
-- [ ] New primary hubs: not placeholder-only — full template + data + views (`exxat-ds/AGENTS.md` §4.1)
+- [ ] Board view: `ListPageBoardCard` shell + `ListHubStatusBadge` + `list-status-badges` when applicable (`apps/web/AGENTS.md` §4.4)
+- [ ] New primary hubs: not placeholder-only — full template + data + views (`apps/web/AGENTS.md` §4.1)
 - [ ] **§6.4:** Parent **context** + quick view/actions → drawer/sheet; primary or long flows → **new page** (`AGENTS.md`, `docs/data-views-pattern.md`)
 - [ ] No raw `<table>` or `ui/table` for product data lists
 - [ ] No double horizontal padding around `DataTable`
@@ -718,7 +879,7 @@ Copy and complete for every list/table/hub page:
 - [ ] All icons: `aria-hidden="true"`; Ask Leo: `fa-duotone fa-solid fa-star-christmas text-brand`
 - [ ] **Every icon that communicates info has a text alternative** — Case A adjacent label (preferred), Case B `role="img"` + `aria-label` + `Tooltip` (calendar-for-date, status dot, trend arrow, icon-only legend), Case C `aria-label` + `Tooltip` on icon-only buttons; target ≥ 24×24 px. See §12 *Icons that communicate information*.
 - [ ] **`Kbd` inside a `Button` uses `variant="bare"`** (glue chords into one bare kbd); **`Kbd` inside `TooltipContent` uses the default tile** — see §11 Keyboard shortcuts
-- [ ] `DialogTitle`/`SheetTitle`/`DrawerTitle` present on every overlay
+- [ ] `DialogTitle`/`SheetTitle` present on every overlay
 - [ ] `role="tablist"` contains only tab-role children
 - [ ] No new shadcn components, no hardcoded colors, no duplicate component abstractions
 

package/template-vite/.cursor/rules/exxat-accessibility.mdc

@@ -0,0 +1,40 @@
+---
+description: Exxat DS — WCAG 2.1 AA, ARIA tablists, 24px targets, contrast; see AGENTS.md §8 and exxat-accessibility skill
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — accessibility (binding summary)
+
+**Full checklist (ARIA, touch targets, color, sidebar badges, audit follow-ups):** repo **`.cursor/skills/exxat-accessibility/SKILL.md`**.
+
+**Product rules in prose + checklist:** **`apps/web/AGENTS.md` §8**.
+
+## Non‑negotiables
+
+1. **Target:** **WCAG 2.1 Level AA** (2.2 where noted — e.g. target size).
+2. **`role="tablist"`** — only **`role="tab"`** (or equivalent) as direct tab semantics. **MUST NOT** put `role="button"`, menus (`aria-haspopup`), or other controls **inside** the same `tablist` container.
+3. **Composite view switchers** (tabs + per-tab menu + remove): use **`role="toolbar"`** + **`aria-label`**; **`aria-pressed`** on toggles — **MUST NOT** misuse `tab`/`tablist` for those controls.
+4. **Touch targets (2.5.8):** interactive controls **≥ 24×24 CSS px** or **24px** spacing so hit areas do not overlap — use **`min-h-6 min-w-6` / `size-6`** for icon-only targets; avoid **`size-4`** as the sole target.
+5. **Contrast:** normal text **≥ 4.5:1**; UI components / focus where required **≥ 3:1**; muted text on tinted surfaces use tokens against the correct surface (e.g. sidebar), not only `--background`.
+6. **Minimum text size:** visible product copy **≥ 11px** — use **`text-xs`** or larger; **MUST NOT** use arbitrary Tailwind font sizes below that (see **`apps/web/AGENTS.md` §8.3**, **`apps/web/app/globals.css`** `--text-xs`).
+7. **Dialogs / sheets:** must expose a **Title** (`DialogTitle` / `SheetTitle`); use **`sr-only`** if visually hidden (shadcn pattern).
+8. **Format hints are persistent, not placeholders (SC 3.3.2 Labels or Instructions, 1.3.1).** Any field that expects a specific format — **date, time, phone, currency, ID pattern, GPA scale, URL, hours, unit-bearing numbers** — MUST show the format as **persistent helper text** via **`FormDescription`** (or the field's description slot). Placeholders disappear on focus and are unreliable for AT, so **MUST NOT** be the sole carrier of the format. Example: GPA → "Out of 4.0"; Date → "MM/DD/YYYY"; Phone → "+1 (555) 555-0100"; Student ID → "STU-YYYY-####". Pair with `inputMode`, `pattern`, or a picker primitive (e.g. `DatePickerField`) where applicable; never rely on a free-text date input.
+9. **Every icon that communicates information MUST have a text alternative** — not just icon-only buttons. Three cases (SC 1.1.1 Non-text Content, 3.3.2 Labels or Instructions, 2.4.6 Headings and Labels):
+
+   - **A. Decorative icon next to text that already names it** (e.g. `<i class="fa-light fa-calendar-days" aria-hidden /> 12/14/2025 – 12/20/2025`) → icon MUST be **`aria-hidden`**; MUST NOT add `aria-label` (screen readers would announce the meaning twice). No tooltip needed.
+   - **B. Informational icon standing alone** — a calendar glyph used to mean "date range", clock for "updated at", pin for "site", graduation cap for "student", trending arrow for direction, status dot, icon-only chart legend — MUST pair **`role="img"` + `aria-label`** (or `aria-labelledby` on a wrapping element) with a visible **`Tooltip`** so sighted users who don't recognise the glyph learn the meaning. The icon wrapper MUST be keyboard-focusable (`tabIndex={0}` on the `span[role="img"]`) so the tooltip opens on focus.
+   - **C. Interactive icon-only button/link** (close `×`, chevron, overflow `⋯`, sort direction, filter chip dismiss, copy, Ask Leo toggle, row actions) → MUST pair **`aria-label`** on the `<button>` with a wrapping **`Tooltip`**. `aria-label` alone is NOT enough — sighted mouse users and keyboard users rely on the tooltip to discover what a bare icon does.
+
+   In all three cases, the inner `<i>` / `<svg>` MUST be `aria-hidden`; the accessible name lives on the wrapping element. Tooltip text MUST match the accessible name. Narrow exception: a chevron inside a labelled composite (`Select`, `Combobox`) where the parent control already names the whole thing. See **§8.6 (Case A/B/C)** in `AGENTS.md` and the accessibility skill.
+10. **Keyboard shortcut hints inside buttons** MUST use **`<Kbd variant="bare">`** (no background, no border, inherits `currentColor` at 70%). The default `tile` variant is reserved for **tooltips** and **menu `shortcut=` slots**. Glue multi-key chords into one bare kbd (e.g. `<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. Reference: `Next` / `Back` buttons in `new-library-item-form.tsx`; see `.cursor/rules/exxat-kbd-shortcuts.mdc`.
+
+After changing **views toolbar** or **tab** UIs, re-run **axe** (or equivalent) on **Placements** (or the affected page).
+
+**Charts:** Keyboard exploration uses **`ChartFigure`**; selected data points should have **visible** focus feedback — see skill **§ Charts (keyboard exploration)** and **`AGENTS.md` §4.3** (`chart-keyboard-selection`).
+
+## See also
+
+- **`apps/web/AGENTS.md`** §8 — accessibility in project context.
+- **`.cursor/rules/exxat-kbd-shortcuts.mdc`** — shortcuts paired with `Kbd` hints.
+- **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** — Data view chart keyboard parity.

package/template-vite/.cursor/rules/exxat-board-cards.mdc

@@ -0,0 +1,28 @@
+---
+description: Exxat DS — board (kanban) cards via ListPageBoardCard, badges, primitives. Auto-attaches when editing React board/list files; ask explicitly when designing kanban surfaces.
+globs: apps/web/components/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
+---
+
+# Exxat DS — board cards
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.4** and **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+
+## MUST
+
+1. **Shell** — Use **`ListPageBoardCard`** from **`components/data-views/list-page-board-card.tsx`** for product board cards (same **`Card` `size="sm"`** treatment as Placements).
+2. **Hierarchy** — **Title** (`ListPageBoardCardTitleRow`) → optional **avatar** (`ListPageBoardCardAvatar` on `trailing`) → **status row** (`ListPageBoardCardBadgeRow` + **`ListHubStatusBadge`** **`surface="board"`**) when the entity has status → **body** (`ListPageBoardCardBody`) with **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** (**`components/data-views/board-card-primitives.tsx`**).
+3. **Status** — Use **`ListHubStatusBadge`** with **`surface="table"`** in grid / list rows and **`surface="board"`** on kanban cards. Generic semantic tints live in **`lib/list-status-badges.ts`** (**`LIST_HUB_STATUS_TINT_SUCCESS / WARNING / INFO / NEUTRAL / DANGER`**); compose per-domain label / icon maps next to the entity's mock data. Reference: **`library-board-view.tsx`** + **`lib/mock/library.ts`**. **MUST NOT** use **`uppercase`** on those chips.
+4. **Simple column boards** — **`ListPageBoardTemplate`** + **`renderCard`**; compose **`ListPageBoardCard`** inside **`renderCard`**.
+
+## MUST NOT
+
+- Duplicate **`ListPageBoardCard`** with ad-hoc **`<button>`** + border/padding classes for the same hub pattern.
+- Show **status** only as plain text in the **body** when the hub uses **status** elsewhere — use the **badge row** + shared maps.
+
+## See also
+
+- **`apps/web/AGENTS.md` §4.4**, **§13** checklist
+- **`apps/web/docs/data-views-pattern.md`** — Board UI reuse
+- **`lib/initials-from-name.ts`** — owner initials when mock has no `initials` field