@trinityui/design-system 2.1.3 → 2.2.1

package/README.md

@@ -1,26 +1,97 @@
 # Trinity Design System
 
-Trinity Design System is an enterprise component platform built on MUI for [Trinity LifeSciences](https://trinitylifesciences.com).
+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.
 
 [![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)
 [![license](https://img.shields.io/npm/l/@trinityui/design-system.svg)](./LICENSE)
 
-It provides:
-- A React component library: `@trinityui/design-system`
-- A CSS-only package for non-React apps: `@trinityui/design-system-css`
+---
+
+## Table of Contents
+
+- [Key Capabilities](#key-capabilities)
+- [Architecture](#architecture)
+- [Packages & Entry Points](#packages--entry-points)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [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)
+  - [Icon System](#icon-system)
+- [Hooks](#hooks-18)
+- [Accessibility](#accessibility)
+- [Design Tokens](#design-tokens)
+- [Theme Presets](#theme-presets)
+- [CSS-Only Usage](#css-only-usage)
+- [Storybook](#storybook)
+- [Development](#development)
+- [Documentation](#documentation)
+- [License](#license)
+
+---
+
+## Key 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 |
+| **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 |
+| **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 |
+
+---
 
 ## Architecture
 
-`Design Tokens` -> `Theme Layer` -> `React Components (@trinityui/design-system)` -> `React Consumer Apps`  
-`Design Tokens` -> `CSS Variables Build` -> `CSS Package (@trinityui/design-system-css)` -> `Angular / Vue / Static Apps`
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Design Tokens (tokens.ts)                │
+│            Base → Semantic → Component (2,700 lines)         │
+└──────────────┬──────────────────────────┬────────────────────┘
+               │                          │
+               ▼                          ▼
+┌──────────────────────────┐  ┌─────────────────────────────────┐
+│    MUI Theme Layer        │  │   CSS Variables Build            │
+│  lightTheme / darkTheme   │  │   generate-css-from-tokens.ts    │
+│  + 3 preset themes        │  │   trinity.css / trinity-base.css │
+└──────────┬───────────────┘  └──────────┬──────────────────────┘
+           │                             │
+           ▼                             ▼
+┌──────────────────────────┐  ┌─────────────────────────────────┐
+│  @trinityui/design-system │  │ @trinityui/design-system-css     │
+│  React + MUI Components   │  │ Angular / Vue / Static HTML      │
+└──────────────────────────┘  └─────────────────────────────────┘
+```
 
-## Packages
+---
 
-| Package | Use Case |
-|---|---|
-| `@trinityui/design-system` | React + MUI applications |
-| `@trinityui/design-system-css` | Angular, Vue, static HTML, or any CSS-only integration |
+## Packages & 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 |
+
+---
 
 ## Installation
 
@@ -30,7 +101,12 @@ It provides:
 pnpm add @trinityui/design-system react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled
 ```
 
-> Commercial licensing: For MUI, AG Grid, or Syncfusion license procurement/renewal, contact Arun Manoharan, Rahul Desai, or Sangeetha before production use.
+**Optional dependencies** (install only if using these features):
+
+```bash
+pnpm add recharts              # Charts
+pnpm add @mui/x-date-pickers dayjs  # DatePicker
+```
 
 ### CSS-only package
 
@@ -38,7 +114,13 @@ pnpm add @trinityui/design-system react react-dom @mui/material @mui/icons-mater
 pnpm add @trinityui/design-system-css
 ```
 
-## React Quick Start
+> **Commercial licensing:** For MUI, AG Grid, or Syncfusion license procurement/renewal, contact Arun Manoharan, Rahul Desai, or Sangeetha before production use.
+
+---
+
+## Quick Start
+
+### 1. Wrap your app with the theme
 
 ```tsx
 import { ThemeProvider, CssBaseline } from '@mui/material';
@@ -54,206 +136,534 @@ export function AppProviders({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## Import Strategy
+### 2. Import strategy
 
-Use MUI for standard UI primitives, and Trinity for domain-specific components and tokens.
+Use **MUI** for standard UI primitives. Use **Trinity** for domain-specific components, tokens, and hooks.
 
 ```tsx
+// MUI primitives
 import { Button, Card, TextField } from '@mui/material';
+
+// Trinity components
 import { StatusIndicator, Toast, useToast } from '@trinityui/design-system';
 ```
 
-## Async Autocomplete
+### 3. Dark mode
+
+```tsx
+import { lightTheme, darkTheme } from '@trinityui/design-system';
+
+<ThemeProvider theme={isDarkMode ? darkTheme : lightTheme}>
+  <CssBaseline />
+  <App />
+</ThemeProvider>
+```
+
+For the full getting-started guide, see [docs/QUICK_START.md](./docs/QUICK_START.md).
+
+---
+
+## Component Catalog
+
+### Navigation (6 components)
+
+| Component | Import | Description |
+|---|---|---|
+| `TopNavHeader` | `@trinityui/design-system` | Primary navigation header with search, client switcher, and user menu |
+| `TopNavWithSidebar` | `@trinityui/design-system` | Full layout with collapsible sidebar navigation |
+| `Footer` | `@trinityui/design-system` | Page footer — light and dark variants, compact 40px height |
+| `SearchBar` | `@trinityui/design-system` | Header search bar primitive with suggestion support |
+| `ClientMenu` | `@trinityui/design-system` | Client/tenant switcher dropdown |
+| `AppsMenu` | `@trinityui/design-system` | Application launcher grid menu |
+
+Also exports: `TrinityLogo`, `UserMenu`, `HeaderActions`, and 14 navigation type definitions.
+
+---
+
+### Layout (7 components)
+
+| Component | Import | Description |
+|---|---|---|
+| `AppLayout` | `@trinityui/design-system` | Primary app shell — nav + content + optional AI panel |
+| `PageHeader` | `@trinityui/design-system` | Page header with breadcrumbs, title, and actions |
+| `SplitPane` | `@trinityui/design-system` | Resizable split view (horizontal/vertical) |
+| `DockLayout` | `@trinityui/design-system` | Dockable panel layout with configurable zones |
+| `ResizablePanel` | `@trinityui/design-system` | Standalone resizable side panel |
+| `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`).
+
+---
+
+### AI (35+ components)
+
+The largest component category — a full suite for building AI-powered experiences.
+
+#### 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 |
+
+#### 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 |
+
+#### 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 |
+
+#### 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) |
+
+#### AI Actions & Layout
+
+| Component | Description |
+|---|---|
+| `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 |
+
+All AI components import from `@trinityui/design-system`. AI-specific design tokens available via `aiTokens`.
+
+---
+
+### Data Display (8 components)
+
+| Component | Import | Description |
+|---|---|---|
+| `DataTable` | `@trinityui/design-system/data-table` | AG Grid Enterprise powered — sorting, filtering, grouping, pivot, server-side row models |
+| `SimpleTable` | `@trinityui/design-system` | Lightweight table for simple data (no AG Grid dependency) |
+| `DataCard` | `@trinityui/design-system` | KPI/metric card with trend indicator and sparkline |
+| `DiffViewer` | `@trinityui/design-system` | Side-by-side or unified diff viewer |
+| `Timeline` | `@trinityui/design-system` | Vertical timeline with status indicators |
+| `TreeView` | `@trinityui/design-system` | Hierarchical tree view with expansion and selection |
+| `TransferList` | `@trinityui/design-system` | Dual-list transfer component with search and bulk actions |
+| `StatusIndicator` / `StatusLegend` | `@trinityui/design-system` | Unified status display (success/warning/error/info) + legend |
+
+**DataTable setup:**
+
+```tsx
+import { DataTable, setAgGridEnterpriseLicenseKey } from '@trinityui/design-system/data-table';
+
+// Set license key once at app bootstrap
+setAgGridEnterpriseLicenseKey('<YOUR_KEY>');
+```
+
+### App Layout
 
-`Autocomplete` supports asynchronous loading from either a callback (`dataSource`) or a URL (`url`), including infinite pagination on scroll.
+`AppLayout` is the recommended shell for React applications that need Trinity branding, sidebar navigation, user context, and optional AI panel integration.
 
-### Data source mode
+```tsx
+import * as React from 'react';
+import HomeOutlinedIcon from '@mui/icons-material/HomeOutlined';
+import BarChartIcon from '@mui/icons-material/BarChart';
+import SettingsOutlinedIcon from '@mui/icons-material/SettingsOutlined';
+import { AppLayout, type NavItem } from '@trinityui/design-system';
+
+const navItems: NavItem[] = [
+  { id: 'home', label: 'Home', icon: <HomeOutlinedIcon /> },
+  { id: 'analytics', label: 'Analytics', icon: <BarChartIcon /> },
+  { id: 'settings', label: 'Settings', icon: <SettingsOutlinedIcon /> },
+];
+
+export default function AppShell() {
+  const [selectedNavItem, setSelectedNavItem] = React.useState('home');
+
+  return (
+    <AppLayout
+      navStyle="sidebar"
+      aiTrigger="none"
+      companyName="Portfolio Console"
+      navItems={navItems}
+      selectedNavItem={selectedNavItem}
+      onSelectedNavItemChange={setSelectedNavItem}
+      user={{ name: 'Jane Doe', email: 'jane@example.com', initials: 'JD' }}
+    >
+      <main>Page content</main>
+    </AppLayout>
+  );
+}
+```
+
+Optional header regions can be disabled when the consuming app owns those controls elsewhere:
 
 ```tsx
-import { Autocomplete, type AutocompleteAsyncRequest } from '@trinityui/design-system';
+<AppLayout
+  navStyle="sidebar"
+  showSearch={false}
+  showClientSelector={false}
+  showSidebarToggle={false}
+>
+  <main>Page content</main>
+</AppLayout>
+```
 
-type UserOption = { id: string; name: string; email: string };
+| Prop | Default | Description |
+|---|---:|---|
+| `showSearch` | `true` | Shows the desktop search field and mobile search action. |
+| `showClientSelector` | `true` | Shows the client selector dropdown in the header. |
+| `showSidebarToggle` | `true` | Shows the sidebar hamburger/collapse button in sidebar mode. |
+
+---
+
+### Input & Forms (18+ components)
+
+| 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 |
+| `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 |
+| `ChipsInput` | `@trinityui/design-system` | Tag/chip entry input with validation |
+| `MentionsInput` | `@trinityui/design-system` | @mention-enabled text input |
+| `FileUpload` / `UploadDropZone` | `@trinityui/design-system` | Drag-and-drop file upload with progress |
+| `CommandPalette` | `@trinityui/design-system` | Cmd+K style command palette with fuzzy search |
+| `FilterBar` | `@trinityui/design-system` | Multi-filter toolbar with presets and saved filters |
+| `NestedMenu` | `@trinityui/design-system` | Multi-level nested menu |
+| `Cron` | `@trinityui/design-system` | Visual cron expression builder |
+| `Carousel` | `@trinityui/design-system` | Content carousel with transition effects |
+| `Popper` | `@trinityui/design-system` | Positioning utility component |
+
+#### Form Utilities
+
+```tsx
+import { FormProvider, useForm, useFormField } from '@trinityui/design-system';
+
+// Built-in validators
+import { required, email, minLength, maxLength, pattern, min, max, custom } from '@trinityui/design-system';
+```
+
+`FormProvider` gives you form state management with composable validation — no additional form library required.
+
+#### Async Autocomplete Example
+
+```tsx
+import { Autocomplete, type AutocompleteAsyncRequest } from '@trinityui/design-system';
 
 const loadUsers = async ({ search, page, pageSize, signal }: AutocompleteAsyncRequest) => {
-  const response = await fetch(`/api/users?q=${encodeURIComponent(search)}&page=${page}&pageSize=${pageSize}`, { signal });
-  const data = await response.json();
-  return {
-    options: data.items as UserOption[],
-    hasMore: data.hasMore as boolean,
-    nextPage: page + 1,
-  };
+  const res = await fetch(`/api/users?q=${encodeURIComponent(search)}&page=${page}&pageSize=${pageSize}`, { signal });
+  const data = await res.json();
+  return { options: data.items, hasMore: data.hasMore, nextPage: page + 1 };
 };
 
-<Autocomplete<UserOption, true, false, false>
+<Autocomplete
   name="users"
   label="Users"
   options={[]}
   multiple
   value={[]}
-  onHandleChange={(next) => setUsers(next as UserOption[])}
+  onHandleChange={(next) => setUsers(next)}
   labelProperty="name"
   valueProperty="id"
-  optionValues={['name', 'email']}
-  async={{
-    dataSource: loadUsers,
-    paginate: true,
-    pageSize: 25,
-    debounceMs: 250,
-    minSearchLength: 1,
-  }}
-/>;
+  async={{ dataSource: loadUsers, paginate: true, pageSize: 25, debounceMs: 250 }}
+/>
 ```
 
-## Sortable Multi-Select Autocomplete
-
-Enable `sortableSelected` to reorder selected chips.
-- Mouse: drag and drop chips.
-- Keyboard: `Ctrl/Cmd + Shift + Arrow` keys on a selected chip.
+#### Predictive Text Input (OpenAI via Azure Function)
 
 ```tsx
-<Autocomplete<string, true, false, false>
-  name="focus-areas"
-  label="Focus Areas"
-  options={['Oncology', 'Safety', 'AI', 'Regulatory']}
-  multiple
-  value={selected}
-  onHandleChange={(next) => setSelected(next as string[])}
-  sortableSelected
-  virtualized={false}
-/>;
+import { PredictiveTextInput, createOpenAIPredictor } from '@trinityui/design-system';
+
+const predictor = createOpenAIPredictor({ endpoint: '/api/predictive-text', maxSuggestions: 5 });
+
+<PredictiveTextInput label="Prompt" value={value} onChange={setValue} onPredict={predictor} />
 ```
 
-## Predictive Text Input (OpenAI via Azure Function)
+See the [Azure Function template](./examples/azure-functions/predictive-text/) for the backend.
+
+---
+
+### Feedback (7 components)
 
-Use `PredictiveTextInput` with `createOpenAIPredictor` and point it to your backend endpoint (for example, an Azure Function at `/api/predictive-text`).
+| Component | Import | Description |
+|---|---|---|
+| `Modal` | `@trinityui/design-system` | Modal dialog with size variants and accessible focus management |
+| `ConfirmDialog` | `@trinityui/design-system` | Confirm/cancel dialog (also available via `useConfirmDialog` hook) |
+| `ToastProvider` / `Toast` | `@trinityui/design-system` | Toast notification system (wrap app in `ToastProvider`, trigger via `useToast`) |
+| `IllustratedMessage` | `@trinityui/design-system` | Empty state / error illustrated message |
+| `Tour` | `@trinityui/design-system` | Guided product tour with step-by-step highlights |
+| `GoToTop` | `@trinityui/design-system` | Scroll-to-top floating button |
+
+---
+
+### Charts (17 components)
+
+All charts are Recharts-based with Trinity theming applied automatically.
+
+| Component | Description |
+|---|---|
+| `LineChart` | Line/time-series chart |
+| `BarChart` | Vertical/horizontal bar chart |
+| `AreaChart` | Filled area chart |
+| `PieChart` | Pie chart |
+| `DonutChart` | Donut variant |
+| `ScatterChart` | Scatter plot |
+| `BubbleChart` | Bubble chart |
+| `RadialBarChart` | Radial/polar bar chart |
+| `GaugeChart` | Gauge/meter chart |
+| `ComposedChart` | Mixed line + bar + area chart |
+| `Sparkline` | Inline mini chart for data cards |
+| `ChartWrapper` | Chart container with consistent sizing |
+| `CustomTooltip` / `SimpleTooltip` | Chart tooltip components |
+| `CustomLegend` / `InteractiveLegend` / `PieLegend` | Chart legend components |
+
+All import from `@trinityui/design-system`. Full type definitions for `DataPoint`, `SeriesConfig`, `AxisConfig`, and chart-specific props.
+
+---
+
+### Icon System
 
 ```tsx
-import { PredictiveTextInput, createOpenAIPredictor } from '@trinityui/design-system';
+import { Icon, IconProvider } from '@trinityui/design-system';
 
-const predictor = createOpenAIPredictor({
-  endpoint: '/api/predictive-text',
-  maxSuggestions: 5,
-});
-
-<PredictiveTextInput
-  label="Prompt"
-  value={value}
-  onChange={setValue}
-  onPredict={predictor}
-/>;
+// Wrap with IconProvider to set the active icon library
+<IconProvider library="feather">
+  <Icon name="check" size="md" />
+</IconProvider>
 ```
 
-Azure Function template:
-- [`examples/azure-functions/predictive-text/index.ts`](./examples/azure-functions/predictive-text/index.ts)
-- [`examples/azure-functions/predictive-text/README.md`](./examples/azure-functions/predictive-text/README.md)
+Supports multiple icon libraries via `IconProvider`. Six intent-based sizes: `inline` (14px), `xs` (16px), `sm` (18px), `md` (20px), `lg` (24px), `display` (36px).
+
+---
+
+## Hooks (18)
 
-### URL mode
+All hooks import from `@trinityui/design-system`.
+
+| Hook | Description |
+|---|---|
+| `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` |
+| `useToggle` | Boolean toggle: `[value, toggle, setValue]` |
+| `usePrevious` | Access the previous render's value |
+| `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 |
+| `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 |
+
+---
+
+## Accessibility
+
+Trinity targets **WCAG 2.1 AA** compliance. 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` |
+| **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 |
 
 ```tsx
-<Autocomplete<UserOption, true, false, false>
-  name="users-url"
-  label="Users"
-  options={[]}
-  multiple
-  value={[]}
-  onHandleChange={(next) => setUsers(next as UserOption[])}
-  labelProperty="name"
-  valueProperty="id"
-  async={{
-    url: '/api/users/search',
-    method: 'GET',
-    queryParam: 'q',
-    pageParam: 'page',
-    pageSizeParam: 'pageSize',
-    paginate: true,
-    mapResponse: (response) => {
-      const data = response as { results: UserOption[]; hasMore: boolean };
-      return { options: data.results, hasMore: data.hasMore };
-    },
-  }}
-/>;
+import { accessibleCombinations } from '@trinityui/design-system';
+
+// Pre-validated WCAG AA pairs
+<Box sx={{
+  backgroundColor: accessibleCombinations.whiteOnNavy.bg,
+  color: accessibleCombinations.whiteOnNavy.text,
+}}>
+  Guaranteed 4.5:1+ contrast ratio
+</Box>
 ```
 
-## Entry Points
+For the full accessibility guide and component checklist, see [docs/ACCESSIBILITY.md](./docs/ACCESSIBILITY.md) and [docs/COMPONENT_A11Y_CHECKLIST.md](./docs/COMPONENT_A11Y_CHECKLIST.md).
 
-| Import | Purpose |
-|---|---|
-| `@trinityui/design-system` | Full API |
-| `@trinityui/design-system/essentials` | Lean entry for common setup and core components |
-| `@trinityui/design-system/theme` | Theme-only exports |
-| `@trinityui/design-system/tokens` | Token-only exports |
-| `@trinityui/design-system/data-table` | DataTable exports (AG Grid powered) |
-| `@trinityui/design-system/css` | CSS file from the React package |
+---
+
+## Design Tokens
 
-## DataTable Entry
+Trinity uses a **3-tier token architecture** (2,700+ lines) spanning colors, spacing, typography, shadows, motion, z-index, border radius, opacity, breakpoints, and effects.
 
-`DataTable` is intentionally isolated behind a subpath:
+### Token Tiers
+
+| Tier | Purpose | Example |
+|---|---|---|
+| **Base** | Raw primitive values | `baseTokens.colors.navy[900]` → `#050742` |
+| **Semantic** | Contextual meaning | `semanticTokens.colors.interactive.primary` |
+| **Component** | Component-level defaults | `componentTokens.card.borderRadius` → `12px` |
+
+### Token Coverage
+
+| Category | What's included |
+|---|---|
+| **Colors** | 6 brand palettes (navy, purple, indigo, coral, azure, gray) with full shade ranges |
+| **Semantic colors** | Brand, text (11 variants), background (8), surface (7), border (6), interactive (5), status (4 × 3) |
+| **Spacing** | 20-step scale (0–32), component spacing, layout spacing with dimensions, density scale |
+| **Typography** | 10 sizes, 6 weights, 6 line heights, 6 letter spacings, semantic scales (display/heading/body/label) |
+| **Border radius** | 9-step scale (none → 9999px), semantic radius (button, input, card, modal, badge, avatar, chip, tooltip) |
+| **Shadows** | 8 levels + semantic (card, dropdown, modal, button, input), effect-based (surface, dialog, inset) |
+| **Motion** | 7 durations (fastest → slowest) + 7 easings (linear, bounce, elastic, etc.) |
+| **Z-index** | 7 numeric levels + 7 semantic (dropdown, sticky, modal, tooltip) |
+| **Effects** | Overlay, onDark states, focus rings, status indicators |
+
+### Usage
 
 ```tsx
-import { DataTable } from '@trinityui/design-system/data-table';
+import { baseTokens, semanticTokens, componentTokens } from '@trinityui/design-system/tokens';
 ```
 
-Set your AG Grid Enterprise license key once during app bootstrap:
+All tokens are also available as CSS variables:
+
+```css
+var(--trinity-color-navy-900)     /* base */
+var(--trinity-card-bg)            /* semantic */
+var(--trinity-switch-track-height) /* component */
+```
+
+For token usage rules, see [docs/TOKEN_USAGE_RULES.md](./docs/TOKEN_USAGE_RULES.md).
+
+---
+
+## Theme Presets
+
+Three pre-configured theme presets for different product contexts:
+
+| Preset | Light / Dark | Use Case |
+|---|---|---|
+| **CRM** | `crmLightTheme` / `crmDarkTheme` | Compact tables, dense forms, high information density |
+| **Portal** | `portalLightTheme` / `portalDarkTheme` | Large touch targets, accessible sizing, customer-facing |
+| **Analytics** | `analyticsLightTheme` / `analyticsDarkTheme` | Data visualization optimized, chart-friendly palette |
 
 ```tsx
-import { setAgGridEnterpriseLicenseKey } from '@trinityui/design-system/data-table';
+import { crmLightTheme, crmDarkTheme } from '@trinityui/design-system';
 
-setAgGridEnterpriseLicenseKey('<AG_GRID_ENTERPRISE_LICENSE_KEY>');
+<ThemeProvider theme={isDarkMode ? crmDarkTheme : crmLightTheme}>
+  <App />
+</ThemeProvider>
 ```
 
-For AG Grid Enterprise licensing, coordinate with Arun Manoharan, Rahul Desai, or Sangeetha.
+You can also create custom presets with `createTrinityThemePreset()`.
+
+---
 
 ## CSS-Only Usage
 
-### Option 1: package CSS import
+For Angular, Vue, or static HTML projects:
 
 ```css
+/* Option 1: package import */
 @import '@trinityui/design-system-css';
-```
-
-### Option 2: direct file path
 
-```html
-<link rel="stylesheet" href="node_modules/@trinityui/design-system-css/dist/trinity.css" />
+/* Option 2: direct file path */
+@import 'node_modules/@trinityui/design-system-css/dist/trinity.css';
 ```
 
-### Dark mode
-
 ```html
+<!-- Dark mode: add data-theme attribute -->
 <html data-theme="dark">
 ```
 
-## Theming
+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.
 
-```tsx
-import { lightTheme, darkTheme } from '@trinityui/design-system';
+---
 
-const theme = isDarkMode ? darkTheme : lightTheme;
+## Storybook
+
+Interactive component documentation with live controls, dark mode toggle, and accessibility audits:
+
+```bash
+pnpm run start        # Opens at http://localhost:6006
 ```
 
+93 stories covering every component with:
+- Live prop controls and variant previews
+- Dark mode toggle for all components
+- Accessibility audit panel (axe-core integration)
+- Code examples with copy-to-clipboard
+- Autodocs — auto-generated API documentation from TypeScript types
+
+---
+
 ## Development
 
 ```bash
-pnpm install
-pnpm run start
-pnpm run build
-pnpm run test
-pnpm run lint
+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
 ```
 
-## Release and Publishing
+### 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
 
-- Push to `main` triggers publish workflows for:
-  - `@trinityui/design-system`
-  - `@trinityui/design-system-css`
-- Version is auto-bumped if the current version is already published.
-- `CHANGELOG.md` is generated during release workflow.
+---
 
-## Support Docs
+## Documentation
 
-- [MIGRATION.md](./MIGRATION.md)
-- [CONTRIBUTING.md](./CONTRIBUTING.md)
-- [CHANGELOG.md](./CHANGELOG.md)
+| Document | Description |
+|---|---|
+| [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 |
+| [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 |
+| [Governance](./docs/GOVERNANCE.md) | Contribution process, RFC, and deprecation policy |
+| [Migration](./MIGRATION.md) | Version migration guides |
+| [Contributing](./CONTRIBUTING.md) | How to contribute |
+| [Changelog](./CHANGELOG.md) | Release history |
+
+---
 
 ## License