@exxatdesignux/ui 0.2.16 → 0.2.18

package/CHANGELOG.md

@@ -15,6 +15,32 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ---
 
+## [0.2.18] - 2026-05-19
+
+### Fixed
+
+- **`Sidebar`**: Read `sidebar_state` on the server for `defaultOpen` so the documents **Resources** heading and rail chrome match the first client paint (fixes hydration warnings). Skip redundant cookie restore when state already matches.
+- **`TablePropertiesDrawer`**: Portaled **Add filter / sort / rule** menus use `z-[90]` above the properties sheet (`z-[80]`); `Sheet` and dropdowns use `modal={false}`; filter updates apply synchronously (no `startTransition` deferral). Drawer button routes column/display handlers through refs for the portaled sheet.
+
+### Changed
+
+- **Starter `template/`** and **consumer extras**: KPI flat band + shell surface elevation patterns/skills; table-properties and hub parity with `apps/web`.
+
+### Chore (monorepo)
+
+- Package **`version`** set to **0.2.18** for npm publish (tag **`ui-v0.2.18`**).
+
+## [0.2.17] - 2026-05-18
+
+### Changed
+
+- **Starter `template/`**: Synced from `apps/web` — Placements hub rename (`placements-*` vs legacy `data-list-*`), Question bank **new question** route, brand palette / appearance, `DataRowList` and folder tree primitives, table-state lifecycle helpers, and hub navigation polish.
+- **Consumer extras**: Cursor skills and pattern docs refreshed (`vendor:consumer-extras`), including **mono IDs** skill/rule.
+
+### Chore (monorepo)
+
+- Package **`version`** set to **0.2.17** for npm publish (tag **`ui-v0.2.17`**).
+
 ## [0.2.16] - 2026-05-15
 
 ### Changed

package/consumer-extras/cursor-skills/exxat-ds-skill/SKILL.md

@@ -21,7 +21,7 @@ description: >
 - **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
-- **Companion skills (narrow topics):** `exxat-fontawesome-icons`, `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`**.
+- **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`**.
 - **Question bank folder-scoped header (rule + doc):** **`.cursor/rules/exxat-question-bank-hub-header.mdc`** and **`docs/question-bank-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.
 
@@ -89,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. Question Bank → 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** (Question Bank 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. "Question bank — 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
@@ -406,7 +551,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) |

package/consumer-extras/cursor-skills/exxat-ds-skill/references/accessibility.md

