@contractspec/lib.contracts 1.56.1 → 1.58.0

package/dist/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -1,17 +1,513 @@
-import { registerDocBlocks } from "./registry.js";
-
-//#region src/docs/accessibility_wcag_compliance_specs.docblock.ts
-const accessibility_wcag_compliance_specs_DocBlocks = [{
-	id: "docs.accessibility_wcag_compliance_specs",
-	title: "Accessibility & WCAG Compliance — **specs.md**",
-	summary: "> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/accessibility_wcag_compliance_specs",
-	tags: ["accessibility_wcag_compliance_specs"],
-	body: "# Accessibility & WCAG Compliance — **specs.md**\n\n> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.\n\n---\n\n## 0) Scope & Principles\n\n- **Standards:** WCAG\xA02.2\xA0AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN\xA0301\xA0549 compliance by conformance to WCAG.\n- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).\n- **Rule of ARIA:** “No ARIA is better than bad ARIA.” Prefer native elements.\n- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.\n- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in `packages/lssm/libs/ui-kit-web`. Prefer those components over per‑app duplicates (`packages/*/apps/*/src/components/ui`). When missing, add to `ui-kit-web` first, then adopt app‑side.\n\n---\n\n## 1) Design Requirements (Design System & Tokens)\n\n**1.1 Color & Contrast**\n\n- Body text, icons essential to meaning: **≥\xA04.5:1**; large text (≥\xA018.66px regular / 14px bold): **≥\xA03:1**.\n- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥\xA03:1** against adjacent colors; text within components follows text ratios.\n- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.\n\n**1.2 Focus Indicators (WCAG\xA02.4.11/12)**\n\n- Every interactive element has a **visible focus** with clear offset; indicator contrast **≥\xA03:1** vs adjacent colors and indicator **area ≥\xA02\xA0CSS\xA0px** thick.\n- Focus **must not be obscured** by sticky headers/footers or scroll containers.\n\n**1.3 Motion & Preferences**\n\n- Respect `prefers-reduced-motion`: suppress large parallax, auto‑animations; provide instant alternatives.\n- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.\n\n**1.4 Target Size (2.5.8)**\n\n- Hit areas **≥\xA024×24\xA0CSS\xA0px** (web) and **≥\xA044×44\xA0dp** (mobile) unless exempt.\n\n**1.5 Typography & Layout**\n\n- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320\xA0CSS\xA0px** width.\n- Maintain clear heading hierarchy (h1…h6), one **h1** per view.\n\n- Repository baseline (Web): default body text uses Tailwind `text-lg` (≈18px). As of 2025‑09‑20, the repository bumped all Tailwind typography scale usages by +1 step (e.g., `text-sm`→`text-base`, `text-base`→`text-lg`, …, `text-8xl`→`text-9xl`). For long‑form content, default to `prose-lg`.\n- Do not use `text-xs` for body copy. Reserve `text-sm` only for non‑essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.\n- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or `leading-relaxed`/`leading-7` for body text where dense blocks appear.\n\n**1.6 Iconography & Imagery**\n\n- Decorative images: `alt=\"\"` or `aria-hidden=\"true\"`.\n- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.\n\n---\n\n## 2) Content Requirements (UX Writing)\n\n- Links say **what happens** (avoid “click here”).\n- Buttons start with verbs; avoid ambiguous labels.\n- Form labels are **visible**; placeholders are **not labels**.\n- Error messages: human + programmatic association; avoid color‑only.\n- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).\n- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).\n\n---\n\n## 3) Engineering Requirements (Web — Next.js/React)\n\n> Use and extend `packages/lssm/libs/ui-kit-web` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to `ui-kit-web` first.\n\n**3.1 Semantics & Landmarks**\n\n- Use native elements: `<button>`, `<a href>`, `<label for>`, `<fieldset>`, `<legend>`, `<table>`, etc.\n- Landmarks per page: `header`, `nav`, `main`, `aside`, `footer`. Provide a **Skip to main content** link.\n- Provide a **Route Announcer** (`aria-live=\"polite\"`) and move focus to page **h1** after navigation.\n\n**3.2 Keyboard**\n\n- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.\n- Common bindings:\n  - Space/Enter → activate button; Enter on link;\n  - Esc closes dialogs/menus;\n  - Arrow keys for lists/menus/tablists with **roving tabindex**.\n\n**3.3 Focus Management**\n\n- On route change (Next.js), move focus to the page `<h1>` or container and announce via a live region.\n- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.\n- Don’t steal focus except after explicit user action.\n\n**3.4 Forms**\n\n- Each input has a `<label>` or `aria-label`. Group related inputs with `<fieldset><legend>`.\n- Associate errors via `aria-describedby` or inline IDs; announce with `role=\"alert\"` (assertive only for critical).\n- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.\n\n**3.5 ARIA Usage**\n\n- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.\n- Ensure **name/role/value** are programmatically determinable.\n\n**3.6 Media**\n\n- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.\n- No auto‑playing audio. Auto‑playing video must be muted and pausable; provide controls.\n\n**3.7 Tables & Data**\n\n- Use `<th scope>` for headers; captions via `<caption>`; announce sorting via `aria-sort`.\n- Provide CSV/JSON export where charts are primary.\n\n**3.8 Performance & Robustness**\n\n- Avoid content shifts that move focus; reserve space or use skeletons.\n- Maintain accessible names through hydration/SSR; avoid `dangerouslySetInnerHTML` where possible.\n\n**3.9 Next.js specifics**\n\n- Use `next/link` for navigation; ensure links are **links**, not buttons.\n- `next/image` must include **alt** (empty if decorative).\n- Announce route changes with a **global live region** and shift focus to the new view.\n\n**3.10 Accessibility library integration**\n\n- Import `@contractspec/lib.accessibility` at app root. It auto-imports its `styles.css` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:\n\n```tsx\n// app/layout.tsx\nimport '@contractspec/lib.accessibility'; // includes tokens and provider exports\n// or if needed: import '@contractspec/lib.accessibility/src/styles.css';\n```\n\n- Wrap the app with `AccessibilityProvider` and include an element with `id=\"main\"` for the skip link target.\n\n---\n\n## 3b) lssm/ui-kit-web — Component Patterns & Defaults\n\n> Source: `packages/lssm/libs/ui-kit-web/ui/*`\n\n- **Button/Input/Textarea**: Built‑in `focus-visible` rings; ensure visible labels via `FormLabel` or `aria-label`.\n- **Form** (`form.tsx`): `FormControl` wires `aria-invalid` and `aria-describedby` to `FormMessage` and `FormDescription`. Prefer `FormMessage` for inline errors. Add `role=\"alert\"` only for critical.\n- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus‑trap and return‑focus. Provide `DialogTitle` + `DialogDescription` for name/description.\n- **Select/Combobox**: Prefer `SelectTrigger` with visible label; for icon‑only triggers, supply `aria-label`. Document examples in each app.\n- **Tabs**: Use `TabsList`, `TabsTrigger`, `TabsContent`; names are programmatically determinable.\n- **Toast/Toaster**: Prefer non‑blocking announcements; map critical to assertive region; include action buttons with clear labels.\n- **Table**: Use `TableCaption`; ensure `TableHead` cells use proper `scope`. Provide `aria-sort` on sortable headers.\n- **Utilities to add (repo action)**:\n  - `SkipLink` component and pattern in layouts.\n  - `RouteAnnouncer` (`aria-live=\"polite\"`) and **FocusOnRouteChange** helper.\n  - `VisuallyHidden` wrapper (Radix visually-hidden or minimal utility).\n  - `useReducedMotion` helper; honor in animated components.\n  - Touch‑size variants (≥44×44) for interactive atoms.\n\n---\n\n## 4) Engineering Requirements (Mobile — Expo/React\xA0Native)\n\n- Set `accessibilityLabel`, `accessibilityHint`, and `accessibilityRole` on touchables.\n- Ensure **hit slop** / min size **≥\xA044×44\xA0dp**.\n- Support Dynamic Type / font scaling; no clipped text at **200%**.\n- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.\n- Group related items with `accessibilityElements` ordering; hide decoration with `accessible={false}` or `importantForAccessibility=\"no-hide-descendants\"` when appropriate.\n- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.\n\n---\n\n## 5) Component Patterns (Acceptance Rules)\n\n**Buttons & Links**\n\n- Use `<button>` for actions, `<a href>` for navigation. Provide disabled states that are perceivable beyond color.\n\n**Navigation**\n\n- Provide **Skip link**. One primary nav landmark. Indicate current page (`aria-current=\"page\"`).\n\n**Menus/Combobox/Autocomplete**\n\n- Follow ARIA patterns: focus moves into list; `aria-expanded`, `aria-controls`, `aria-activedescendant` when applicable; Esc closes; typing filters.\n\n**Modals/Dialogs**\n\n- `role=\"dialog\"` or `alertdialog` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.\n\n**Tabs**\n\n- `role=\"tablist\"`; tabs are in the tab order; arrow keys switch focus; content is `role=\"tabpanel\"` with `aria-labelledby`.\n\n**Toasts/Notifications**\n\n- Non-critical: `aria-live=\"polite\"`; critical: `role=\"alert\"` sparingly.\n\n**Infinite Scroll / “Load More”**\n\n- Provide **Load more** control; announce new content to SR; preserve keyboard position.\n\n**Drag & Drop (2.5.7)**\n\n- Provide **non‑drag** alternative (e.g., move up/down buttons).\n\n**Charts & Maps**\n\n- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.\n\n---\n\n## 6) Testing & CI (Blocking Gates)\n\n**Static & Unit**\n\n- `eslint-plugin-jsx-a11y` — error on violations.\n- `jest-axe` — unit tests for components.\n\n**Automated Integration**\n\n- `axe-core` via Playwright or Cypress on critical flows.\n- `pa11y-ci` on key routes; threshold: **0 Critical / 0 Serious** to merge.\n- Lighthouse CI a11y score **≥\xA095** on target pages.\n\n**Manual QA (per release)**\n\n- **Keyboard patrol:** navigate primary flows without mouse.\n- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.\n- **Zoom & Reflow:** 200–400% & 320\xA0px width.\n- **Color/Contrast check:** tokens in both themes.\n\n**Reporting**\n\n- A11y issues labeled: `a11y-blocker`, `a11y-bug`, `a11y-enhancement` with WCAG ref.\n\n---\n\n## 7) Repository‑Specific Adoption Plan\n\n- Centralize UI usage on `packages/lssm/libs/ui-kit-web` and de‑duplicate per‑app `components/ui` where feasible.\n- Introduce `SkipLink`, `RouteAnnouncer`, `FocusOnRouteChange`, and `VisuallyHidden` in `ui-kit-web`. Adopt in app layouts (`app/layout.tsx`) first.\n- Add `useReducedMotion` and wire into animated components (e.g., `drawer`, `tooltip`, `carousel`).\n- Add touch‑size variants to `Button`, `IconButton`, `TabsTrigger`, toggles.\n- Document Select label patterns and error association in Forms.\n\n---\n\n## 8) Code Snippets\n\n**Skip Link**\n\n```html\n<a\n  class=\"sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2\"\n  href=\"#main\"\n  >Skip to main content</a\n>\n<main id=\"main\">…</main>\n```\n\n**Dialog (Radix + shadcn/ui) — essentials**\n\n```tsx\n// Ensure label, description, focus trap, and return focus on close remain intact\n<Dialog>\n  <DialogTrigger asChild>\n    <button aria-haspopup=\"dialog\">Open settings</button>\n  </DialogTrigger>\n  <DialogContent aria-describedby=\"settings-desc\">\n    <DialogTitle>Settings</DialogTitle>\n    <p id=\"settings-desc\">Update your preferences.</p>\n    <DialogClose asChild>\n      <button>Close</button>\n    </DialogClose>\n  </DialogContent>\n</Dialog>\n```\n\n**Form error association**\n\n```tsx\n<label htmlFor=\"email\">Email</label>\n<input id=\"email\" name=\"email\" type=\"email\" aria-describedby=\"email-err\" />\n<p id=\"email-err\" role=\"alert\">Enter a valid email.</p>\n```\n\n**Route change announcement (Next.js)**\n\n```tsx\n// Add once at app root\n<div\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n  id=\"route-announcer\"\n  className=\"sr-only\"\n/>\n```\n\n---\n\n## 9) Exceptions & Waivers\n\n- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**\n\n---\n\n## 10) Ownership\n\n- **Design:** maintains token contrast, component specs.\n- **Engineering:** enforces CI gates, implements patterns.\n- **QA:** runs manual checks per release.\n- **PM:** blocks release if AA not met on user‑visible flows.\n\n---\n\n## 11) References (internalize; no external dependency at runtime)\n\n- WCAG\xA02.2 (AA), EN\xA0301\xA0549. ARIA Authoring Practices. Platform HIG (Apple, Material).\n- `packages/lssm/libs/ui-kit-web` as the canonical UI source for web.\n\n> **Bottom line:** Shipping means **accessible by default**. We don’t trade a11y for speed; we bake it into speed.\n\n---\n\n## 12) Adoption Status (2025-09-23)\n\n- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.\n- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.\n- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to `Section`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role=\"alert\" where critical.\n\n> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.\n\n---\n\n## 13) CI Hardening & Visual QA\n\n- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.\n- Unit: Run jest-axe for ui-kit-web and app-level components.\n- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).\n- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).\n- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.\n- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.\n\n### Recent additions (2025-09-26)\n\n- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with `aria-controls`, `aria-activedescendant`, `Escape`/`Tab` handling, and labelled listbox.\n- Cypress a11y tests added for furniture and incidents modules on `/modules` and operators flows; checks run axe with critical/serious impacts.\n\n## 14) Accessibility Telemetry (PostHog)\n\n- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.\n- Properties: app, route, previous_value, new_value, timestamp.\n- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.\n- Privacy: No PII; aggregate only.\n"
-}];
-registerDocBlocks(accessibility_wcag_compliance_specs_DocBlocks);
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/docs/accessibility_wcag_compliance_specs.docblock.ts
+var accessibility_wcag_compliance_specs_DocBlocks = [
+  {
+    id: "docs.accessibility_wcag_compliance_specs",
+    title: "Accessibility & WCAG Compliance \u2014 **specs.md**",
+    summary: "> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non\u2011negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low\u2011cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/accessibility_wcag_compliance_specs",
+    tags: ["accessibility_wcag_compliance_specs"],
+    body: `# Accessibility & WCAG Compliance \u2014 **specs.md**
+
+> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non\u2011negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low\u2011cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.
+
+---
+
+## 0) Scope & Principles
+
+- **Standards:** WCAG\xA02.2\xA0AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN\xA0301\xA0549 compliance by conformance to WCAG.
+- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).
+- **Rule of ARIA:** \u201CNo ARIA is better than bad ARIA.\u201D Prefer native elements.
+- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.
+- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in \`packages/lssm/libs/ui-kit-web\`. Prefer those components over per\u2011app duplicates (\`packages/*/apps/*/src/components/ui\`). When missing, add to \`ui-kit-web\` first, then adopt app\u2011side.
+
+---
+
+## 1) Design Requirements (Design System & Tokens)
+
+**1.1 Color & Contrast**
+
+- Body text, icons essential to meaning: **\u2265\xA04.5:1**; large text (\u2265\xA018.66px regular / 14px bold): **\u2265\xA03:1**.
+- Interactive states (default/hover/active/disabled/focus) must maintain contrast **\u2265\xA03:1** against adjacent colors; text within components follows text ratios.
+- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.
+
+**1.2 Focus Indicators (WCAG\xA02.4.11/12)**
+
+- Every interactive element has a **visible focus** with clear offset; indicator contrast **\u2265\xA03:1** vs adjacent colors and indicator **area \u2265\xA02\xA0CSS\xA0px** thick.
+- Focus **must not be obscured** by sticky headers/footers or scroll containers.
+
+**1.3 Motion & Preferences**
+
+- Respect \`prefers-reduced-motion\`: suppress large parallax, auto\u2011animations; provide instant alternatives.
+- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.
+
+**1.4 Target Size (2.5.8)**
+
+- Hit areas **\u2265\xA024\xD724\xA0CSS\xA0px** (web) and **\u2265\xA044\xD744\xA0dp** (mobile) unless exempt.
+
+**1.5 Typography & Layout**
+
+- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320\xA0CSS\xA0px** width.
+- Maintain clear heading hierarchy (h1\u2026h6), one **h1** per view.
+
+- Repository baseline (Web): default body text uses Tailwind \`text-lg\` (\u224818px). As of 2025\u201109\u201120, the repository bumped all Tailwind typography scale usages by +1 step (e.g., \`text-sm\`\u2192\`text-base\`, \`text-base\`\u2192\`text-lg\`, \u2026, \`text-8xl\`\u2192\`text-9xl\`). For long\u2011form content, default to \`prose-lg\`.
+- Do not use \`text-xs\` for body copy. Reserve \`text-sm\` only for non\u2011essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.
+- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or \`leading-relaxed\`/\`leading-7\` for body text where dense blocks appear.
+
+**1.6 Iconography & Imagery**
+
+- Decorative images: \`alt=""\` or \`aria-hidden="true"\`.
+- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.
+
+---
+
+## 2) Content Requirements (UX Writing)
+
+- Links say **what happens** (avoid \u201Cclick here\u201D).
+- Buttons start with verbs; avoid ambiguous labels.
+- Form labels are **visible**; placeholders are **not labels**.
+- Error messages: human + programmatic association; avoid color\u2011only.
+- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).
+- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).
+
+---
+
+## 3) Engineering Requirements (Web \u2014 Next.js/React)
+
+> Use and extend \`packages/lssm/libs/ui-kit-web\` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to \`ui-kit-web\` first.
+
+**3.1 Semantics & Landmarks**
+
+- Use native elements: \`<button>\`, \`<a href>\`, \`<label for>\`, \`<fieldset>\`, \`<legend>\`, \`<table>\`, etc.
+- Landmarks per page: \`header\`, \`nav\`, \`main\`, \`aside\`, \`footer\`. Provide a **Skip to main content** link.
+- Provide a **Route Announcer** (\`aria-live="polite"\`) and move focus to page **h1** after navigation.
+
+**3.2 Keyboard**
+
+- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.
+- Common bindings:
+  - Space/Enter \u2192 activate button; Enter on link;
+  - Esc closes dialogs/menus;
+  - Arrow keys for lists/menus/tablists with **roving tabindex**.
+
+**3.3 Focus Management**
+
+- On route change (Next.js), move focus to the page \`<h1>\` or container and announce via a live region.
+- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.
+- Don\u2019t steal focus except after explicit user action.
+
+**3.4 Forms**
+
+- Each input has a \`<label>\` or \`aria-label\`. Group related inputs with \`<fieldset><legend>\`.
+- Associate errors via \`aria-describedby\` or inline IDs; announce with \`role="alert"\` (assertive only for critical).
+- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.
+
+**3.5 ARIA Usage**
+
+- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.
+- Ensure **name/role/value** are programmatically determinable.
+
+**3.6 Media**
+
+- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.
+- No auto\u2011playing audio. Auto\u2011playing video must be muted and pausable; provide controls.
+
+**3.7 Tables & Data**
+
+- Use \`<th scope>\` for headers; captions via \`<caption>\`; announce sorting via \`aria-sort\`.
+- Provide CSV/JSON export where charts are primary.
+
+**3.8 Performance & Robustness**
+
+- Avoid content shifts that move focus; reserve space or use skeletons.
+- Maintain accessible names through hydration/SSR; avoid \`dangerouslySetInnerHTML\` where possible.
+
+**3.9 Next.js specifics**
+
+- Use \`next/link\` for navigation; ensure links are **links**, not buttons.
+- \`next/image\` must include **alt** (empty if decorative).
+- Announce route changes with a **global live region** and shift focus to the new view.
+
+**3.10 Accessibility library integration**
+
+- Import \`@contractspec/lib.accessibility\` at app root. It auto-imports its \`styles.css\` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:
+
+\`\`\`tsx
+// app/layout.tsx
+import '@contractspec/lib.accessibility'; // includes tokens and provider exports
+// or if needed: import '@contractspec/lib.accessibility/src/styles.css';
+\`\`\`
+
+- Wrap the app with \`AccessibilityProvider\` and include an element with \`id="main"\` for the skip link target.
+
+---
+
+## 3b) lssm/ui-kit-web \u2014 Component Patterns & Defaults
+
+> Source: \`packages/lssm/libs/ui-kit-web/ui/*\`
+
+- **Button/Input/Textarea**: Built\u2011in \`focus-visible\` rings; ensure visible labels via \`FormLabel\` or \`aria-label\`.
+- **Form** (\`form.tsx\`): \`FormControl\` wires \`aria-invalid\` and \`aria-describedby\` to \`FormMessage\` and \`FormDescription\`. Prefer \`FormMessage\` for inline errors. Add \`role="alert"\` only for critical.
+- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus\u2011trap and return\u2011focus. Provide \`DialogTitle\` + \`DialogDescription\` for name/description.
+- **Select/Combobox**: Prefer \`SelectTrigger\` with visible label; for icon\u2011only triggers, supply \`aria-label\`. Document examples in each app.
+- **Tabs**: Use \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`; names are programmatically determinable.
+- **Toast/Toaster**: Prefer non\u2011blocking announcements; map critical to assertive region; include action buttons with clear labels.
+- **Table**: Use \`TableCaption\`; ensure \`TableHead\` cells use proper \`scope\`. Provide \`aria-sort\` on sortable headers.
+- **Utilities to add (repo action)**:
+  - \`SkipLink\` component and pattern in layouts.
+  - \`RouteAnnouncer\` (\`aria-live="polite"\`) and **FocusOnRouteChange** helper.
+  - \`VisuallyHidden\` wrapper (Radix visually-hidden or minimal utility).
+  - \`useReducedMotion\` helper; honor in animated components.
+  - Touch\u2011size variants (\u226544\xD744) for interactive atoms.
+
+---
+
+## 4) Engineering Requirements (Mobile \u2014 Expo/React\xA0Native)
+
+- Set \`accessibilityLabel\`, \`accessibilityHint\`, and \`accessibilityRole\` on touchables.
+- Ensure **hit slop** / min size **\u2265\xA044\xD744\xA0dp**.
+- Support Dynamic Type / font scaling; no clipped text at **200%**.
+- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.
+- Group related items with \`accessibilityElements\` ordering; hide decoration with \`accessible={false}\` or \`importantForAccessibility="no-hide-descendants"\` when appropriate.
+- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.
+
+---
+
+## 5) Component Patterns (Acceptance Rules)
+
+**Buttons & Links**
 
-//#endregion
-export { accessibility_wcag_compliance_specs_DocBlocks };
+- Use \`<button>\` for actions, \`<a href>\` for navigation. Provide disabled states that are perceivable beyond color.
+
+**Navigation**
+
+- Provide **Skip link**. One primary nav landmark. Indicate current page (\`aria-current="page"\`).
+
+**Menus/Combobox/Autocomplete**
+
+- Follow ARIA patterns: focus moves into list; \`aria-expanded\`, \`aria-controls\`, \`aria-activedescendant\` when applicable; Esc closes; typing filters.
+
+**Modals/Dialogs**
+
+- \`role="dialog"\` or \`alertdialog\` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.
+
+**Tabs**
+
+- \`role="tablist"\`; tabs are in the tab order; arrow keys switch focus; content is \`role="tabpanel"\` with \`aria-labelledby\`.
+
+**Toasts/Notifications**
+
+- Non-critical: \`aria-live="polite"\`; critical: \`role="alert"\` sparingly.
+
+**Infinite Scroll / \u201CLoad More\u201D**
+
+- Provide **Load more** control; announce new content to SR; preserve keyboard position.
+
+**Drag & Drop (2.5.7)**
+
+- Provide **non\u2011drag** alternative (e.g., move up/down buttons).
+
+**Charts & Maps**
+
+- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.
+
+---
+
+## 6) Testing & CI (Blocking Gates)
+
+**Static & Unit**
+
+- \`eslint-plugin-jsx-a11y\` \u2014 error on violations.
+- \`jest-axe\` \u2014 unit tests for components.
+
+**Automated Integration**
+
+- \`axe-core\` via Playwright or Cypress on critical flows.
+- \`pa11y-ci\` on key routes; threshold: **0 Critical / 0 Serious** to merge.
+- Lighthouse CI a11y score **\u2265\xA095** on target pages.
+
+**Manual QA (per release)**
+
+- **Keyboard patrol:** navigate primary flows without mouse.
+- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.
+- **Zoom & Reflow:** 200\u2013400% & 320\xA0px width.
+- **Color/Contrast check:** tokens in both themes.
+
+**Reporting**
+
+- A11y issues labeled: \`a11y-blocker\`, \`a11y-bug\`, \`a11y-enhancement\` with WCAG ref.
+
+---
+
+## 7) Repository\u2011Specific Adoption Plan
+
+- Centralize UI usage on \`packages/lssm/libs/ui-kit-web\` and de\u2011duplicate per\u2011app \`components/ui\` where feasible.
+- Introduce \`SkipLink\`, \`RouteAnnouncer\`, \`FocusOnRouteChange\`, and \`VisuallyHidden\` in \`ui-kit-web\`. Adopt in app layouts (\`app/layout.tsx\`) first.
+- Add \`useReducedMotion\` and wire into animated components (e.g., \`drawer\`, \`tooltip\`, \`carousel\`).
+- Add touch\u2011size variants to \`Button\`, \`IconButton\`, \`TabsTrigger\`, toggles.
+- Document Select label patterns and error association in Forms.
+
+---
+
+## 8) Code Snippets
+
+**Skip Link**
+
+\`\`\`html
+<a
+  class="sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2"
+  href="#main"
+  >Skip to main content</a
+>
+<main id="main">\u2026</main>
+\`\`\`
+
+**Dialog (Radix + shadcn/ui) \u2014 essentials**
+
+\`\`\`tsx
+// Ensure label, description, focus trap, and return focus on close remain intact
+<Dialog>
+  <DialogTrigger asChild>
+    <button aria-haspopup="dialog">Open settings</button>
+  </DialogTrigger>
+  <DialogContent aria-describedby="settings-desc">
+    <DialogTitle>Settings</DialogTitle>
+    <p id="settings-desc">Update your preferences.</p>
+    <DialogClose asChild>
+      <button>Close</button>
+    </DialogClose>
+  </DialogContent>
+</Dialog>
+\`\`\`
+
+**Form error association**
+
+\`\`\`tsx
+<label htmlFor="email">Email</label>
+<input id="email" name="email" type="email" aria-describedby="email-err" />
+<p id="email-err" role="alert">Enter a valid email.</p>
+\`\`\`
+
+**Route change announcement (Next.js)**
+
+\`\`\`tsx
+// Add once at app root
+<div
+  aria-live="polite"
+  aria-atomic="true"
+  id="route-announcer"
+  className="sr-only"
+/>
+\`\`\`
+
+---
+
+## 9) Exceptions & Waivers
+
+- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**
+
+---
+
+## 10) Ownership
+
+- **Design:** maintains token contrast, component specs.
+- **Engineering:** enforces CI gates, implements patterns.
+- **QA:** runs manual checks per release.
+- **PM:** blocks release if AA not met on user\u2011visible flows.
+
+---
+
+## 11) References (internalize; no external dependency at runtime)
+
+- WCAG\xA02.2 (AA), EN\xA0301\xA0549. ARIA Authoring Practices. Platform HIG (Apple, Material).
+- \`packages/lssm/libs/ui-kit-web\` as the canonical UI source for web.
+
+> **Bottom line:** Shipping means **accessible by default**. We don\u2019t trade a11y for speed; we bake it into speed.
+
+---
+
+## 12) Adoption Status (2025-09-23)
+
+- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.
+- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.
+- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to \`Section\`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role="alert" where critical.
+
+> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.
+
+---
+
+## 13) CI Hardening & Visual QA
+
+- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.
+- Unit: Run jest-axe for ui-kit-web and app-level components.
+- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).
+- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).
+- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.
+- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.
+
+### Recent additions (2025-09-26)
+
+- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with \`aria-controls\`, \`aria-activedescendant\`, \`Escape\`/\`Tab\` handling, and labelled listbox.
+- Cypress a11y tests added for furniture and incidents modules on \`/modules\` and operators flows; checks run axe with critical/serious impacts.
+
+## 14) Accessibility Telemetry (PostHog)
+
+- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.
+- Properties: app, route, previous_value, new_value, timestamp.
+- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.
+- Privacy: No PII; aggregate only.
+`
+  }
+];
+registerDocBlocks(accessibility_wcag_compliance_specs_DocBlocks);
+export {
+  accessibility_wcag_compliance_specs_DocBlocks
+};

package/dist/docs/capabilities/documentationSystem.capability.d.ts

@@ -1,7 +1,2 @@
-import { CapabilitySpec } from "../../capabilities/capabilities.js";
-import "../../index.js";
-
-//#region src/docs/capabilities/documentationSystem.capability.d.ts
-declare const DocumentationSystemCapability: CapabilitySpec;
-//#endregion
-export { DocumentationSystemCapability };
+export declare const DocumentationSystemCapability: import("../..").CapabilitySpec;
+//# sourceMappingURL=documentationSystem.capability.d.ts.map

package/dist/docs/capabilities/documentationSystem.capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentationSystem.capability.d.ts","sourceRoot":"","sources":["../../../src/docs/capabilities/documentationSystem.capability.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,6BAA6B,gCA8DxC,CAAC"}