@assure-one/design-system 1.32.0 → 1.34.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/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).
 - [**`claude-skills/`**](./claude-skills) — drop-in Claude Code skill for consuming projects.
 
@@ -53,15 +54,35 @@ no component reads them, and importing them changes nothing on its own.
 | `./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
+| `./css/components.css` | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens. **Unused until the class-vocabulary flip (W1-11):** no component emits a prefixed class yet, so importing it styles nothing. Published so the file, its size and its hygiene can be reviewed before the flip. |
+
+Import order is `tokens.css` → `legacy-aliases.css` (optional) → `tailwind.css`
+→ `shadcn.css` (optional) → `base.css` (optional) → `components.css`, after your own
+`@import "tailwindcss"` and under the layer statement
+`@layer theme, base, ds, components, utilities;`.
+[**`docs/integration/css.md`**](./docs/integration/css.md) has the full
+sequence, where the per-app preset goes, when the `@source` into our package may
+be removed, and the fixture run behind each of those claims. The reasoning lives
+in [ADR-004](./docs/adr/004-css-delivery-cascade.md) and
 [ADR-005](./docs/adr/005-app-vocabulary-bridge.md).
 
+### Runtime brand theming (experimental)
+
+For a tenant colour known only at runtime, `@assure-one/design-system/tokens`
+exports `createBrandTheme()`: a validated seed becomes the custom properties a
+built-in brand scope declares, ready to spread into a `style` attribute.
+
+```tsx
+import { createBrandTheme } from "@assure-one/design-system/tokens";
+
+<div style={{ ...createBrandTheme({ brand: "#2258d8", accent: "#f59e0b" }) }}>…</div>;
+```
+
+It is pure and SSR-deterministic, clamps a fill too pale to read against the
+canvas, and guarantees WCAG AA for every foreground it emits. The seed shape is
+gated by decision D7 and may change while that decision is open — see
+[`docs/integration/css.md`](./docs/integration/css.md#5-runtime-brand-theming).
+
 ## Develop
 
 ```bash
@@ -76,14 +97,24 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full dev loop, including iter
 
 ## Architecture
 
-3-tier token system (W3C Design Tokens spec compatible):
+3-tier token system, authored as DTCG JSON in [`tokens/src`](./tokens/README.md)
+and generated into `src/tokens/` and the `./css/*` entries (ADR-003):
 
-```
-reference   →   system (semantic)   →   component
-color.navy.700  →  color.action.primary.bg  →  button.primary.bg
-```
+| Tier | Example (namespaced name → value) | Reads |
+| --- | --- | --- |
+| reference | `--ds-ref-brand-pro-fg: #6c42f8` | a literal; the raw ramps, one per brand |
+| system (semantic) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | the reference tier; **this is the public contract** |
+| component | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | the system tier; only where a component must be themable on its own |
+
+Components consume **system tokens**, never reference values directly. Themes
+(colour scheme, per-product brand, a runtime brand from `createBrandTheme()`)
+re-map system → reference without touching component code.
 
-Components consume **system tokens**, never reference values directly. Themes (light, dark, per-product accent) re-map system → reference without touching component code.
+Every token has two published spellings: the namespaced `--ds-*` name above and
+the legacy name it ships as today (`--color-brand`, `--color-pro-fg`,
+`--color-menu-item-hover-bg`). `css/legacy-aliases.css` declares
+`<legacy>: var(<--ds-* name>)` in the same scopes, so both resolve to the same
+value — proved by `pnpm tokens:ds-check`.
 
 ## Releases
 

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,13 +107,123 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 
 ## 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()` |
