@dreamtree-org/twreact-ui 1.2.1 → 1.3.1

package/DESIGN.md

@@ -0,0 +1,118 @@
+---
+name: Dreamtree
+description: Shared design rules for every Dreamtree product UI, generated from twreact-ui tokens/tokens.json.
+source: "@dreamtree-org/twreact-ui/tokens/tokens.json"
+colors:
+  background: "#f8fafc"
+  surface: "#ffffff"
+  foreground: "#0f172a"
+  muted: "#475569"
+  line: "#e2e8f0"
+  shell: "#0f172a"
+  shell-foreground: "#cbd5e1"
+  shell-active: "#1e293b"
+  primary: "#2563eb"
+  secondary: "#475569"
+  success: "#16a34a"
+  warning: "#d97706"
+  error: "#dc2626"
+  info: "#0284c7"
+colorsDark:
+  background: "#0b1120"
+  surface: "#111827"
+  foreground: "#e5e7eb"
+  muted: "#94a3b8"
+  line: "#1f2937"
+  shell: "#020617"
+  shell-foreground: "#cbd5e1"
+  shell-active: "#1e293b"
+typography:
+  fontFamily: "Inter"
+  pageTitle: { size: 24px, lineHeight: 32px, weight: 600 }
+  sectionTitle: { size: 16px, lineHeight: 24px, weight: 600 }
+  body: { size: 14px, lineHeight: 20px, weight: 400 }
+  caption: { size: 12px, lineHeight: 16px, weight: 400 }
+  micro: { size: 11px, lineHeight: 16px, weight: 500 }
+  kpi: { size: 30px, lineHeight: 36px, weight: 600 }
+rounded:
+  control: 8px
+  card: 12px
+  pill: 9999px
+spacing:
+  grid: 4px
+  steps: [4, 8, 12, 16, 20, 24, 32]
+brands: [default, practicepro]
+---
+
+<!-- Generated by twreact-ui scripts/build-tokens.mjs from tokens/tokens.json. Edit the tokens or this generator, not this file. -->
+
+# Dreamtree design rules
+
+Every Dreamtree product screen, and every prototype generated by Dreamtree Studio, follows these rules. They are enforced by `@dreamtree-org/config` design-lint (`dreamtree({ design: true })`) and by Studio's `validate_screen`.
+
+## 1. Components come from twreact-ui
+
+- Build screens from `@dreamtree-org/twreact-ui` components and blocks. Do not hand-roll a Button, Dialog, Table, Badge, Card, Toast, Tabs or Pagination.
+- Page structure comes from blocks: `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`.
+- Icons come from `lucide-react` only. Icon-only buttons need an `aria-label`.
+- If a pattern is missing, compose it from existing components and flag it as a candidate block. Do not copy one from another product.
+
+## 2. Colour comes from tokens, never raw values
+
+- **Never** write hex, `rgb()` or `hsl()` in `className` or `style`, and never use Tailwind's raw palette (`bg-blue-500`, `text-slate-600`).
+- Use the semantic scales: `primary` (the one accent), `secondary` (neutral), `success`, `warning`, `error`, `info`, and `gray` for borders and quiet fills. Each has steps 50–950.
+- Use roles for surfaces and text:
+
+| Role | Utility | Light | Dark | Use |
+| --- | --- | --- | --- | --- |
+| `background` | `bg-background` / `text-background` | #f8fafc | #0b1120 | Page background. |
+| `surface` | `bg-surface` / `text-surface` | #ffffff | #111827 | Cards, dialogs, menus. |
+| `foreground` | `bg-foreground` / `text-foreground` | #0f172a | #e5e7eb | Body text and titles. |
+| `muted` | `bg-muted` / `text-muted` | #475569 | #94a3b8 | Subtitles, labels, captions (7.5:1 on white). |
+| `line` | `bg-line` / `text-line` | #e2e8f0 | #1f2937 | Card and divider borders. |
+| `shell` | `bg-shell` / `text-shell` | #0f172a | #020617 | App shell sidebar background. |
+| `shell-foreground` | `bg-shell-foreground` / `text-shell-foreground` | #cbd5e1 | #cbd5e1 | Sidebar text. |
+| `shell-active` | `bg-shell-active` / `text-shell-active` | #1e293b | #1e293b | Active sidebar item fill. |
+
+- **One accent per screen.** `primary` marks the primary action, the active nav item, the current step and progress. Red (`error`) is only for errors, overdue items and destructive actions.
+- Badge and status fills use the 100 step with 800 text, which keeps contrast at or above 4.5:1.
+- Products change their look with a **brand file** (`tokens/brands/<product>.json`), which overrides `--dt-*` variables. Brands available: `default`, `practicepro`.
+
+## 3. Type, space and shape
+
+- Font: Inter. Numbers in tables and KPIs use `tabular-nums`.
+- Scale: page title `text-2xl font-semibold`, section title `text-base font-semibold`, body `text-sm`, caption `text-xs text-muted`, KPI `text-3xl font-semibold`. For tiny labels use `text-micro`, never `text-[10px]` or `text-[11px]`.
+- **No arbitrary values** (`w-[312px]`, `text-[13px]`, `p-[7px]`). Use the Tailwind scale on a 4 px grid: steps 1, 2, 3, 4, 5, 6, 8.
+- Radius: `rounded-control` (8 px) for buttons, inputs and menus; `rounded-card` (12 px) for cards and dialogs; `rounded-full` for pills and badges.
+- Sentence case everywhere ("Add obligation", not "Add Obligation").
+
+## 4. Page anatomy
+
+- One `h1` per page, inside `PageHeader` (title, optional subtitle, actions). **One primary action per page**, top right; it becomes full-width below `sm`.
+- All content sits in cards (`Card`), never loose on the page background. Use a grid with `gap-4 md:gap-6`; main plus side panel is `lg:grid-cols-[minmax(0,1fr)_360px]`. That column template is the one allowed arbitrary value.
+- Creating a record opens a Dialog (short form) or goes to a `/new` page (a wizard).
+
+## 5. Every data screen has its states
+
+- **Loading:** `LoadingState` or `Skeleton` shaped like the final content, inside the card. No page-level spinners.
+- **Empty:** `EmptyState` inside the card, with a title, one line saying what to do, and the primary action.
+- **Error:** `ErrorState` inside the card, with neutral copy and a Retry button. Never show raw `error.message`.
+- Statuses use `StatusPill`, a single map from domain state to tone and a human label. Never show a raw enum such as `in_review`.
+
+## 6. Dialogs and feedback
+
+- **Never** use `alert()`, `confirm()` or `prompt()`. Confirmations use `ConfirmDialog`: the title is the action as a question, the body is one line saying what happens, and the action button is named with the verb (`destructive` when the action can't be undone).
+- Outcomes ("Saved", "Reminder drafted") use `Toast`. Errors that block the user stay inline in an `Alert`.
+
+## 7. Responsive and accessible
+
+- No horizontal page scroll at **390 px**. Below `lg` the shell becomes a top bar with a drawer. Wide tables scroll inside their card.
+- Tap targets are at least 40 px. Every control has a visible label. Focus is visible (`focus:ring-2 focus:ring-primary-500 focus:ring-offset-2`).
+- Text contrast is at least 4.5:1. Status is never shown by colour alone: badges carry words.
+- Respect `prefers-reduced-motion`.
+
+## 8. Data and content
+
+- Prototypes use **mock data only**, never real client data.
+- Indian products format money as ₹ with lakh/crore grouping (₹12,34,567; ₹4.8L), and dates as DD MMM YYYY (20 Oct 2026).
+- Use realistic content, including awkward cases: long company names, ₹0, empty lists and very long lists.

package/README.md

@@ -64,6 +64,45 @@ npm install @dreamtree-org/twreact-ui
 yarn add @dreamtree-org/twreact-ui
 ```
 
+Import the stylesheet once (app entry or root layout):
+
+```js
+import '@dreamtree-org/twreact-ui/dist/index.css';
+```
+
+### Bundle size and tree-shaking
+
+Import from the package root. Bundlers (Vite, webpack 5, esbuild, Rollup, Next.js) resolve it to a
+per-module ES build (`dist/esm/`, via the `module` field and the `module` export condition), and the
+package declares `"sideEffects": ["**/*.css"]`, so only the components you import end up in your
+bundle. `import { Button } from '@dreamtree-org/twreact-ui'` costs about 8 KB gzip, down from about
+100 KB. `require()`, Jest and plain Node keep getting the CommonJS build (`dist/index.js`).
+
+There are no per-component subpaths such as `@dreamtree-org/twreact-ui/button`. The root import
+already tree-shakes. Existing file paths (`dist/index.css`, `dist/tokens/*`, `tokens/*`,
+`dist/index.esm.js`, `package.json`, …) still resolve through the `exports` map.
+
+### Next.js App Router
+
+Every module that uses React starts with `'use client'`, so Server Components can import
+components directly. You no longer need a `"use client"` wrapper file that re-exports the library:
+
+```tsx
+// app/page.tsx — a Server Component
+import { Button, cn } from '@dreamtree-org/twreact-ui';
+
+export default function Page() {
+  return <Button className={cn('mt-4')}>Save</Button>;
+}
+```
+
+`cn`, `Helpers` and `Emitter` carry no directive, so they also run on the server. Two React
+Server Component rules still apply. You cannot pass functions (`onClick`, `render`, …) from a
+Server Component to these Client Components. You also cannot dot into a client export, so
+`<Card.Header>`, `<Tabs.List>` and `<Dialog.Footer>` must be used inside a `'use client'` file.
+In Vite, Rollup can log `Module level directives cause errors when bundled, "use client" … was ignored`.
+This message is harmless. To hide it, filter `MODULE_LEVEL_DIRECTIVE` in `build.rollupOptions.onwarn`.
+
 ## Quick Start
 
 ```jsx
@@ -147,7 +186,7 @@ Versatile button component with multiple variants and states.
 
 **Props:**
 - `variant`: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'success' | 'warning' (default: 'primary')
-- `size`: 'sm' | 'md' | 'lg' (default: 'md')
+- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' (default: 'md') — heights h-7 / h-8 / h-10 / h-12 / h-14 / h-16
 - `disabled`: boolean
 - `loading`: boolean
 - `leftIcon`: ReactNode
@@ -172,6 +211,7 @@ Enhanced text input with validation states, icons, and clear functionality.
 - `placeholder`: string
 - `error`: string
 - `success`: string
+- `helperText`: ReactNode — hint below the input, linked via `aria-describedby`; replaced by `error` / `success` while shown
 - `disabled`: boolean
 - `required`: boolean
 - `clearable`: boolean
@@ -197,17 +237,18 @@ Enhanced text input with validation states, icons, and clear functionality.
 Advanced select component with search, multi-select, and grouping support.
 
 **Props:**
-- `options`: Array<{value: any, label: string, disabled?: boolean}>
+- `options`: Array<{value: any, label: string, disabled?: boolean, group?: string}> (with `grouped`: also `[{ label, options }]` groups)
 - `value`: any | Array<any>
 - `onChange`: (value: any) => void
 - `placeholder`: string (default: 'Select an option...')
-- `label`: string
+- `label`: string — associated with the trigger (accessible name = label + value)
 - `error`: string
+- `helperText`: ReactNode — hint below the control; replaced by `error` while shown
 - `disabled`: boolean
 - `required`: boolean
 - `multiSelect`: boolean
 - `searchable`: boolean
-- `grouped`: boolean
+- `grouped`: boolean — groups objects or flat options with a `group` key; malformed input is skipped (console warning), never thrown
 - `creatable`: boolean
 - `onCreateOption`: (value: string) => void
 - `onSearch`: (term: string) => void
@@ -241,6 +282,8 @@ Declarative form builder with validation support.
 - `resetText`: string (default: 'Reset')
 - `showReset`: boolean (default: true)
 
+Field types: `text`, `email`, `password`, `number`, `tel`, `url`, `select`, `date`, `textarea`, `checkbox`, `radio`, `file`, `switch`, `color` (mounts `ColorPicker`; accepts `swatches` / `showAlpha`), `custom`. Every field accepts `helperText` (hint under the field; the validation error replaces it while shown).
+
 ```jsx
 const formFields = [
   {
@@ -273,7 +316,8 @@ actions, and expandable row details.
 - `data`: Array<object>
 - `columns`: Array<Column>
 - `sortable`: boolean (default: true)
-- `filterable`: boolean
+- `filterable`: boolean — per-column filter inputs; filter client-side data as you type (not in `serverSide` mode)
+- `globalSearch`: boolean — search box; filters client-side data with or without `filterable` (skips `searchable: false` columns)
 - `selectable`: boolean
 - `pagination`: boolean
 - `pageSize`: number (default: 25)
@@ -281,7 +325,7 @@ actions, and expandable row details.
 - `onFilter`: (filters: object) => void
 - `onSelectionChange`: (selectedRows: object[]) => void
 - `onRowClick`: (row: object, index: number) => void
-- `onPageChange`: (page: number) => void
+- `onPageChange`: (page: number) => void — also called when the table clamps a page that no longer exists after the data shrinks
 - `hasDetails`: boolean | ((row, index) => boolean)
 - `DetailsComponent`: ReactComponent
 - `withAction`: boolean (default: true)
@@ -295,6 +339,15 @@ actions, and expandable row details.
 - `onSave`: ({ updatedRows, newRows, allData, tableData }) => void | Promise<allData | { data: allData } | void>
 - `onEdit`: ({ rowKey, colKey, newValue, row, action, isNew }) => void
 - `showSerial`: boolean (default: true)
+- `showToolbar`: boolean (default: true) — `false` hides the toolbar (reload, page size, result count, pager header) and the column picker; interactive save controls still render
+- `showColumnPicker`: boolean (default: true) — hide just the column-picker button and its column
+- `wrapCells`: boolean (default: false) — let every cell wrap; a column's own `wrap` wins
+- `mobileMaxFields`: number — cap the fields shown on each mobile card (column order, after `hideOnMobile`)
+- `serverSide` / `totalRecords`: in server-side mode the "start - end of total" counter reads `totalRecords`
+
+Column extras: `searchable: false` keeps a column out of the global search
+(ids, codes), `wrap: true` lets its text wrap instead of staying on one line, and
+`hideOnMobile: true` leaves it off the mobile card view (desktop is unaffected).
 
 An `Action` is `{ name, label, icon, render?, onClick?, hidden?, disabled?,
 inline? }`. `label`, `icon`, `hidden` and `disabled` each accept a value **or** a
@@ -335,6 +388,7 @@ Calendar-based date selection with keyboard navigation.
 - `placeholder`: string (default: 'Select date...')
 - `label`: string
 - `error`: string
+- `helperText`: ReactNode — hint below the trigger; replaced by `error` while shown
 - `disabled`: boolean
 - `required`: boolean
 - `minDate`: Date | string
@@ -367,22 +421,31 @@ Collapsible sidebar navigation with nested items.
 - `logo`: ReactNode
 - `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>}
 - `onUserClick`: (user: object) => void
+- `linkAs`: ElementType (default: `"a"`) — e.g. Next.js `Link`
+- `expandedIds` / `defaultExpandedIds`: string[] — open groups (controlled / uncontrolled); `onExpandedChange`: (ids: string[]) => void
+- `footer`: ReactNode | ({ collapsed, isMobile, closeMobile }) => ReactNode — pinned region above the user block
+- `stickyOffset`: number | string — height of a top bar above the sidebar (sticks below it, fits the viewport); `containerClassName` for the outer sticky wrapper
+- `isMobileOpen` / `setIsMobileOpen`: mobile drawer — inert while closed; focus-trapped, Escape-to-close and focus-restoring while open
+
+Every item renders as an `<a>`. Give an item an `href` and it becomes a real link, so Ctrl/Cmd-click or middle-click opens it in a new tab. Parents with an `href` navigate and expand; their chevron toggles without navigating. The group holding an `active: true` item (any depth) opens on load. Items take `badge` (+ accessible `badgeLabel`) and top-level `group` (section heading, a divider when collapsed — same as `AppShell`). With `onUserClick` the user block is a real `<button>`.
 
 ```jsx
 const sidebarItems = [
   {
     id: 'dashboard',
     label: 'Dashboard',
+    href: '/dashboard',
     icon: <Home className="h-4 w-4" />,
     active: true
   },
   {
     id: 'users',
     label: 'Users',
+    href: '/users',
     icon: <Users className="h-4 w-4" />,
     children: [
-      { id: 'all-users', label: 'All Users' },
-      { id: 'new-user', label: 'Add New User' }
+      { id: 'all-users', label: 'All Users', href: '/users' },
+      { id: 'new-user', label: 'Add New User', href: '/users/new' }
     ]
   }
 ];
@@ -398,9 +461,10 @@ const sidebarItems = [
 Top navigation bar with user menu and notifications.
 
 **Props:**
-- `logo`: ReactNode
+- `logo`: ReactNode (truncates on narrow screens)
+- `center`: ReactNode — centre slot (e.g. a search field); shrinks first so the bar fits a 390px phone
 - `items`: Array<NavItem>
-- `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>}
+- `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>} — without `avatar`, the menu shows `name` initials; below `sm` the logout icon moves into the user menu as "Sign out"
 - `notifications`: Array<Notification>
 - `searchable`: boolean
 - `onSearch`: (term: string) => void
@@ -420,6 +484,38 @@ Top navigation bar with user menu and notifications.
 />
 ```
 
+#### FootNav
+Fixed bottom tab bar for phones (`md:hidden`). Uses the semantic `bg-surface` / `border-line` tokens, so it follows dark mode.
+
+**Props:**
+- `items`: Array<{ id, label, icon, onClick?, active?, badge? }>
+- `className`: string
+
+The `active` item gets a tinted primary background, `text-primary-700` and `aria-current="page"` (inactive tabs are neutral `text-muted`). Badges sit on their own item's icon. Items share the width and labels truncate, so five tabs fit a 375px screen.
+
+```jsx
+<FootNav
+  items={[
+    { id: 'home', label: 'Home', icon: <Home />, active: true, onClick: () => navigate('/') },
+    { id: 'inbox', label: 'Inbox', icon: <Inbox />, badge: 3, onClick: () => navigate('/inbox') },
+  ]}
+/>
+```
+
+#### Breadcrumbs
+Breadcrumb trail with an optional Home link.
+
+**Props:**
+- `items`: Array<{ id?, label, href?, icon?, onClick? }> — `id` is optional (used as the React key when present)
+- `separator`: ReactNode
+- `showHome`: boolean (default: true)
+- `homeIcon`: ReactNode
+- `onHomeClick`: () => void
+
+```jsx
+<Breadcrumbs items={[{ label: 'Projects', href: '/projects' }, { label: 'Alpha' }]} />
+```
+
 ### Feedback Components
 
 #### Alert
@@ -455,6 +551,23 @@ Notification messages with different types, actions, bottom progress bar, and po
 - `onClose`: (id: string) => void
 - `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'
 
+**App-level provider (recommended).** Wrap the app once in `ToastProvider`; every `useToast()` below it shares one queue and the provider renders it — no per-screen `ToastContainer`:
+
+```jsx
+import { ToastProvider, useToast } from '@dreamtree-org/twreact-ui';
+
+<ToastProvider position="top-right">
+  <App />
+</ToastProvider>;
+
+function SaveButton() {
+  const { toast } = useToast();
+  return <button onClick={() => toast.success('Saved')}>Save</button>;
+}
+```
+
+**Standalone (no provider).** Outside a provider each `useToast()` owns its own queue; render it with `ToastContainer`. Under a provider, a `ToastContainer` handed the provider's own `toasts` renders nothing, so it never double-renders while you migrate.
+
 ```jsx
 import { useToast, ToastContainer } from '@dreamtree-org/twreact-ui';
 
@@ -567,47 +680,121 @@ const tabItems = [
 <Tabs items={tabItems} variant="pills" />
 ```
 
+### Overlays, inputs and lists
+
+Interaction primitives that products used to compose by hand. All are `forwardRef`, accept `className` + `...rest`, are keyboard-operable with explicit ARIA, dark-mode aware and respect `prefers-reduced-motion`.
+
+| Component | Group | Use for |
+|---|---|---|
+| [`Drawer`](doc/Drawer.md) | Feedback | Side/edge sheet (`placement` right/left/top/bottom, `size` sm–full) — record peeks and editors. Same `isOpen`/`onClose` contract as `Dialog`; focus trap, Escape/backdrop close, focus restore, scroll lock; `Drawer.Header/Body/Footer` |
+| [`Popover`](doc/Popover.md) | Core | Anchored, click-triggered panel with interactive content (unlike `Tooltip`). Controlled/uncontrolled `open`, `placement` with flip, Escape/outside-click close, `aria-expanded`/`aria-controls`/`aria-haspopup="dialog"` |
+| [`Textarea`](doc/Textarea.md) | Core | Multi-line input mirroring `Input`: `label`, `error`, `helperText`, `required`, `showCount`/`maxLength`, `autoResize`/`maxRows` |
+| [`Slider`](doc/Slider.md) | Core | Single value or `[low, high]` range; `min`/`max`/`step`, arrows/PageUp/PageDown/Home/End, `role="slider"` with full `aria-value*` |
+| [`Sortable`](doc/Sortable.md) | Utility | Drag-to-reorder list (pointer events, no extra dependency) + keyboard reordering (Space, arrows, Space/Escape) with live announcements; `items`, `onReorder`, `renderItem`, `getKey` |
+| [`Tour`](doc/Tour.md) | Feedback | Step-based onboarding: spotlight on each `target` (selector or ref), Back/Next/Skip/Finish, `open`/`onClose`/`onFinish`, scrolls targets into view |
+
+```jsx
+import { Drawer, Popover, Textarea, Slider, Sortable, Tour, Button } from '@dreamtree-org/twreact-ui';
+
+<Drawer isOpen={open} onClose={() => setOpen(false)} title="Edit task" footer={<Button onClick={save}>Save</Button>}>
+  <Textarea label="Description" autoResize showCount maxLength={500} />
+</Drawer>
+
+<Popover trigger={<Button variant="outline">Filters</Button>} title="Filters">
+  <Slider label="Budget" defaultValue={[2000, 8000]} min={0} max={10000} step={500} showValue />
+</Popover>
+
+<Sortable aria-label="Backlog" items={tasks} onReorder={setTasks} renderItem={(t) => t.title} />
+
+<Tour open={tourOpen} steps={[{ title: 'Welcome' }, { target: '[data-tour="new-task"]', title: 'Capture work' }]} onClose={() => setTourOpen(false)} />
+```
+
+### Page blocks
+
+Page-level patterns extracted from the Dreamtree products. Build pages from these before composing layouts by hand.
+
+| Block | Use for |
+|---|---|
+| [`AppShell`](doc/AppShell.md) | Product shell: sidebar, top bar, mobile drawer (`nav`, `linkAs`) |
+| [`PageHeader`](doc/PageHeader.md) | The page's `h1`, subtitle, one primary action, back link |
+| [`StatCard`](doc/StatCard.md) | KPI tile with icon, tone and change |
+| [`StatusPill`](doc/StatusPill.md) | Domain status → tone and human label (never a raw enum) |
+| [`EmptyState`](doc/EmptyState.md) / [`ErrorState`](doc/ErrorState.md) / [`LoadingState`](doc/LoadingState.md) | The three states every data card needs |
+| [`ConfirmDialog`](doc/ConfirmDialog.md) | Confirmation step — replaces `window.confirm()` |
+
+```jsx
+import { PageHeader, StatCard, StatusPill, EmptyState, Button } from '@dreamtree-org/twreact-ui';
+
+<PageHeader title="Compliance calendar" actions={<Button>Add obligation</Button>} />
+<StatCard label="Due this week" value={18} icon={<CalendarDays className="h-6 w-6" />} />
+<StatusPill status="docs_missing" map={{ docs_missing: { label: 'Missing documents', tone: 'warning' } }} />
+```
+
+Component types now carry their props (`<Button variant="bogus" />` is a type error).
+
+### Hooks
+
+#### useApi
+Thin axios wrapper. Returns `{ data, error, loading, lastRequest, fetchData, fetchApi, fetchApiWith }`.
+
+- `fetchApi(key, data?, needLoading?)` calls `apiMap[key](data)` with **one** argument.
+- `fetchApiWith(key, args, { needLoading }?)` spreads `args` into the map entry — use it for entries like `(id, body) => ({...})`.
+
+```jsx
+const { fetchApi, fetchApiWith } = useApi({
+  BASE_URL: 'https://api.example.com',
+  apiMap: {
+    getUser: (id) => ({ url: `/users/${id}`, method: 'GET' }),
+    updateUser: (id, body) => ({ url: `/users/${id}`, method: 'PUT', data: body }),
+  },
+});
+
+fetchApi('getUser', 7);
+fetchApiWith('updateUser', [7, { name: 'Ada' }]);
+```
+
+See [doc/useApi.md](doc/useApi.md).
+
 ## Theming
 
-Dreamtree UI supports custom theming through Tailwind CSS configuration:
+Every colour in the compiled CSS is a CSS variable (`--dt-primary-600`, `--dt-surface`, …) generated from `tokens/tokens.json` (W3C Design Tokens format). The defaults equal the classic palette, so nothing changes until you override a variable.
+
+**Re-theme with a brand file** (no Tailwind config needed, works with the precompiled CSS):
+
+```css
+@import "@dreamtree-org/twreact-ui/dist/index.css";
+@import "@dreamtree-org/twreact-ui/dist/tokens/brands/practicepro.css"; /* or your own --dt-* overrides */
+```
+
+**Use the same tokens in your own classes:**
 
 ```js
-// tailwind.config.js
+// Tailwind 3 — tailwind.config.js
 module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        primary: {
-          50: '#eff6ff',
-          100: '#dbeafe',
-          500: '#3b82f6',
-          600: '#2563eb',
-          700: '#1d4ed8',
-        },
-        success: {
-          50: '#f0fdf4',
-          100: '#dcfce7',
-          500: '#22c55e',
-          600: '#16a34a',
-        },
-        error: {
-          50: '#fef2f2',
-          100: '#fee2e2',
-          500: '#ef4444',
-          600: '#dc2626',
-        },
-        warning: {
-          50: '#fffbeb',
-          100: '#fef3c7',
-          500: '#f59e0b',
-          600: '#d97706',
-        }
-      }
-    }
-  }
-}
+  presets: [require('@dreamtree-org/twreact-ui/dist/tokens/tailwind3-preset.cjs')],
+  content: ['./src/**/*.{js,jsx,ts,tsx}', './node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}'],
+};
+```
+
+```css
+/* Tailwind 4 — globals.css */
+@layer theme, base, twreact, components, utilities;
+@import "@dreamtree-org/twreact-ui/dist/index.css" layer(twreact);
+@import "tailwindcss";
+@import "@dreamtree-org/twreact-ui/dist/tokens/theme.css";
+/* Generate twreact-ui's classes in your utilities layer too. Without it, an app class such as `hidden`
+   lands in a higher layer than twreact's `lg:flex` and responsive components (AppShell) break. */
+@source "../node_modules/@dreamtree-org/twreact-ui/dist/index.esm.js";
 ```
 
+This adds semantic utilities next to the palettes: `bg-surface`, `bg-background`, `text-foreground`, `text-muted`, `border-line`, `bg-shell`, `text-micro`, `rounded-control` and `rounded-card`. Add a brand by creating `tokens/brands/<name>.json`; it overrides only the steps and roles you list.
+
+**Design rules:** [`DESIGN.md`](DESIGN.md) is the rule set for product screens and AI agents: tokens only, blocks first, loading, empty and error states, 390 px, no native dialogs. It is generated from the tokens (`npm run build:tokens`).
+
+**Colour props are overrides, not defaults.** Without colour props, `ProgressBar`, `Checkbox`, `Rate` and `Skeleton` use token classes, so a brand file recolours them. Their HEX props (`color`, `bgColor`, `borderColor`, `activeColor`, `inactiveColor`) still work but are deprecated.
+
+**SSR:** `Tabs`, `Tooltip` and `Switch` generate ids with `React.useId()`, so server-rendered pages (Next.js) hydrate without mismatches.
+
 ## Dark Mode
 
 Enable dark mode with the built-in theme provider: