@contractspec/lib.contracts-spec 2.0.0

package/dist/data-views/types.d.ts

@@ -0,0 +1,152 @@
+import type { OwnerShipMeta } from '../ownership';
+import type { EventRef, OpRef, PresentationRef } from '../features';
+/**
+ * Supported data view kinds.
+ */
+export type DataViewKind = 'list' | 'detail' | 'table' | 'grid';
+/**
+ * Metadata for a data view spec.
+ */
+export interface DataViewMeta extends OwnerShipMeta {
+    /** Canonical entity slug (e.g., "space", "resident"). */
+    entity: string;
+}
+/**
+ * Source configuration for fetching data in a data view.
+ */
+export interface DataViewSource {
+    /** Primary query used to fetch items for this view. */
+    primary: OpRef;
+    /** Optional operation used to fetch a single item (detail views). */
+    item?: OpRef;
+    /** Optional record mutation operations (used for inline editing or actions). */
+    mutations?: {
+        create?: OpRef;
+        update?: OpRef;
+        delete?: OpRef;
+    };
+    /** Events that should trigger refresh when emitted. */
+    refreshEvents?: EventRef[];
+}
+/**
+ * Display formatting hints for data view fields.
+ */
+export type DataViewFieldFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'dateTime' | 'boolean' | 'markdown' | 'badge';
+/**
+ * Field definition within a data view.
+ */
+export interface DataViewField {
+    /** Unique identifier for the field within the view. */
+    key: string;
+    /** Human-friendly label for headers/tooltips. */
+    label: string;
+    /** Dot-path into the data item (e.g., "address.city"). */
+    dataPath: string;
+    /** Optional description surfaced in tooltips or docs. */
+    description?: string;
+    /** Optional formatting hint for renderers. */
+    format?: DataViewFieldFormat;
+    /** When true, the field can be used for sorting. */
+    sortable?: boolean;
+    /** When true, the field can be used for filtering. */
+    filterable?: boolean;
+    /** Optional width hint for table layouts. */
+    width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+    /** Optional presentation override (e.g., card component). */
+    presentation?: PresentationRef;
+}
+/**
+ * Filter definition for a data view.
+ */
+export interface DataViewFilter {
+    key: string;
+    label: string;
+    field: string;
+    type: 'search' | 'enum' | 'number' | 'date' | 'boolean';
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+/**
+ * Action that can be triggered from a data view.
+ */
+export interface DataViewAction {
+    key: string;
+    label: string;
+    kind: 'navigation' | 'operation';
+    /** Operation invoked when kind === 'operation'. */
+    operation?: OpRef;
+    /** Optional feature flag gating the action. */
+    requiresFlag?: string;
+}
+/**
+ * Section configuration for detail views.
+ */
+export interface DataViewSections {
+    title?: string;
+    description?: string;
+    fields: string[];
+}
+/**
+ * Base configuration shared by all data view kinds.
+ */
+export interface DataViewBaseConfig {
+    kind: DataViewKind;
+    fields: DataViewField[];
+    primaryField?: string;
+    secondaryFields?: string[];
+    filters?: DataViewFilter[];
+    actions?: DataViewAction[];
+}
+/**
+ * List view configuration.
+ */
+export interface DataViewListConfig extends DataViewBaseConfig {
+    kind: 'list';
+    layout?: 'card' | 'compact';
+}
+/**
+ * Detail view configuration.
+ */
+export interface DataViewDetailConfig extends DataViewBaseConfig {
+    kind: 'detail';
+    sections?: DataViewSections[];
+}
+/**
+ * Table column configuration.
+ */
+export interface DataViewTableColumn {
+    field: string;
+    label?: string;
+    width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * Table view configuration.
+ */
+export interface DataViewTableConfig extends DataViewBaseConfig {
+    kind: 'table';
+    columns?: DataViewTableColumn[];
+    rowSelectable?: boolean;
+    density?: 'comfortable' | 'compact';
+}
+/**
+ * Grid view configuration.
+ */
+export interface DataViewGridConfig extends DataViewBaseConfig {
+    kind: 'grid';
+    columns?: number;
+}
+/**
+ * Union of all data view configurations.
+ */
+export type DataViewConfig = DataViewListConfig | DataViewDetailConfig | DataViewTableConfig | DataViewGridConfig;
+/**
+ * Presentation references for different view states.
+ */
+export interface DataViewStates {
+    empty?: PresentationRef;
+    error?: PresentationRef;
+    loading?: PresentationRef;
+}

package/dist/data-views/types.js

@@ -0,0 +1 @@
+// @bun

package/dist/data-views/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/docs/accessibility_wcag_compliance_specs.docblock.d.ts

@@ -0,0 +1,2 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
+export declare const accessibility_wcag_compliance_specs_DocBlocks: DocBlock[];

package/dist/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -0,0 +1,513 @@
+// @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**
+
+- 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

@@ -0,0 +1 @@
+export declare const DocumentationSystemCapability: import("../..").CapabilitySpec;