@@ -0,0 +1,142 @@
+# WCAG 2.1 AA — Full Accessibility Checklist
+
+This is the single source of truth for all accessibility requirements in Exxat DS. Every component, edit, or feature must pass ALL applicable sections before it is considered done.
+
+---
+
+## 1. Interactive Elements
+
+- Every `<button>` has visible text OR `aria-label`
+- Icon-only buttons: `aria-label` + wrap with `<Tip>` (from `@/components/ui/tip`) — no exceptions
+- Stateful buttons describe current state: `aria-label="Sort ascending — click to sort descending"`
+- Links describe destination (no "click here"); new-window links: "(opens in new tab)"
+- No nested interactive elements (button inside button, anchor inside button)
+- Custom clickable `<div>`/`<span>`: `role="button"` + `tabIndex={0}` + `onKeyDown` (Enter/Space)
+- Disabled: use native `disabled` or `aria-disabled="true"`; keep discoverable by screen readers
+
+## 2. Keyboard
+
+- ALL interactions reachable by keyboard alone — zero mouse-only features
+- Tab order follows visual reading order
+- Skip link → `#main-content` (verify after layout changes)
+- `Enter`/`Space` activate buttons; `Escape` closes modals/popovers; `Arrow keys` in composite widgets
+- `focus-visible:` ring on ALL interactive elements (≥ 2px, 3:1 contrast against adjacent colors)
+- Hidden elements (opacity-0): `group-focus-within:opacity-100` for keyboard visibility
+- Modal: focus trapped inside, returns to trigger on close
+- Multi-step forms: move focus to step heading on advance (`tabIndex={-1}` + `.focus()`)
+- Popover/Dropdown: `initialFocus` on first interactive child
+
+## 3. Forms & Inputs
+
+- Every `<input>`/`<textarea>`/`<select>` has `<label>` (visible or `sr-only`) OR `aria-label`
+- Labels use `htmlFor` matching input `id`; placeholder is NOT a label
+- Errors: `aria-describedby` → error element + `aria-invalid="true"` + visible descriptive text
+- Required fields: `aria-required="true"` or HTML `required`
+- Grouped controls: `<fieldset>` + `<legend>` or `role="group"` + `aria-labelledby`
+- Dates: ALWAYS Calendar + Popover picker; format MM/DD/YYYY; `initialFocus` on Calendar open
+- Toggle/Switch: `role="switch"` + `aria-checked` + `<label htmlFor>`
+
+## 4. Semantic Structure
+
+- One `<main>` per page with `id="main-content"` + `tabIndex={-1}` (required for skip link)
+- Heading hierarchy: one `<h1>` (via `PageHeader`), logical `<h2>` → `<h3>` (no skipping)
+- `SiteHeader` title in the breadcrumb bar is NOT an `<h1>`
+- Multiple `<nav>` elements: each must have `aria-label`
+- Modal/Sheet/Dialog: `DialogTitle`/`SheetTitle`/`DrawerTitle` ALWAYS present — use `sr-only` if visually hidden
+- `<aside>` panels: `aria-label` (e.g. "Ask Leo assistant", "Rotation navigation")
+- Data tables: `<table>` + `<thead>` + `<th scope="col">`; sortable columns: `aria-sort` on `<th>`
+- Listbox: `role="listbox"` + `role="option"` + `aria-selected`
+
+## 5. Tooltips
+
+- Use `<Tip>` from `@/components/ui/tip` — NEVER the HTML `title` attribute
+- Open on BOTH hover AND keyboard focus
+- Every icon-only button gets `<Tip>` — no exceptions
+- Tooltip content is supplementary; never the sole source of critical information
+
+## 6. Color & Contrast
+
+- **Normal text**: 4.5:1 ratio
+- **Large text** (≥18px regular / ≥14px bold): 3:1
+- **UI components** (borders, focus rings): 3:1
+- Status conveyed NEVER by color alone — always include text label or icon alongside
+- Error states: red + icon + descriptive text (not just red color)
+- Decorative icons: `aria-hidden="true"`
+- All ratios apply in BOTH light AND dark themes
+- Hover states visibly distinct in dark mode (brand-tinted `--accent`, not grey)
+- Test against all themes: Lavender × Prism × light × dark × high-contrast
+
+## 7. Dynamic Content
+
+- Count changes (filter results, badge updates): `aria-live="polite"` on the element
+- Toast/snackbar notifications: `role="status"` or `aria-live="polite"`
+- Loading states: `aria-busy="true"` on the loading container
+- Progress indicators: `role="progressbar"` + `aria-valuenow/min/max`
+
+## 8. Images & Media
+
+- Informative images: descriptive `alt` text
+- Decorative images: `alt=""` or `aria-hidden="true"`
+- SVG icons accompanying text: `aria-hidden="true"`
+- Standalone SVG (no adjacent text): `role="img"` + `aria-label`
+
+## 9. ARIA Roles — Critical Rules
+
+### Tabs
+- `role="tablist"` → only `role="tab"` (or equivalent tab semantics) as direct children
+- **Never** put `role="button"`, menus (`aria-haspopup`), remove buttons, or other controls **inside** the `tablist` container
+- Tab panels: `role="tabpanel"` + `aria-labelledby`
+
+### View Switchers (tabs + per-tab settings + remove)
+- These are composite toolbar widgets — use `role="toolbar"` + `aria-label`
+- Use `aria-pressed` on toggle-style controls within the toolbar
+- Do NOT misuse `tablist`/`tab` for mixed-control toolbars
+
+### Touch Targets (WCAG 2.2 — 2.5.8)
+- Interactive controls: minimum **24×24 CSS pixels**, OR 24px spacing so hit areas don't overlap
+- Icon-only buttons: `size-6` or `min-h-6 min-w-6` — **never** `size-4` as the sole target
+
+## 10. Component-Specific Requirements
+
+| Component | Requirements |
+|-----------|-------------|
+| Sidebar nav | `aria-current="page"` on active link; badges include value in `aria-label`; collapsed state → tooltip shows label |
+| DataTable header column menu | `group-focus-within/th:opacity-100`; wrap trigger with `<Tip label="Column options">` |
+| Sort button | `<Tip label="Sort by {col}">` + `aria-sort` attribute on `<th>` |
+| Selection checkbox | `aria-label="Select {row name}"` |
+| Tabs | `role="tablist"` / `role="tab"` / `role="tabpanel"` + `aria-selected` + arrow key navigation |
+| Dropdown | `aria-haspopup` + `aria-expanded` (Radix handles automatically) |
+| Filter pill | Keyboard-navigable; Escape closes the popover |
+| Modal/Dialog | Focus trap + Escape closes + `aria-hidden` on background (Radix handles automatically) |
+| Sheet/Drawer | `SheetTitle` required; floating style defined in component reuse rules |
+| Ask Leo sidebar | `<aside aria-label="Ask Leo assistant">` |
+
+## 11. Pre-Completion Testing Protocol
+
+Run for EVERY task before marking done:
+
+1. **Keyboard:** Tab through all changed elements — can you reach and activate every control without a mouse?
+2. **Focus ring:** Visible on every interactive element after tabbing to it?
+3. **Tooltips:** Every icon-only button has `<Tip>`?
+4. **Labels:** Every input has a label? Every button has text or `aria-label`?
+5. **Color contrast:** Text ≥ 4.5:1, UI ≥ 3:1? (Check with browser devtools or axe)
+6. **Dark mode:** Repeat contrast check in dark theme
+7. **200% zoom:** Layout usable at 200% browser zoom?
+8. **axe audit:** Run axe (DevTools extension) on any page where you touched views toolbar, tabs, or primary list surfaces
+
+## Quick Reference Card
+
+```
+Icon button     → aria-label + <Tip>
+Toggle/Switch   → role="switch" + aria-checked
+Dropdown        → aria-haspopup + aria-expanded (Radix auto)
+Tab             → role="tab" + aria-selected
+Sort column     → aria-sort on <th>
+Live count      → aria-live="polite"
+Error message   → id + aria-describedby on input
+Date input      → Calendar + Popover + initialFocus
+Modal           → DialogTitle (required) + focus trap
+Progress        → role="progressbar" + aria-valuenow/min/max
+Tablist         → only tab-role children (no buttons/menus inside)
+View switcher   → role="toolbar" + aria-label + aria-pressed
+```

