@exxatdesignux/ui 0.5.11 → 0.5.13

package/template-vite/.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` 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/template-vite/.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