@assure-one/design-system 1.30.0 → 1.32.0

package/README.md

@@ -11,6 +11,7 @@ The single source of truth for visual design across all Assure products.
 - [**`CHANGELOG.md`**](./CHANGELOG.md) — release-by-release log of what shipped.
 - [**`CONTRIBUTING.md`**](./CONTRIBUTING.md) — dev loop, release flow, versioning, pitfalls.
 - [**`CLAUDE.md`**](./CLAUDE.md) — invariants and conventions for AI assistants working in this repo.
+- [**`docs/testing.md`**](./docs/testing.md) — rendering the real package in your app's Jest tests (`@assure-one/design-system/testing`, experimental).
 - [**`claude-skills/`**](./claude-skills) — drop-in Claude Code skill for consuming projects.
 
 ## Install
@@ -19,7 +20,10 @@ The single source of truth for visual design across all Assure products.
 pnpm add @assure-one/design-system
 ```
 
-Import tokens once in your root layout:
+Import the consumer stylesheet once in your root layout. Its bundled component
+utilities intentionally live below your app's Tailwind `utilities` layer, so
+local classes and responsive variants remain authoritative even when a bundler
+reorders CSS chunks:
 
 ```ts
 import "@assure-one/design-system/styles.css";
@@ -35,6 +39,29 @@ export default function Page() {
 }
 ```
 
+### The split CSS entries (experimental)
+
+`styles.css` stays the supported way to consume the design system, unchanged.
+Alongside it, the package now also publishes the individual stylesheets the new
+CSS mode is built from. They are **experimental**: nothing requires them yet,
+no component reads them, and importing them changes nothing on its own.
+
+| Subpath | What it is |
+| --- | --- |
+| `./css/tokens.css` | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component. |
+| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names. |
+| `./css/tailwind.css` | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in *your* build instead of silently producing nothing. |
+| `./css/shadcn.css` | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override. |
+| `./css/base.css` | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import. |
+
+Import order, once the mode is supported end to end, is
+`tokens.css` → `tailwind.css` → `shadcn.css` (optional) → `base.css`
+(optional), after your own `@import "tailwindcss"`. The integration guide with
+the full sequence, the layer statement and the per-app preset lands with the
+rest of Wave 1; until then the reasoning lives in
+[ADR-004](./docs/adr/004-css-delivery-cascade.md) and
+[ADR-005](./docs/adr/005-app-vocabulary-bridge.md).
+
 ## Develop
 
 ```bash

package/codemods/0.2.0-radix-migration.mjs