package/consumer-extras/cursor-skills/exxat-ds-skill/references/coach-marks.md

@@ -0,0 +1,169 @@
+# Coach Marks — Implementation Guide
+
+> **Use coach marks for onboarding flows and feature discovery.** Every tour is defined once, targets elements by CSS selector, and is managed centrally from the Settings page.
+
+---
+
+## Architecture
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `CoachMark` | `@/components/ui/coach-mark` | Selector-targeted popover with spotlight overlay, brand-colored background |
+| `useCoachMark` | `@/hooks/use-coach-mark` | Flow state manager — step navigation, localStorage persistence, element targeting |
+| `CoachMarkStep` | `@/hooks/use-coach-mark` (type) | Step definition — target selector, side, align, title, description, optional image |
+| Coach mark registry | `@/lib/coach-mark-registry` | Central definition of all flows for the Settings page |
+| Settings page | `@/components/settings-client` + `app/(app)/settings/page.tsx` | UI to view, reset, and preview all coach mark flows |
+
+---
+
+## How It Works
+
+1. **Selector-based targeting** — each step has a `target` CSS selector (e.g. `[aria-label='Properties']`). The coach mark finds the element, scrolls it into view, and positions a popover next to it.
+2. **Spotlight overlay** — a semi-transparent backdrop with an SVG mask cutout highlights the target element with a ring.
+3. **Brand background** — the popover uses `bg-brand-deep text-white` for high visibility. Buttons are white/inverted.
+4. **localStorage persistence** — once completed or skipped, a flow is marked as dismissed and won't show again unless reset from Settings.
+5. **Per-step positioning** — each step can specify its own `side` and `align` for optimal placement relative to the target.
+
+---
+
+## Adding a New Coach Mark Flow
+
+### Step 1 — Define the steps
+
+```tsx
+import type { CoachMarkStep } from "@/hooks/use-coach-mark"
+
+const MY_TOUR_STEPS: CoachMarkStep[] = [
+  {
+    id: "step-1",
+    target: "[aria-label='My Widget']",   // CSS selector for the target element
+    side: "bottom",                        // popover side: top | bottom | left | right
+    align: "start",                        // popover alignment: start | center | end
+    title: "Meet My Widget",
+    description: "This widget helps you do X. Click to explore.",
+  },
+  {
+    id: "step-2",
+    target: "button[aria-label='Settings']",
+    side: "left",
+    align: "center",
+    title: "Customise Settings",
+    description: "Open settings to configure Y and Z.",
+    image: "https://example.com/screenshot.jpg",   // optional hero image
+    imageAlt: "Settings panel screenshot",          // required when image is provided
+  },
+]
+```
+
+### Step 2 — Wire the hook and component
+
+```tsx
+import { CoachMark } from "@/components/ui/coach-mark"
+import { useCoachMark } from "@/hooks/use-coach-mark"
+
+function MyPageClient() {
+  const tour = useCoachMark({
+    flowId: "my-feature-tour",    // unique ID — used as localStorage key
+    steps: MY_TOUR_STEPS,
+    delay: 1200,                  // ms before first appearance
+  })
+
+  return (
+    <>
+      <CoachMark state={tour} />
+      {/* rest of your page */}
+    </>
+  )
+}
+```
+
+**Key points:**
+- `CoachMark` renders via portal — place it anywhere, it does NOT wrap children
+- The component handles element lookup, scrolling, spotlight overlay, and positioning
+- On flow completion, `localStorage` marks the flow as dismissed
+
+### Step 3 — Register in the coach mark registry
+
+Add your flow to `lib/coach-mark-registry.ts`:
+
+```ts
+{
+  id: "my-feature-tour",
+  name: "My Feature Tour",
+  description: "Introduces the main controls and settings for My Feature.",
+  page: "My Feature",
+  pageUrl: "/my-feature",
+  stepCount: 2,
+}
+```
+
+This makes it appear in the Settings page where users can reset or preview it.
+
+---
+
+## Variants
+
+| Variant | How to use |
+|---------|-----------|
+| **Single step** | Pass a 1-item array to `steps` — no step indicator shown, button says "Got it" |
+| **Multi-step flow** | Pass 2+ items — shows step dots, Skip, Back, Next buttons |
+| **With image** | Set `image` + `imageAlt` on the step — hero image appears above the content |
+| **Without image** | Omit `image` — text-only popover |
+
+---
+
+## Target Selector Best Practices
+
+Use stable, semantic selectors that survive refactors:
+
+| Prefer | Avoid |
+|--------|-------|
+| `[aria-label='Properties']` | `.css-class-name` |
+| `[role='toolbar'][aria-label='Views']` | `div:nth-child(3)` |
+| `button[aria-label='Search']` | `#auto-generated-id` |
+| `h1` | `.page-header > div > h1` |
+
+If no stable selector exists, add a `data-coach-mark="step-name"` attribute to the target element.
+
+---
+
+## Existing Flows
+
+| Flow ID | Page | Steps | What it covers |
+|---------|------|-------|---------------|
+| `dashboard-tour` | Dashboard | 4 | Welcome, Key Metrics, AI Insights, Ask Leo |
+| `placements-views-tour` | Placements | 6 | View tabs, view settings, add view, search, filter, Properties |
+
+---
+
+## Settings Page
+
+The Settings page at `/settings` (`components/settings-client.tsx`) provides:
+
+- **List of all registered flows** from `lib/coach-mark-registry.ts`
+- **Status** — Completed vs Active per flow
+- **Reset** — clears localStorage so the tour replays on next visit
+- **Preview** — resets the flow and navigates to its page
+- **Reset all** — clears all coach mark dismissals
+
+---
+
+## Utilities (exported from `use-coach-mark`)
+
+| Function | Purpose |
+|----------|---------|
+| `getAllCoachMarkKeys()` | List all dismissed coach mark flow IDs |
+| `resetCoachMarkFlow(flowId)` | Clear dismissal for one flow |
+| `resetAllCoachMarks()` | Clear all dismissals |
+
+---
+
+## Rules
+
+1. **Always register new flows** in `lib/coach-mark-registry.ts` so they appear in Settings
+2. **Use CSS selectors based on ARIA attributes** — they're stable and semantic
+3. **Brand background is mandatory** — coach marks use `bg-brand-deep text-white`, not `bg-popover`
+4. **No wrapping children** — `CoachMark` targets elements by selector, never wraps them
+5. **Keep flows short** — 3–6 steps per flow is ideal; split longer tours into separate flows
+6. **Add `data-coach-mark` attributes** if no stable selector exists on the target element
+7. **Set appropriate `delay`** — 800–1200ms gives the page time to render before the first step appears