@lssm/lib.contracts 0.0.0-canary-20251209233744 → 0.0.0-canary-20251210081515

package/dist/app-config/docs/app-config.docblock.js

@@ -0,0 +1,220 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.app-config`,title:`App Configuration Layers`,summary:`App orchestration is split into three explicit layers:`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/app-config`,tags:[`tech`,`contracts`,`app-config`],body:`## App Configuration Layers
+
+App orchestration is split into three explicit layers:
+
+1. **AppBlueprintSpec** – global, versioned description of what an app can look like. Stored in Git, no tenant/environment data.
+2. **TenantAppConfig** – tenant/environment overrides that the future Studio edits. Stored per tenant (DB/contract), mutable at runtime.
+3. **ResolvedAppConfig** – pure, merged view consumed by the runtime. Derived in-memory from a blueprint + tenant config.
+
+- Types & registry: \`packages/libs/contracts/src/app-config/spec.ts\`
+- Resolution helpers: \`packages/libs/contracts/src/app-config/runtime.ts\`
+- CLI wizard (blueprint scaffolding): \`contractspec create app-config\`
+
+### 1. AppBlueprintSpec
+
+\`\`\`ts
+export interface AppBlueprintSpec {
+  meta: AppBlueprintMeta;          // { name, version, appId, ownership }
+  capabilities?: { enabled?: CapabilityRef[]; disabled?: CapabilityRef[] };
+  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };
+  integrationSlots?: AppIntegrationSlot[];
+  branding?: BrandingDefaults;
+  dataViews?: Record<string, SpecPointer>;
+  workflows?: Record<string, SpecPointer>;
+  policies?: PolicyRef[];
+  theme?: AppThemeBinding;
+  telemetry?: TelemetryBinding;
+  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };
+  featureFlags?: FeatureFlagState[];
+  routes?: AppRouteConfig[];
+  notes?: string;
+}
+\`\`\`
+
+Register blueprints with \`AppBlueprintRegistry\`. Blueprints only capture the default/global experience.
+
+- **Integration slots** declare the categories and capability requirements an app expects (e.g. \`"primary-payments"\` must be a payments provider that supports managed or BYOK credentials). Slots never include secrets; tenants bind concrete connections later.
+- **Branding defaults** provide message-key based names, placeholder assets, and theme token references that downstream tenants can override.
+
+### 2. TenantAppConfig
+
+\`\`\`ts
+export interface TenantAppConfig {
+  meta: TenantAppConfigMeta;  // { id, tenantId, appId, blueprintName/version, environment?, version, timestamps }
+  capabilities?: { enable?: CapabilityRef[]; disable?: CapabilityRef[] };
+  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };
+  dataViewOverrides?: TenantSpecOverride[];
+  workflowOverrides?: TenantSpecOverride[];
+  additionalPolicies?: PolicyRef[];
+  themeOverride?: { primary?: ThemeRef | null; fallbacks?: ThemeRef[] };
+  telemetryOverride?: { spec?: SpecPointer | null; disabledEvents?: string[] };
+  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };
+  featureFlags?: FeatureFlagState[];
+  routeOverrides?: TenantRouteOverride[];
+  integrations?: AppIntegrationBinding[];
+  knowledge?: AppKnowledgeBinding[];
+  branding?: TenantBrandingConfig;
+  notes?: string;
+}
+\`\`\`
+
+This object represents what a tenant edits via the Studio (stored in DB/contracts later).
+
+- **AppIntegrationBinding** now maps \`slotId\` → \`connectionId\` (plus optional workflow scopes). It no longer carries capability lists; those are defined once in the slot.
+- **TenantBrandingConfig** allows per-tenant names, assets, and domain overrides while keeping secrets and large files out of blueprints.
+
+### 3. ResolvedAppConfig
+
+\`\`\`ts
+export interface ResolvedAppConfig {
+  appId: string;
+  tenantId: string;
+  environment?: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+  capabilities: { enabled: CapabilityRef[]; disabled: CapabilityRef[] };
+  features: { include: FeatureRef[]; exclude: FeatureRef[] };
+  dataViews: Record<string, SpecPointer>;
+  workflows: Record<string, SpecPointer>;
+  policies: PolicyRef[];
+  theme?: AppThemeBinding;
+  telemetry?: TelemetryBinding;
+  experiments: { catalog: ExperimentRef[]; active: ExperimentRef[]; paused: ExperimentRef[] };
+  featureFlags: FeatureFlagState[];
+  routes: AppRouteConfig[];
+  integrations: ResolvedIntegration[];
+  knowledge: ResolvedKnowledge[];
+  branding: ResolvedBranding;
+  notes?: string;
+}
+\`\`\`
+
+Use \`resolveAppConfig(blueprint, tenant)\` to produce this merged view. No IO, no registry lookups—pure data merge.
+
+- \`resolveAppConfig\` validates slot/category/mode constraints when \`integrationConnections\` and \`integrationSpecs\` are provided.
+- \`branding\` merges blueprint defaults with tenant overrides, producing a runtime-friendly shape (resolved asset URLs, color values, and effective domain).
+
+### Materializing specs
+
+\`composeAppConfig(blueprint, tenant, registries, { strict })\`:
+
+1. Calls \`resolveAppConfig\` to build the merged pointers.
+2. Looks up referenced specs in the provided registries.
+3. Returns:
+   - \`resolved\` – the merged pointer view
+   - \`capabilities\`, \`features\`, \`dataViews\`, \`workflows\`, \`policies\`, \`theme\`, \`telemetry\`, \`experiments\`
+   - \`missing\` – unresolved references (strict mode throws).
+
+\`\`\`ts
+const blueprint = blueprintRegistry.get('core.app', 1)!;
+const tenant = loadTenantConfigFromDB();
+
+const composition = composeAppConfig(blueprint, tenant, {
+  capabilities,
+  features,
+  dataViews,
+  workflows,
+  policies,
+  themes,
+  telemetry,
+  experiments,
+});
+
+if (composition.missing.length) {
+  console.warn('Unresolved references', composition.missing);
+}
+\`\`\`
+
+### CLI workflow
+
+\`\`\`
+contractspec create app-config
+\`\`\`
+
+Generates an \`AppBlueprintSpec\`. A separate flow will later scaffold tenant configs.
+
+### Best practices
+
+1. Keep blueprint and tenant versions monotonic; bump when referenced spec versions change.
+2. Favor stable slot keys (e.g. \`dataViews.dashboard\`) to align with Studio UX.
+3. Reference telemetry and experiments declared in their respective specs to maintain observability.
+4. Run \`resolveAppConfig\` in pure unit tests and \`composeAppConfig(..., { strict: true })\` in CI to catch drift early.
+5. Pair resolved configs with \`TestSpec\` scenarios to guard tenant experiences end-to-end.
+
+### Static validation
+
+Use the validation helpers in \`@lssm/lib.contracts/app-config/validation\` to keep blueprints and tenant configs safe before publish time.
+
+\`\`\`ts
+import {
+  validateConfig,
+  validateBlueprint,
+  validateTenantConfig,
+  validateResolvedConfig,
+} from '@lssm/lib.contracts/app-config/validation';
+
+const context = {
+  integrationSpecs,
+  tenantConnections,
+  knowledgeSpaces,
+  knowledgeSources,
+  translationCatalogs: {
+    blueprint: blueprintCatalog,
+    platform: platformCatalog,
+  },
+  existingConfigs,
+};
+
+const blueprintReport = validateBlueprint(blueprint, context);
+const tenantReport = validateTenantConfig(blueprint, tenant, context);
+const publishReport = validateConfig(blueprint, tenant, context);
+\`\`\`
+
+- \`ValidationResult\` exposes \`valid\`, plus structured \`errors\`, \`warnings\`, and \`info\`.
+- Core rules cover capability references, integration slot bindings (category/ownership/capabilities), knowledge bindings, branding constraints (domains + assets), and translation coverage.
+- Call \`validateBlueprint\` in CI when committing new specs, and \`validateConfig\` before promoting/publishing a tenant config.
+- \`validateResolvedConfig\` can be used as a runtime pre-flight check when composing full configs for workflows.
+- CLI usage example (blueprint + tenant):
+
+\`\`\`
+pnpm contractspec validate \\
+  packages/examples/integration-stripe/blueprint.ts \\
+  --blueprint packages/examples/integration-stripe/blueprint.ts \\
+  --tenant-config packages/examples/integration-stripe/tenant.ts
+\`\`\`
+- Repository script:
+
+\`\`\`
+bun run validate:blueprints
+\`\`\`
+
+Runs the static validator for the sample blueprints/tenants and is wired into CI.
+
+
+### Lifecycle types & events
+
+To model multi-step configuration changes, use the lifecycle helpers exported from \`@lssm/lib.contracts/app-config\`:
+
+\`\`\`ts
+import type {
+  ConfigStatus,
+  TenantAppConfigVersion,
+  ConfigTransition,
+} from '@lssm/lib.contracts/app-config';
+import {
+  ConfigDraftCreatedEvent,
+  ConfigPromotedToPreviewEvent,
+  ConfigPublishedEvent,
+  ConfigRolledBackEvent,
+} from '@lssm/lib.contracts/app-config';
+\`\`\`
+
+- \`ConfigStatus\` enumerates the canonical states: \`draft\`, \`preview\`, \`published\`, \`archived\`, \`superseded\`.
+- \`TenantAppConfigMeta\` now includes lifecycle metadata (\`status\`, \`createdBy\`, \`publishedBy\`, \`publishedAt\`, \`rolledBackFrom\`, \`rolledBackTo\`, \`changeSummary\`).
+- \`TenantAppConfigVersion\` couples the lifecycle-aware metadata with the \`TenantAppConfig\` payload for history views.
+- \`ConfigTransition\` captures state changes with actor, timestamp, and optional reason.
+- Lifecycle events (\`app_config.draft_created\`, \`app_config.promoted_to_preview\`, \`app_config.published\`, \`app_config.rolled_back\`) standardize observability across services.
+- Lifecycle contract specs (\`appConfig.lifecycle.*\`) expose typed commands/queries for create → preview → publish → rollback flows.
+
+`}];e(t);export{t as tech_contracts_app_config_DocBlocks};

