@assure-one/design-system 1.33.0 → 1.35.0

package/README.md

@@ -13,6 +13,7 @@ The single source of truth for visual design across all Assure products.
 - [**`CLAUDE.md`**](./CLAUDE.md) — invariants and conventions for AI assistants working in this repo.
 - [**`docs/integration/css.md`**](./docs/integration/css.md) — how an application loads our CSS: layer order, import sequence, the compatibility preset, removing `@source`, runtime brand theming.
 - [**`docs/testing.md`**](./docs/testing.md) — rendering the real package in your app's Jest tests (`@assure-one/design-system/testing`, experimental).
+- [**`docs/design-system/icons.md`**](./docs/design-system/icons.md) — the icon catalogue and its server-safe entry (`@assure-one/design-system/icons`, experimental): import an icon in a Server Component without a client boundary.
 - [**`claude-skills/`**](./claude-skills) — drop-in Claude Code skill for consuming projects.
 
 ## Install

package/codemods/README.md

@@ -15,7 +15,7 @@ node node_modules/@assure-one/design-system/codemods/run.mjs list
 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
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-02 src --report reports/cm-02
 
 # Everything this project is missing, in program order
 node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
@@ -81,12 +81,19 @@ Commit it with the codemod's changes. It is what makes
   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;
+  the replacement API; a codemod whose prerequisite depends on its own state
+  exports a `guard` hook and calls `requireLedger([…])` from it (CM-03 phase 2
+  runs only when the ledger shows phase 1 **and** CM-02);
 - **`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
+A transforming codemod is recorded when it ran for real: on its **first** run
+even when every call site was already in the target shape (`filesChanged: 0` —
+a project whose Buttons were all explicit must still be able to satisfy a
+prerequisite on CM-02), and again whenever a later run changed a file. A run
+that changes nothing in a project that already records the codemod adds no
+entry. 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
@@ -100,16 +107,191 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 
 ## Codemods
 
-| Id    | Class | What it does                                                                                                                        |
-| ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                    |
-| 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()` |
-| CM-20 | X     | Select sentinel finder: option values standing in for "no value", and the line where each is converted back                         |
+| Id    | Class | What it does                                                                                                                                                           |
+| ----- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CM-05 | A     | Button family `iconLeft` / `iconRight` → `iconStart` / `iconEnd` (pure rename; both names of one slot, spreads → "could not be transformed")                           |
+| CM-02 | A     | Button explicit default size: `size="md"` on every `Button`, `SubmitButton` and `LinkButton` that passes no `size` (pixel-neutral)                                     |
+| CM-04 | R     | Button family legacy `variant` → `variant` + `intent` pair (`primary` → `solid`, `destructive` → `solid` + `danger`, …); `accent`, `dashed`, dynamic → report          |
+| CM-06 | R     | `tone` → `intent` on StatusDot, IconTile, Spinner, SegmentedProgress, SuiteProgress (`pro` → `brand`, listed for review); product hues → report                        |
+| CM-19 | R     | ProgressBar/ProgressRing: `variant` → `intent`, and the value → colour rule written down as an explicit `intent` where the value is a literal; dynamic values → report |
+| CM-12 | R     | Button `type="submit"` where the intent is evident (inside `<form>` in the same file, no `onClick`); everything else untyped → report                                  |
+| CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                                                       |
+| 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()`                                    |
+| CM-20 | X     | Select sentinel finder: option values standing in for "no value", and the line where each is converted back                                                            |
 
 The remaining ids of plan §29 land with the waves that ship their replacement
 APIs.
 
+### CM-05 — Button family `iconLeft` / `iconRight` → `iconStart` / `iconEnd`
+
+Class A. W3-07 named the two icon slots of `Button`, `LinkButton` and
+`SubmitButton` logically — `iconStart` is the left in LTR and the right in
+RTL — and kept `iconLeft` / `iconRight` as deprecated aliases of the same
+slots (contract C-BTN-ICONPROPS, removed in 3.0). Each alias is the same slot
+under another name, so this is a pure rename: only the attribute's name is
+replaced, and its value — a one-line icon or a multi-line element — keeps its
+text and formatting. Aliased and namespace imports count.
+
+| rule           | Contract        | What happens                                      |
+| -------------- | --------------- | ------------------------------------------------- |
+| `icon-renamed` | C-BTN-ICONPROPS | `iconLeft` → `iconStart`, `iconRight` → `iconEnd` |
+
+Not touched, and listed under "could not be transformed": an element that
+passes **both names of one slot** (`iconStart` and `iconLeft` — the component
+throws on that in development; a rename would make a duplicate attribute;
+delete the deprecated one by hand), and an element with a spread
+(`<Button iconLeft={…} {...props}>` — the spread may carry the other name for
+the same slot, and which one wins depends on attribute order). Not touched and
+not reported: elements already on the new names, local components with the
+same names, test files.
+
+### CM-04 — Button family legacy `variant` → `variant` + `intent`
+
+Class R. W3-02 gave `Button`, `LinkButton` and `SubmitButton` the two axes of
+ADR-007 — `variant` is the emphasis, `intent` the meaning — and kept the
+single-axis words as deprecated aliases (contract C-BTN-VAR, removed in 3.0),
+each a fixed pair (`LEGACY_BUTTON_VARIANTS`, ADR-007 §4). Every alias renders
+the exact classes it always did, so the rewrite is pixel-neutral. `intent` is
+written only where it differs from what the new emphasis resolves on its own
+(`DEFAULT_BUTTON_INTENT`, ADR-007 §3), so the output is the smallest call that
+renders today's pixels; when written it goes right after `variant`, on its own
+line in a one-attribute-per-line element. `tests/codemods/cm-04.test.mjs`
+checks both tables against `src/primitives/behavior/button-base.ts`.
+
+| legacy word   | becomes                            | `intent` written?                         |
+| ------------- | ---------------------------------- | ----------------------------------------- |
+| `primary`     | `variant="solid"`                  | no — `brand` is what `solid` defaults to  |
+| `secondary`   | `variant="soft"`                   | no — `neutral` is what `soft` defaults to |
+| `destructive` | `variant="solid" intent="danger"`  | yes                                       |
+| `success`     | `variant="solid" intent="success"` | yes                                       |
+| `accent`      | left alone, reported               | its suite-action colour has no pair (D13) |
+| `dashed`      | left alone, reported               | its dashed border has no pair (2.x alias) |
+
+| rule                    | Contract                | What happens                                                                                                                                     |
+| ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant-split`         | C-BTN-VAR               | the alias became its pair, or its emphasis alone when the intent is the default (applied, low)                                                   |
+| `destructive-as-danger` | C-BTN-VAR               | `destructive` → `solid` + `danger` (applied, **medium**): the word moves to D4's default (`danger` canonical, ADR-007 §5); confirm               |
+| `legacy-look`           | C-BTN-VAR, C-BTN-ACCENT | `dashed` (C-BTN-VAR) and `accent` (C-BTN-ACCENT, D13) have a look no pair renders; they stay (review, medium)                                    |
+| `dynamic-intent`        | C-BTN-VAR               | a legacy word next to `intent={expr}` whose alias intent is not the new emphasis's default: `undefined` would change the colour (review, medium) |
+| `dynamic-variant`       | C-BTN-VAR               | `variant={expr}`: map the expression's values by hand (review, high)                                                                             |
+| `spread-props`          | C-BTN-VAR               | `{...props}` may carry `variant` or `intent`; rewriting the literal could change which wins (review, medium)                                     |
+| `unknown-variant`       | C-BTN-VAR               | a word the Button never accepted (review, high)                                                                                                  |
+
+A legacy word next to a **literal** `intent` (`variant="destructive"
+intent="success"`) is rewritten to its emphasis only: the intent already wins
+on both sides of the rewrite. `intent="destructive"` is not touched — that is
+CM-17, gated by D4. Not touched and not reported: the emphases (`ghost`,
+`outline`, `link`, `solid`, `soft`), elements with no `variant`, local
+components with the same names, test files.
+
+### CM-06 — `tone` → `intent`
+
+Class R. W3-21 gave `StatusDot`, `IconTile`, `Spinner`, `SegmentedProgress` and
+`SuiteProgress` the shared `intent` axis of ADR-007 and kept `tone` as a
+deprecated alias (contract C-TONE, removed in 3.0). Every legacy word resolves
+to one intent and renders the same classes, so the rename is pixel-neutral. The
+attribute is rewritten in place — `tone="pro"` → `intent="brand"` — so a
+Prettier-formatted file stays formatted; `tone="current"` on `Spinner` is the
+default and is removed.
+
+| component         | `tone` → `intent`                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| StatusDot         | `pro` → `brand`; `danger` `warning` `info` `success` `neutral` unchanged                                                 |
+| IconTile          | `pro` → `brand`; status words unchanged; `audit` `books` `tax` → review                                                  |
+| Spinner           | `muted` → `neutral`, `accent` → `info`, `destructive` → `danger`, `current` → removed; `success` `warning` unchanged     |
+| SegmentedProgress | `default` → `brand`, `destructive` → `danger`; `success` `warning` `info` unchanged; `tax` `audit` `accounting` → review |
+| SuiteProgress     | `pro` → `brand`; `audit` `books` `tax` → review                                                                          |
+
+| rule           | Contract | What happens                                                                                                                    |
+| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `tone-renamed` | C-TONE   | the attribute becomes `intent="…"` (applied, low)                                                                               |
+| `pro-as-brand` | C-TONE   | `pro` becomes `brand` (applied, **medium**): confirm the call site meant the brand colour, not "generic purple"                 |
+| `tone-removed` | C-TONE   | `tone="current"` is deleted (applied, low)                                                                                      |
+| `product-tone` | C-TONE   | `audit` `books` `tax` `accounting` have no intent (ADR-007 §2) and stay on `tone` until the products own a service → colour map |
+| `dynamic-tone` | C-TONE   | `tone={expr}`: map the expression's values by hand (review, high)                                                               |
+| `spread-props` | C-TONE   | `{...props}` may carry `tone` too; renaming the literal could change which one wins (review)                                    |
+| `has-intent`   | C-TONE   | both axes present; `intent` already wins, delete `tone` by hand (review, low)                                                   |
+| `unknown-tone` | C-TONE   | a word the component never accepted (review, high)                                                                              |
+
+Not touched: elements that already speak `intent` (idempotency), local
+components with the same names, test files.
+
+### CM-19 — Progress: explicit `intent`
+
+Class R. `ProgressBar` and `ProgressRing` colour themselves **by value** when
+no colour is passed (`< 50%` brand, `≥ 50%` warning, `≥ 80%` success) — a
+business mapping the design system should not own, which 2.0 switches off
+(W9-10, contract C-PROGRESS). W3-21 added `intent`; passing it disables the
+rule. CM-19 makes every call site say what it renders today, so the flip
+changes nothing a consumer did not write down: `variant="<legacy word>"`
+becomes `intent="<colour>"` (`default` → `brand`, `destructive` → `danger`),
+and a meter with no colour and a literal `value` (literal or absent `max`)
+gets the `intent` the rule picks for that value, after `value`. The rename to
+the unified `Progress variant="bar" | "ring"` (target architecture §26) is the
+second half of this codemod and lands with that component.
+
+| rule                        | Contract   | What happens                                                                                                     |
+| --------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `variant-renamed`           | C-PROGRESS | `variant` becomes `intent` (applied, low)                                                                        |
+| `auto-colour-made-explicit` | C-PROGRESS | the value rule's intent is written down (applied, **medium**): confirm the colour, not the number, was the point |
+| `indeterminate-brand`       | C-PROGRESS | `value={null}` gets `intent="brand"` (applied, low)                                                              |
+| `dynamic-value`             | C-PROGRESS | no colour and `value={expr}` (or `max={expr}`): the colour depends on runtime data → a human (review, high)      |
+| `dynamic-variant`           | C-PROGRESS | `variant={expr}`: map the values by hand (review, high)                                                          |
+| `spread-props`              | C-PROGRESS | `{...props}` may carry `variant`, `intent` or `value` (review)                                                   |
+| `unknown-variant`           | C-PROGRESS | a word the component never accepted (review, high)                                                               |
+
+`SegmentedProgress` and `SuiteProgress` have no value rule; CM-06 moves their
+`tone`. Not touched: elements that already pass `intent`, local components
+with the same names, test files.
+
+### CM-02 — Button explicit default size
+
+Class A. Every `Button`, `SubmitButton` and `LinkButton` imported from the
+design system (aliased and namespace imports included) that passes no `size`
+gets `size="md"` — the value the component resolves today
+(`defaultVariants.size`, 40px), so nothing moves on screen. It exists because
+a size _meaning_ can only change once no call site depends on the default:
+after CM-02, the D5 size flip (CM-03 phase 2, W9-06) touches nothing a
+consumer did not write down, and 2.0 gate G6 counts exactly this.
+
+The attribute goes after `variant` when there is one (the order the
+applications use) and first otherwise, on its own line when the element's
+attributes are one per line — a Prettier-formatted file stays formatted.
+
+| rule            | Contract   | What happens         |
+| --------------- | ---------- | -------------------- |
+| `implicit-size` | C-BTN-SIZE | `size="md"` is added |
+
+Not touched, and listed under "could not be transformed": an element with a
+spread (`<Button {...props}>`) — the spread may already carry `size`. Not
+touched and not reported: an element with any `size` (the icon sizes, a
+dynamic `size={x}`), a local component called `Button`, test files (the
+scanner that measures G6 counts production files only).
+
+### CM-12 — Button `type="submit"` where evident
+
+Class R. An untyped `Button` renders `<button>` without a `type`, which the
+browser treats as `submit`; 2.0 flips the default to `"button"` (W9-05,
+C-BTN-TYPE, gate G4). CM-12 writes down, before the flip, which Buttons submit
+on purpose — and only where the file itself makes that evident:
+
+| rule              | Action  | Severity | When                                                                         |
+| ----------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+| `submit-in-form`  | applied | medium   | inside a lower-case `<form>` in the same file, no `onClick`, no spread       |
+| `in-form-onclick` | review  | high     | inside a `<form>` with an `onClick` — submit with side effects, or a button? |
+| `in-form-spread`  | review  | high     | inside a `<form>` with `{...props}` — the spread may carry `type`            |
+| `outside-form`    | review  | low      | no `<form>` in this file; rendered inside one elsewhere, it submits today    |
+
+The applied change states what the browser does today, so it is
+behaviour-neutral; it is still in the report because a human has to agree that
+submitting is what the button is for — a "Cancel" matching that shape is a
+bug today, now visible. Nothing is followed across files (a component
+rendered inside a `<form>` by another component is `outside-form`), and a
+capitalised `<Form>` does not count: the react-hook-form / shadcn `Form` is a
+context provider, not a form element. `SubmitButton`, `LinkButton`, a Button
+with any `type`, a Button with `asChild` and test files are not reported.
+
 ### CM-14 — hidden-input mirror finder
 
 Report-only, **for ever**: deleting a mirror changes what the server receives,
