@trinityui/design-system 2.11.1 → 2.13.0

package/README.md

@@ -1,6 +1,10 @@
 # Trinity Design System
 
-Enterprise component platform built on **MUI v9** for [Trinity LifeSciences](https://trinitylifesciences.com). Provides 100+ accessible React components, a 3-tier design token system, 35+ AI-specific components, 17 chart types, 18 custom hooks, and a CSS-only package for non-React consumers.
+<!-- catalog-counts:start intro -->
+
+Enterprise component platform built on **MUI 9** and **React 19** for [Trinity LifeSciences](https://trinitylifesciences.com). Provides 143 accessible React components (43 of them AI and human-in-the-loop components, 17 chart components and 13 page templates), 32 hooks, a 3-tier design token system, and a CSS-only package for non-React consumers, with the tokens, the React theme and the CSS package kept in parity.
+
+<!-- catalog-counts:end intro -->
 
 [![npm version](https://img.shields.io/npm/v/@trinityui/design-system.svg)](https://www.npmjs.com/package/@trinityui/design-system)
 [![npm css package](https://img.shields.io/npm/v/@trinityui/design-system-css.svg)](https://www.npmjs.com/package/@trinityui/design-system-css)
@@ -15,16 +19,18 @@ Enterprise component platform built on **MUI v9** for [Trinity LifeSciences](htt
 - [Packages & Entry Points](#packages--entry-points)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [What's New in 2.13.0](#whats-new-in-2130)
 - [Component Catalog](#component-catalog)
-  - [Navigation](#navigation-6-components)
-  - [Layout](#layout-7-components)
-  - [AI](#ai-35-components)
-  - [Data Display](#data-display-8-components)
-  - [Input & Forms](#input--forms-18-components)
-  - [Feedback](#feedback-7-components)
-  - [Charts](#charts-17-components)
+  - [Navigation](#navigation)
+  - [Layout](#layout)
+  - [AI](#ai)
+  - [Data Display](#data-display)
+  - [Input & Forms](#input--forms)
+  - [Feedback](#feedback)
+  - [Charts](#charts)
   - [Icon System](#icon-system)
-- [Hooks](#hooks-18)
+  - [Patterns](#patterns)
+- [Hooks](#hooks-33)
 - [Accessibility](#accessibility)
 - [Design Tokens](#design-tokens)
 - [Theme Presets](#theme-presets)
@@ -39,20 +45,25 @@ Enterprise component platform built on **MUI v9** for [Trinity LifeSciences](htt
 
 ## Key Capabilities
 
+<!-- catalog-counts:start capabilities -->
+
 | Capability | Details |
 |---|---|
-| **100+ Components** | Navigation, layout, AI, data display, inputs, feedback, charts |
-| **35+ AI Components** | InsightEngine, ChatThread, ChainOfThought, voice input, explainability, sources, personas |
-| **17 Chart Types** | Line, bar, area, pie, donut, scatter, bubble, radial, gauge, composed, sparkline |
-| **3-Tier Design Tokens** | Base → Semantic → Component tokens with CSS variable output |
-| **Dark Mode** | Automatic light/dark themes with WCAG 2.1 AA color contrast |
+| **143 Components** | Navigation, layout, AI, data display, inputs, feedback, charts |
+| **43 AI Components** | InsightEngine, ChatThread, AIMessage, AIChainOfThought, the human-in-the-loop blocks, voice input, explainability, sources, personas |
+| **17 Chart Components** | Line, bar, area, pie, donut, scatter, bubble, radial, gauge, composed, sparkline, plus the chart wrapper, tooltips and legends |
+| **13 Page Templates** | Dashboard, list-detail, settings, auth, catalog, wizard, report, the AI review queue and more, plus one pattern (`AICopilotPattern`) |
+| **3-Tier Design Tokens** | Base → Semantic → Component tokens; the React theme and the CSS variables are generated from the same source and kept in parity |
+| **Dark Mode** | Automatic light/dark themes with WCAG 2.2 AA color contrast |
 | **3 Theme Presets** | CRM (compact), Portal (accessible), Analytics (data-viz) |
-| **18 Custom Hooks** | Debounce, clipboard, breakpoints, focus trap, roving tabindex, and more |
-| **TypeScript-First** | 200+ exports with full type definitions |
-| **CSS-Only Package** | Angular, Vue, and static HTML support via CSS variables |
+| **32 Hooks** | Debounce, clipboard, breakpoints, disclosure, roving tabindex, live announcements, and more |
+| **TypeScript-First** | 850 root exports with full type definitions |
+| **CSS-Only Package** | Angular, Vue, and static HTML support through 1186 `--trinity-*` CSS variables |
 | **80+ Brand Assets** | Gradient icons, background images, logos |
-| **Bundle Governance** | Size-limit enforced: core ≤50KB, main ≤200KB |
-| **Accessibility** | axe-core testing, eslint-plugin-jsx-a11y, ARIA hooks, skip links, focus traps |
+| **Bundle Governance** | A size-limit ratchet on every public entry; each raise is measured and recorded |
+| **Accessibility** | WCAG 2.2 AA: axe on every story, a strict behavior contract, live announcements, skip links, forced colors and reduced motion |
+
+<!-- catalog-counts:end capabilities -->
 
 ---
 
@@ -68,7 +79,7 @@ Enterprise component platform built on **MUI v9** for [Trinity LifeSciences](htt
 ┌──────────────────────────┐  ┌─────────────────────────────────┐
 │    MUI Theme Layer        │  │   CSS Variables Build            │
 │  lightTheme / darkTheme   │  │   generate-css-from-tokens.ts    │
-│  + 3 preset themes        │  │   trinity.css / trinity-base.css │
+│  + 3 preset themes        │  │   trinity-generated.css          │
 └──────────┬───────────────┘  └──────────┬──────────────────────┘
            │                             │
            ▼                             ▼
@@ -82,15 +93,19 @@ Enterprise component platform built on **MUI v9** for [Trinity LifeSciences](htt
 
 ## Packages & Entry Points
 
+<!-- catalog-counts:start entry-points -->
+
 | Package / Import | Exports | Use Case |
-|---|---|---|
-| `@trinityui/design-system` | 200+ | Full API — all components, hooks, tokens, utilities |
-| `@trinityui/design-system/essentials` | 16 | Quick-start — theme + core components |
-| `@trinityui/design-system/theme` | ~10 | Theme utilities only (tree-shakeable) |
-| `@trinityui/design-system/tokens` | ~30 | Design tokens only (tree-shakeable) |
-| `@trinityui/design-system/data-table` | 3 | DataTable + AG Grid Enterprise license setup |
-| `@trinityui/design-system/css` | — | CSS file from the React package |
-| `@trinityui/design-system-css` | — | Standalone CSS-only package for non-React apps |
+|---|---:|---|
+| `@trinityui/design-system` | 850 | Full API: components, templates, patterns, hooks, tokens, themes and utilities |
+| `@trinityui/design-system/essentials` | 45 | Quick start: the themes and the core components |
+| `@trinityui/design-system/theme` | 52 | Theme utilities only (tree-shakeable) |
+| `@trinityui/design-system/tokens` | 131 | Design tokens only (tree-shakeable) |
+| `@trinityui/design-system/data-table` | 6 | DataTable and the AG Grid Enterprise license setup |
+| `@trinityui/design-system/css` | CSS file | The CSS variables, from the React package |
+| `@trinityui/design-system-css` | 1186 CSS variables | Standalone CSS-only package for non-React apps |
+
+<!-- catalog-counts:end entry-points -->
 
 ---
 
@@ -102,12 +117,9 @@ Enterprise component platform built on **MUI v9** for [Trinity LifeSciences](htt
 pnpm add @trinityui/design-system react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled
 ```
 
-**Optional dependencies** (install only if using these features):
+**Requirements:** React and React DOM 19.2.4 or later, MUI 9 (`@mui/material`, `@mui/icons-material`), Emotion 11.14 or later, and Node 20, 22 or 24 ([support matrix](./SUPPORT.md)).
 
-```bash
-pnpm add recharts              # Charts
-pnpm add @mui/x-date-pickers dayjs  # DatePicker
-```
+There are no optional dependencies to add: the chart (Highcharts), DataTable (AG Grid) and flow-layout libraries install with the package. DataTable's Enterprise features need your AG Grid license key; set it once at startup with `setAgGridEnterpriseLicenseKey` from `@trinityui/design-system/data-table` (see [Data Display](#data-display)).
 
 ### CSS-only package
 
@@ -137,6 +149,8 @@ export function AppProviders({ children }: { children: React.ReactNode }) {
 }
 ```
 
+Pick a [theme preset](#theme-presets) instead of `lightTheme` when your product is a dense CRM (`crmLightTheme`), a customer portal (`portalLightTheme`) or an analytics app (`analyticsLightTheme`); each has a dark twin. Build your own with `createTrinityTheme(mode, overrides)` or `createTrinityThemePreset(options)`.
+
 ### 2. Import strategy
 
 Use **MUI** for standard UI primitives. Use **Trinity** for domain-specific components, tokens, and hooks.
@@ -160,13 +174,67 @@ import { lightTheme, darkTheme } from '@trinityui/design-system';
 </ThemeProvider>
 ```
 
-For the full getting-started guide, see [docs/QUICK_START.md](./docs/QUICK_START.md).
+### 4. Add the AI assistant
+
+`AppLayout` is the app shell; with `aiTrigger="fab"` it opens an AI panel, docked and resizable (320 to 800px) or fullscreen, and a full-width drawer on phones. Wire your backend through `panelProps`:
+
+```tsx
+import { AppLayout, type ChatMessage } from '@trinityui/design-system';
+
+<AppLayout
+  navStyle="topnav"
+  aiTrigger="fab"
+  panelProps={{
+    messages,
+    onMessagesChange: setMessages,
+    onSendMessage: (text, options) => ask(text, options),
+    streaming: waitingForAnswer,
+    userInitials: user.initials,
+    messageActions: { onFeedback: rate, onRegenerate: regenerate },
+  }}
+>
+  <Page />
+</AppLayout>
+```
+
+| Option | Default | What it does |
+|---|---|---|
+| `aiPanelSide` | `'end'` | `'start'` docks the panel before the page content (the FAB, the resize handle and the phone drawer follow) |
+| `aiPanelWidth` | `420` | The panel's first width; people resize it from 320 to 800px by dragging or with the arrow keys |
+| `keepAiPanelMounted` | `false` | Keeps the draft, the conversation and the scroll position while the panel is closed |
+| `renderAiPanel` | none | Renders your own surface (for example `AICopilotPattern` or `InsightEngine presentation="embedded"`) inside the same panel, with `onClose`, `isFullscreen` and `onFullscreenToggle` |
+| `showFabWhenPanelOpen` | `false` | Keeps the AI FAB beside the docked panel; by default it hides while the panel is open and focus returns to it on close |
+| `mobilePanelPresentation` | `'drawer'` | `'docked'` keeps the desktop panel below the `md` breakpoint |
+
+Answers with plans to confirm, clarifying questions, queries, confidence, verification and reasoning use the same panel (`onBlockEvent`, `getReasoning`); [the AI panel guide](./docs/APPLAYOUT_AI_PANEL.md) explains the three routes and the 2.13.0 panel changes, and [the AI table](#ai) says which component does what.
+
+### 5. AI strings and white-labelling
+
+The AI components read their built-in strings from one catalog, which `AIConfigProvider` replaces for translation and white-labelling, with the confidence thresholds, locale and time zone ([Overriding strings](./docs/MICROCOPY.md#overriding-strings)). The provider is not a package export yet: it waits for its component proposal vote, and the Storybook page AI/AIConfigProvider shows the proposed API. Until it ships, use the components' own props (for example the panel's `title` and `placeholder`).
+
+### 6. Without React
+
+Load the CSS package and use the `--trinity-*` variables; `data-theme="dark"` switches the mode. See [CSS-Only Usage](#css-only-usage) and the CSS AI agent guide in Storybook (Getting Started/AI Agent Guide (CSS)).
+
+For the full getting-started guide, see [docs/QUICK_START.md](./docs/QUICK_START.md) and the Getting Started page in Storybook.
+
+---
+
+## What's New in 2.13.0
+
+2.13.0 ships the remediation program's work in one minor release; nothing is removed (removals wait for v3.0).
+
+- **AI and human in the loop:** `AIPlanReview`, `AIClarificationPrompt`, `AIQueryDisclosure`, `AIConfidenceBadge`, `AIVerificationBadge`, `AIFeedbackControl` and `AIFeedbackForm`, `AISourceChip` with inline citations, `AIRelatedQuestions`, `AIReviewItem` and the new `AIReviewQueueTemplate`, the golden-dataset action on `AIMessage`, the `AIChatWelcome` start screen, the redesigned `AIChainOfThought`, and the `AICopilotPattern` pattern.
+- **AppLayout's AI panel:** messages render through `ChatThread` with the interactive blocks; `aiPanelSide`, `keepAiPanelMounted`, `renderAiPanel`, `showFabWhenPanelOpen` and the phone drawer are new.
+- **Theme:** new colour roles (the AI avatar and launcher gradient, AI progress, the start-screen canvas, favorite), each in the tokens, the React theme and the CSS package.
+- **Accessibility:** WCAG 2.2 AA, a strict behavior contract on every component, and screen-reader announcements across the AI set.
+- **Behavior corrections:** defaults that were objectively broken change in this minor (ADR-23). [MIGRATION.md, Behavior corrections](./MIGRATION.md#behavior-corrections-2x) lists each one with its before, after, opt-out and consumer action (the release adds the rows from its changesets), and the release notes land in [CHANGELOG.md](./CHANGELOG.md) when 2.13.0 is published.
 
 ---
 
 ## Component Catalog
 
-### Navigation (6 components)
+### Navigation
 
 | Component | Import | Description |
 |---|---|---|
@@ -181,7 +249,7 @@ Also exports: `TrinityLogo`, `UserMenu`, `HeaderActions`, and 14 navigation type
 
 ---
 
-### Layout (7 components)
+### Layout
 
 | Component | Import | Description |
 |---|---|---|
@@ -193,74 +261,122 @@ Also exports: `TrinityLogo`, `UserMenu`, `HeaderActions`, and 14 navigation type
 | `InsightEnginePanel` | `@trinityui/design-system` | AI insight panel designed for AppLayout integration |
 | `LandingPage` | `@trinityui/design-system` | Pre-built landing page template |
 
-Also exports: 3 page templates (`DashboardTemplate`, `ListDetailTemplate`, `SettingsTemplate`).
+Also exports the page templates (`DashboardTemplate`, `ListDetailTemplate`, `SettingsTemplate` and the others under `Templates/` in Storybook). Templates and patterns are public components, imported from the root like everything else.
 
 ---
 
-### AI (35+ components)
+### AI
 
 The largest component category — a full suite for building AI-powered experiences.
 
+<!-- catalog-counts:start ai-table -->
+
 #### AI Containers & Orchestration
 
-| Component | Description |
-|---|---|
-| `InsightEngine` | Top-level AI experience orchestrator |
-| `ChatThread` | Scrollable conversation thread with message grouping |
-| `ChatHeader` | Chat view header with mode switching |
-| `ChatHistoryList` | Navigable list of past conversations |
+| Component | Description | Storybook |
+|---|---|---|
+| `InsightEngine` | A whole AI surface: header, history, `ChatThread` and composer; a right-anchored drawer (`presentation="drawer"`, the default) or `presentation="embedded"` to fill its parent | AI/InsightEngine |
+| `InsightEnginePanel` | The AI panel of `AppLayout` (`aiTrigger`; configure it with `panelProps` or replace it with `renderAiPanel`): docked and resizable or fullscreen, a modal drawer below `md`. Renders its messages through `ChatThread`, with `messageActions` / `onRegenerate`, `getReasoning` (an `AIChainOfThought` in the message), `onBlockEvent` and `blockRenderers` (the interactive blocks, `hitlBlockRenderers` by default) | Templates/InsightEnginePanel |
+| `AIChatWelcome` | The AI start screen before the first message, in the `showcase` (greeting, centred composer, category cards) or `context` variant (scope chips, Continue, New since yesterday, Try asking); laid out by its container width; the default start screen of `InsightEnginePanel` and `InsightEngine` (`welcome`) | AI/AIChatWelcome |
+| `ChatThread` | The conversation log: each turn as `AIMessage` or `UserMessage`, with the message actions (`messageActions`), the interactive blocks (`onBlockEvent`, `blockRenderers`, `renderBlock`), per-message slots (`getMessageSlots`) and the follow-up questions | AI/ChatThread |
+| `ChatHeader` | Chat view header with mode switching | AI/ChatHeader |
+| `ChatHistoryList` | Navigable list of past conversations | AI/ChatHistoryList |
 
 #### AI Input
 
-| Component | Description |
-|---|---|
-| `InsightEngineInput` | Primary AI query input with context awareness |
-| `AIVoiceOverlay` | Voice input overlay with transcription |
-| `AIListeningIndicator` | Animated listening state indicator |
-| `PredictiveTextInput` | AI-powered autocomplete text input (OpenAI-compatible) |
-| `AIChatInput` | Lightweight chat input primitive |
-| `AIQuickReply` | Quick-reply suggestion chips |
+| Component | Description | Storybook |
+|---|---|---|
+| `InsightEngineInput` | The AI composer: send, stop while generating, mentions, models and sources, voice input, and an unavailable state with its reason | AI/InsightEngineInput |
+| `AIVoiceOverlay` | Voice input overlay with transcription | AI/Chat Components |
+| `AIVoiceMode` | Full-screen voice conversation mode: an orb that follows the conversation, a live transcript, mute and end | AI/AIVoiceMode |
+| `AIListeningIndicator` | Animated listening state indicator | AI/Chat Components |
+| `PredictiveTextInput` | AI-powered autocomplete text input (OpenAI-compatible) | Form Inputs/PredictiveTextInput |
+
+#### AI Human in the Loop
+
+| Component | Description | Storybook |
+|---|---|---|
+| `AIPlanReview` | The plan the AI proposes before it runs a query, for the user to review, correct and confirm (inline or in a dialog; `readOnly` for the record) | AI/AIPlanReview |
+| `AIReviewItem` | One answer in a golden-dataset review: the question, what produced the answer, and the reviewer's approve, edit or reject decision with its history | AI/AIReviewItem |
+| `AIClarificationPrompt` | A clarifying question the AI asks before it answers: options, a free-text answer and a typed result the backend can act on | AI/AIClarificationPrompt |
+| `AIQueryDisclosure` | The query behind an answer, shown on demand, with Copy | AI/AIQueryDisclosure |
+| `AIFeedbackControl` | Thumbs up and down on an answer, and the "Tell us what went wrong" flow | AI/AIFeedbackControl |
+| `AIFeedbackForm` | What went wrong with an answer: problem types, a comment and an optional rerun | AI/AIFeedbackForm |
+| `AIConfidenceBadge` | How confident the AI is in an answer, as a level and a percent, with the rationale on demand | AI/AIConfidenceBadge |
+| `AIVerificationBadge` | Who checked an answer or a plan, as a glyph and a label, with the details on demand | AI/AIVerificationBadge |
 
 #### AI Rendering & Explainability
 
-| Component | Description |
-|---|---|
-| `AIResponseRenderer` | Renders structured AI responses (text, tables, charts, actions) |
-| `AITextBlock` | Styled text block for AI output with streaming support |
-| `AIChainOfThought` | Multi-phase reasoning visualization (understand → plan → execute → output) |
-| `AIExplainability` | Confidence scores and explainability panel |
-| `AISource` / `AISourcesSection` / `AISourcesPanel` | Source citations — individual, grouped, and full panel views |
-| `AIRelatedQuestions` | Suggested follow-up questions |
+| Component | Description | Storybook |
+|---|---|---|
+| `AIResponseRenderer` | Renders an AI response's blocks: text blocks natively (through `AITextBlock`); the interactive blocks through `hitlBlockRenderers`; tables, charts and other block types through your `blockRenderers` (one component per block type) or `renderBlock` | AI/AIResponseRenderer |
+| `AITextBlock` | Text of an AI response: plain text, or lightweight markdown (bold, italic, code, links, headings, lists, quotes, fenced code) with opt-in `[^id]` source citations and `headingOffset` | AI/AITextBlock |
+| `AIChainOfThought` | The reasoning behind an answer: thinking, a plan awaiting confirmation, execution with failed tasks and Retry, and the output | AI/AIChainOfThought |
+| `AIExplainability` | Confidence scores and explainability panel | AI/AIExplainability |
+| `AISource` | One source citation | none yet |
+| `AISourcesSection` | A simple list of source citations | AI/AISourcesSection |
+| `AISourcesPanel` | Source citations grouped by category | AI/AISourcesPanel |
+| `AISourceChip` | One source at the number, sentence, table cell or chart point it supports: a number or label chip that opens the source's details | AI/AISourceChip |
+| `AIRelatedQuestions` | Suggested follow-up questions | AI/AIRelatedQuestions |
 
 #### AI Messages & Avatars
 
-| Component | Description |
-|---|---|
-| `AIMessage` | AI-authored message bubble with actions |
-| `UserMessage` | User-authored message bubble |
-| `AIChatMessage` | Lightweight chat message primitive |
-| `AIAvatar` | AI bot avatar (animated) |
-| `UserAvatar` | User avatar for chat contexts |
-| `AILabel` | "AI-generated" badge/label (multiple sizes and variants) |
+| Component | Description | Storybook |
+|---|---|---|
+| `AIMessage` | An assistant turn: the response blocks, sources, follow-ups, the reasoning slot and the actions (Copy always; Feedback, Share, Download and Regenerate when their handler is passed) | AI/AIMessage |
+| `UserMessage` | A user turn | AI/UserMessage |
+| `AIAvatar` | AI bot avatar (animated) | AI/AIAvatar |
+| `UserAvatar` | User avatar for chat contexts | AI/AIAvatar |
+| `AILabel` | "AI-generated" badge/label (multiple sizes and variants) | AI/AILabel |
 
 #### AI Actions & Layout
 
-| Component | Description |
+| Component | Description | Storybook |
+|---|---|---|
+| `AISuggestedAction` | A suggested action as a pill button | AI/AISuggestedAction |
+| `AICircularAction` | A suggested action as a circular icon button | AI/AIActions |
+| `AIActionsGroup` | A group of suggested actions | AI/AIActions |
+| `AIContainer` | Themed container for AI content | AI/AIContainer |
+| `AIExpandableSection` | Collapsible section for AI detail panels | AI/AIExpandableSection |
+| `AIPersonaCard` | AI persona/agent identity card | AI/AIContainer |
+| `AIDigestCard` | An AI-generated daily or weekly briefing card | AI/AIDigestCard |
+| `GradientText` | Gradient text for AI headings | AI/AIVisuals |
+| `GradientIconBadge` | Gradient icon badge for AI UI | AI/AIVisuals |
+| `StatCard` | KPI stat card for AI dashboards | AI/AIVisuals |
+| `AIShimmer` | Shimmer loading state for AI content | AI/AIShimmer |
+
+#### AI Contracts & Helpers
+
+| Export | What it is |
 |---|---|
-| `AISuggestedAction` / `AICircularAction` / `AIActionsGroup` | AI-suggested action buttons and groups |
-| `AIContainer` | Themed container for AI content |
-| `AIExpandableSection` | Collapsible section for AI detail panels |
-| `AIPersonaCard` | AI persona/agent identity card |
-| `GradientText` / `GradientIconBadge` | Visual flourishes for AI UI |
-| `StatCard` | KPI stat card for AI dashboards |
-| `AIShimmer` | Shimmer loading state for AI content |
-| `AITypingIndicator` | Animated typing indicator |
+| `hitlBlockRenderers` | The built-in renderers of the interactive blocks (`query`, `clarification`, `plan-review`): pass as `blockRenderers` or spread into your own map |
+| `ChatThreadMessage` | One message of `ChatThread` (`role`, `content`, `response`, `sources`, `relatedQuestions`, `feedback`, `streaming`) |
+| `ChatThreadMessageSlots` | The slots of an assistant message (`badges`, `feedbackControl`, `attachments`) that `getMessageSlots` can replace |
+| `InsightEnginePanelMessageActions` | The panel's message actions: `onCopy`, `onFeedback`, `onFeedbackSubmit`, `onShare`, `onDownload`, `onRegenerate`, `getActions` |
+| `AIMessageAction` | An app action on an assistant message (`getActions`) |
+| `AIRelatedQuestion` | A follow-up question: its text, an optional stable id and the `verified` mark |
+| `aiTokens` | The AI design tokens |
+
+#### Deprecated (v3.0)
+
+These still work in 2.x and warn once in development; do not start new work with them ([MIGRATION.md](./MIGRATION.md)).
+
+| Deprecated | Use instead | Storybook |
+|---|---|---|
+| `AIChatMessage` | `AIMessage` (and `UserMessage` for the user's turn) | AI/AIMessage |
+| `AIChatInput` | `InsightEngineInput`, or `ChatThread` for a whole conversation | AI/AIChat |
+| `AITypingIndicator` | `AIMessage`'s streaming state with `AIShimmer` | AI/AIChat |
+| `AIQuickReply` | `AISuggestedAction` or `AIActionsGroup` | AI/AIChat |
+| `QueryInput` | `InsightEngineInput` | AI/InsightEngineInput |
+| `AIFabLayout` | `AppLayout` with `navStyle="topnav"` and `aiTrigger="fab"` | Templates/AppLayout |
+
+<!-- catalog-counts:end ai-table -->
 
 All AI components import from `@trinityui/design-system`. AI-specific design tokens available via `aiTokens`.
 
 ---
 
-### Data Display (8 components)
+### Data Display
 
 | Component | Import | Description |
 |---|---|---|
@@ -339,12 +455,12 @@ Optional header regions can be disabled when the consuming app owns those contro
 
 ---
 
-### Input & Forms (18+ components)
+### Input & Forms
 
 | Component | Import | Description |
 |---|---|---|
 | `Autocomplete` | `@trinityui/design-system` | Full-featured autocomplete — async loading, pagination, sortable chips, virtualization |
-| `VirtualizedAutocomplete` | `@trinityui/design-system` | Virtualized variant for large option lists |
+| `VirtualizedAutocomplete` | `@trinityui/design-system` | **Deprecated** (removed in v3.0): use `Autocomplete`, which is already virtualized |
 | `Combobox` | `@trinityui/design-system` | Accessible combobox with keyboard navigation |
 | `SearchInput` | `@trinityui/design-system` | Standalone search input with suggestion dropdown |
 | `ClearableTextField` | `@trinityui/design-system` | Text field with integrated clear button |
@@ -407,7 +523,7 @@ See the [Azure Function template](./examples/azure-functions/predictive-text/) f
 
 ---
 
-### Feedback (7 components)
+### Feedback
 
 | Component | Import | Description |
 |---|---|---|
@@ -420,9 +536,9 @@ See the [Azure Function template](./examples/azure-functions/predictive-text/) f
 
 ---
 
-### Charts (17 components)
+### Charts
 
-All charts are Recharts-based with Trinity theming applied automatically.
+All charts are Highcharts-based, with Trinity theming applied automatically.
 
 | Component | Description |
 |---|---|
@@ -460,7 +576,18 @@ Supports multiple icon libraries via `IconProvider`. Six intent-based sizes: `in
 
 ---
 
-## Hooks (18)
+### Patterns
+
+Reference compositions of public organisms in `src/patterns/` ([Patterns](./docs/PATTERNS.md), ADR-12): a pattern owns layout and wiring only, with no state, live region, landmark or focus code of its own. Exported from the root entry only.
+
+| Pattern | Status | Story |
+|---|---|---|
+| `AICopilotPattern` | Built (2.13.0): the HITL copilot (InsightEngine, the plan-review and clarification blocks, reasoning and sources), as a drawer or embedded in `AppLayout`'s AI panel through `renderAiPanel` | Patterns/AICopilot |
+| `DashboardPattern`, `DataTablePattern`, `FilterPattern`, `EmptyStatePattern` | Not started (owner unassigned) | - |
+
+---
+
+## Hooks (33)
 
 All hooks import from `@trinityui/design-system`.
 
@@ -468,39 +595,56 @@ All hooks import from `@trinityui/design-system`.
 |---|---|
 | `useDebounce` | Debounce a value by delay |
 | `useDebouncedCallback` | Returns a debounced callback function |
-| `useClipboard` | Copy text to clipboard with success feedback |
-| `useLocalStorage` | Persist state to `localStorage` with SSR safety |
-| `useTrinityBreakpoints` | Responsive flags: `isMobile`, `isTablet`, `isDesktop`, `isLargeDesktop` |
+| `useInterval` | Declarative `setInterval` with cleanup |
 | `useToggle` | Boolean toggle: `[value, toggle, setValue]` |
 | `usePrevious` | Access the previous render's value |
+| `useLocalStorage` | Persist state to `localStorage`; server and hydration renders use `initialValue` |
+| `useClipboard` | Copy text, with an optional screen reader announcement of the outcome |
 | `useOnClickOutside` | Detect clicks outside a ref element |
 | `useKeyPress` | Detect a specific key press |
-| `useInterval` | Declarative `setInterval` with cleanup |
-| `useFocusTrap` | Trap keyboard focus within a container (accessibility) |
-| `useReducedMotion` | Detect `prefers-reduced-motion` user preference |
-| `useAriaLive` | Manage ARIA live region announcements for screen readers |
-| `useRovingTabIndex` | Arrow-key navigation for composite widgets |
+| `useAnnounce` | Announce a message to screen readers through the nearest live region |
+| `useAriaLive` | Live-region announcements; announces through `useAnnounce`, or through your own region when you spread its `ariaProps` |
+| `useDisclosure` | Expand/collapse and popup triggers: `aria-expanded`, `aria-controls` and ids from `useId` |
+| `useAsyncAction` | Run an async action once at a time: errors reported, pending, success and error announced |
+| `useRovingTabIndex` | Arrow-key navigation for composite widgets (registry form) |
+| `useReducedMotion` | Detect the `prefers-reduced-motion` preference (SSR-stable) |
+| `useFocusTrap` | **Deprecated** (removed in v3.0): use MUI's built-in trap (`Dialog`, `Popover`, `Menu`, temporary `Drawer`) |
+| `useTrinityBreakpoints` | Responsive flags: `isMobile`, `isTablet`, `isDesktop`, `isLargeDesktop` |
+| `useTrinityTokens` | Typed access to the semantic tokens of the current theme |
+| `useTrinityPalette` | Access Trinity semantic palette from the current theme |
+| `useForm` | Form state manager paired with `<FormProvider>` |
+| `useFormField` | Field registration and validation inside `<FormProvider>` |
 | `useConfirmDialog` | Imperatively open confirmation dialogs |
 | `useToast` | Show toast notifications (requires `ToastProvider`) |
-| `useTrinityPalette` | Access Trinity semantic palette from the current theme |
 | `useFlowAutoLayout` | Auto-layout for React Flow / XYFlow diagrams |
+| `useBrowserVoiceMode` | Browser speech recognition and synthesis for `AIVoiceMode` |
+| `useSourceCategories` | A response's sources as `AISourcesPanel` categories, numbered like inline source chips, with the AI strings, locale and time zone |
+| `useFormatAsOf` | Formats ISO 8601 as-of dates and date-times the same way on the server and in the browser |
+| `useBlockSources` | The sources behind one table or chart block of an AI response: per cell, per point, and each source's number |
+| `useAIStrings` | The AI strings: the nearest `AIConfigProvider`'s `strings` merged over its ancestors' and the English defaults |
+| `useAIThresholds` | The confidence thresholds from the nearest `AIConfigProvider`, or the defaults (medium from 60%, high from 85%) |
+| `useAILocale` | The locale for numbers and counts from `AIConfigProvider`, or `undefined` (formatters then use `en-US`) |
+| `useAITimeZone` | The IANA time zone for dates from `AIConfigProvider`, else the runtime's; `UTC` during server rendering |
+| `useAIInteraction` | Reports a content-free `AIInteractionEvent` to the nearest `AIConfigProvider`'s `onInteraction`; a no-op without one |
+
+The behavior toolkit (`useAnnounce`, `liveRegionProps`, `REDUCED_MOTION_QUERY`, `visuallyHiddenSx`, `useDisclosure`, `useAsyncAction` and the hooks above) is the one sanctioned way to build each behavior; [docs/BEHAVIOR_CONTRACT.md](docs/BEHAVIOR_CONTRACT.md) maps every behavior to its export.
 
 ---
 
 ## Accessibility
 
-Trinity targets **WCAG 2.1 AA** compliance. The system provides:
+Trinity targets **WCAG 2.2 AA**. Every story runs axe in Storybook, the behavior contract's rules are all strict with no open finding, and the AI components announce their state changes to screen readers. Right-to-left layouts are best effort: logical properties, the theme's direction and bidi isolation are kept, but RTL is not release-tested ([docs/RTL.md](./docs/RTL.md)). The system provides:
 
 | Feature | Details |
 |---|---|
 | **Automated testing** | `vitest-axe` (axe-core) a11y tests, dedicated `test:a11y` script |
 | **Linting** | `eslint-plugin-jsx-a11y` enforced across all components |
 | **Storybook addon** | `@storybook/addon-a11y` for interactive accessibility auditing |
-| **ARIA hooks** | `useFocusTrap`, `useAriaLive`, `useRovingTabIndex`, `useReducedMotion` |
+| **Behavior toolkit** | `useAnnounce`, `liveRegionProps`, `useAriaLive`, `useDisclosure`, `useAsyncAction`, `useClipboard`, `useRovingTabIndex`, `useReducedMotion`, `REDUCED_MOTION_QUERY` ([BEHAVIOR_CONTRACT](docs/BEHAVIOR_CONTRACT.md)); `useFocusTrap` is deprecated in favor of MUI's built-in trap |
 | **Skip links** | `SkipLink` component for keyboard-first navigation |
 | **Accessible colors** | `accessibleCombinations` — pre-validated WCAG AA text/background pairs |
 | **Contrast utilities** | `getContrastRatio()`, `validateAccessibility()`, `meetsWCAG()` |
-| **Visual hiding** | `VisuallyHidden` component for screen-reader-only content |
+| **Visual hiding** | `VisuallyHidden` component for screen-reader-only content, and `visuallyHiddenSx` for an element that cannot be one |
 
 ```tsx
 import { accessibleCombinations } from '@trinityui/design-system';
@@ -550,12 +694,18 @@ Trinity uses a **3-tier token architecture** (2,700+ lines) spanning colors, spa
 import { baseTokens, semanticTokens, componentTokens } from '@trinityui/design-system/tokens';
 ```
 
-All tokens are also available as CSS variables:
+All tokens are also available as CSS variables, in two name families. The static stylesheet (`trinity.css` in `@trinityui/design-system/css` and `@trinityui/design-system-css`) uses short names. The runtime variables that `injectTrinityCssVariables()` adds use `color-`, `spacing-`, `semantic-` and `component-` names. Use the names of the layer you load.
 
 ```css
-var(--trinity-color-navy-900)     /* base */
-var(--trinity-card-bg)            /* semantic */
-var(--trinity-switch-track-height) /* component */
+/* Static stylesheet (trinity.css) */
+var(--trinity-navy-900)                    /* base */
+var(--trinity-text-primary)                /* semantic */
+var(--trinity-switch-track-on)             /* component */
+
+/* Runtime variables (injectTrinityCssVariables) */
+var(--trinity-color-navy-900)              /* base */
+var(--trinity-semantic-text-primary)       /* semantic */
+var(--trinity-component-switch-track-on)   /* component */
 ```
 
 For token usage rules, see [docs/TOKEN_USAGE_RULES.md](./docs/TOKEN_USAGE_RULES.md).
@@ -601,7 +751,7 @@ For Angular, Vue, or static HTML projects:
 <html data-theme="dark">
 ```
 
-All design tokens are exposed as `--trinity-*` CSS variables. See the [CSS package README](./packages/design-system-css/README.md) for the full variable reference.
+All design tokens are exposed as `--trinity-*` CSS variables with the static stylesheet names (`--trinity-navy-900`, `--trinity-space-4`). See the [CSS package README](./packages/design-system-css/README.md) for the full variable reference.
 
 ---
 
@@ -613,7 +763,7 @@ Interactive component documentation with live controls, dark mode toggle, and ac
 pnpm run start        # Opens at http://localhost:6006
 ```
 
-93 stories covering every component with:
+Stories for every public component, with:
 - Live prop controls and variant previews
 - Dark mode toggle for all components
 - Accessibility audit panel (axe-core integration)
@@ -628,7 +778,7 @@ Trinity exposes component and docs knowledge to AI coding agents (Claude Code, C
 
 | Server | URL | When to use |
 |---|---|---|
-| `trinity-design-system-mcp` | `https://design.trinitylifesciences.com/api/mcp` | Production. Always available, backed by the deployed Storybook. Use this for day-to-day agent work. |
+| `trinity-design-system-mcp` | `https://design.trinitylifesciences.com/api/mcp` | Production, backed by the Storybook of the latest stable release (see below). Use this for day-to-day agent work. |
 | `trinity-storybook` | `http://localhost:6006/mcp` | Local dev only. Backed by `@storybook/addon-mcp`, requires `pnpm run start` to be running. |
 
 Both are pre-configured in [`.mcp.json`](./.mcp.json) — an MCP-aware client picks them up automatically from the repo root.
@@ -637,7 +787,10 @@ Available tools: `list-all-documentation`, `get-documentation`, `get-documentati
 
 ### How the production server is deployed
 
-The production endpoint is **not** a separate service — it's an Azure Functions app in [`api/`](./api) (`@storybook/mcp`), deployed alongside the static Storybook build by the existing Azure Static Web Apps workflow (`api_location: "api"`). It derives its component manifest at request time from the deployed Storybook's own `index.json`, so there's no extra build step to keep in sync.
+The production endpoint is **not** a separate service — it's an Azure Functions app in [`api/`](./api) (`@storybook/mcp`), deployed alongside the static Storybook build by the Azure Static Web Apps workflow (`api_location: "api"`).
+
+- **What it serves.** The workflow copies the build's own component manifest (`manifests/components.json`), its `index.json` and the package version into `api/manifests/`, and installs the API with `npm ci` from `api/package-lock.json`. The endpoint therefore lists exactly the components of the deployed build, named by their export (for example `InsightEngine`), without internal components. A component's status leads its summary and description: `[Deprecated — use X]`, `[Prerelease — @next only]` or `[Documentation incomplete]` ([`api/src/manifest.js`](./api/src/manifest.js)). Without a bundled manifest it falls back to one derived from the deployed `index.json`.
+- **Which version.** Production shows the latest stable release only: it is deployed after a successful npm publish, from the published commit. Pushes to `main` go to a separate `next` environment ([CHANGESETS.md](./docs/CHANGESETS.md#the-public-catalog-follows-releases)). Both deploys are paused while the remediation program pauses npm publishing.
 
 `staticwebapp.config.json` allows anonymous access to `/api/mcp`, `/index.json`, and `/project.json` specifically so the MCP handler and its manifest source stay reachable without authentication, while the rest of the site stays behind Azure AD.
 
@@ -654,27 +807,31 @@ curl -s -X POST https://design.trinitylifesciences.com/api/mcp \
 
 A healthy response is `HTTP/2 200` with an `mcp-session-id` header and a JSON-RPC `result` containing `serverInfo.name: "@storybook/mcp"`.
 
+For a full check, `node scripts/mcp-smoke.mjs --url <host>/api/mcp --manifest storybook-static/manifests/components.json` also lists the components and compares them with the manifest the deploy bundled. The catalog workflow runs it after every deploy, and the deploy fails when they differ. The `next` environment's URL, for checking unreleased work, is in the Azure portal (Static Web App → Environments). The production endpoint currently answers `POST` with HTTP 405; the triage and the open checks are in [docs/DOCS_DEPLOYMENT.md](./docs/DOCS_DEPLOYMENT.md).
+
 ---
 
 ## Development
 
 ```bash
-pnpm install          # Install dependencies
-pnpm run start        # Storybook dev server (:6006)
-pnpm run dev          # Vite dev server (:5173)
-pnpm run build        # TypeScript + Vite production build
-pnpm run test         # Run all tests
-pnpm run test:a11y    # Run accessibility tests only
-pnpm run lint         # ESLint
-pnpm run lint:tokens  # Token usage rule validation
-pnpm run size         # Check bundle size limits
+pnpm install            # Install dependencies
+pnpm run start          # Storybook dev server (:6006); there is no separate app dev server
+pnpm run build          # Token CSS sync, Vite library build and declarations
+pnpm run typecheck      # Library type check and the app type-debt ratchet
+pnpm run test           # Run all tests
+pnpm run test:a11y      # Run accessibility tests only
+pnpm run lint:changed   # ESLint on the lines you changed
+pnpm run lint:tokens    # Token usage rule validation
+pnpm run size           # Check bundle size limits
+pnpm run verify:release # Every release gate, in CI order
 ```
 
 ### Release and Publishing
 
-- Push to `main` triggers publish workflows for both `@trinityui/design-system` and `@trinityui/design-system-css`
-- Version is auto-bumped if the current version is already published
-- `CHANGELOG.md` is generated during the release workflow
+- **Versions and changelogs come from [Changesets](./docs/CHANGESETS.md).** Pull requests add changesets. A maintainer runs `pnpm changeset:version` on a release branch and merges the version and `CHANGELOG.md` changes to `main` through a reviewed pull request. `@trinityui/design-system` and `@trinityui/design-system-css` are versioned together.
+- **Only verified artifacts are published.** `verify-release.yml` runs every gate of `pnpm run verify:release` (the ordered list is in [docs/process/CI.md](docs/process/CI.md)) on pull requests to `main` and `release/**`, and packs two checksum-bound tarballs, each with its LICENSE. The publish workflows run that verification again for the commit they publish. The `publish` job checks the tarballs' checksums and publishes only those tarballs, with npm provenance and lifecycle scripts disabled, and only for versions not yet on npm.
+- **Direct publication is blocked.** In a source checkout, a `prepublishOnly` guard in both packages stops `npm publish` and `pnpm publish`, `pnpm changeset:publish` runs the same guard, and `pnpm run check:release-paths` enforces the single publication path.
+- **Publishing is paused during the remediation program.** The `publish` job is `if: false`, so a push to `main` runs verification and publishes nothing. See [G-05 freeze record](./docs/remediation/G-05-freeze-2026-10.md).
 
 ---
 
@@ -684,17 +841,21 @@ pnpm run size         # Check bundle size limits
 |---|---|
 | [Quick Start](./docs/QUICK_START.md) | 5-minute getting-started guide |
 | [Developer Guide](./docs/DEVELOPER_GUIDE.md) | Comprehensive development reference |
-| [Accessibility](./docs/ACCESSIBILITY.md) | WCAG 2.1 AA compliance guide |
+| [Accessibility](./docs/ACCESSIBILITY.md) | WCAG 2.2 AA compliance guide |
+| [Behavior Contract](./docs/BEHAVIOR_CONTRACT.md) | The behavior rules every component meets, and the toolkit export for each |
 | [Component A11y Checklist](./docs/COMPONENT_A11Y_CHECKLIST.md) | Per-component accessibility requirements |
 | [Token Usage Rules](./docs/TOKEN_USAGE_RULES.md) | When and how to use each token tier |
 | [Storybook Standards](./docs/STORYBOOK_STANDARDS.md) | Story authoring conventions |
 | [Testing Strategy](./docs/TESTING_STRATEGY.md) | Unit, a11y, and visual regression testing |
-| [MUI Compatibility](./docs/MUI_COMPATIBILITY.md) | MUI version support matrix |
 | [Integrating into Existing Apps](./docs/TRINITY_EXISTING_APP.md) | Migration guide for existing projects |
 | [New App Setup](./docs/TRINITY_NEW_APP.md) | Starting a new project with Trinity |
-| [Component Picker](./docs/COMPONENT_PICKER.md) | Decision tree: which component to use |
+| [Component Picker](./docs/COMPONENT_PICKER.md) | Which component to use, and what the theme changes on MUI components |
+| [Patterns](./docs/PATTERNS.md) | The pattern layer: contract, index, export waiver |
+| [AppLayout AI Panel](./docs/APPLAYOUT_AI_PANEL.md) | The AI panel's three routes, both modes, and what changed in 2.13.0 |
+| [HITL Catalog](./docs/HITL_CATALOG.md) | The human-in-the-loop components and their stories |
+| [Microcopy](./docs/MICROCOPY.md) | Voice, labels, errors and the AI strings |
 | [Governance](./docs/GOVERNANCE.md) | Contribution process, RFC, and deprecation policy |
-| [Migration](./MIGRATION.md) | Version migration guides |
+| [Migration](./MIGRATION.md) | Behavior corrections in 2.x and the v3.0 removals |
 | [Contributing](./CONTRIBUTING.md) | How to contribute |
 | [Changelog](./CHANGELOG.md) | Release history |