package/dist/capabilities/docs/capabilities.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.capabilities`,title:`CapabilitySpec Overview`,summary:"Capability specs provide a canonical, versioned contract for what a module offers (`provides`) and what it depends on (`requires`). They enable safe composition across features, automated validation during `installFeature`, and consistent documentation for shared surfaces (APIs, events, workflows, UI, resources).",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/capabilities`,tags:[`tech`,`contracts`,`capabilities`],body:"# CapabilitySpec Overview\n\n## Purpose\n\nCapability specs provide a canonical, versioned contract for what a module offers (`provides`) and what it depends on (`requires`). They enable safe composition across features, automated validation during `installFeature`, and consistent documentation for shared surfaces (APIs, events, workflows, UI, resources).\n\n## Schema\n\nDefined in `@lssm/lib.contracts/src/capabilities.ts`.\n\n```ts\nexport interface CapabilitySpec {\n  meta: CapabilityMeta;              // ownership metadata + { key, version, kind }\n  provides?: CapabilitySurfaceRef[]; // what concrete surfaces this capability exposes\n  requires?: CapabilityRequirement[];// capabilities that must already exist\n}\n```\n\n- **CapabilityMeta**\n  - `key`: stable slug (e.g., `payments.stripe`)\n  - `version`: bump on breaking changes\n  - `kind`: `'api' | 'event' | 'data' | 'ui' | 'integration'`\n  - ownership fields (`title`, `description`, `domain`, `owners`, `tags`, `stability`)\n- **CapabilitySurfaceRef**\n  - `surface`: `'operation' | 'event' | 'workflow' | 'presentation' | 'resource'`\n  - `name` / `version`: points to the declared contract (operation name, event name, etc.)\n  - optional `description`\n- **CapabilityRequirement**\n  - `key`: capability slug to satisfy\n  - `version?`: pin to an exact version when required (defaults to highest registered)\n  - `kind?`: extra guard if the same key hosts multiple kinds\n  - `optional?`: skip strict enforcement (informational requirement)\n  - `reason?`: why this dependency exists (docs + tooling)\n\n## Registry\n\n`CapabilityRegistry` provides:\n\n- `register(spec)`: register a capability (`key + version` must be unique)\n- `get(key, version?)`: retrieve the exact or highest version\n- `list()`: inspect all capabilities\n- `satisfies(requirement, additional?)`: check if a requirement is met (includes locally provided capabilities passed via `additional`)\n\n## Feature Integration\n\n`FeatureModuleSpec` now accepts:\n\n```ts\ncapabilities?: {\n  provides?: CapabilityRef[];    // capabilities this feature exposes\n  requires?: CapabilityRequirement[]; // capabilities the feature needs\n};\n```\n\nDuring `installFeature`:\n\n1. `provides` entries must exist in the `CapabilityRegistry`.\n2. `requires` entries must be satisfied either by:\n   - the same feature’s `provides`,\n   - or existing capabilities already registered in the global registry.\n\nErrors are thrown when dependencies cannot be satisfied, preventing unsafe module composition.\n\n## Authoring Guidelines\n\n1. **Register capability specs** in a shared package (e.g., `packages/.../capabilities`) before referencing them in features.\n2. **Version consciously**: bump capability versions when the provided surfaces or contract semantics change.\n3. **Document dependencies** via `reason` strings to help operators understand why a capability is required.\n4. **Prefer stable keys** that map to business/technical domains (`billing.invoices`, `payments.stripe`, `cms.assets`).\n5. When introducing new capability kinds, update the `CapabilityKind` union and accompanying docs/tests.\n\n## Tooling (Roadmap)\n\n- CLI validation warns when feature specs reference missing capabilities.\n- Future build steps will leverage capability data to scaffold adapters and enforce policy in generated code.\n- Capability metadata will surface in docs/LLM guides to describe module marketplaces and installation flows.\n\n"}];e(t);export{t as tech_contracts_capabilities_DocBlocks};