@@ -271,26 +453,41 @@ export function transform(file, { ts, postcss }) {
 ```
 
 `usesTypeScript` and `usesPostcss` ask the runner to resolve that parser from
-the project and inject it; a codemod never imports one itself.
+the project and inject it; a codemod never imports one itself. A transforming
+codemod edits the source with `lib/jsx-edit.mjs` (`insertAttribute`,
+`applyInsertions`), which keeps the file's own formatting; a finding it
+applied carries `action: "applied"`, one it leaves to a human
+`action: "review"`.
+
+A codemod may also export `guard(context)`, run before any file is read, that
+returns the problems that refuse the run. It receives `{ root, ledger,
+dsVersion, dry, requireLedger }`, where `requireLedger(["CM-02"])` returns one
+problem per prerequisite the ledger lacks. `meta.requires.codemods` is the
+declarative form of the same check; the hook is for a prerequisite that
+depends on the codemod's own state (CM-03 phase 2).
 
 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):
+small project, the expected findings and, for transforming codemods, the
+expected output of every file that changes:
 
 ```
 === file: src/thing.tsx
 <source>
+=== output: src/thing.tsx
+<the source after the codemod>
 === 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.
+directory, runs the codemod **twice** and asserts that the second run changes
+nothing and finds what the first run did not apply — the idempotency
+requirement of plan §29. A file without an `=== output:` section must come out
+unchanged; a fixture with none is report-only and may write no ledger.
 `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

package/codemods/lib/jsx-edit.mjs

@@ -0,0 +1,118 @@
+/**
+ * Source edits for transforming codemods.
+ *
+ * A transforming codemod (class A or R) changes consumer files that are
+ * formatted by the consumer's Prettier, so an edit must leave the file in the
+ * shape Prettier would produce: a new attribute goes on its own line when the
+ * element's attributes are one per line, and inline when they are inline. The
+ * edits are computed against the parsed tree and applied to the original text
+ * from the end backwards, so nothing else in the file moves.
+ *
+ * As everywhere in `codemods/lib`, the TypeScript module is passed in.
+ */
+
+const isWhitespace = (text) => /^\s*$/.test(text);
+
+/**
+ * The edit that inserts `text` (e.g. `size="md"`) as an attribute of the JSX
+ * opening or self-closing element `opening`.
+ *
+ * The attribute goes right after the attribute named `after` when the element
+ * has one, otherwise first. The separator copies the whitespace the element
+ * already uses before that position (a newline plus the indentation for
+ * one-attribute-per-line elements, a space otherwise).
+ *
+ * @returns {{ pos: number, text: string }}
+ */
+export function insertAttribute(ts, sf, opening, text, { after = null } = {}) {
+  const source = sf.text;
+  const attrs = opening.attributes.properties;
+  const attributesStart = opening.attributes.pos;
+  const separatorBefore = (index) => {
+    const from = index === 0 ? attributesStart : attrs[index - 1].getEnd();
+    const gap = source.slice(from, attrs[index].getStart(sf));
+    return gap && isWhitespace(gap) ? gap : " ";
+  };
+
+  if (after) {
+    const index = attrs.findIndex(
+      (attr) => ts.isJsxAttribute(attr) && attr.name.getText(sf) === after,
+    );
+    if (index >= 0) {
+      return { pos: attrs[index].getEnd(), text: `${separatorBefore(index)}${text}` };
+    }
+  }
+  const separator = attrs.length ? separatorBefore(0) : " ";
+  return { pos: attributesStart, text: `${separator}${text}` };
+}
+
+/** The JSX attribute named `name` on `opening`, or null. */
+export function attributeNamed(ts, opening, name) {
+  return (
+    opening.attributes.properties.find(
+      (attr) => ts.isJsxAttribute(attr) && attr.name.getText() === name,
+    ) ?? null
+  );
+}
+
+/**
+ * The edit that replaces the attribute named `name` (its whole text, name and
+ * initializer) with `text`, e.g. `tone="pro"` → `intent="brand"`. The
+ * attribute keeps its place, so the file's formatting is untouched.
+ *
+ * @returns {{ pos: number, end: number, text: string } | null}
+ */
+export function replaceAttribute(ts, sf, opening, name, text) {
+  const attr = attributeNamed(ts, opening, name);
+  if (!attr) return null;
+  return { pos: attr.getStart(sf), end: attr.getEnd(), text };
+}
+
+/**
+ * The edit that renames the attribute `name` to `to` and keeps its value,
+ * e.g. `iconLeft={<X />}` → `iconStart={<X />}`. Only the name's characters
+ * are replaced, so the initializer — however many lines it spans — and the
+ * file's formatting are untouched.
+ *
+ * @returns {{ pos: number, end: number, text: string } | null}
+ */
+export function renameAttribute(ts, sf, opening, name, to) {
+  const attr = attributeNamed(ts, opening, name);
+  if (!attr) return null;
+  return { pos: attr.name.getStart(sf), end: attr.name.getEnd(), text: to };
+}
+
+/**
+ * The edit that removes the attribute named `name` together with the
+ * whitespace before it, so `<X a tone="current" b>` becomes `<X a b>` and a
+ * one-attribute-per-line element loses the whole line.
+ *
+ * @returns {{ pos: number, end: number, text: string } | null}
+ */
+export function removeAttribute(ts, sf, opening, name) {
+  const attrs = opening.attributes.properties;
+  const index = attrs.findIndex((attr) => ts.isJsxAttribute(attr) && attr.name.getText() === name);
+  if (index < 0) return null;
+  const from = index === 0 ? opening.attributes.pos : attrs[index - 1].getEnd();
+  return { pos: from, end: attrs[index].getEnd(), text: "" };
+}
+
+/**
+ * `source` with every edit applied, from the end backwards so positions stay
+ * valid. An edit is `{ pos, text }` (an insertion) or `{ pos, end, text }` (a
+ * replacement of the range). Edits must not overlap.
+ */
+export function applyEdits(source, edits) {
+  let out = source;
+  const ordered = [...edits].sort((a, b) => b.pos - a.pos || (b.end ?? b.pos) - (a.end ?? a.pos));
+  for (const edit of ordered) {
+    out = `${out.slice(0, edit.pos)}${edit.text}${out.slice(edit.end ?? edit.pos)}`;
+  }
+  return out;
+}
+
+/** `source` with every `{ pos, text }` insertion applied. */
+export const applyInsertions = applyEdits;
+
+/** The opening element of a JSX element node (a self-closing one is its own). */
+export const openingOf = (ts, node) => (ts.isJsxElement(node) ? node.openingElement : node);

package/codemods/lib/ledger.mjs

@@ -56,9 +56,25 @@ export function recordApplied(root, { id, appliedAt, dsVersion, filesChanged })
   return { schema: LEDGER_SCHEMA, applied };
 }
 
+/**
+ * The problems that stop codemod `id` while the codemods in `ids` are not in
+ * the ledger — one line per missing prerequisite, `[]` when all are there.
+ *
+ * `meta.requires.codemods` is the declarative form and goes through here. A
+ * codemod whose prerequisite depends on its own state calls it from its
+ * `guard` hook instead: CM-03 phase 2 runs only when the ledger shows phase 1
+ * and CM-02 (`requireLedger(["CM-02"])`, plan §29).
+ */
+export function requireLedger(ledger, ids, { id = "This codemod" } = {}) {
+  const applied = appliedIds(ledger);
+  return ids
+    .filter((required) => !applied.has(required))
+    .map((required) => `${id} needs ${required} to be applied first (not in ${LEDGER_FILE}).`);
+}
+
 /**
  * Why `meta` may not be applied to a project with this ledger and installed
- * DS version, or `null`. Checked before any file is read.
+ * DS version, or `[]`. Checked before any file is read.
  */
 export function guardProblems(meta, ledger, dsVersion, compareVersions) {
   const problems = [];
@@ -69,11 +85,7 @@ export function guardProblems(meta, ledger, dsVersion, compareVersions) {
       `${meta.id} is a one-shot codemod and the ledger shows it was already applied${when ? ` (${when})` : ""}.`,
     );
   }
-  for (const required of meta.requires?.codemods ?? []) {
-    if (!ids.has(required)) {
-      problems.push(`${meta.id} needs ${required} to be applied first (not in ${LEDGER_FILE}).`);
-    }
-  }
+  problems.push(...requireLedger(ledger, meta.requires?.codemods ?? [], { id: meta.id }));
   const minimum = meta.requires?.dsVersion;
   if (minimum && compareVersions(dsVersion, minimum) < 0) {
     problems.push(

package/codemods/lib/registry.mjs

@@ -3,6 +3,12 @@
  * codemods listed here can be run by id; the sequence is the plan's.
  */
 export const CODEMODS = [
+  { id: "CM-05", module: "../transforms/cm-05-button-icon-slots.mjs" },
+  { id: "CM-02", module: "../transforms/cm-02-button-explicit-size.mjs" },
+  { id: "CM-04", module: "../transforms/cm-04-button-variant-intent.mjs" },
+  { id: "CM-06", module: "../transforms/cm-06-tone-to-intent.mjs" },
+  { id: "CM-19", module: "../transforms/cm-19-progress-explicit-intent.mjs" },
+  { id: "CM-12", module: "../transforms/cm-12-button-type-submit.mjs" },
   { id: "CM-14", module: "../transforms/cm-14-hidden-mirrors.mjs" },
   { id: "CM-15", module: "../transforms/cm-15-dom-selectors.mjs" },
   { id: "CM-16", module: "../transforms/cm-16-globals-css.mjs" },

package/codemods/lib/report.mjs

@@ -63,6 +63,7 @@ export function renderMarkdown(report) {
         const what = [
           f.component,
           f.rule,
+          f.action,
           f.severity && `severity ${f.severity}`,
           f.gate && `gate ${f.gate}`,
           f.confidence && `confidence ${f.confidence}`,

package/codemods/lib/runner.mjs

@@ -15,7 +15,7 @@ import {
   loadPostcss,
   loadTypeScript,
 } from "./environment.mjs";
-import { appliedIds, guardProblems, readLedger, recordApplied } from "./ledger.mjs";
+import { appliedIds, guardProblems, readLedger, recordApplied, requireLedger } from "./ledger.mjs";
 import { loadCodemod } from "./registry.mjs";
 
 export const REPORT_SCHEMA = 1;
@@ -37,18 +37,31 @@ export class Refused extends Error {
  * @param {string[]} [options.paths] files or directories (default: the root)
  * @param {boolean} [options.dry] report only; never write files or the ledger
  * @param {() => Date} [options.now] clock, for tests
+ * @param {(id: string) => Promise<object|null>} [options.load] codemod loader, for tests
  * @returns {Promise<object>} the report
  */
 export async function runCodemod(
   id,
-  { root, paths = [], dry = false, now = () => new Date() } = {},
+  { root, paths = [], dry = false, now = () => new Date(), load = loadCodemod } = {},
 ) {
-  const mod = await loadCodemod(id);
+  const mod = await load(id);
   if (!mod) throw new Refused([`Unknown codemod ${id}. \`run.mjs list\` shows the available ids.`]);
   const meta = mod.meta;
   const dsVersion = installedDsVersion();
   const ledger = readLedger(root);
   const problems = guardProblems(meta, ledger, dsVersion, compareVersions);
