@assure-one/design-system 1.34.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

@@ -107,18 +107,143 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 
 ## Codemods
 
-| 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                           |
+| 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-04 and CM-05 need the Button `intent` and `iconStart`/`iconEnd` API of
-W3-02 and W3-07).
+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
 

package/codemods/lib/jsx-edit.mjs

@@ -46,14 +46,73 @@ export function insertAttribute(ts, sf, opening, text, { after = null } = {}) {
   return { pos: attributesStart, text: `${separator}${text}` };
 }
 
-/** `source` with every `{ pos, text }` insertion applied. */
-export function applyInsertions(source, edits) {
+/** 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;
-  for (const edit of [...edits].sort((a, b) => b.pos - a.pos)) {
-    out = `${out.slice(0, edit.pos)}${edit.text}${out.slice(edit.pos)}`;
+  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/registry.mjs

@@ -3,7 +3,11 @@
  * 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" },

package/codemods/transforms/cm-04-button-variant-intent.mjs

@@ -0,0 +1,223 @@
+/**
+ * CM-04 — Button family: legacy single-axis `variant` → the `variant` +
+ * `intent` pair (class R; plan §29 seq 5, registry `C-BTN-VAR`, `C-BTN-ACCENT`).
+ *
+ * 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, each a fixed pair
+ * (`LEGACY_BUTTON_VARIANTS` in `src/primitives/behavior/button-base.ts`,
+ * ADR-007 §4). Every alias renders the exact classes it always did, so the
+ * rewrite is pixel-neutral:
+ *
+ * | legacy word   | becomes                              | `intent` written?                        |
+ * | ------------- | ------------------------------------ | ---------------------------------------- |
+ * | `primary`     | `variant="solid"`                    | no — `brand` is what `solid` defaults to |
+ * | `secondary`   | `variant="soft"`                     | no — `neutral` is `soft`'s default        |
+ * | `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) |
+ *
+ * `intent` is omitted where it equals what the new emphasis resolves on its
+ * own (`DEFAULT_BUTTON_INTENT`), so the output is the smallest call that
+ * renders today's pixels. `ghost`, `outline` and `link` are emphases already
+ * and are not touched.
+ *
+ * ## What it reports
+ *
+ * | rule                    | action  | severity | why                                                                          |
+ * | ----------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+ * | `variant-split`         | applied | low      | the alias became its pair (or its emphasis alone, when the intent is the default) |
+ * | `destructive-as-danger` | applied | medium   | `destructive` → `solid` + `danger`: the word moves to D4's default (`danger` canonical, ADR-007 §5); a human confirms |
+ * | `legacy-look`           | review  | medium   | `accent` (D13) and `dashed` have a look no pair renders; they stay until decided / 2.x |
+ * | `dynamic-intent`        | review  | medium   | a legacy word next to `intent={expr}` whose alias intent is not the new emphasis's default: when the expression is `undefined` the alias renders its own intent, the new word its default |
+ * | `dynamic-variant`       | review  | high     | `variant={expr}`: the value is not visible here; map it by hand               |
+ * | `spread-props`          | review  | medium   | `{...props}` may carry `variant` or `intent`; rewriting the literal could change which wins |
+ * | `unknown-variant`       | review  | high     | a word the Button never accepted                                              |
+ *
+ * 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 (ADR-007 §4, `resolveButtonStyle`).
+ * `intent="destructive"` is not touched — that is CM-17, gated by D4.
+ *
+ * Elements that already speak the new words are not touched (idempotency).
+ * Local components with the same names are not touched; test files are
+ * skipped, as by the scanner that measures C-BTN-VAR.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyEdits, insertAttribute, openingOf, replaceAttribute } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-04",
+  title: "Button family: legacy variant → variant + intent",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-BTN-VAR", "C-BTN-ACCENT"],
+};
+
+/** The design-system components that read `buttonVariants` (W3-02). */
+export const BUTTONS = new Set(["Button", "LinkButton", "SubmitButton"]);
+
+/**
+ * The legacy alias map — `LEGACY_BUTTON_VARIANTS` of
+ * `src/primitives/behavior/button-base.ts`, row for row (ADR-007 §4). A row
+ * with a `look` is a legacy-only look: no pair renders it, so the word stays.
+ * `tests/codemods/cm-04.test.mjs` checks this table against the source.
+ */
+export const LEGACY_VARIANTS = {
+  primary: { variant: "solid", intent: "brand" },
+  secondary: { variant: "soft", intent: "neutral" },
+  destructive: { variant: "solid", intent: "danger" },
+  success: { variant: "solid", intent: "success" },
+  accent: { variant: "solid", intent: "brand", look: "accent" },
+  dashed: { variant: "outline", intent: "neutral", look: "dashed" },
+};
+
+/**
+ * The intent each emphasis renders when only `variant` is passed —
+ * `DEFAULT_BUTTON_INTENT` of button-base.ts (ADR-007 §3). Where the alias
+ * intent equals this, `intent` is omitted from the output.
+ */
+export const DEFAULT_INTENT = {
+  solid: "brand",
+  soft: "neutral",
+  outline: "neutral",
+  ghost: "neutral",
+  link: "brand",
+};
+
+/** The emphases: already vocabulary, never rewritten. */
+export const EMPHASES = new Set(Object.keys(DEFAULT_INTENT));
+
+/** The registry contract a legacy word belongs to. */
+export const contractOf = (word) => (word === "accent" ? "C-BTN-ACCENT" : "C-BTN-VAR");
+
+/**
+ * What a literal legacy `variant` becomes, or null when the word is not a
+ * legacy alias: `{ rule, action, severity, variant, intent }`, `intent` being
+ * `null` when it is the new emphasis's default and is left out.
+ */
+export function classifyVariant(word) {
+  const pair = LEGACY_VARIANTS[word];
+  if (!pair) return null;
+  if (pair.look) return { rule: "legacy-look", action: "review", severity: "medium" };
+  const intent = pair.intent === DEFAULT_INTENT[pair.variant] ? null : pair.intent;
+  if (word === "destructive") {
+    return {
+      rule: "destructive-as-danger",
+      action: "applied",
+      severity: "medium",
+      variant: pair.variant,
+      intent,
+    };
+  }
+  return {
+    rule: "variant-split",
+    action: "applied",
+    severity: "low",
+    variant: pair.variant,
+    intent,
+  };
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !BUTTONS.has(el.base) || el.component !== el.base) continue;
+    const variant = el.props.get("variant");
+    if (!variant) continue;
+    const word = variant.expression || variant.literals.length !== 1 ? null : variant.literals[0];
+    if (word !== null && EMPHASES.has(word)) continue;
+
+    const intentAttr = el.props.get("intent") ?? null;
+    const base = {
+      line: el.line,
+      registryId: contractOf(word),
+      match: `<${el.tag} variant=${variant.text ?? ""}>`,
+      component: el.component,
+      gate: null,
+      detail: {
+        variant: word,
+        dynamic: variant.expression,
+        intent: intentAttr
+          ? intentAttr.expression
+            ? null
+            : (intentAttr.literals[0] ?? null)
+          : undefined,
+      },
+    };
+    const review = (rule, severity) => findings.push({ ...base, rule, severity, action: "review" });
+
+    if (word === null) {
+      review("dynamic-variant", "high");
+      continue;
+    }
+    if (el.spread) {
+      review("spread-props", "medium");
+      continue;
+    }
+    const outcome = classifyVariant(word);
+    if (!outcome) {
+      review("unknown-variant", "high");
+      continue;
+    }
+    if (outcome.action === "review") {
+      review(outcome.rule, outcome.severity);
+      continue;
+    }
+    // A dynamic `intent` may be `undefined` at runtime, in which case the
+    // alias renders its own intent and the new emphasis its default: only
+    // safe when the two agree.
+    if (intentAttr && intentAttr.expression && outcome.intent !== null) {
+      review("dynamic-intent", "medium");
+      continue;
+    }
+
+    const opening = openingOf(ts, el.node);
+    const replaced = replaceAttribute(
+      ts,
+      facts.sf,
+      opening,
+      "variant",
+      `variant="${outcome.variant}"`,
+    );
+    if (!replaced) {
+      review("dynamic-variant", "high");
+      continue;
+    }
+    edits.push(replaced);
+    const writesIntent = outcome.intent !== null && !intentAttr;
+    if (writesIntent) {
+      edits.push(
+        insertAttribute(ts, facts.sf, opening, `intent="${outcome.intent}"`, { after: "variant" }),
+      );
+    }
+    findings.push({
+      ...base,
+      rule: outcome.rule,
+      severity: outcome.severity,
+      action: "applied",
+      detail: {
+        ...base.detail,
+        variant: word,
+        emphasis: outcome.variant,
+        intent: writesIntent ? outcome.intent : base.detail.intent,
+      },
+    });
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}