package/dist/data-views/docs/data-views.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.data-views`,title:`DataViewSpec Overview`,summary:"`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/data-views`,tags:[`tech`,`contracts`,`data-views`],body:"# DataViewSpec Overview\n\n## Purpose\n\n`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.\n\n## Location\n\n- Type definitions and registry: `packages/libs/contracts/src/data-views.ts`\n- React renderers: `packages/libs/design-system/src/components/data-view`\n- CLI scaffolding: `contractspec create --type data-view`\n\n## Schema Highlights\n\n```ts\nexport interface DataViewSpec {\n  meta: DataViewMeta;       // ownership meta + { name, version, entity }\n  source: DataViewSource;   // contract operations and refresh events\n  view: DataViewConfig;     // union of list/detail/table/grid definitions\n  states?: DataViewStates;  // optional empty/error/loading presentations\n  policy?: { flags?: string[]; pii?: string[] };\n}\n```\n\n- **DataViewMeta**: `name`, `version`, `entity`, ownership metadata (title, description, domain, owners, tags, stability).\n- **DataViewSource**:\n  - `primary`: required query operation (`OpRef`) for fetching collections.\n  - `item`: optional detail query (recommended for `detail` views).\n  - `mutations`: optional create/update/delete operation refs.\n  - `refreshEvents`: events that should trigger refresh.\n- **DataViewConfig** (union):\n  - `list`: card/compact list, `primaryField`, `secondaryFields`.\n  - `table`: column configuration (`columns`, alignments, density).\n  - `detail`: sections of fields for record inspection.\n  - `grid`: multi-column grid (rendered as card list today).\n- **DataViewField**: `key`, `label`, `dataPath`, formatting hints (`format`), sort/filter toggles, optional presentation override.\n- **DataViewFilter**: describes filter inputs (search, enum, number, date, boolean).\n- **DataViewAction**: simple declarative actions (`navigation` or `operation`).\n\n## Registry Usage\n\n```ts\nimport { DataViewRegistry } from '@lssm/lib.contracts/data-views';\nimport { ResidentsDataView } from './data-views/residents.data-view';\n\nconst registry = new DataViewRegistry();\nregistry.register(ResidentsDataView);\n\nconst listView = registry.get('residents.admin.list');\n```\n\nRegistries guard against duplicate `(name, version)` pairs and make latest-version lookup trivial.\n\n## Rendering\n\n```tsx\nimport { DataViewRenderer } from '@lssm/lib.design-system';\nimport { ResidentsDataView } from '../contracts/data-views/residents.data-view';\n\nfunction ResidentsTable({ rows }: { rows: Record<string, unknown>[] }) {\n  return (\n    <DataViewRenderer\n      spec={ResidentsDataView}\n      items={rows}\n      onRowClick={(row) => console.log('Selected', row)}\n    />\n  );\n}\n```\n\nFor more control, use specific components:\n\n- `DataViewList` – friendly cards/rows\n- `DataViewTable` – tabular presentation with optional header/footers\n- `DataViewDetail` – two-column grouped layout for record inspection\n\nRenderers rely on the field definitions (`dataPath`, `format`) to extract values and render them consistently.\n\n## CLI Scaffolding\n\n```bash\n# Interactive wizard\ncontractspec create --type data-view\n\n# Generates packages/.../data-views/<name>.data-view.ts\n\n# Optional renderer scaffold\ncontractspec build path/to/<name>.data-view.ts\n# → produces <name>.renderer.tsx that wraps DataViewRenderer with sensible props\n```\n\nWizard prompts:\n- name (dot notation), version, entity\n- kind (`list`, `table`, `detail`, `grid`)\n- primary query operation (required) and optional item query\n- fields (label, data path, format, sorting/filtering)\n\n## Authoring Guidelines\n\n1. **Separation of data & presentation**: keep fetching logic inside contract operations; DataViewSpec only references them via `source`.\n2. **Versioning**: bump `meta.version` when field membership, ordering, or semantics change.\n3. **Consistency**: reuse common field keys across modules to enable shared renderers and filters.\n4. **States**: reference `PresentationRef` for empty/error/loader states to ensure consistent UX.\n5. **Actions**: prefer referencing contract operations instead of embedding business logic in the UI.\n\n## Roadmap\n\n- Derived filters from `fields.filterable` (auto-generated UI).\n- Table density presets per platform.\n- Bridge to PolicySpec for field-level visibility (Phase 2 policy expansion).\n- Automated docs/LLM sync via CLI.\n\n"}];e(t);export{t as tech_contracts_data_views_DocBlocks};