+  // A codemod whose prerequisite depends on its own state (CM-03 phase 2)
+  // exports `guard`; it gets the ledger and `requireLedger(ids)` bound to it.
+  if (typeof mod.guard === "function") {
+    const extra = await mod.guard({
+      root,
+      ledger,
+      dsVersion,
+      dry,
+      requireLedger: (ids) => requireLedger(ledger, ids, { id: meta.id }),
+    });
+    problems.push(...(extra ?? []));
+  }
   // A dry run may preview an already-applied one-shot codemod; missing
   // prerequisites still refuse, because the preview would be wrong.
   const blocking = dry ? problems.filter((p) => !p.includes("already applied")) : problems;
@@ -108,7 +121,13 @@ export async function runCodemod(
       String(a.match).localeCompare(String(b.match)),
   );
 
-  const applied = meta.class !== "X" && !dry && changed.length > 0;
+  // A transforming codemod is recorded when it ran for real: on its first run
+  // even when every call site was already in the target shape (a prerequisite
+  // such as CM-02 must be satisfiable in such a project), and again whenever
+  // it changed a file. A run that changes nothing in a project that already
+  // records it adds no entry.
+  const applied =
+    meta.class !== "X" && !dry && (changed.length > 0 || !appliedIds(ledger).has(meta.id));
   const appliedAt = now().toISOString();
   if (applied)
     recordApplied(root, { id: meta.id, appliedAt, dsVersion, filesChanged: changed.length });

