@staffbase/design 18.8.1 → 19.0.1

package/codemods/v17-migrate-tokens/README.md

@@ -0,0 +1,176 @@
+# v17 — Migrate Tailwind tokens
+
+This codemod automatically migrates renamed Tailwind tokens introduced as breaking changes in `@staffbase/design` v17.
+
+## What it transforms
+
+### Border radius
+
+All Tailwind positional prefixes are handled (`t`, `b`, `l`, `r`, `tl`, `tr`, `bl`, `br`, `s`, `e`, `ss`, `se`, `es`, `ee`):
+
+| Before              | After                |
+| ------------------- | -------------------- |
+| `rounded-4`         | `rounded-sm`         |
+| `rounded-6`         | `rounded-md`         |
+| `rounded-8`         | `rounded-lg`         |
+| `rounded-16`        | `rounded-xl`         |
+| `rounded-t-4`       | `rounded-t-sm`       |
+| `rounded-e-8`       | `rounded-e-lg`       |
+| `rounded-tl-16`     | `rounded-tl-xl`      |
+| `sm:rounded-4`      | `sm:rounded-sm`      |
+| `hover:rounded-t-6` | `hover:rounded-t-md` |
+
+### Font size
+
+| Before    | After      |
+| --------- | ---------- |
+| `text-12` | `text-xs`  |
+| `text-14` | `text-sm`  |
+| `text-16` | `text-md`  |
+| `text-18` | `text-lg`  |
+| `text-20` | `text-xl`  |
+| `text-24` | `text-2xl` |
+| `text-28` | `text-3xl` |
+| `text-32` | `text-4xl` |
+| `text-36` | `text-5xl` |
+
+### Font weight
+
+| Before         | After         |
+| -------------- | ------------- |
+| `font-regular` | `font-normal` |
+
+### Letter spacing
+
+| Before             | After             |
+| ------------------ | ----------------- |
+| `tracking-default` | `tracking-normal` |
+
+### Pill
+
+The `variant` prop (previously used for colour) is replaced by `color`. Only static string values are transformed; dynamic expressions will surface as TypeScript errors after migration.
+
+| Before                    | After                     |
+| ------------------------- | ------------------------- |
+| `<Pill variant="blue">`   | `<Pill color="primary">`  |
+| `<Pill variant="green">`  | `<Pill color="success">`  |
+| `<Pill variant="grey">`   | `<Pill color="neutral">`  |
+| `<Pill variant="red">`    | `<Pill color="critical">` |
+| `<Pill variant="yellow">` | `<Pill color="warning">`  |
+
+`variant="outline"` and `variant="solid"` are left untouched — they already use the new API.
+
+### PillGroup
+
+`PillGroup` is removed. Its usage is replaced with a plain `div`:
+
+```tsx
+// Before
+import {PillGroup} from '@staffbase/design';
+<PillGroup><Pill>One</Pill><Pill>Two</Pill></PillGroup>
+
+// After
+<div className='flex flex-wrap gap-1'><Pill>One</Pill><Pill>Two</Pill></div>
+```
+
+A static `className` prop is merged into the base classes:
+
+```tsx
+// Before
+<PillGroup className='mt-4'>…</PillGroup>
+
+// After
+<div className='flex flex-wrap gap-1 mt-4'>…</div>
+```
+
+The `PillGroup` import is removed automatically. Other props (`id`, `data-*`, `aria-*`, etc.) are preserved on the resulting `div`.
+
+### TextArea
+
+`TextArea` is renamed to `TextAreaDeprecated` and `TextAreaProps` to `TextAreaDeprecatedProps`. Import specifiers, JSX usages, and TypeScript type references are all updated.
+
+```tsx
+// Before
+import {TextArea, TextAreaProps} from '@staffbase/design';
+const props: TextAreaProps = {};
+<TextArea {...props} />;
+
+// After
+import {TextAreaDeprecated, TextAreaDeprecatedProps} from '@staffbase/design';
+const props: TextAreaDeprecatedProps = {};
+<TextAreaDeprecated {...props} />;
+```
+
+Aliased imports are handled correctly — only the exported name changes, the local alias is preserved:
+
+```tsx
+// Before
+import {TextArea as TA} from '@staffbase/design';
+
+// After
+import {TextAreaDeprecated as TA} from '@staffbase/design';
+```
+
+**Tokens are replaced in all string contexts** — `className` props, `clsx()`/`cn()` calls, variant maps, and constants:
+
+```tsx
+// Before
+<div className="rounded-4 text-14 font-regular" />
+clsx('rounded-8', isActive && 'rounded-t-16')
+const styles = {base: 'tracking-default text-12 rounded-s-6'}
+
+// After
+<div className="rounded-sm text-sm font-normal" />
+clsx('rounded-lg', isActive && 'rounded-t-xl')
+const styles = {base: 'tracking-normal text-xs rounded-s-md'}
+```
+
+## Usage
+
+### Step 1 — Install jscodeshift
+
+```bash
+npm install --save-dev jscodeshift
+# or
+pnpm add -D jscodeshift
+```
+
+### Step 2 — Run the codemod
+
+Point the `--transform` flag at this file inside your `node_modules`:
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v17-migrate-tokens/transform.js \
+  --extensions tsx,ts,jsx,js \
+  --parser tsx \
+  src/
+```
+
+Run a **dry run** first to preview changes without writing files:
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v17-migrate-tokens/transform.js \
+  --extensions tsx,ts,jsx,js \
+  --parser tsx \
+  --dry \
+  --print \
+  src/
+```
+
+### Step 3 — Review and commit
+
+1. Run your type-checker:
+   ```bash
+   npx tsc --noEmit
+   ```
+2. Run your tests.
+3. Commit the result.
+
+## What the codemod does NOT handle
+
+- **CSS files** — `@apply rounded-4` in `.css` files is not transformed. Update these manually.
+- **Dynamic class composition** — e.g. `` `rounded-${size}` `` where the suffix is a variable. Only static string content is replaced.
+- **Dynamic `className` on `PillGroup`** — e.g. `<PillGroup className={cn('mt-4')}>`. The dynamic value is replaced with the base classes only; merge manually afterward.
+- **Spacing tokens** — the v17 spacing scale change (divide by 4 for margins, padding, gap, etc.) is a numeric transformation that cannot be automated safely. Refer to the v17 migration guide.

