@mieweb/ui 0.8.0 → 0.9.0-dev.0

package/README.md

@@ -1,619 +1,136 @@
 # @mieweb/ui
 
-A themeable, accessible React component library built with Tailwind CSS 4.
-
-## Features
-
-- 🎨 **Fully Themeable** - Customize colors, fonts, border radius, and more using CSS variables
-- 🏢 **Multi-Brand Support** - Pre-configured themes for BlueHive, Enterprise Health, WebChart, Waggleline, and MIE
-- ♿ **Accessible** - Built with WCAG guidelines in mind, including proper ARIA attributes and keyboard navigation
-- 🌳 **Tree-Shakeable** - Import only the components you need
-- 🌙 **Dark Mode** - Built-in dark mode support with system preference detection
-- 📦 **Dual Format** - ESM and CommonJS support
-- 🎯 **TypeScript** - Full TypeScript support with comprehensive type definitions
-- 📚 **Storybook** - Interactive documentation and component playground
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Development](#development)
-- [Date & Time Standard](#date--time-standard)
-- [Storybook](#storybook)
-- [Using in Other Projects](#using-in-other-projects)
-- [Brand System](#brand-system)
-- [Theming](#theming)
-- [Components](#components)
-- [Hooks](#hooks)
-- [Utilities](#utilities)
-- [Releases](#releases)
-- [Contributing](#contributing)
-
-## Installation
+**Build applications that feel familiar from the first interaction.**
 
-```bash
-npm install @mieweb/ui
-# or
-yarn add @mieweb/ui
-# or
-pnpm add @mieweb/ui
-```
-
-### Peer Dependencies
-
-This library requires React 18+ and React DOM 18+:
-
-```bash
-npm install react react-dom
-```
-
-### Optional Add-ons
-
-Heavy or specialized dependencies are kept in separate entry points so they don't bloat the core bundle. Install the peer dependencies for the add-ons you need:
-
-| Entry point              | Install                                       | Import path          |
-| ------------------------ | --------------------------------------------- | -------------------- |
-| **AG Grid** (deprecated) | `npm install ag-grid-community ag-grid-react` | `@mieweb/ui/ag-grid` |
-| **DataVis**              | `npm install @mieweb/datavis datavis-ace`     | `@mieweb/ui/datavis` |
-
-> ⚠️ **AGGrid is deprecated.** Use DataVis NITRO (`@mieweb/ui/datavis`) for all
-> tables. The `@mieweb/ui/ag-grid` entry remains available for existing
-> consumers but will be removed in a future major release.
-
-### AI Agent Rules
-
-Working with AI coding agents (Copilot, Claude Code, Cursor, …)? Install
-@mieweb/ui's agent rules into your repo so agents use library components
-(DataVis NITRO for tables, `Button`/`Badge`/`Modal`/… instead of raw HTML):
-
-```bash
-npx @mieweb/ui init-agent
-```
-
-This writes `.github/instructions/mieweb-ui.instructions.md` (auto-applied by
-VS Code Copilot) and a marked block in `AGENTS.md` (the cross-tool convention).
-Idempotent — rerun after upgrading to refresh the rules. See [agent/](agent/).
-
-## Quick Start
-
-### Option 1: With Tailwind CSS (Recommended)
-
-If your project uses Tailwind CSS 4, you can use the library's Tailwind preset for the best experience:
-
-1. Add the preset to your `tailwind.config.js`:
-
-```js
-// tailwind.config.js
-module.exports = {
-  presets: [require('@mieweb/ui/tailwind-preset')],
-  content: [
-    // ... your content
-    './node_modules/@mieweb/ui/dist/**/*.js',
-  ],
-  // Override theme values to match your brand
-  theme: {
-    extend: {
-      colors: {
-        primary: {
-          500: '#your-brand-color',
-        },
-      },
-    },
-  },
-};
-```
+People should not have to relearn how to navigate, fill out a form, or recover
+from an error every time they open another application. Clean, consistent
+interfaces let users carry what they already know from one task to the next.
+Predictable controls and clear feedback reduce hesitation and leave more
+attention for the work that matters.
 
-2. Import and use components:
+That consistency should extend beyond appearance. A coherent experience adapts
+from mobile to desktop, remains legible in light and dark mode, accommodates
+different languages and right-to-left layouts, and supports keyboard and
+assistive-technology users. Responsive design, internationalization (i18n), and
+accessibility (a11y) belong in the foundation, not on a finishing checklist.
 
-```tsx
-import { Button, Card, Input } from '@mieweb/ui';
+`@mieweb/ui` brings that approach to your browser interface through reusable
+controls, navigation, forms, feedback, and data displays. Shared interaction
+patterns provide familiarity; theme and brand tokens give you room to make the
+application your own. Developed at MIE, the library is available for applications
+in any domain under its [license terms](#license), not just MIE products.
 
-function App() {
-  return (
-    <Card>
-      <Input label="Email" type="email" />
-      <Button>Submit</Button>
-    </Card>
-  );
-}
-```
+The components are built with React, but your application does not have to be.
+Use them throughout a React application or embed them in selected areas of
+Bootstrap-based, server-rendered, or other non-React pages. Adopt a component or
+a workflow at a time without rewriting the rest of your interface.
 
-### Option 2: Pre-compiled CSS
+Start with a common foundation and spend more time on what makes your application
+valuable. The components support inclusive design; they do not automatically
+translate your content or guarantee accessibility. Validate their composition,
+language, and behavior with the people and devices your application serves.
 
-If you're not using Tailwind CSS, you can import the pre-compiled stylesheet:
+**The library is `@mieweb/ui`. Storybook is its documentation and experimentation
+environment**, where you can explore those components without building an app
+first. This introduction is shared by GitHub, npm, and Storybook.
 
-```tsx
-import '@mieweb/ui/styles.css';
-import { Button } from '@mieweb/ui';
-```
+- [See it in action](#see-it-in-action), no installation needed.
+- [Get started](#get-started), with or without an AI coding agent.
+- [Explore and compose components](#explore-and-compose-components).
+- [Contribute or run locally](#contribute-or-run-locally).
 
-## Development
+## See It In Action
 
-### Getting Started
+[![Open the interactive dashboard demo: navigation, summary cards, recent orders, and activity](https://ui.mieweb.org/dashboard-preview.png)](https://ui.mieweb.org/?path=/story/dashboards-dashboard-demo--dashboard)
 
-1. **Clone the repository (including submodules):**
+**[Open the interactive dashboard](https://ui.mieweb.org/?path=/story/dashboards-dashboard-demo--dashboard)**
+to see navigation, headers, cards, and data displays working together in an
+application layout. Try the brand and theme switchers to see how the same
+components adapt. No installation required.
 
-```bash
-git clone --recurse-submodules https://github.com/mieweb/ui.git
-cd ui
-```
+## Get Started
 
-> `--recurse-submodules` is strongly recommended for first clone so the `packages/esheet` and `packages/ychart` submodules are populated immediately. Without them, the eSheet and YChart stories will not work. DataVis NITRO is not a submodule — it ships as the published `@mieweb/datavis` npm package.
+### Install in Your Application
 
-If you already cloned without submodules, run:
-
-```bash
-git submodule update --init --recursive
-```
-
-2. **Install dependencies:**
-
-```bash
-npm install
-```
-
-Use one package manager consistently per clone. The commands below use npm.
-
-3. **eSheet packages build automatically.** A `prestorybook` hook runs `npm run build:esheet` before Storybook starts, so the `@esheet/*` packages are compiled on first run with no manual step. It's a near-instant no-op on later runs once the artifacts exist.
-
-If `packages/esheet` is updated later (submodule update, branch switch, or pull) and you need to force a fresh rebuild, remove the built artifacts and run the build again:
-
-```bash
-rm -f packages/esheet/packages/core/dist/index.d.ts packages/esheet/packages/renderer/src/index.output.css
-npm run build:esheet
-```
-
-4. **Start Storybook:**
-
-```bash
-npm run storybook
-```
-
-This starts the Storybook development server at [http://localhost:6006](http://localhost:6006) with all components, including eSheet, DataVis NITRO, and YChart.
-
-### How the Sub-Packages Are Wired
-
-Storybook integrates three sibling MIE projects, each sourced differently:
-
-- **DataVis NITRO** — npm package `@mieweb/datavis`. No build step; consumed as a published package (no submodule needed).
-- **eSheet** — git submodule `packages/esheet`. Built automatically by the `prestorybook` hook; rebuilds only when its artifacts are missing.
-- **YChart** — git submodule `packages/ychart`. No build step; the story imports it directly from source via a relative dynamic import, and Storybook's Vite config adds a `virtual:git-info` plugin, a `__YCHART_VERSION__` define, and dependency pre-bundling (`optimizeDeps`).
-
-### Library Development (watch mode)
-
-To rebuild the library on file changes (for consumers that link this repo locally):
-
-```bash
-npm run dev
-```
-
-This watches for source changes and rebuilds automatically. It does **not** start Storybook.
-
-### Available Scripts
-
-| Script                    | Description                                                                                       |
-| ------------------------- | ------------------------------------------------------------------------------------------------- |
-| `npm run dev`             | Watch & rebuild the library (for local consumers, not Storybook)                                  |
-| `npm run build:esheet`    | Build eSheet submodule packages (auto-run by `prestorybook`/`prebuild`; skips when already built) |
-| `npm run build`           | Build the library for production                                                                  |
-| `npm run storybook`       | Start Storybook development server                                                                |
-| `npm run build-storybook` | Build Storybook for static hosting                                                                |
-| `npm run typecheck`       | Run TypeScript type checking                                                                      |
-| `npm run lint`            | Run ESLint                                                                                        |
-| `npm run lint:fix`        | Run ESLint with auto-fix                                                                          |
-| `npm run format`          | Check code formatting with Prettier                                                               |
-| `npm run format:fix`      | Fix code formatting with Prettier                                                                 |
-| `npm run test`            | Run tests                                                                                         |
-| `npm run test:watch`      | Run tests in watch mode                                                                           |
-
-## Date & Time Standard
-
-For UI/UX date and time behavior, this project uses **Luxon** as the preferred library.
-
-### Guidelines
-
-- Use `DateTime` from `luxon` for all new date/time parsing, formatting, and comparisons.
-- Keep timezone explicit when logic depends on business rules (for example: office hours, “open now”, appointment windows).
-- Use IANA timezone identifiers (for example: `America/New_York`) instead of abbreviations.
-- Prefer storing/transmitting ISO-8601 values and convert for display at the component edge.
-- Avoid adding new date logic with raw `Date` math unless there is a clear performance or compatibility reason.
-
-### Examples
-
-```ts
-import { DateTime } from 'luxon';
-
-const localDisplay = DateTime.fromISO(timestamp).toFormat('LLL d, yyyy h:mm a');
-
-const inProviderZone = DateTime.fromISO(timestamp, {
-  zone: 'America/New_York',
-});
-
-const isOpen =
-  DateTime.now().setZone('America/New_York') <
-  inProviderZone.plus({ hours: 1 });
-```
-
-## Storybook
-
-Storybook provides interactive documentation and a component playground where you can explore all components with different props and themes.
-
-### Running Storybook
-
-```bash
-npm run storybook
-```
-
-This starts the Storybook development server at [http://localhost:6006](http://localhost:6006).
-
-### Features in Storybook
-
-- **Component Explorer**: Browse all components with live examples
-- **Props Documentation**: See all available props for each component
-- **Theme Switcher**: Toggle between light and dark modes
-- **Brand Switcher**: Preview components with different brand themes (BlueHive, Enterprise Health, WebChart, Waggleline, MIE)
-- **Accessibility Panel**: Check accessibility compliance for each component
-- **Controls**: Interactively modify component props
-
-### Building Storybook
-
-To build a static version of Storybook for deployment:
-
-```bash
-npm run build-storybook
-```
-
-The output will be in the `storybook-static` directory.
-
-### Configuring the Ozwell API (AI stories)
-
-The AI stories (AIChat, Hands-Free Chat, and the DataVis NITRO **Ozwell Assistant**
-story) call the real Ozwell backend when a key is configured and fall back to a
-canned reply when it isn't. Set the key and endpoint from the browser console:
-
-```js
-// Recommended — survives reloads and is shared with the story iframe:
-localStorage.setItem(
-  'ozwellConfig',
-  JSON.stringify({ apiKey: 'YOUR_KEY', baseURL: 'https://your-ozwell-host' })
-);
-```
-
-`baseURL` is optional (defaults to `https://api.ozwell.ai`); other optional keys are
-`model`, `system`, and `temperature`. Never commit a key — see
-[src/components/AI/OZWELL-BACKEND.md](src/components/AI/OZWELL-BACKEND.md) for full
-details, including why `window.__ozwell` is unreliable inside Storybook iframes and
-how to proxy the key for public deploys.
-
-## Using in Other Projects
-
-### Method 1: NPM Package (Recommended)
-
-Once published, install the package in your project:
+The components require React 18+ and React DOM 18+ to render, including when
+embedded in a non-React page. If your project already has those dependencies:
 
 ```bash
 npm install @mieweb/ui
 ```
 
-Then import components:
-
-```tsx
-import { Button, Card, Input, ThemeProvider } from '@mieweb/ui';
-import '@mieweb/ui/styles.css'; // or use a brand CSS file
-
-function App() {
-  return (
-    <ThemeProvider>
-      <Card>
-        <Card.Header>
-          <Card.Title>Welcome</Card.Title>
-        </Card.Header>
-        <Card.Content>
-          <Input label="Email" type="email" placeholder="you@example.com" />
-          <Button className="mt-4">Submit</Button>
-        </Card.Content>
-      </Card>
-    </ThemeProvider>
-  );
-}
-```
-
-### Method 2: Local Development (npm link)
-
-For local development across projects:
+Use `pnpm add @mieweb/ui` or `yarn add @mieweb/ui` if that is your project's
+package manager. You do not need to clone this repository or run Storybook to use
+the library.
 
-1. **In the @mieweb/ui directory:**
+For a project without React, install the rendering dependencies:
 
 ```bash
-cd /path/to/mieweb-ui
-npm run build
-npm link
+npm install react react-dom
 ```
 
-2. **In your consuming project:**
-
-```bash
-cd /path/to/your-project
-npm link @mieweb/ui
-```
+Using an AI coding agent? [Set up its instructions](#set-up-your-ai-coding-agent)
+and [read the component-selection and integration rules](https://github.com/mieweb/ui/blob/main/agent/mieweb-ui.instructions.md)
+before asking it to add components to your application.
 
-3. **Import and use components:**
+Mount components into a dedicated DOM element with React DOM's `createRoot`, leaving the rest of
+the page under its existing framework's control. Unmount the React root when the
+host removes that area. This requires a JavaScript build that supports React;
+the components are not framework-free HTML widgets.
 
-```tsx
-import { Button } from '@mieweb/ui';
-import '@mieweb/ui/dist/styles.css';
-```
+When embedding alongside Bootstrap or other stylesheets, check CSS resets,
+global selectors, and theme styles for conflicts. Mounting into a separate DOM
+element does not isolate CSS.
 
-### Method 3: Direct Path Import
+### Set Up Your AI Coding Agent
 
-For monorepo setups or when you want to reference the source directly:
+From your application's repository root, run:
 
-```tsx
-// In your consuming project's package.json
-{
-  "dependencies": {
-    "@mieweb/ui": "file:../mieweb-ui"
-  }
-}
+```bash
+npx @mieweb/ui init-agent
 ```
 
-Then run `npm install` and import as usual.
+This installs component-selection, composition, theming, and accessibility rules
+so your agent can start with existing library components. It writes
+`mieweb-ui.instructions.md` in `.github/instructions/` for VS Code Copilot and
+updates a managed block in `AGENTS.md` for agents that read that file. Rerun after upgrading
+`@mieweb/ui` to refresh the rules.
 
-### Using with Different Frameworks
-
-#### Next.js
-
-```tsx
-// app/layout.tsx or pages/_app.tsx
-import '@mieweb/ui/brands/bluehive.css';
-import { ThemeProvider } from '@mieweb/ui';
+Read the [agent setup guide and rules](https://github.com/mieweb/ui/tree/main/agent).
+These are instructions for coding agents, not an automatic PR reviewer or merge
+gate. Agent-assisted and manual development use the same library and setup below.
 
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en">
-      <body>
-        <ThemeProvider>{children}</ThemeProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-#### Vite
-
-```tsx
-// main.tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import '@mieweb/ui/brands/enterprise-health.css';
-import { ThemeProvider } from '@mieweb/ui';
-import App from './App';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <ThemeProvider>
-      <App />
-    </ThemeProvider>
-  </React.StrictMode>
-);
-```
+### Render Your First Component
 
-#### Meteor
+Import the precompiled stylesheet once in your application's entry point or root
+layout. Import a brand stylesheet after it when you want that brand's tokens:
 
 ```tsx
-// client/main.tsx
-import { Meteor } from 'meteor/meteor';
-import React from 'react';
-import { createRoot } from 'react-dom/client';
+import '@mieweb/ui/styles.css';
 import '@mieweb/ui/brands/bluehive.css';
-import { ThemeProvider } from '@mieweb/ui';
-import App from '/imports/ui/App';
-
-Meteor.startup(() => {
-  const container = document.getElementById('react-target');
-  const root = createRoot(container!);
-  root.render(
-    <ThemeProvider>
-      <App />
-    </ThemeProvider>
-  );
-});
-```
-
-## Brand System
-
-The library includes pre-configured themes for multiple brands. Each brand has its own design system with unique colors, typography, border radius, and shadows.
-
-### Available Brands
-
-| Brand                 | Primary Color        | Font   | Description                                       |
-| --------------------- | -------------------- | ------ | ------------------------------------------------- |
-| **BlueHive**          | `#27AAE1` (Blue)     | Nunito | DOT Physical scheduling and healthcare compliance |
-| **Enterprise Health** | `#6E2B68` (Burgundy) | Jost   | Employee health and occupational medicine         |
-| **WebChart**          | `#F5841F` (Orange)   | Inter  | Future-ready electronic health record system      |
-| **Waggleline**        | `#17AEED` (Blue)     | Inter  | Experience visualization and orchestration        |
-| **MIE**               | `#27AE60` (Green)    | Inter  | Healthcare software and services                  |
-
-### Using a Brand Theme
-
-#### Method 1: Import the brand CSS file
-
-```tsx
-// Import the brand's CSS file
-import '@mieweb/ui/brands/enterprise-health.css';
-
-import { Button, Card } from '@mieweb/ui';
 ```
 
-#### Method 2: Use the ThemeProvider with brand
+This CSS path does not require Tailwind in your application. For a first interactive
+example, render a theme switcher inside the provider:
 
 ```tsx
-import { ThemeProvider } from '@mieweb/ui';
-import { enterpriseHealthBrand } from '@mieweb/ui/brands';
-
-function App() {
-  return (
-    <ThemeProvider brand={enterpriseHealthBrand}>
-      <YourApp />
-    </ThemeProvider>
-  );
-}
-```
-
-#### Method 3: Tailwind CSS preset
-
-```js
-// tailwind.config.js
-const { enterpriseHealthBrand } = require('@mieweb/ui/brands');
-const { createBrandPreset } = require('@mieweb/ui/brands/types');
-
-module.exports = {
-  presets: [createBrandPreset(enterpriseHealthBrand)],
-  // ...
-};
-```
-
-### Brand Design Tokens
-
-Each brand defines the following design tokens:
-
-#### Enterprise Health
-
-Extracted from [enterprisehealth.com](https://enterprisehealth.com):
-
-```css
-/* Primary: Burgundy/Purple */
---mieweb-primary-600: #6e2b68;
-
-/* Secondary: Deep Teal Blue (for gradients) */
---mieweb-secondary: #00497a;
-
-/* Accent: Gold/Yellow (logo) */
---mieweb-accent: #f8b700;
-
-/* Brand Gradient */
---mieweb-gradient: linear-gradient(111.02deg, #00497a, #6e2b68);
-
-/* Typography */
---mieweb-font-sans: 'Jost', ui-sans-serif, system-ui, sans-serif;
-
-/* Border Radius (larger, more rounded) */
---mieweb-radius-sm: 0.375rem; /* 6px - badges */
---mieweb-radius-md: 0.625rem; /* 10px - buttons */
---mieweb-radius-lg: 0.75rem; /* 12px - inputs */
---mieweb-radius-2xl: 1.5rem; /* 24px - cards */
-
-/* Shadows (subtle, layered) */
---mieweb-shadow-card:
-  0 16px 32px 0 rgba(34, 35, 38, 0.05), 0 8px 16px 0 rgba(34, 35, 38, 0.05);
-```
-
-#### BlueHive
-
-```css
-/* Primary: Blue */
---mieweb-primary-500: #27aae1;
-
-/* Typography */
---mieweb-font-sans: 'Nunito', ui-sans-serif, system-ui, sans-serif;
-```
-
-### Creating a Custom Brand
-
-You can create your own brand configuration:
-
-```ts
-import type { BrandConfig } from '@mieweb/ui/brands/types';
-
-export const myBrand: BrandConfig = {
-  name: 'my-brand',
-  displayName: 'My Brand',
-  description: 'Custom brand for my application',
-
-  colors: {
-    primary: {
-      50: '#f0f9ff',
-      // ... full color scale 50-950
-      600: '#0284c7', // Main brand color
-      // ...
-    },
-    light: {
-      background: '#ffffff',
-      foreground: '#171717',
-      // ... semantic colors
-    },
-    dark: {
-      background: '#171717',
-      foreground: '#fafafa',
-      // ... semantic colors
-    },
-  },
-
-  typography: {
-    fontFamily: {
-      sans: ['Your Font', 'ui-sans-serif', 'system-ui', 'sans-serif'],
-      mono: ['ui-monospace', 'SFMono-Regular', 'Menlo', 'monospace'],
-    },
-  },
-
-  borderRadius: {
-    none: '0',
-    sm: '0.25rem',
-    md: '0.5rem',
-    lg: '0.75rem',
-    xl: '1rem',
-    '2xl': '1.5rem',
-    full: '9999px',
-  },
-
-  boxShadow: {
-    card: '0 1px 3px 0 rgb(0 0 0 / 0.1)',
-    dropdown: '0 4px 6px -1px rgb(0 0 0 / 0.1)',
-    modal: '0 10px 15px -3px rgb(0 0 0 / 0.1)',
-  },
-};
-```
-
-## Theming
-
-The library uses CSS custom properties for theming. Override these variables to customize the appearance:
-
-```css
-:root {
-  /* Primary color scale */
-  --mieweb-primary-500: #27aae1;
-
-  /* Semantic colors */
-  --mieweb-background: hsl(0 0% 100%);
-  --mieweb-foreground: hsl(222.2 84% 4.9%);
-
-  /* Border radius */
-  --mieweb-radius-md: 0.5rem;
-
-  /* Font */
-  --mieweb-font-sans: 'Your Font', sans-serif;
-}
-```
-
-### Dark Mode
-
-The library supports dark mode via the `.dark` class or `data-theme="dark"` attribute on a parent element:
-
-```tsx
-import { ThemeProvider, useThemeContext, Button } from '@mieweb/ui';
+import { Button, ThemeProvider, useThemeContext } from '@mieweb/ui';
 
 function ThemeToggle() {
   const { resolvedTheme, setTheme } = useThemeContext();
+
   return (
     <Button
+      aria-label="Dark mode"
+      aria-pressed={resolvedTheme === 'dark'}
       onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
     >
-      Toggle Theme
+      Dark mode
     </Button>
   );
 }
 
-function App() {
+export default function App() {
   return (
     <ThemeProvider>
       <ThemeToggle />
@@ -622,186 +139,92 @@ function App() {
 }
 ```
 
-## Components
-
-### Primitives
-
-- `Button` - Multi-variant button with loading state
-- `Input` - Text input with label, error, and helper text
-- `Card` - Container component with header, content, and footer
-- `Text` - Typography component with variants
-- `Badge` - Status indicators and labels
-- `Alert` - Feedback messages
-
-### Specialized Inputs
-
-- `PhoneInput` - US phone number formatting
-- `DateInput` - Date input with validation modes (DOB, expiration, etc.)
-
-### Overlays
-
-- `Tooltip` - Accessible tooltip with multiple placements
-- `Dropdown` - Dropdown menu with items, separators, and labels
-
-### Utilities
-
-- `VisuallyHidden` - Screen reader only content
-- `ThemeProvider` - Theme context provider
-
-## Hooks
-
-- `useTheme()` - Theme state management
-- `useClickOutside()` - Detect clicks outside an element
-- `useEscapeKey()` - Handle escape key press
-- `useFocusTrap()` - Trap focus within a container
-- `usePrefersReducedMotion()` - Detect reduced motion preference
-
-## Utilities
-
-### Class Names
-
-```tsx
-import { cn } from '@mieweb/ui/utils';
-
-// Merge classes with Tailwind conflict resolution
-cn('px-4 py-2', isActive && 'bg-primary-500', className);
-```
-
-### Phone Utilities
-
-```tsx
-import { formatPhoneNumber, isValidPhoneNumber } from '@mieweb/ui/utils';
-
-formatPhoneNumber('5551234567'); // "(555) 123-4567"
-isValidPhoneNumber('5551234567'); // true
-```
-
-### Date Utilities
-
-```tsx
-import { formatDateValue, calculateAge, isValidDate } from '@mieweb/ui/utils';
-
-formatDateValue('01152024'); // "01/15/2024"
-calculateAge('01/15/1990'); // 34
-isValidDate('01/15/2024'); // true
-```
-
-## Tree-Shaking
-
-Import components directly for optimal bundle size:
-
-```tsx
-// Import only what you need
-import { Button } from '@mieweb/ui/components/Button';
-import { useTheme } from '@mieweb/ui/hooks';
-import { cn } from '@mieweb/ui/utils';
-```
-
-## TypeScript
-
-All components are fully typed. Import types as needed:
-
-```tsx
-import type { ButtonProps, InputProps, Theme } from '@mieweb/ui';
-```
-
-## Releases
-
-This package uses automated releases via GitHub Actions. There are two release channels:
-
-### Release Channels
-
-| Channel        | npm Tag  | Install Command               | Description               |
-| -------------- | -------- | ----------------------------- | ------------------------- |
-| **Stable**     | `latest` | `npm install @mieweb/ui`      | Production-ready releases |
-| **Prerelease** | `next`   | `npm install @mieweb/ui@next` | Latest from `main` branch |
-
-### Prerelease (Automatic)
-
-Every push to the `main` branch automatically publishes a prerelease version to npm:
-
-- **Version format:** `x.y.z-dev.{run_number}` (e.g., `0.1.0-dev.45`)
-- **npm tag:** `next`
-- **Install:** `npm install @mieweb/ui@next`
-
-This allows consumers to test the latest changes before a stable release.
-
-### Stable Release (Manual)
-
-To create a stable release:
-
-1. Go to the repository on GitHub
-2. Navigate to **Actions** → **Create Stable Release**
-3. Click **Run workflow**
-4. Select the version bump type:
-   - `patch` - Bug fixes (0.1.0 → 0.1.1)
-   - `minor` - New features (0.1.0 → 0.2.0)
-   - `major` - Breaking changes (0.1.0 → 1.0.0)
-5. Click **Run workflow**
-
-The workflow will:
-
-1. Bump the version in `package.json`
-2. Commit and push the change
-3. Create a git tag (e.g., `v0.2.0`)
-4. Trigger the release workflow which publishes to npm and creates a GitHub Release
-
-### Manual Tag Release
-
-You can also create a release by pushing a version tag directly:
-
-```bash
-# Create and push a tag
-git tag v1.0.0
-git push origin v1.0.0
-```
-
-The release workflow will automatically:
-
-- Run tests and build
-- Publish to npm with the appropriate tag (`latest` for stable, `next` for prereleases like `v1.0.0-beta.1`)
-- Create a GitHub Release with auto-generated release notes
-
-### Version Guidelines
-
-We follow [Semantic Versioning](https://semver.org/):
-
-- **MAJOR** version for incompatible API changes
-- **MINOR** version for backwards-compatible functionality additions
-- **PATCH** version for backwards-compatible bug fixes
-
-## Contributing
-
-We welcome contributions! This README and the [Storybook](https://ui.mieweb.org)
-are the **consumer** docs (how to _use_ the library). If you want to _build or
-change_ the library itself, the **provider / maintainer** guide is
-**[CONTRIBUTING.md](CONTRIBUTING.md)** — it covers repo layout, the component
-anatomy and conventions, the autodocs story pattern, exports & tree-shaking,
-build, testing (unit + visual baselines), submodules, brands, and the release
-process.
-
-Quick start for contributors:
-
-```bash
-git clone --recurse-submodules https://github.com/mieweb/ui.git
-cd ui && pnpm install
-pnpm storybook            # http://localhost:6006
-# before opening a PR:
-pnpm typecheck && pnpm lint && pnpm format && pnpm test
-```
-
-Non-trivial modules also carry a `MAINTAINERS.md` next to the code with internals,
-invariants, and gotchas for that module — see the table in
-[CONTRIBUTING.md](CONTRIBUTING.md#per-component-maintainer-notes).
+In production, supply translated labels through your application's i18n system.
+In Next.js App Router, put this interactive example in a client component and
+import global styles from the root layout.
+
+Already using Tailwind? Follow the
+[Tailwind 4 integration guide](https://github.com/mieweb/ui/blob/main/lessons/tailwind4-integration.md)
+for CSS-first configuration, `@source`, and theme tokens. Tailwind 3 consumers can
+use `@mieweb/ui/tailwind-preset`. Do not apply a Tailwind 3 configuration as a
+Tailwind 4 setup.
+
+### Add Specialized Capabilities When Needed
+
+Heavy integrations use separate entry points and optional peer dependencies so
+you only install what you need:
+
+- **Data grids:** [DataVis NITRO](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro--docs), imported from `@mieweb/ui/datavis`.
+- **Form authoring and rendering:** [eSheet integration](https://github.com/mieweb/ui/blob/main/src/components/ESheet/MAINTAINERS.md), imported from `@mieweb/ui/esheet`.
+- **Rich text and code editing:** [Kerebron editor setup](https://github.com/mieweb/ui/tree/main/src/components/RichEditor), imported from `@mieweb/ui/kerebron`.
+
+Check the selected integration's dependencies before importing its entry point.
+AGGrid is deprecated for new work; start with DataVis NITRO for tabular data.
+
+## Explore and Compose Components
+
+Open [the component explorer](https://ui.mieweb.org/). Storybook is the wrapper
+around the examples: its sidebar selects components, a **story** demonstrates a
+particular configuration, and **Docs** presents guidance and the API. **Controls**
+change example props; theme and brand tools let you inspect different appearances.
+Those tools belong to Storybook, not to the component you install.
+
+Start with the user's task, then compare components before choosing an API:
+
+- **Browse and work with records:** start with [DataVis NITRO](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro--docs)
+  and compare [Table](https://ui.mieweb.org/?path=/docs/grids-table--docs).
+  NITRO provides integrated data tooling; Table provides lower-level markup.
+  Consider the behavior your application would need to supply and consult the
+  selection rules before choosing an exception.
+- **Navigate a long document:** compare [TableOfContents](https://ui.mieweb.org/?path=/docs/navigation-tableofcontents--docs)
+  and [ReadingProgressBar](https://ui.mieweb.org/?path=/docs/navigation-readingprogressbar--docs).
+  A TOC provides named destinations and navigation. A reading bar is a decorative
+  document-scroll cue, not navigation or proof of reading. They can complement
+  each other; neither may be needed for short content.
+- **Assemble an application view:** explore the [Dashboard example](https://ui.mieweb.org/?path=/story/dashboards-dashboard-demo--dashboard).
+  Inspect how navigation, headers, and content fit together, then adapt the
+  composition to your workflow rather than copying the layout indiscriminately.
+
+For each choice, ask why it fits, when an alternative would be better, what state
+your application owns, and how it behaves alongside neighboring components.
+Exercise loading, empty, error, keyboard, and narrow-screen states in the actual
+application, not only the isolated story.
+
+The catalog is still being improved: not every component has comparison or
+composition guidance yet. Do not treat an isolated example as evidence that no
+related component exists. Use the
+[component policy](https://github.com/mieweb/ui/blob/main/lessons/component-policy.md)
+and flag missing or conflicting guidance in a
+[documentation issue](https://github.com/mieweb/ui/issues/new).
+
+### Go Deeper
+
+- [Branding](https://ui.mieweb.org/?path=/docs/branding--docs): the brand system and visual tokens.
+- [Adoption guides](https://github.com/mieweb/ui/blob/main/lessons/README.md): integration pitfalls and migration paths for existing applications.
+- [AI-assisted migration plan](https://github.com/mieweb/ui/blob/main/lessons/execution-plan.md): an ordered approach to adopting the library.
+- [Meteor migration](https://github.com/mieweb/ui/blob/main/lessons/migration-meteor-blaze-to-react.md): framework-specific migration guidance.
+
+## Contribute or Run Locally
+
+To change the library, improve its guidance, or run your own Storybook, follow
+[CONTRIBUTING.md](https://github.com/mieweb/ui/blob/main/CONTRIBUTING.md). It covers
+repository setup, local development, tests, component conventions, and releases.
+Those steps are not required to consume the npm package.
+
+Found unclear selection advice or an undocumented relationship? Documentation
+contributions are welcome alongside component fixes.
+[Edit this introduction](https://github.com/mieweb/ui/edit/main/README.md) to
+improve the shared GitHub, npm, and Storybook content. Published copies update
+when the package is released or the documentation site is deployed.
 
 ## License
 
 Copyright © 2026 Medical Informatics Engineering, Inc. All rights reserved.
 
-This software is **source available** with the following terms:
+This software is **source available**:
 
-- ✅ **Free for open source projects** - Use, modify, and distribute freely in open source projects with attribution
-- ✅ **Free for non-commercial use** - Personal projects, education, research
-- 💼 **Commercial license required** - For proprietary products or commercial use, contact [licensing@mieweb.com](mailto:licensing@mieweb.com)
+- **Free for open source projects:** use, modify, and distribute in open source projects with attribution.
+- **Free for non-commercial use:** personal projects, education, and research.
+- **Commercial license required:** for proprietary products or commercial use, contact [licensing@mieweb.com](mailto:licensing@mieweb.com).
 
-See the [LICENSE](LICENSE) file for full details.
+See the [LICENSE](https://github.com/mieweb/ui/blob/main/LICENSE) for full terms.