package/dist/docs/PUBLISHING.docblock.js

@@ -0,0 +1,76 @@
+import{registerDocBlocks as e}from"./registry.js";const t=[{id:`docs.PUBLISHING`,title:`Publishing ContractSpec Libraries`,summary:`This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).`,kind:`reference`,visibility:`public`,route:`/docs/PUBLISHING`,tags:[`PUBLISHING`],body:`# Publishing ContractSpec Libraries
+
+This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).
+
+## Release Tracks
+
+| Track | Branch | npm Tag | Frequency | Versioning | Use Case |
+|-------|--------|---------|-----------|------------|----------|
+| **Stable** | \`release\` | \`latest\` | Manual | SemVer (e.g., \`1.7.4\`) | Production, external users |
+| **Canary** | \`main\` | \`canary\` | Every Push | Snapshot (e.g., \`1.7.4-canary...\`) | Dev, internal testing |
+
+## Prerequisites
+
+- ✅ \`NPM_TOKEN\` secret is configured in GitHub (owner or automation token with _publish_ scope).
+- ✅ \`GITHUB_TOKEN\` (built-in) has permissions to create PRs (enabled by default in new repos).
+- ✅ For stable releases: \`release\` branch exists and is protected.
+
+## Canary Workflow (Automatic)
+
+Every commit pushed to \`main\` triggers the \`.github/workflows/publish-canary.yml\` workflow.
+
+1. **Trigger**: Push to \`main\`.
+2. **Versioning**: Runs \`changeset version --snapshot canary\` to generate a temporary snapshot version.
+3. **Publish**: Packages are published to npm with the \`canary\` tag using \`changeset publish --tag canary\`.
+
+### Consuming Canary Builds
+
+To install the latest bleeding-edge version:
+
+\`\`\`bash
+npm install @lssm/lib.contracts@canary
+# or
+bun add @lssm/lib.contracts@canary
+\`\`\`
+
+## Stable Release Workflow (Manual)
+
+Stable releases are managed via the \`release\` branch using the standard [Changesets Action](https://github.com/changesets/action).
+
+1. **Develop on \`main\`**: Create features and fixes.
+2. **Add Changesets**: Run \`bun changeset\` to document changes and impact (major/minor/patch).
+3. **Merge to \`release\`**: When ready to ship, open a PR from \`main\` to \`release\` or merge manually.
+4. **"Version Packages" PR**:
+   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **"Version Packages"**.
+   - This PR contains the version bumps and updated \`CHANGELOG.md\` files.
+5. **Merge & Publish**:
+   - Review and merge the "Version Packages" PR.
+   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the \`latest\` tag.
+
+### Publishing Steps
+
+1. Ensure all changesets are present on \`main\`.
+2. Merge \`main\` into \`release\`:
+   \`\`\`bash
+   git checkout release
+   git pull origin release
+   git merge main
+   git push origin release
+   \`\`\`
+3. Go to GitHub Pull Requests. You will see a **"Version Packages"** PR created by the bot.
+4. Merge that PR.
+5. The release is now live on npm!
+
+## Manual Verification (Optional)
+
+Before publishing a new version you can run:
+
+\`\`\`bash
+bun run build:not-apps
+npx npm-packlist --json packages/libs/contracts
+\`\`\`
+
+## Rollback
+
+If a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use \`npm deprecate <package>@<version>\` if we need to warn consumers about a broken release.
+`}];e(t);export{t as PUBLISHING_DocBlocks};