package/codemods/v17-migrate-tokens/transform.js

@@ -0,0 +1,428 @@
+/**
+ * Jscodeshift codemod: Migrate v17 Tailwind token renames.
+ *
+ * Replaces renamed tokens in all string literals (including clsx/cn calls and
+ * template literals) across JS/TS/JSX/TSX files.
+ *
+ * Border radius — all Tailwind positional prefixes handled
+ * (t, b, l, r, tl, tr, bl, br, s, e, ss, se, es, ee):
+ *   rounded-{prefix?}-4  → rounded-{prefix?}-sm
+ *   rounded-{prefix?}-6  → rounded-{prefix?}-md
+ *   rounded-{prefix?}-8  → rounded-{prefix?}-lg
+ *   rounded-{prefix?}-16 → rounded-{prefix?}-xl
+ *
+ * Font size:
+ *   text-12 → text-xs    text-24 → text-2xl
+ *   text-14 → text-sm    text-28 → text-3xl
+ *   text-16 → text-md    text-32 → text-4xl
+ *   text-18 → text-lg    text-36 → text-5xl
+ *   text-20 → text-xl
+ *
+ * Font weight:
+ *   font-regular → font-normal
+ *
+ * Letter spacing:
+ *   tracking-default → tracking-normal
+ *
+ * Breakpoints (only as responsive prefixes — e.g. 3xl:flex, not text-3xl):
+ *   3xl → 2xl
+ *   2xs → xs
+ *
+ * Background overlay:
+ *   bg-overlay-default → bg-neutral-strong/50
+ *   bg-overlay-strong  → bg-neutral-strong/80
+ *
+ * Pill — JSX prop migration (scoped to <Pill> imported from @staffbase/design):
+ *   variant="blue"   → color="primary"
+ *   variant="green"  → color="success"
+ *   variant="grey"   → color="neutral"
+ *   variant="red"    → color="critical"
+ *   variant="yellow" → color="warning"
+ *
+ * PillGroup — replaced with a plain div:
+ *   <PillGroup> → <div className="flex flex-wrap gap-1">
+ *
+ * TextArea — renamed to the deprecated export:
+ *   TextArea      → TextAreaDeprecated
+ *   TextAreaProps → TextAreaDeprecatedProps
+ *
+ * Tooltip — swapped with the new implementation:
+ *   Tooltip    → TooltipDeprecated
+ *   TooltipNew → Tooltip
+ *
+ * PillProps — replaced with an inlined type query:
+ *   PillProps → React.ComponentProps<typeof Pill>
+ *
+ * Usage:
+ *   npx jscodeshift@latest \
+ *     --transform node_modules/@staffbase/design/codemods/v17-migrate-tokens/transform.js \
+ *     --extensions tsx,ts,jsx,js \
+ *     --parser tsx \
+ *     src/
+ */
+
+// ── Token mappings ────────────────────────────────────────────────────────────
+
+const ROUNDED_SIZES = {4: 'sm', 6: 'md', 8: 'lg', 16: 'xl'};
+
+// All Tailwind border-radius positional prefixes. Empty string = no prefix (e.g. rounded-4).
+const ROUNDED_PREFIXES = [
+  '',
+  't-',
+  'b-',
+  'l-',
+  'r-',
+  'tl-',
+  'tr-',
+  'bl-',
+  'br-',
+  's-',
+  'e-',
+  'ss-',
+  'se-',
+  'es-',
+  'ee-',
+];
+
+const TEXT_SIZES = {
+  12: 'xs',
+  14: 'sm',
+  16: 'md',
+  18: 'lg',
+  20: 'xl',
+  24: '2xl',
+  28: '3xl',
+  32: '4xl',
+  36: '5xl',
+};
+
+const DIRECT_RENAMES = [
+  ['font-regular', 'font-normal'],
+  ['tracking-default', 'tracking-normal'],
+  ['bg-overlay-default', 'bg-neutral-strong/50'],
+  ['bg-overlay-strong', 'bg-neutral-strong/80'],
+];
+
+// Breakpoint prefixes only — matched with a lookahead for `:` to avoid touching
+// size suffixes like `text-3xl` or `rounded-2xl`.
+const BREAKPOINT_RENAMES = [
+  ['3xl', '2xl'],
+  ['2xs', 'xs'],
+];
+
+const DESIGN_PKG = '@staffbase/design';
+
+const PILL_GROUP_CLASSES = 'flex flex-wrap gap-1';
+
+const TEXT_AREA_RENAMES = new Map([
+  ['TextArea', 'TextAreaDeprecated'],
+  ['TextAreaProps', 'TextAreaDeprecatedProps'],
+]);
+
+const TOOLTIP_RENAMES = new Map([
+  ['Tooltip', 'TooltipDeprecated'],
+  ['TooltipNew', 'Tooltip'],
+]);
+
+// Pill: old variant color values → new color prop values.
+// variant="outline" | "solid" are left untouched (they already use the new API).
+const PILL_COLOR_MAP = {
+  blue: 'primary',
+  green: 'success',
+  grey: 'neutral',
+  red: 'critical',
+  yellow: 'warning',
+};
+
+// ── Pre-build replacement list ────────────────────────────────────────────────
+
+/** @type {Array<[RegExp, string]>} */
+const REPLACEMENTS = [];
+
+for (const [size, name] of Object.entries(ROUNDED_SIZES)) {
+  for (const prefix of ROUNDED_PREFIXES) {
+    REPLACEMENTS.push([new RegExp(`\\brounded-${prefix}${size}\\b`, 'g'), `rounded-${prefix}${name}`]);
+  }
+}
+
+for (const [size, name] of Object.entries(TEXT_SIZES)) {
+  REPLACEMENTS.push([new RegExp(`\\btext-${size}\\b`, 'g'), `text-${name}`]);
+}
+
+for (const [from, to] of DIRECT_RENAMES) {
+  REPLACEMENTS.push([new RegExp(`\\b${from}\\b`, 'g'), to]);
+}
+
+// Breakpoints: match only when used as a responsive prefix (followed by `:`),
+// not when part of a size utility (e.g. text-3xl, rounded-2xl).
+for (const [from, to] of BREAKPOINT_RENAMES) {
+  REPLACEMENTS.push([new RegExp(`\\b${from}(?=:)`, 'g'), to]);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function replaceTokens(str) {
+  let result = str;
+  for (const [pattern, replacement] of REPLACEMENTS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+// ── Pill migration ────────────────────────────────────────────────────────────
+
+function migratePills(j, root) {
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return false;
+
+  let pillLocalName = null;
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (spec.node.imported.name === 'Pill') {
+      pillLocalName = spec.node.local ? spec.node.local.name : 'Pill';
+    }
+  });
+  if (!pillLocalName) return false;
+
+  let dirty = false;
+  root.find(j.JSXElement, {openingElement: {name: {name: pillLocalName}}}).forEach((path) => {
+    const attrs = path.node.openingElement.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const attr = attrs[i];
+      if (attr.type !== 'JSXAttribute' || attr.name.name !== 'variant') continue;
+      if (!attr.value || attr.value.type !== 'StringLiteral') continue;
+
+      const newColor = PILL_COLOR_MAP[attr.value.value];
+      if (!newColor) continue; // variant="outline" | "solid" — already new API, skip
+
+      attrs[i] = j.jsxAttribute(j.jsxIdentifier('color'), j.stringLiteral(newColor));
+      dirty = true;
+    }
+  });
+
+  return dirty;
+}
+
+// ── PillGroup migration ───────────────────────────────────────────────────────────
+
+function migratePillGroups(j, root) {
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return false;
+
+  let localName = null;
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (spec.node.imported.name === 'PillGroup') {
+      localName = spec.node.local ? spec.node.local.name : 'PillGroup';
+    }
+  });
+  if (!localName) return false;
+
+  let dirty = false;
+  root.find(j.JSXElement, {openingElement: {name: {name: localName}}}).forEach((path) => {
+    const {openingElement, closingElement} = path.node;
+
+    // Merge base classes with any existing static className.
+    const existingClassAttr = openingElement.attributes.find(
+      (attr) => attr.type === 'JSXAttribute' && attr.name.name === 'className',
+    );
+    let mergedClass = PILL_GROUP_CLASSES;
+    if (existingClassAttr?.value?.type === 'StringLiteral') {
+      mergedClass = `${PILL_GROUP_CLASSES} ${existingClassAttr.value.value}`;
+    }
+
+    // Build new attrs: className first, then all other existing attrs (minus old className).
+    const otherAttrs = openingElement.attributes.filter(
+      (attr) => !(attr.type === 'JSXAttribute' && attr.name.name === 'className'),
+    );
+    openingElement.name = j.jsxIdentifier('div');
+    openingElement.attributes = [
+      j.jsxAttribute(j.jsxIdentifier('className'), j.stringLiteral(mergedClass)),
+      ...otherAttrs,
+    ];
+    if (closingElement) closingElement.name = j.jsxIdentifier('div');
+
+    dirty = true;
+  });
+
+  if (!dirty) return false;
+
+  // Remove PillGroup import specifier.
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (spec.node.imported.name === 'PillGroup') j(spec).remove();
+  });
+
+  return true;
+}
+
+// ── TextArea migration ───────────────────────────────────────────────────────────
+
+function migrateTextArea(j, root) {
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return false;
+
+  // Collect local → new name mappings for non-aliased imports.
+  const localRenames = new Map();
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    const importedName = spec.node.imported.name;
+    const newImportedName = TEXT_AREA_RENAMES.get(importedName);
+    if (!newImportedName) return;
+
+    const localName = spec.node.local.name;
+    spec.node.imported = j.identifier(newImportedName);
+
+    // When no alias, local name equals imported name — rename local usages too.
+    if (localName === importedName) {
+      spec.node.local = j.identifier(newImportedName);
+      localRenames.set(localName, newImportedName);
+    }
+  });
+
+  if (!localRenames.size) return false;
+
+  localRenames.forEach((newName, oldName) => {
+    root.find(j.Identifier, {name: oldName}).forEach((path) => {
+      const parent = path.parent.node;
+      if (parent.type === 'ImportSpecifier') return; // already handled above
+      // Skip property accesses (foo.TextArea) and non-computed object keys.
+      if (parent.type === 'MemberExpression' && parent.property === path.node && !parent.computed) return;
+      if (parent.type === 'ObjectProperty' && parent.key === path.node && !parent.computed) return;
+      path.node.name = newName;
+    });
+  });
+
+  return true;
+}
+
+// ── Tooltip migration ────────────────────────────────────────────────────────────
+
+function migrateTooltip(j, root) {
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return false;
+
+  // Collect all renames first, then apply — avoids conflicts when both
+  // Tooltip and TooltipNew are imported in the same file.
+  const localRenames = new Map();
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    const importedName = spec.node.imported.name;
+    const newImportedName = TOOLTIP_RENAMES.get(importedName);
+    if (!newImportedName) return;
+
+    const localName = spec.node.local.name;
+    spec.node.imported = j.identifier(newImportedName);
+
+    if (localName === importedName) {
+      spec.node.local = j.identifier(newImportedName);
+      localRenames.set(localName, newImportedName);
+    }
+  });
+
+  if (!localRenames.size) return false;
+
+  localRenames.forEach((newName, oldName) => {
+    root.find(j.Identifier, {name: oldName}).forEach((path) => {
+      const parent = path.parent.node;
+      if (parent.type === 'ImportSpecifier') return;
+      if (parent.type === 'MemberExpression' && parent.property === path.node && !parent.computed) return;
+      if (parent.type === 'ObjectProperty' && parent.key === path.node && !parent.computed) return;
+      path.node.name = newName;
+    });
+  });
+
+  return true;
+}
+
+// ── PillProps migration ───────────────────────────────────────────────────────────
+
+function migratePillProps(j, root) {
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return false;
+
+  let pillPropsLocalName = null;
+  let pillLocalName = null;
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (spec.node.imported.name === 'PillProps') pillPropsLocalName = spec.node.local.name;
+    if (spec.node.imported.name === 'Pill') pillLocalName = spec.node.local.name;
+  });
+
+  if (!pillPropsLocalName) return false;
+
+  // `typeof Pill` requires Pill to be imported as a value. Add it if missing.
+  if (!pillLocalName) {
+    pillLocalName = 'Pill';
+    designImports.get().node.specifiers.push(j.importSpecifier(j.identifier('Pill')));
+  }
+
+  const buildReplacementType = (localPillName) =>
+    j.tsTypeReference(
+      j.tsQualifiedName(j.identifier('React'), j.identifier('ComponentProps')),
+      j.tsTypeParameterInstantiation([j.tsTypeQuery(j.identifier(localPillName))]),
+    );
+
+  // Replace all TSTypeReference nodes that use the old local name.
+  let dirty = false;
+  root.find(j.TSTypeReference).forEach((path) => {
+    const {typeName} = path.node;
+    if (typeName.type === 'Identifier' && typeName.name === pillPropsLocalName) {
+      j(path).replaceWith(buildReplacementType(pillLocalName));
+      dirty = true;
+    }
+  });
+
+  if (!dirty) return false;
+
+  // Remove the PillProps import specifier.
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (spec.node.imported.name === 'PillProps') j(spec).remove();
+  });
+
+  return true;
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export default function transform(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let dirty = false;
+
+  // Replace within all string literals (className props, clsx/cn args, constants, etc.).
+  root.find(j.StringLiteral).forEach((path) => {
+    const next = replaceTokens(path.node.value);
+    if (next !== path.node.value) {
+      path.node.value = next;
+      dirty = true;
+    }
+  });
+
+  // Replace within the static parts of template literals.
+  root.find(j.TemplateElement).forEach((path) => {
+    const {raw, cooked} = path.node.value;
+    const nextRaw = replaceTokens(raw);
+    if (nextRaw !== raw) {
+      path.node.value = {
+        raw: nextRaw,
+        cooked: cooked != null ? replaceTokens(cooked) : cooked,
+      };
+      dirty = true;
+    }
+  });
+
+  // Migrate <Pill variant="color"> → <Pill color="newColor">.
+  if (migratePills(j, root)) dirty = true;
+
+  // Migrate <PillGroup> → <div className="flex flex-wrap gap-1">.
+  if (migratePillGroups(j, root)) dirty = true;
+
+  // Rename TextArea → TextAreaDeprecated and TextAreaProps → TextAreaDeprecatedProps.
+  if (migrateTextArea(j, root)) dirty = true;
+
+  // Rename Tooltip → TooltipDeprecated and TooltipNew → Tooltip.
+  if (migrateTooltip(j, root)) dirty = true;
+
+  // Replace PillProps with React.ComponentProps<typeof Pill>.
+  if (migratePillProps(j, root)) dirty = true;
+
+  return dirty ? root.toSource({quote: 'single'}) : undefined;
+}