+| Id    | Class | What it does                                                                                                                          |
+| ----- | ----- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| CM-02 | A     | Button explicit default size: `size="md"` on every `Button`, `SubmitButton` and `LinkButton` that passes no `size` (pixel-neutral)    |
+| 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.
+APIs (CM-04 and CM-05 need the Button `intent` and `iconStart`/`iconEnd` API of
+W3-02 and W3-07).
+
+### 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,
+and plan §29 never automates that. It is the input to W4-04 (native form
+participation) and to the registry contract `C-HIDDEN-MIRRORS`.
+
+The applications do not put a mirror next to its control — they collect the
+mirrors at the top of the `<form>` and bind the control far below ([CU §18]).
+"Next to" is therefore read as _bound to the same state_:
+
+| Rule                        | Contract         | Found                                                                          |
+| --------------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `mirror-shared-binding`     | C-HIDDEN-MIRRORS | the hidden input's `value` reads a binding a design-system control is bound to |
+| `mirror-in-form`            | C-HIDDEN-MIRRORS | same `<form>` as a control that posts nothing today; nothing ties the two      |
+| `unregistered-hidden-input` | (unregistered)   | no control to mirror — a value the server supplied (a token, an id)            |
+
+Each finding names the control, the field name and whether that control takes
+`name` **today** (`yes`) or only after Wave 4 (`planned`); severity is `high`
+when the control takes `name` and the call site already passes it, because the
+form then posts the field twice.
+
+The third rule is why the report reconciles with the audit's census of every
+hidden `<input>` ([CU §24]): CM-14 reports the same population, classified,
+rather than a smaller number with no explanation. It does not look across
+files — a mirror whose control lives elsewhere lands in `mirror-in-form` or
+`unregistered-hidden-input` and says so. An `<input type={expr}>` whose type is
+computed appears in "could not be transformed".
+
+The `name` capability table lives in the transform, and
+`tests/codemods/cm-14.test.mjs` checks it against the design system's own
+sources so it cannot describe components this version does not ship.
+
+### CM-20 — Select sentinel finder
+
+Report-only, **for ever**: replacing a sentinel with `null` changes what the
+server receives. It is the input to W4-08 (`Select value: string | null`) and
+to the registry contract `C-SELECT-EMPTY`.
+
+The spellings are **found, not assumed**. The registry names `"none"` and
+`"__unassigned__"`; the applications use far more, and `"none"` is also a real
+domain value. CM-20 reports a spelling only where the file itself proves it
+stands in for nothing:
+
+| Rule                  | Contract       | Found                                                             |
+| --------------------- | -------------- | ----------------------------------------------------------------- |
+| `empty-string-value`  | C-SELECT-EMPTY | `value=""` on a Select-family control or an option                |
+| `sentinel-dunder`     | C-SELECT-EMPTY | a `__…__` spelling used as a Select value                         |
+| `sentinel-constant`   | C-SELECT-EMPTY | a no-value-named constant used as a Select value                  |
+| `sentinel-word`       | C-SELECT-EMPTY | `none`/`all`/… **with** a no-value label or a round trip          |
+| `sentinel-discovered` | C-SELECT-EMPTY | any other spelling the file converts to nothing                   |
+| `sentinel-conversion` | C-SELECT-EMPTY | the line that maps a reported sentinel to `null`/`undefined`/`""` |
+
+A known word with no evidence at all is **not** reported: CM-20 would rather
+miss a sentinel than invite someone to change a value the backend depends on.
+Sentinels outside the Select family — grouping keys, tab ids, route segments —
+are out of scope even when the spelling matches, and nothing is followed across
+files.
 
 ### CM-15 — DOM-selector finder
 
@@ -211,26 +328,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/forms.mjs

