@assure-one/design-system 1.34.0 → 1.36.0

package/docs/for-ai-agents.md

@@ -0,0 +1,153 @@
+# `@assure-one/design-system` — the short rulebook for AI agents and new contributors
+
+You are writing UI in an Assure product (Pro, Tax, Books, Audit, the client portal) or in this repository. This page is the ten-minute version of the rules; every line links to the source of truth. The full component list is [`docs/components.md`](./components.md) — it is generated from the API reports, so it is complete: if a component is not there, the package does not export it.
+
+Both files ship in the npm package, so they are readable offline:
+`node_modules/@assure-one/design-system/docs/components.md` and `…/docs/for-ai-agents.md`.
+
+## 1. Install and import
+
+```bash
+pnpm add @assure-one/design-system
+```
+
+```tsx
+// root layout, once
+import "@assure-one/design-system/styles.css";
+
+// components — everything public is on the root entry
+import { Button, Field, Input, Label, Select } from "@assure-one/design-system";
+
+// icons — the same components, server-safe (no "use client"), for Server Components
+import { CheckIcon } from "@assure-one/design-system/icons";
+
+// tokens as JavaScript, for the rare inline style or chart config
+import { systemTokens } from "@assure-one/design-system/tokens";
+
+// test helpers, for Jest / Vitest suites that render the real package
+import { withAssureDesignSystem } from "@assure-one/design-system/testing";
+
+// the Next.js adapter: the provider preconfigured with next/link and next/image
+import { NextDesignSystemProvider } from "@assure-one/design-system/next";
+```
+
+Mount `DesignSystemProvider` (or `NextDesignSystemProvider` on Next.js) once in the root layout: it carries the string overrides (`messages`), `locale`, `dir`, the portal container and the router link/image adapters that `LinkButton` and `Logo` render. `ThemeScope` themes one subtree (scheme, brand, density) and re-stamps the overlays opened from inside it; `BrandScope` is the product brand alone.
+
+The root entry is `"use client"`; import icons from `/icons` when you need them in a Server Component. The split CSS entries (`css/tokens.css`, `css/components.css`, …) and how an app declares its layer order are in [`docs/integration/css.md`](./integration/css.md). Nothing outside `src/index.ts` and the five entries above is public ([ADR-011](./adr/011-public-api-governance.md)).
+
+## 2. Never raw HTML, never re-implement
+
+If a UI element exists in the design system, use it. Do not write `<button>`, `<input>`, `<select>`, `<textarea>`, `<dialog>`, `<table>`, `<a role="button">`, `<div onClick>`, `<h1>`, `<p>`, `<hr>`, `<kbd>`, `<code>` or an inline `<svg>` in product code, and do not build a local copy of a component that ships here. The mapping is the ["Never hand-roll"](./components.md#never-hand-roll) table; the short form:
+
+| Instead of                                            | Use                                                                                                                                       |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `<button>`, `<a role="button">`, `<div onClick>`      | `Button`, `IconButton`, `LinkButton`, `SubmitButton`, `Pressable`                                                                         |
+| `<input>` and its types                               | `Input`, `NumberInput`, `SearchInput`, `PhoneField`, `OTPInput`, `DatePicker`, `FileUpload`, `Checkbox`, `RadioGroup`, `Switch`, `Slider` |
+| `<textarea>`                                          | `Textarea`                                                                                                                                |
+| `<select>`, `<datalist>`                              | `Select`, `Combobox`, `MultiSelect`                                                                                                       |
+| `<label>`, `aria-describedby` wiring, red error `<p>` | `Field` + `Label` + `FieldDescription` + `FieldError`                                                                                     |
+| `<fieldset>`, `<legend>`                              | `Fieldset` + `FieldsetLegend`                                                                                                             |
+| `<dialog>`, fixed overlay divs                        | `Dialog`, `AlertDialog`, `Sheet`, `ResponsiveDialog`, `Popover`                                                                           |
+| `<table>`                                             | `Table`, `DataTable`, `DataTableView`                                                                                                     |
+| `<h1>`–`<h6>`, `<p>`, `<code>`, `<kbd>`               | `Heading`, `Text`, `Code`, `Kbd`                                                                                                          |
+| `<hr>`                                                | `Separator`                                                                                                                               |
+| `<svg>`, `lucide-react`                               | the icon catalogue (`/icons`)                                                                                                             |
+| `flex gap-*` wrappers                                 | `Stack`, `Inline`; `Surface` / `Card` for boxes                                                                                           |
+| `title="…"`, `window.confirm()`, `alert()`            | `Tooltip`, `ConfirmActionButton` / `AlertDialog`, `useToast`                                                                              |
+
+Before writing any element, look it up in the ["Pick a component"](./components.md#pick-a-component) table. The only raw elements that are fine are structural ones the design system does not model (`<main>`, `<article>`, `<ul>` for plain lists, `<img>` for content images, `<form>` itself).
+
+## 3. Forms: the `Field` recipe
+
+The full guide — `Field` + design-system controls + a Server Action + zod, reset and `required`, what each control submits, and how to test it — is [`docs/forms.md`](./forms.md). The rules in one breath:
+
+Every design-system control binds itself to the surrounding `Field` (ids, `aria-describedby`, `aria-invalid`, `required`) and posts a real value on native form submission — there is no need for hidden inputs, manual ids or `htmlFor` plumbing ([ADR-006](./adr/006-field-native-form-participation.md), contract ids `C-FORM-*`, `C-HIDDEN-MIRRORS`).
+
+```tsx
+<Field invalid={!!errors.email}>
+  <Label>Email</Label>
+  <Input name="email" type="email" autoComplete="email" />
+  <FieldDescription>We only use it for receipts.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+<Fieldset disabled={saving}>
+  <FieldsetLegend>Notifications</FieldsetLegend>
+  <Field><Label>Email me</Label><Switch name="notify_email" /></Field>
+  <Field><Label>Text me</Label><Switch name="notify_sms" /></Field>
+</Fieldset>
+
+<SubmitButton>Save</SubmitButton>
+```
+
+- A control that is not from the design system (a rich-text editor, a canvas) gets the same wiring through `<FieldControl>` around it, or by calling `useFieldControl()` inside it.
+- Every control takes `size` on the shared control scale (`xs` `sm` `md` `lg` `xl`, [`docs/design-system/control-sizes.md`](./design-system/control-sizes.md)) and `onValueChange` with the plain value. `inputSize`, `triggerClassName` and fake `onChange` events are deprecated aliases (§7).
+- `Select` has a real empty value; never invent a sentinel option such as `"none"` (`C-SELECT-EMPTY`, finder codemod CM-20).
+- Test a form through its labels with the `/testing` helpers: `fillField`, `selectOption`, `pickDate` (§8).
+
+## 4. Styling: `className`, `classNames`, and who wins
+
+- **`className`** lands on the component's styling root (its `data-slot="<component>"` element), `style` with it. Compound components (`Card`, `Dialog`, `DataTable`…) expose their parts as JSX, each taking its own `className`.
+- **`classNames`** is for data-driven components whose parts are not JSX (`Select`, `Combobox`, `DataTableView`, `Pagination`, `FileUpload`, `Questions`): `classNames={{ trigger: "…", content: "…" }}`, typed by the component's exported `*Slot` union. The old `triggerClassName` / `contentClassName` / `wrapperClassName` / `iconClassName` props are deprecated aliases ([ADR-008](./adr/008-component-anatomy.md)).
+- **Your class wins by cascade, not by `tailwind-merge`.** Component classes are `ds:`-prefixed and compiled into the package stylesheet at the `components` layer; your Tailwind utilities sit in your `utilities` layer, so `<Button className="rounded-none">` beats the component's `ds:rounded-md` without `!important` ([ADR-004](./adr/004-css-delivery-cascade.md) decision 4). Do not try to "remove" a component class; add yours.
+- **Do not select a component's internals** (`.rounded-md.font-medium` into a card, `> div > span`). Internal DOM, wrapper elements and class names are not a contract; `data-slot` attributes and `classNames` are. The finder codemod CM-15 lists offending selectors (`C-DOM-*`).
+- **Geometry comes from the component's CSS variable** where one is documented (for example the sidebar width), never from overriding a width class.
+
+## 5. The `ds:` prefix and the CSS entries
+
+- Every class a component renders is prefixed: `ds:flex ds:bg-surface`. These compile inside `styles.css` (and `css/components.css`), not in your build — that is what makes them stable. Your own code writes ordinary, unprefixed Tailwind. You never write `ds:` classes in a product.
+- `styles.css` still ships the frozen legacy unprefixed utilities the 1.x apps used directly (`bg-surface`, `text-fg-3`…); they are additive-only until 2.0. Do not depend on new ones.
+- `@source` into `node_modules/@assure-one/design-system` in your Tailwind config is unnecessary and no longer regenerates component classes with your theme; the per-app preset is the supported way to keep a theme value ([`docs/integration/css.md`](./integration/css.md) §3–4, "What changed in W1-11").
+- Inline styles the design system writes read `var(--ds-x, var(--x))`; do the same when you must write an inline `var()` in this repository.
+
+## 6. Tokens
+
+- Components consume **system tokens** (`--color-action-primary-bg`, `--ds-*` names), never reference values (`--color-navy-700`). The namespaced `--ds-*` name of every token is in `tokens/src/ds-name-map.json`; the roles are documented in [`docs/design-system/`](./design-system/) (`shape-roles.md`, `typography-roles.md`, `control-sizes.md`, `microinteractions.md`).
+- In an app, use the generated utilities (`bg-surface`, `text-fg-2`, `border-rule`) or the `--ds-*` custom properties. Override a token by redeclaring the variable in your preset or on a scope, not by editing component classes. Product theming is `BrandScope` / `data-brand` and runtime brand themes (`createBrandTheme`, [`docs/integration/css.md`](./integration/css.md) §5); status colour is the `intent` prop; service-line colour is `serviceToneStyle`.
+- Tokens are additive: nothing is renamed or removed without a major.
+
+## 7. Deprecated aliases and codemods
+
+Every deprecated name keeps rendering what it did until 3.0, and most have a codemod. The complete table with codemod ids is ["Deprecated aliases and their replacements"](./components.md#deprecated-aliases-and-their-replacements). The ones you will meet most:
+
+| Deprecated                                                               | Write instead                                                                                         | Codemod |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------- |
+| `Button variant="primary" \| "secondary" \| "destructive" \| "success"`  | `variant` (`solid` `soft` `outline` `ghost` `link`) + `intent` (`brand` `neutral` `success` `danger`) | CM-04   |
+| `iconLeft` / `iconRight`                                                 | `iconStart` / `iconEnd`                                                                               | CM-05   |
+| `inputSize`                                                              | `size`                                                                                                | CM-07   |
+| `tone` on StatusDot, IconTile, Spinner, SegmentedProgress, SuiteProgress | `intent`                                                                                              | CM-06   |
+| ProgressBar / ProgressRing `variant`                                     | `intent`                                                                                              | CM-19   |
+| `SearchSelect`                                                           | `Combobox` with `Option` (`{ value, label }`)                                                         | CM-08   |
+| `DatePicker onChange={e => …e.target.value}`                             | `onValueChange={value => …}`                                                                          | CM-10   |
+| `FormError` / `FormSuccess` / `FormSection`                              | `FieldError` / `FieldDescription` / `Fieldset`                                                        | —       |
+| `triggerClassName` etc.                                                  | `classNames={{ trigger }}`                                                                            | —       |
+
+Run codemods from the installed package so they match your design-system version ([`codemods/README.md`](../codemods/README.md)):
+
+```bash
+node node_modules/@assure-one/design-system/codemods/run.mjs list
+node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry   # everything this project is missing
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-07 src         # one codemod, writes the ledger
+```
+
+Transforming codemods append to **`.ds-migrations.json`** in the project root — commit it. The ledger is what makes one-shot codemods refuse to run twice, prerequisites enforceable and `upgrade` exact; the consumer scanner reads it for the migration dashboard. Class X codemods (CM-14 hidden mirrors, CM-15 DOM selectors, CM-16 globals.css, CM-20 select sentinels) only report; fix what they list by hand.
+
+## 8. Testing with the real package
+
+Do not stub the design system in unit tests. `@assure-one/design-system/testing` (experimental) makes the real build load under Jest — `withAssureDesignSystem(config)` — or Vitest (`installDomPolyfills()`), and ships DOM-level helpers: `fillField` (type into a control by its Field label), `selectOption` for `Select`, `pickDate` for `DatePicker`, `openMenu` for `DropdownMenu`, `createToastRecorder` for toasts. Guide: [`docs/testing.md`](./testing.md); architecture: [ADR-014](./adr/014-testing-architecture.md). Query by role and name, never by internal class.
+
+## 9. What is experimental
+
+`@experimental` (ADR-011) means the API may change in a minor release; pin the version and read the changelog on upgrade. Today that is: the **Field family** (`Field`, `FieldControl`, `Fieldset`, `useFieldControl`), the **new controls and variants** (`Combobox`, `MultiSelect`, `NumberInput`, `IconButton`, `Chip`, `Pressable`), the **layout and typography primitives** (`Stack`, `Inline`, `Surface`, `Heading`, `Text`, `Code`, `Kbd`), `defineStatusMap`, the **provider and theming layer** (`DesignSystemProvider`, `useDsMessages`, `ThemeScope`, the **`/next` entry**), the **`/icons` entry**, the **`/testing` entry**, the split CSS entries and runtime brand theming. The catalogue marks each row; the source of truth is the JSDoc tag in `src/`.
+
+## 10. The component you need is not there
+
+Do not build it in the product and do not fork one from here. Check the catalogue's "Pick a component" table first — the need is usually covered by a composition (`Field` + `Input`, `Card` + `Stack`, `Popover` + a form). If it is genuinely missing:
+
+1. Compose from primitives locally **behind one component in your app**, with no design-system internals selected, so the swap is one file later.
+2. Propose it for the shared layer through [ADR-009](./adr/009-shared-product-promotion.md): the API is free of product vocabulary and business rules, two products commit to adopting it with named owners, an owning team is named, and it ships `@experimental` with a story, interaction tests, axe checks and a docs page ([template](./design-system/component-docs-template.md)). Open the proposal as an issue or PR in this repository.
+3. Once two production consumers use it (visible on the migration dashboard, `docs/migration/status.md`), it becomes stable and the local copies are removed.
+
+## 11. Working inside this repository
+
+Read `CLAUDE.md` and `CONTRIBUTING.md` first. Every new or changed public component updates [`docs/components.registry.json`](./components.registry.json) and regenerates the catalogue (`pnpm docs:catalogue`); `pnpm test:contracts` fails otherwise. Every component ships a story next to it, uses system tokens only, names its transition property (no `transition-all`), respects `prefers-reduced-motion`, and is axe-clean.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assure-one/design-system",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "Assure One design system — tokens, primitives, and patterns for the Assure Suite.",
   "license": "UNLICENSED",
   "private": false,
@@ -27,6 +27,14 @@
       "types": "./dist/tokens/index.d.ts",
       "import": "./dist/tokens/index.js"
     },
+    "./icons": {
+      "types": "./dist/icons/index.d.ts",
+      "import": "./dist/icons/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js"
+    },
     "./testing": {
       "import": {
         "types": "./dist/testing/index.d.ts",
@@ -43,6 +51,9 @@
     "dist",
     "codemods",
     "!codemods/__test__",
+    "docs/components.md",
+    "docs/components.registry.json",
+    "docs/for-ai-agents.md",
     "README.md"
   ],
   "publishConfig": {
@@ -71,6 +82,7 @@
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-context-menu": "^2.2.16",
     "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dismissable-layer": "^1.1.11",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-hover-card": "^1.1.15",
     "@radix-ui/react-label": "^2.1.8",
@@ -147,7 +159,8 @@
     "vite": "^6.0.7",
     "vitest": "^4.1.11",
     "vitest-browser-react": "^2.3.0",
-    "wait-on": "^9.0.6"
+    "wait-on": "^9.0.6",
+    "zod": "^4.6.5"
   },
   "engines": {
     "node": ">=22"
@@ -158,6 +171,10 @@
     "build:css": "tailwindcss -i ./src/tokens/consumer.css -o ./dist/styles.css --minify && node scripts/css/compat.mjs",
     "class-flip": "node scripts/class-flip/run.mjs",
     "class-flip:check": "node scripts/class-flip/run.mjs --check",
+    "icons:generate": "node scripts/icons/generate.mjs",
+    "icons:check": "node scripts/icons/generate.mjs --check",
+    "messages:generate": "node scripts/messages/generate.mjs",
+    "messages:check": "node scripts/messages/generate.mjs --check",
     "build:css:entries": "node scripts/build-css-entries.mjs",
     "build:testing": "tsup --config tsup.testing.config.ts",
     "dev": "tsup --watch",
@@ -175,7 +192,8 @@
     "test": "vitest run",
     "test:browser": "vitest run --config vitest.browser.config.ts",
     "typecheck:browser": "tsc -p tests/browser/tsconfig.json --noEmit",
-    "test:contracts": "node --test tests/design-system-contracts.test.mjs",
+    "test:contracts": "node --test tests/design-system-contracts.test.mjs && pnpm messages:check && node scripts/docs/catalogue.mjs --check",
+    "docs:catalogue": "node scripts/docs/catalogue.mjs",
     "contracts:check": "node scripts/contracts/run.mjs --check",
     "contracts:snapshot": "node scripts/contracts/run.mjs --snapshot",
     "typecheck": "tsc --noEmit",