@@ -0,0 +1,315 @@
+/**
+ * @assure-one/design-system 0.1.x → 0.2.0 migration codemod
+ *
+ * Run from the consumer repo (firm or portal):
+ *
+ *   npx jscodeshift -t node_modules/@assure-one/design-system/codemods/0.2.0-radix-migration.mjs \
+ *     --extensions=tsx,ts,jsx,js \
+ *     --parser=tsx \
+ *     'src/**\/*.{ts,tsx,js,jsx}'
+ *
+ * Or, if you've copied the file locally:
+ *
+ *   npx jscodeshift -t ./codemods/0.2.0-radix-migration.mjs \
+ *     --extensions=tsx,ts,jsx,js --parser=tsx 'src/**\/*.{ts,tsx}'
+ *
+ * VERBOSE per-file logs:
+ *   VERBOSE=1 npx jscodeshift -t ... 'src/**\/*.tsx'
+ *
+ * What it does
+ * ------------
+ *   1. <Slider value={n} />        → <Slider value={[n]} />
+ *      <Slider defaultValue={n} /> → <Slider defaultValue={[n]} />
+ *      Adds a `// TODO 0.2.0: onValueChange now receives number[]` line above
+ *      any <Slider> with `onValueChange` so the consumer can review the body.
+ *
+ *   2. <Avatar><Image src=... alt=... /></Avatar>  (next/image inner)
+ *      → <Avatar src=... alt=... />
+ *      Drops the inner <Image>. If <Avatar> already has `src`, leaves it and
+ *      emits a TODO. If the <Image> isn't `next/image`, leaves it untouched.
+ *
+ *   3. useToast — no-op. `useToast()` already returned `{ toast }`; 0.2.0
+ *      adds `dismiss` (additive). Existing call sites keep working.
+ *
+ *   4. TeamMemberSelect — no-op. The `value: ""` (unassigned) contract is
+ *      preserved on the consumer-facing API; the `__unassigned__` sentinel
+ *      is internal only.
+ *
+ * Idempotent: running twice changes nothing the second time. Already-array
+ * Slider values and already-flattened Avatars are skipped.
+ */
+
+const SLIDER_NUMERIC_PROPS = ["value", "defaultValue"];
+const TODO_SLIDER = " TODO 0.2.0: onValueChange now receives number[] (was number) ";
+const TODO_SLIDER_IDENT =
+  " TODO 0.2.0: Slider value/defaultValue is now number[] — wrap in [] if this expression is still number ";
+const TODO_AVATAR_CONFLICT =
+  " TODO 0.2.0: <Avatar> already has src — could not auto-merge with inner next/image child ";
+const TODO_AVATAR_MERGED =
+  " TODO 0.2.0: review hoisted Avatar src/alt (was inner next/image child) ";
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let changed = false;
+  const log = [];
+
+  /* -------------------------------------------------------------------- */
+  /* Helpers                                                              */
+  /* -------------------------------------------------------------------- */
+
+  function jsxOpeningName(opening) {
+    const name = opening.name;
+    if (!name) return null;
+    if (name.type === "JSXIdentifier") return name.name;
+    return null;
+  }
+
+  function findAttr(opening, attrName) {
+    return opening.attributes?.find(
+      (a) =>
+        a.type === "JSXAttribute" &&
+        a.name?.type === "JSXIdentifier" &&
+        a.name.name === attrName,
+    );
+  }
+
+  function isAlreadyArrayExpression(attr) {
+    if (!attr || attr.type !== "JSXAttribute") return false;
+    const v = attr.value;
+    if (!v || v.type !== "JSXExpressionContainer") return false;
+    const expr = v.expression;
+    if (!expr) return false;
+    // already array literal
+    if (expr.type === "ArrayExpression") return true;
+    // identifier / member / call — assume the consumer is already passing an
+    // array; do not double-wrap. (Idempotency over a brittle type check.)
+    return (
+      expr.type === "Identifier" ||
+      expr.type === "MemberExpression" ||
+      expr.type === "CallExpression" ||
+      expr.type === "ConditionalExpression" ||
+      expr.type === "LogicalExpression"
+    );
+  }
+
+  function isScalarNumericLiteralExpression(attr) {
+    if (!attr || attr.type !== "JSXAttribute") return false;
+    const v = attr.value;
+    // Bare `value=42` is not legal JSX numeric, so we only care about expr
+    // containers wrapping a NumericLiteral or unary minus numeric.
+    if (!v || v.type !== "JSXExpressionContainer") return false;
+    const e = v.expression;
+    if (!e) return false;
+    if (e.type === "NumericLiteral" || e.type === "Literal") {
+      return typeof e.value === "number";
+    }
+    if (
+      e.type === "UnaryExpression" &&
+      e.operator === "-" &&
+      e.argument &&
+      (e.argument.type === "NumericLiteral" ||
+        (e.argument.type === "Literal" && typeof e.argument.value === "number"))
+    ) {
+      return true;
+    }
+    return false;
+  }
+
+  function wrapAttrInArray(attr) {
+    const expr = attr.value.expression;
+    attr.value = j.jsxExpressionContainer(j.arrayExpression([expr]));
+  }
+
+  function hasLeadingComment(node, text) {
+    const list = node.leadingComments || [];
+    return list.some((c) => c.value === text);
+  }
+
+  function addLeadingComment(path, text) {
+    const node = path.node;
+    if (hasLeadingComment(node, text)) return false;
+    node.comments = node.comments || [];
+    const comment = { type: "CommentLine", value: text, leading: true, trailing: false };
+    node.comments.unshift(comment);
+    // jscodeshift / recast also reads `leadingComments`
+    node.leadingComments = node.leadingComments || [];
+    node.leadingComments.unshift(comment);
+    return true;
+  }
+
+  /* -------------------------------------------------------------------- */
+  /* Detect imported local names                                          */
+  /*                                                                      */
+  /* We only want to touch <Slider> and <Avatar> when they come from      */
+  /* @assure-one/design-system (or are unambiguous globally). To stay     */
+  /* safe across the firm + portal codebases, we scope by import source.  */
+  /* -------------------------------------------------------------------- */
+
+  const dsLocalNames = new Set();
+  const nextImageLocalNames = new Set();
+
+  root.find(j.ImportDeclaration).forEach((path) => {
+    const src = path.node.source?.value;
+    if (!src) return;
+    if (src === "@assure-one/design-system") {
+      for (const spec of path.node.specifiers || []) {
+        if (spec.type === "ImportSpecifier" && spec.local?.name) {
+          dsLocalNames.add(spec.local.name);
+        }
+      }
+    }
+    if (src === "next/image") {
+      for (const spec of path.node.specifiers || []) {
+        if (
+          (spec.type === "ImportDefaultSpecifier" ||
+            spec.type === "ImportSpecifier") &&
+          spec.local?.name
+        ) {
+          nextImageLocalNames.add(spec.local.name);
+        }
+      }
+    }
+  });
+
+  // The DS exports `Slider` and `Avatar` under those exact names. If the
+  // consumer didn't import them from DS we leave their JSX alone — that
+  // avoids touching a local component that happens to share a name.
+  const sliderLocal = dsLocalNames.has("Slider") ? "Slider" : null;
+  const avatarLocal = dsLocalNames.has("Avatar") ? "Avatar" : null;
+
+  /* -------------------------------------------------------------------- */
+  /* Change 1 — Slider value/defaultValue scalar → array                  */
+  /* -------------------------------------------------------------------- */
+
+  if (sliderLocal) {
+    root
+      .find(j.JSXElement, {
+        openingElement: { name: { type: "JSXIdentifier", name: sliderLocal } },
+      })
+      .forEach((path) => {
+        const opening = path.node.openingElement;
+
+        let wrappedAny = false;
+        let needsIdentTodo = false;
+        for (const propName of SLIDER_NUMERIC_PROPS) {
+          const attr = findAttr(opening, propName);
+          if (!attr) continue;
+          if (isScalarNumericLiteralExpression(attr)) {
+            wrapAttrInArray(attr);
+            changed = true;
+            wrappedAny = true;
+            log.push(`Slider: ${propName}={n} → ${propName}={[n]}`);
+            continue;
+          }
+          if (isAlreadyArrayExpression(attr)) {
+            // Could be Identifier / MemberExpression / CallExpression / etc.
+            // We can't tell from AST whether it's number[] (already migrated)
+            // or number (needs migration). Leave it and emit a TODO so the
+            // consumer reviews. Idempotent on the array-literal case.
+            const v = attr.value?.expression;
+            if (v && v.type !== "ArrayExpression") {
+              needsIdentTodo = true;
+            }
+          }
+        }
+        if (needsIdentTodo) {
+          if (addLeadingComment(path, TODO_SLIDER_IDENT)) {
+            changed = true;
+            log.push("Slider: added value/defaultValue identifier TODO comment");
+          }
+        }
+
+        // TODO comment for onValueChange
+        const onValueChange = findAttr(opening, "onValueChange");
+        if (onValueChange) {
+          if (addLeadingComment(path, TODO_SLIDER)) {
+            changed = true;
+            log.push("Slider: added onValueChange TODO comment");
+          }
+        }
+      });
+  }
+
+  /* -------------------------------------------------------------------- */
+  /* Change 2 — Avatar with next/image child → flat src/alt props         */
+  /* -------------------------------------------------------------------- */
+
+  if (avatarLocal && nextImageLocalNames.size > 0) {
+    root
+      .find(j.JSXElement, {
+        openingElement: { name: { type: "JSXIdentifier", name: avatarLocal } },
+      })
+      .forEach((path) => {
+        const el = path.node;
+        const opening = el.openingElement;
+        const children = el.children || [];
+
+        // Find a single next/image child (ignoring whitespace text nodes)
+        const meaningful = children.filter(
+          (c) =>
+            !(
+              c.type === "JSXText" &&
+              (c.value === "" || /^\s*$/.test(c.value))
+            ),
+        );
+        if (meaningful.length !== 1) return;
+        const child = meaningful[0];
+        if (child.type !== "JSXElement") return;
+        const childName = jsxOpeningName(child.openingElement);
+        if (!childName || !nextImageLocalNames.has(childName)) return;
+
+        // Don't merge if Avatar already has src — emit TODO and skip
+        const existingSrc = findAttr(opening, "src");
+        if (existingSrc) {
+          if (addLeadingComment(path, TODO_AVATAR_CONFLICT)) {
+            changed = true;
+            log.push("Avatar: src conflict — TODO comment added");
+          }
+          return;
+        }
+
+        // Hoist src + alt from <Image>
+        const childOpening = child.openingElement;
+        const srcAttr = findAttr(childOpening, "src");
+        const altAttr = findAttr(childOpening, "alt");
+        if (!srcAttr) return; // nothing to hoist
+
+        const newAttrs = [...opening.attributes];
+        newAttrs.push(j.jsxAttribute(j.jsxIdentifier("src"), srcAttr.value));
+        if (altAttr && !findAttr(opening, "alt")) {
+          newAttrs.push(j.jsxAttribute(j.jsxIdentifier("alt"), altAttr.value));
+        }
+        opening.attributes = newAttrs;
+
+        // Self-close the Avatar (no remaining children)
+        opening.selfClosing = true;
+        el.closingElement = null;
+        el.children = [];
+
+        addLeadingComment(path, TODO_AVATAR_MERGED);
+        changed = true;
+        log.push("Avatar: hoisted next/image src/alt and removed inner element");
+      });
+  }
+
+  /* -------------------------------------------------------------------- */
+  /* Done                                                                 */
+  /* -------------------------------------------------------------------- */
+
+  if (!changed) return null;
+
+  if (process.env.VERBOSE) {
+    // eslint-disable-next-line no-console
+    console.log(`[0.2.0-radix-migration] ${file.path}`);
+    for (const line of log) {
+      // eslint-disable-next-line no-console
+      console.log(`  - ${line}`);
+    }
+  }
+
+  return root.toSource({ quote: "double" });
+}
+
+// jscodeshift parser hint
+export const parser = "tsx";