@@ -0,0 +1,253 @@
+/**
+ * Form-shaped source facts, shared by the two report-only finders of the
+ * forms wave (plan §16): CM-14 (hidden-input mirrors) and CM-20 (Select
+ * sentinels).
+ *
+ * `lib/jsx.mjs` answers "which class tokens sit on which design-system
+ * component" and therefore only records elements that carry a class
+ * attribute. A hidden `<input type="hidden" name="x" value={x} />` carries
+ * none, and a sentinel lives in a prop value, not in a class token — so the
+ * forms codemods need a different view of the same tree:
+ *
+ * - **every** JSX element, design-system and raw alike, in document order;
+ * - each element's attributes, with the string literals and the identifiers
+ *   of the expression behind them (the identifiers are what tie a mirror to
+ *   the control it mirrors);
+ * - the nearest `<form>` ancestor, because the applications do not put a
+ *   mirror next to its control — they collect the mirrors at the top of the
+ *   form ([CU §18]);
+ * - top-level `const NAME = "literal"` declarations, because the sentinels
+ *   are named constants (`const NONE_VALUE = "__none__"`).
+ *
+ * As everywhere in `codemods/lib`, the TypeScript module is passed in: a
+ * codemod never imports a parser itself (`lib/environment.mjs`).
+ */
+import { DS_PACKAGE, createSourceFile } from "./jsx.mjs";
+
+export { DS_PACKAGE };
+
+const isDsSpecifier = (s) => s === DS_PACKAGE || s.startsWith(`${DS_PACKAGE}/`);
+
+/** Attributes whose value is the control's current value, in binding order. */
+export const VALUE_PROPS = ["value", "defaultValue", "checked", "defaultChecked", "selected"];
+
+/** Attributes through which a control writes its value back. */
+export const CHANGE_PROPS = [
+  "onValueChange",
+  "onCheckedChange",
+  "onChange",
+  "onSelect",
+  "onRemove",
+  "onSelectionChange",
+];
+
+/**
+ * Parses one file into form facts.
+ *
+ * Returns:
+ * - `sf`, `lineOf` — the source file and a node → line helper
+ * - `imports` — design-system local name → exported name
+ * - `namespaces` — local names of `import * as X from the package`
+ * - `elements` — every JSX element, in document order, as described below
+ * - `constants` — top-level `const` name → `{ text, line }` for string consts
+ * - `componentsUsed` — the design-system base names used as JSX
+ * - `parseErrors`
+ *
+ * An element is
+ * `{ index, parent, tag, base, component, isDs, line, props, spread, form }`
+ * where `props` is a Map of attribute name → `{ literals, identifiers, text,
+ * line, expression }` and `form` is the index of the nearest `<form>`
+ * ancestor (or `null`).
+ */
+export function analyseForms(ts, text, rel) {
+  const sf = createSourceFile(ts, text, rel);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+
+  const imports = new Map();
+  const namespaces = new Set();
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (!isDsSpecifier(stmt.moduleSpecifier.text)) continue;
+    const clause = stmt.importClause;
+    if (!clause || clause.isTypeOnly) continue;
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else if (bindings && ts.isNamedImports(bindings)) {
+      for (const el of bindings.elements) {
+        if (!el.isTypeOnly) imports.set(el.name.text, (el.propertyName ?? el.name).text);
+      }
+    }
+  }
+
+  /** Top-level `const NAME = "text"`, the shape the sentinels are declared in. */
+  const constants = new Map();
+  for (const stmt of sf.statements) {
+    const list = ts.isVariableStatement(stmt) ? stmt.declarationList : null;
+    if (!list || !(list.flags & ts.NodeFlags.Const)) continue;
+    for (const decl of list.declarations) {
+      if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
+      const init = decl.initializer;
+      if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+        constants.set(decl.name.text, { text: init.text, line: lineOf(init) });
+      }
+    }
+  }
+
+  /** String literals inside an expression, at any depth below JSX. */
+  const literalsIn = (node, out = []) => {
+    if (!node) return out;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      out.push(node.text);
+      return out;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+      return out;
+    }
+    // A block body: `forEachChild` stops at the first truthy return, and the
+    // accumulator is always truthy.
+    ts.forEachChild(node, (child) => {
+      literalsIn(child, out);
+    });
+    return out;
+  };
+
+  /**
+   * Identifier names an expression reads. Member names (`a.b`), object keys
+   * and JSX subtrees are excluded: what matters is which bindings the value
+   * depends on, so that two attributes reading `entityType` can be recognised
+   * as two views of the same state.
+   */
+  const identifiersIn = (node, out = new Set()) => {
+    if (!node) return out;
+    if (ts.isIdentifier(node)) {
+      const parent = node.parent;
+      const isMemberName = parent && ts.isPropertyAccessExpression(parent) && parent.name === node;
+      const isKey =
+        parent &&
+        (ts.isPropertyAssignment(parent) || ts.isPropertySignature(parent)) &&
+        parent.name === node;
+      if (!isMemberName && !isKey) out.add(node.text);
+      return out;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+      return out;
+    }
+    ts.forEachChild(node, (child) => {
+      identifiersIn(child, out);
+    });
+    return out;
+  };
+
+  const resolveTag = (tag) => {
+    const members = [];
+    let current = tag;
+    while (ts.isPropertyAccessExpression(current)) {
+      members.unshift(current.name.text);
+      current = current.expression;
+    }
+    if (!ts.isIdentifier(current)) return null;
+    const root = current.text;
+    if (namespaces.has(root) && members.length) {
+      return { base: members[0], component: members.join(".") };
+    }
+    const base = imports.get(root);
+    if (!base) return null;
+    return { base, component: [base, ...members].join(".") };
+  };
+
+  const elements = [];
+  const openingOf = (node) => (ts.isJsxElement(node) ? node.openingElement : node);
+
+  const record = (node, parent, form) => {
+    const opening = openingOf(node);
+    const info = resolveTag(opening.tagName);
+    const tag = opening.tagName.getText(sf);
+    const props = new Map();
+    let spread = false;
+    for (const attr of opening.attributes.properties) {
+      if (ts.isJsxSpreadAttribute(attr)) {
+        spread = true;
+        continue;
+      }
+      if (!ts.isJsxAttribute(attr)) continue;
+      const name = attr.name.getText(sf);
+      const init = attr.initializer;
+      if (init === undefined) {
+        // A bare attribute (`required`) is the boolean `true`.
+        props.set(name, {
+          literals: [],
+          identifiers: [],
+          text: "true",
+          line: lineOf(attr),
+          expression: false,
+        });
+        continue;
+      }
+      const inner = ts.isJsxExpression(init) ? (init.expression ?? null) : init;
+      const isLiteral =
+        inner !== null && (ts.isStringLiteral(inner) || ts.isNoSubstitutionTemplateLiteral(inner));
+      props.set(name, {
+        literals: inner ? literalsIn(inner) : [],
+        identifiers: inner ? [...identifiersIn(inner)] : [],
+        text: inner ? inner.getText(sf) : null,
+        line: lineOf(attr),
+        expression: Boolean(inner) && !isLiteral,
+      });
+    }
+    const entry = {
+      index: elements.length,
+      parent,
+      tag,
+      base: info?.base ?? null,
+      component: info?.component ?? null,
+      isDs: Boolean(info),
+      line: lineOf(opening),
+      props,
+      spread,
+      form,
+      node,
+    };
+    elements.push(entry);
+    return entry;
+  };
+
+  const walk = (node, parent, form) => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const entry = record(node, parent, form);
+      const nextForm = /^(?:form|Form)$/.test(entry.tag) ? entry.index : form;
+      ts.forEachChild(node, (child) => walk(child, entry.index, nextForm));
+      return;
+    }
+    ts.forEachChild(node, (child) => walk(child, parent, form));
+  };
+  walk(sf, null, null);
+
+  const parseErrors = (sf.parseDiagnostics ?? []).map((d) => ({
+    line: d.start === undefined ? null : sf.getLineAndCharacterOfPosition(d.start).line + 1,
+    message: ts.flattenDiagnosticMessageText(d.messageText, " "),
+  }));
+
+  return {
+    sf,
+    lineOf,
+    literalsIn,
+    identifiersIn: (node) => [...identifiersIn(node)],
+    imports,
+    namespaces,
+    elements,
+    constants,
+    componentsUsed: new Set(elements.filter((e) => e.isDs).map((e) => e.base)),
+    parseErrors,
+  };
+}
+
+/** The literal value of an attribute when it is a single string, else `null`. */
+export const literalValue = (prop) =>
+  prop && !prop.expression && prop.literals.length === 1 ? prop.literals[0] : null;
+
+/** Whether `inner` is `outer` or sits below it in the element tree. */
+export function isWithin(elements, inner, outer) {
+  if (outer === null || inner === null) return false;
+  for (let i = inner; i !== null; i = elements[i].parent) if (i === outer) return true;
+  return false;
+}

package/codemods/lib/jsx-edit.mjs

@@ -0,0 +1,59 @@
+/**
+ * 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}` };
+}
+
+/** `source` with every `{ pos, text }` insertion applied. */
+export function applyInsertions(source, edits) {
+  let out = source;
+  for (const edit of [...edits].sort((a, b) => b.pos - a.pos)) {
+    out = `${out.slice(0, edit.pos)}${edit.text}${out.slice(edit.pos)}`;
+  }
+  return out;
+}
+
+/** 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,8 +3,12 @@
  * codemods listed here can be run by id; the sequence is the plan's.
  */
 export const CODEMODS = [
+  { id: "CM-02", module: "../transforms/cm-02-button-explicit-size.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" },
+  { id: "CM-20", module: "../transforms/cm-20-select-sentinels.mjs" },
 ];
 
 export const findCodemod = (id) =>