package/codemods/transforms/cm-02-button-explicit-size.mjs

@@ -0,0 +1,96 @@
+/**
+ * CM-02 — Button: make the implicit default size explicit (class A; plan §29
+ * seq 4, registry `C-BTN-SIZE`, prerequisite of the size remap CM-03 and of
+ * 2.0 gate G6).
+ *
+ * Every `Button`, `SubmitButton` and `LinkButton` imported from the design
+ * system that passes no `size` gets `size="md"` — the value the component
+ * resolves today (`defaultVariants.size = "md"`, 40px), so the change is
+ * pixel-neutral. It exists because a size *meaning* can only change once no
+ * call site depends on the default: after CM-02, flipping what `md` or the
+ * default means (D5, W9-06) touches nothing a consumer did not write down.
+ *
+ * ## What it changes
+ *
+ * | rule            | registry   | what happens                                          |
+ * | --------------- | ---------- | ----------------------------------------------------- |
+ * | `implicit-size` | C-BTN-SIZE | `size="md"` is added, after `variant` when there is one |
+ *
+ * The attribute follows the file's own formatting (one per line or inline,
+ * see `lib/jsx-edit.mjs`), so a Prettier-formatted file stays formatted.
+ *
+ * ## What it leaves alone, and reports
+ *
+ * - An element with a spread (`<Button {...props}>`): the spread may already
+ *   carry `size`, and adding a literal before or after it would either be
+ *   overridden or override. It is listed under "could not be transformed"
+ *   with its line, for a human.
+ * - An element that already has `size` — any value, including the icon sizes
+ *   and a dynamic `size={x}` — is not touched. That is also what makes the
+ *   codemod idempotent.
+ * - Local components called `Button` that are not imported from the design
+ *   system, and test files (the scanner that measures G6 counts production
+ *   files only).
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyInsertions, insertAttribute, openingOf } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-02",
+  title: 'Button: make the implicit default size explicit (size="md")',
+  class: "A",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-BTN-SIZE"],
+};
+
+/** The design-system components whose `size` defaults to `md` today. */
+export const SIZED_BUTTONS = new Set(["Button", "SubmitButton", "LinkButton"]);
+
+/** What the component resolves when `size` is omitted (button.tsx `defaultVariants`). */
+export const DEFAULT_SIZE = "md";
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const notTransformed = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !SIZED_BUTTONS.has(el.base) || el.component !== el.base) continue;
+    if (el.props.has("size")) continue;
+    if (el.spread) {
+      notTransformed.push({
+        line: el.line,
+        reason: "spread-props",
+        detail: `<${el.tag} {…}> — the spread may already pass \`size\`; add size="${DEFAULT_SIZE}" by hand if it does not`,
+      });
+      continue;
+    }
+    edits.push(
+      insertAttribute(ts, facts.sf, openingOf(ts, el.node), `size="${DEFAULT_SIZE}"`, {
+        after: "variant",
+      }),
+    );
+    findings.push({
+      line: el.line,
+      registryId: "C-BTN-SIZE",
+      rule: "implicit-size",
+      match: `<${el.tag}>`,
+      component: el.component,
+      action: "applied",
+      gate: "G6",
+    });
+  }
+
+  return {
+    output: edits.length ? applyInsertions(file.source, edits) : file.source,
+    findings,
+    notTransformed,
+    parseErrors: facts.parseErrors,
+  };
+}