package/codemods/v19-migrate-button/README.md

@@ -0,0 +1,94 @@
+# v19 — Migrate to the new Button
+
+This codemod automatically migrates your code from the four deprecated button components in `@staffbase/design` v18 to the new unified `Button` in v19.
+
+## What it transforms
+
+| Before (v18)                        | After (v19)                                       |
+| ----------------------------------- | ------------------------------------------------- |
+| `<Button variant="primary">`        | `<Button>`                                        |
+| `<Button variant="secondary">`      | `<Button color="neutral">`                        |
+| `<Button variant="critical">`       | `<Button color="critical">`                       |
+| `<GhostButton variant="primary">`   | `<Button variant="ghost">`                        |
+| `<GhostButton variant="secondary">` | `<Button variant="ghost" color="neutral">`        |
+| `<IconButton icon={<X />} />`       | `<Button iconOnly><X /></Button>`                 |
+| `<IconGhostButton icon={<X />} />`  | `<Button variant="ghost" iconOnly><X /></Button>` |
+| `<ButtonDeprecated …>`              | `<Button …>`                                      |
+
+**Icon props are moved into children:**
+
+```tsx
+// Before
+<Button icon={<SaveIcon />} iconPosition="leading">Save</Button>
+
+// After
+<Button><SaveIcon />Save</Button>
+```
+
+```tsx
+// Before
+<GhostButton icon={<ShareIcon />} iconPosition="trailing">Share</GhostButton>
+
+// After
+<Button variant="ghost">Share<ShareIcon /></Button>
+```
+
+**Imports are updated automatically:**
+
+```tsx
+// Before
+import {Button, GhostButton, IconButton, IconGhostButton} from '@staffbase/design';
+
+// After
+import {Button} from '@staffbase/design';
+```
+
+## Usage
+
+### Step 1 — Install jscodeshift
+
+```bash
+npm install --save-dev jscodeshift
+# or
+pnpm add -D jscodeshift
+```
+
+### Step 2 — Run the codemod
+
+Point the `--transform` flag at this file inside your `node_modules`:
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v19-migrate-button/transform.js \
+  --extensions tsx,ts \
+  --parser tsx \
+  src/
+```
+
+Run a **dry run** first to preview changes without writing files:
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v19-migrate-button/transform.js \
+  --extensions tsx,ts \
+  --parser tsx \
+  --dry \
+  --print \
+  src/
+```
+
+### Step 3 — Review and commit
+
+1. Run your type-checker to catch anything the codemod couldn't handle statically:
+   ```bash
+   npx tsc --noEmit
+   ```
+2. Run your tests.
+3. Commit the result.
+
+## What the codemod does NOT handle
+
+- **Dynamic `variant` expressions** — e.g. `variant={someVariable}`. The original `variant` prop is preserved so TypeScript will surface a type error at that location. Update these manually.
+- **Spread props** — e.g. `<Button {...buttonProps} />`. The spread is preserved; if `buttonProps` contains old-style variant/icon fields those object shapes need updating manually.
+- **Type annotations** — `ButtonDeprecatedProps`, `GhostButtonProps`, etc. are removed from imports. If you use these types in your own interfaces or function signatures, TypeScript errors will point you to the right places.
+- **Non-JSX prop passing** — e.g. `React.createElement(Button, {variant: 'secondary'})`. Only JSX syntax is transformed.