package/codemods/README.md

@@ -0,0 +1,305 @@
+# @assure-one/design-system codemods
+
+Migration tooling shipped inside the package: every codemod of the program in
+implementation plan §29 runs from the installed copy in a consumer project, so
+a consumer never installs a second tool and always runs the codemods that match
+its design-system version.
+
+## Running a codemod
+
+```bash
+# What is available, and what this project has not applied yet
+node node_modules/@assure-one/design-system/codemods/run.mjs list
+
+# Preview: report only, no file is written
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-15 src --dry --print
+
+# Apply, and write a JSON + Markdown report next to the run
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-05 src --report reports/cm-05
+
+# Everything this project is missing, in program order
+node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
+```
+
+There is deliberately **no** `bin` entry and **no** `exports` entry for the
+codemods: `exports` is locked (L-ENTRIES) and a `bin` would put a command on
+consumers' `PATH` that has nothing to do with using the design system. The file
+path above is the documented interface. Inside this repository the same runner
+is `pnpm codemods <id> <paths>`.
+
+| Option                          | Effect                                                                         |
+| ------------------------------- | ------------------------------------------------------------------------------ |
+| `--dry`                         | report what would happen; write neither files nor the ledger                   |
+| `--root <dir>`                  | project root (default: the nearest `package.json` above the working directory) |
+| `--report <prefix>`             | write `<prefix>.json` and `<prefix>.md`                                        |
+| `--json <file>` / `--md <file>` | write one of the two                                                           |
+| `--print`                       | print the full Markdown report                                                 |
+| `--quiet`                       | print nothing but errors                                                       |
+| `--fail-on-findings`            | exit 1 when a finding maps to a compatibility contract (for CI gates)          |
+
+Exit codes: `0` done · `1` findings with `--fail-on-findings` · `2` usage error
+· `3` refused by a guard.
+
+Paths are files or directories; with none, the whole project root is scanned.
+`node_modules`, `dist`, `.next`, `build`, `coverage`, `public/` and the other
+generated directories are always skipped, and test files are read only by
+codemods that ask for them.
+
+## Classes
+
+| Class | Meaning                                                |
+| ----- | ------------------------------------------------------ |
+| **A** | safely automatic                                       |
+| **R** | automatic, plus a report a human reviews               |
+| **X** | report-only; the runner refuses to let it write a file |
+
+Nothing that changes submitted form data, business mappings, copy, colour
+_meaning_ or e-sign flow logic is ever automated.
+
+## The ledger — `.ds-migrations.json`
+
+Applying a transforming codemod appends an entry to `.ds-migrations.json` in
+the consumer project root:
+
+```json
+{
+  "schema": 1,
+  "applied": [
+    {
+      "id": "CM-05",
+      "appliedAt": "2026-09-17T09:12:44.001Z",
+      "dsVersion": "1.31.0",
+      "filesChanged": 12
+    }
+  ]
+}
+```
+
+Commit it with the codemod's changes. It is what makes
+
+- **one-shot codemods safe** — a codemod declaring `oneShot` refuses to run a
+  second time (a `--dry` preview is still allowed, with a warning);
+- **prerequisites enforceable** — `requires.codemods` refuses to run before the
+  codemods it builds on, and `requires.dsVersion` before the release that ships
+  the replacement API;
+- **`upgrade` exact** — a consumer several versions behind gets precisely the
+  codemods it is missing, in program order.
+
+Report-only codemods and dry runs never touch it. The consumer scanner reads
+the file and the migration dashboard shows the applied ids
+(`migration-status/<app>.json` → `codemodLedger`).
+
+## Reports
+
+Every run produces the same report: a JSON document (`schema`, the codemod, the
+design-system version, a summary, the findings, the files changed, what could
+**not** be transformed and parse errors) and a Markdown rendering of it. "Could
+not be transformed" is the part that matters for class A and R codemods: it is
+the list a human has to pick up — spread props, dynamic expressions, conflicting
+`classNames` objects.
+
+## Codemods
+
+| Id    | Class | What it does                                                                                                                        |
+| ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids   |
+| CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()` |
+
+The remaining ids of plan §29 land with the waves that ship their replacement
+APIs.
+
+### CM-15 — DOM-selector finder
+
+Report-only. It never modifies a file; the runner throws if it tries. What it
+looks for:
+
+- **class tokens that reach into a component's children** on a design-system
+  tag — arbitrary variants with a descendant, child or sibling combinator, the
+  `*` / `**` child variants, `has-[…]` — and the same tokens on a wrapper
+  element whose subtree holds a design-system component;
+- **group references the design system provides** (`group-data-[labels…]`,
+  `…/sidebar`, `…/row`);
+- **DOM queries** — `querySelector(All)`, `closest`, `matches`, Playwright
+  `locator` — whose selector names design-system internals, including
+  selectors held in a file-level constant;
+- **text matching on copy the design system renders** ("Next", "Notifications",
+  "Next page", "Clear search", "Back") through `getByText`-style queries,
+  `getByRole({ name })` or `textContent` comparisons;
+- **tests that parse the built bundle** (`…/design-system/dist/index.js`);
+- **global CSS selectors** that name design-system internals.
+
+Self-only variants (`[&[data-state=open]]:…`, `[&:hover]:…`), Radix
+`data-state`/`data-side`/`data-align` attributes, ARIA roles and cmdk
+attributes are **not** reported: they are permanent contracts (P-DATA-STATE,
+P-ROLES, C-CMDK-ATTR).
+
+Findings carry a `registryId` when they match a contract and
+`rule: "unregistered-…"` when they are DOM coupling the registry does not track
+yet — those are the candidates for new registry entries. `confidence` is `high`
+for a token on the component itself, `medium` for a wrapper or a heuristic,
+`low` for an unmapped wrapper.
+
+CM-15 feeds 2.0 gate G7 (`consumerSelectors = 0` for the freezes with removal
+target 2.0). Use `--fail-on-findings` to gate on it. The committed findings for
+the four consumer apps are in `docs/codemods/`.
+
+### CM-16 — `globals.css` analyser
+
+Report-only, and the input to the consumer compatibility presets (plan §12).
+It finds, with a line number and a severity, the mechanisms by which an
+application restyles design-system components today:
+
+| Rule                      | Contract        | Gate | Found                                                                    |
+| ------------------------- | --------------- | ---- | ------------------------------------------------------------------------ |
+| `source-into-ds`          | C-CSS-SOURCE    | G2   | `@source` pointing into the design-system package                        |
+| `ds-styles-import`        | C-CSS-STYLES    | G1   | `@assure-one/design-system/styles.css` imported (from CSS or from code)  |
+| `duplicate-preflight`     | C-CSS-STYLES    | G1   | the app compiles a Tailwind preflight while the DS sheet ships one too   |
+| `theme-collision-differs` | C-TOKENS-LEGACY | —    | an `@theme` key that shadows a DS token **with a different value**       |
+| `theme-collision-equal`   | C-TOKENS-LEGACY | —    | the same name with the same value today                                  |
+| `legacy-var-write`        | C-TOKENS-WRITE  | —    | a DS token name declared outside `@theme` — a deliberate override        |
+| `legacy-var-read`         | C-TOKENS-LEGACY | —    | `var(--<ds token>)` read by app CSS                                      |
+| `brand-scope-spelling`    | C-CSS-DARKCLASS | —    | DS tokens re-declared under `.dark` or `[data-brand="…"]`                |
+| `dark-variant-mismatch`   | C-CSS-DARKCLASS | —    | an app `dark` variant that cannot match the `.dark` element itself       |
+| `unlayered-ds-dom`        | (unregistered)  | —    | an unlayered app rule that styles DS markup (`button`, `*`, `.shadow-…`) |
+| `layered-ds-dom`          | (unregistered)  | —    | the same, inside the app's own `base`/`components` layer                 |
+
+Severity is `high` for anything that blocks G1/G2 or changes what a DS
+component renders, `medium` for coupling that a rename has to carry, `low` for
+what is only fragile today.
+
+Boundary with CM-15: selectors that name design-system **internals**
+(`[data-radix-…]`, `[data-esign-…]`, `[data-labels]`, `[cmdk-…]`, the toast
+region) are the `C-DOM-*` contracts and belong to CM-15, which already reports
+them from CSS. CM-16 skips them, so the two finders never count the same rule
+twice.
+
+CM-16 reads the **authored** stylesheets; `scripts/derive-consumer-preset`
+(W1-18) reads the **compiled** ones with a full cascade. The two therefore
+count different things on purpose — `docs/codemods/cm-16-globals-css.md` puts
+the numbers side by side and explains every difference. Both call two values
+"different" through the same normalisation (`codemods/lib/css-values.mjs`),
+which is why the value-level counts can be compared at all.
+
+It parses CSS with the project's own `postcss` (borrowed exactly as
+`typescript` is, see "Packaging"), and compares against the design system's
+own `dist/styles.css` from the installed package.
+
+## Writing a codemod
+
+A codemod is one module in `codemods/transforms/`, registered in
+`codemods/lib/registry.mjs` (the registry order is the program order that
+`upgrade` follows):
+
+```js
+export const meta = {
+  id: "CM-07",
+  title: "inputSize → size on Input, Textarea and SearchInput",
+  class: "A",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: "1.32.0" },
+  parses: ["code"], // "code" and/or "css"
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-INPUT-SIZE"],
+};
+
+export function transform(file, { ts, postcss }) {
+  // file: { rel, path, source, kind, test }
+  return { output, findings, notTransformed, parseErrors };
+}
+```
+
+`usesTypeScript` and `usesPostcss` ask the runner to resolve that parser from
+the project and inject it; a codemod never imports one itself.
+
+The runner owns everything else: the guards, which files are read, writing
+files and the ledger, the report, and the rule that a class X codemod may not
+change anything.
+
+Fixtures live in `codemods/__test__/<id>/*.snap` — one file per case, holding a
+small project and the expected findings (and, for transforming codemods, the
+expected output):
+
+```
+=== file: src/thing.tsx
+<source>
+=== expect
+{ "findings": [ ["src/thing.tsx:12", "C-DOM-03", "class-on-component", "<class token>"] ] }
+```
+
+`codemods/__test__/harness.mjs` materialises a fixture in a temporary
+directory, runs the codemod **twice** and asserts that the second run finds the
+same things and changes nothing — the idempotency requirement of plan §29.
+`tests/codemods/*.test.mjs` runs all of it as part of `pnpm test:contracts`.
+
+Fixtures are `.snap` on purpose: Tailwind scans every other repository file for
+class names, and a fixture full of consumer classes would change
+`dist/styles.css`. `tests/codemods/tailwind-inert.test.mjs` proves the codemod
+sources, fixtures and findings stay invisible to that scan — which is also why
+class-like text in a `.mjs` or `.md` file here is assembled from parts.
+
+## Packaging
+
+`codemods` is part of the published tarball (`package.json` → `files`);
+`codemods/__test__` is not. The codemods need `typescript` at run time and
+resolve it from the consumer project, so the published package gains no
+dependency. See `docs/codemods/README.md` for that decision.
+
+## Legacy: 0.2.0-radix-migration.mjs
+
+The pre-program codemod, written before the runner existed. It is a
+jscodeshift transform and is run with `npx jscodeshift`, not with `run.mjs`.
+
+### Run it
+
+From the consumer repo (firm or portal), with `@assure-one/design-system@0.2.0` installed:
+
+```bash
+# Dry-run first to preview
+npx jscodeshift -t node_modules/@assure-one/design-system/codemods/0.2.0-radix-migration.mjs \
+  --extensions=tsx,ts,jsx,js --parser=tsx --dry --print 'src/**/*.{ts,tsx}'
+
+# Apply
+VERBOSE=1 npx jscodeshift -t node_modules/@assure-one/design-system/codemods/0.2.0-radix-migration.mjs \
+  --extensions=tsx,ts,jsx,js --parser=tsx 'src/**/*.{ts,tsx}'
+```
+
+### What it changes
+
+1. `Slider` value props become `number[]` (Radix range convention)
+   - `<Slider value={50} />` becomes `<Slider value={[50]} />`
+   - `<Slider defaultValue={75} />` becomes `<Slider defaultValue={[75]} />`
+   - Adds a `// TODO 0.2.0: onValueChange now receives number[]` comment above any `<Slider>` with `onValueChange` so you review the callback body.
+   - Identifier expressions (`value={vol}`) get a TODO instead of being auto-wrapped — we can't tell from AST if the variable is already `number[]`. Tsc will catch the rest.
+
+2. `Avatar` no longer accepts a `next/image` child
+   - `<Avatar><Image src=".." alt=".." /></Avatar>` becomes `<Avatar src=".." alt=".." />`
+   - Inner non-`next/image` children are left alone.
+   - If the `Avatar` already has `src`, the inner `<Image>` is left and a TODO is emitted.
+
+### Explicit no-ops (documented for completeness)
+
+- `useToast` — fully back-compat. `useToast()` returned `{ toast }` in 0.1.x; 0.2.0 returns `{ toast, dismiss }`. Existing destructures keep working; `dismiss` is just newly available.
+- `TeamMemberSelect` — the `value: ""` (unassigned) consumer contract is preserved. The `__unassigned__` sentinel is internal.
+
+### Scoping
+
+The transform only rewrites `Slider`/`Avatar` JSX whose name is imported from `@assure-one/design-system` in the same file. Local components named `Slider` or `Avatar` from other paths are left alone.
+
+### Idempotency
+
+Running twice produces zero further changes. Already-array Slider props and already-flattened Avatars are detected and skipped.
+
+### Validate the output
+
+Test fixtures live in `codemods/__test__/*.input.tsx`. To smoke-test against them:
+
+```bash
+cp codemods/__test__/slider.input.tsx /tmp/slider.tsx
+VERBOSE=1 npx jscodeshift -t codemods/0.2.0-radix-migration.mjs \
+  --extensions=tsx --parser=tsx /tmp/slider.tsx
+diff codemods/__test__/slider.input.tsx /tmp/slider.tsx
+```
+
+After running on your codebase, run `tsc --noEmit` to catch any leftover number-vs-`number[]` mismatches the TODO comments flagged.