package/dist/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -0,0 +1,350 @@
+import{registerDocBlocks as e}from"./registry.js";const t=[{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**
+
+> **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)**.
+
+---
+
+## 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:** “No ARIA is better than bad ARIA.” 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‑app duplicates (\`packages/*/apps/*/src/components/ui\`). When missing, add to \`ui-kit-web\` first, then adopt app‑side.
+
+---
+
+## 1) Design Requirements (Design System & Tokens)
+
+**1.1 Color & Contrast**
+
+- Body text, icons essential to meaning: **≥\xA04.5:1**; large text (≥\xA018.66px regular / 14px bold): **≥\xA03:1**.
+- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥\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 **≥\xA03:1** vs adjacent colors and indicator **area ≥\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‑animations; 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 **≥\xA024×24\xA0CSS\xA0px** (web) and **≥\xA044×44\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…h6), one **h1** per view.
+
+- 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\`.
+- 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.
+- 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 “click here”).
+- Buttons start with verbs; avoid ambiguous labels.
+- Form labels are **visible**; placeholders are **not labels**.
+- Error messages: human + programmatic association; avoid color‑only.
+- 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 — 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 → 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’t 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‑playing audio. Auto‑playing 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 \`@lssm/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 '@lssm/lib.accessibility'; // includes tokens and provider exports
+// or if needed: import '@lssm/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 — Component Patterns & Defaults
+
+> Source: \`packages/lssm/libs/ui-kit-web/ui/*\`
+
+- **Button/Input/Textarea**: Built‑in \`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‑trap and return‑focus. Provide \`DialogTitle\` + \`DialogDescription\` for name/description.
+- **Select/Combobox**: Prefer \`SelectTrigger\` with visible label; for icon‑only triggers, supply \`aria-label\`. Document examples in each app.
+- **Tabs**: Use \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`; names are programmatically determinable.
+- **Toast/Toaster**: Prefer non‑blocking 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‑size variants (≥44×44) for interactive atoms.
+
+---
+
+## 4) Engineering Requirements (Mobile — Expo/React\xA0Native)
+
+- Set \`accessibilityLabel\`, \`accessibilityHint\`, and \`accessibilityRole\` on touchables.
+- Ensure **hit slop** / min size **≥\xA044×44\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 / “Load More”**
+
+- Provide **Load more** control; announce new content to SR; preserve keyboard position.
+
+**Drag & Drop (2.5.7)**
+
+- Provide **non‑drag** 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\` — error on violations.
+- \`jest-axe\` — 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 **≥\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–400% & 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‑Specific Adoption Plan
+
+- Centralize UI usage on \`packages/lssm/libs/ui-kit-web\` and de‑duplicate per‑app \`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‑size 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">…</main>
+\`\`\`
+
+**Dialog (Radix + shadcn/ui) — 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‑visible 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’t 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.
+`}];e(t);export{t as accessibility_wcag_compliance_specs_DocBlocks};