package/codemods/transforms/cm-05-button-icon-slots.mjs

@@ -0,0 +1,117 @@
+/**
+ * CM-05 — Button family: `iconLeft` / `iconRight` → `iconStart` / `iconEnd`
+ * (class A; plan §29 seq 1, registry `C-BTN-ICONPROPS`).
+ *
+ * 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
+ * (`ButtonIconProps`, `resolveButtonIcons` in
+ * `src/primitives/behavior/button-base.ts`). Each alias is the same slot under
+ * another name, so the rename 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 its formatting.
+ *
+ * | rule           | registry       | what happens                              |
+ * | -------------- | -------------- | ----------------------------------------- |
+ * | `icon-renamed` | C-BTN-ICONPROPS | `iconLeft` → `iconStart`, `iconRight` → `iconEnd` |
+ *
+ * ## What it leaves alone, and lists under "could not be transformed"
+ *
+ * - An element that passes **both names of one side** (`iconStart` and
+ *   `iconLeft`): the component throws on that in development — two names,
+ *   one slot — and a rename would turn the error into a duplicate attribute.
+ *   Neither side of that element is touched; a human deletes one.
+ * - An element with a spread (`<Button iconLeft={…} {...props}>`): the spread
+ *   may carry either name for the same slot, and which one wins depends on
+ *   the order of the attributes — renaming the literal could change it.
+ *
+ * Elements that already use the new names are not touched (idempotency).
+ * Local components with the same names are not touched; test files are
+ * skipped, as by the scanner that measures C-BTN-ICONPROPS.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyEdits, openingOf, renameAttribute } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-05",
+  title: "Button family: iconLeft/iconRight → iconStart/iconEnd",
+  class: "A",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-BTN-ICONPROPS"],
+};
+
+/** The design-system components with the two icon slots (W3-07). */
+export const ICON_BUTTONS = new Set(["Button", "LinkButton", "SubmitButton"]);
+
+/**
+ * Deprecated alias → the slot it names (`ButtonIconProps` of button-base.ts).
+ * `tests/codemods/cm-05.test.mjs` checks it against the source.
+ */
+export const ICON_SLOTS = {
+  iconLeft: "iconStart",
+  iconRight: "iconEnd",
+};
+
+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 || !ICON_BUTTONS.has(el.base) || el.component !== el.base) continue;
+    const legacy = Object.keys(ICON_SLOTS).filter((name) => el.props.has(name));
+    if (!legacy.length) continue;
+
+    const clashes = legacy.filter((name) => el.props.has(ICON_SLOTS[name]));
+    if (clashes.length) {
+      notTransformed.push({
+        line: el.line,
+        reason: "both-names",
+        detail: `<${el.tag}> passes ${clashes
+          .map((name) => `\`${name}\` and \`${ICON_SLOTS[name]}\``)
+          .join(" and ")} — one slot, two names; delete the deprecated one by hand`,
+      });
+      continue;
+    }
+    if (el.spread) {
+      notTransformed.push({
+        line: el.line,
+        reason: "spread-props",
+        detail: `<${el.tag} {…}> — the spread may carry \`${legacy
+          .map((name) => ICON_SLOTS[name])
+          .join("\` or \`")}\` for the same slot; rename by hand once you know it does not`,
+      });
+      continue;
+    }
+
+    const opening = openingOf(ts, el.node);
+    for (const name of legacy) {
+      const edit = renameAttribute(ts, facts.sf, opening, name, ICON_SLOTS[name]);
+      if (!edit) continue;
+      edits.push(edit);
+      findings.push({
+        line: el.props.get(name).line,
+        registryId: "C-BTN-ICONPROPS",
+        rule: "icon-renamed",
+        match: `<${el.tag} ${name}>`,
+        component: el.component,
+        action: "applied",
+        gate: null,
+        detail: { from: name, to: ICON_SLOTS[name] },
+      });
+    }
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed,
+    parseErrors: facts.parseErrors,
+  };
+}