@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 5.0.0-alpha.0

package/MIGRATION-5.0.md

@@ -0,0 +1,155 @@
+# Migrating to logician-ui 5.0 (BAZE palette)
+
+5.0 replaces the golden-ratio palette (blue primary, violet secondary, cool slate
+gray) with the BAZE colour system: warm black primary, beige-brown secondary, a
+coral action colour, and 12 system hues for status and categories. Tokens and
+component variants are redesigned together.
+
+**Most app code keeps working.** Every 4.x _semantic_ colour name still
+resolves (as a deprecated alias, removed in 6.0), so the ~5,300 semantic
+references in factchat-nextjs change colour without a code change. Two things do break:
+components whose variant props changed, and raw primitives (`blue.500`,
+`gray.300` …) read directly.
+
+## 1. Run the codemod
+
+```sh
+npx jscodeshift -t node_modules/@mindlogic-ai/logician-ui/codemods/5.0/index.js \
+  --parser=tsx --extensions=tsx,ts src/
+# or, with a summary table of what needs a human:
+node node_modules/@mindlogic-ai/logician-ui/codemods/5.0/index.js --dry src/
+```
+
+It rewrites Button / IconButton / Badge / Tag / Chip / Card props (section 3) and
+renames every deprecated token string (section 2), then prints the call sites
+it could not migrate: dynamic props (`variant={x}`), spreads, raw `blue.N`-style
+primitives, and combinations that need judgement. Details and per-transform
+runs: [`codemods/5.0/README.md`](codemods/5.0/README.md). Run Prettier afterwards.
+
+## 2. Tokens
+
+### Lint
+
+```js
+// eslint.config.js (flat)
+const logician = require('@mindlogic-ai/logician-ui/eslint');
+module.exports = [logician.configs.recommended]; // logician/no-deprecated-tokens: warn
+```
+
+ESLint 8 `.eslintrc`: `eslint --rulesdir node_modules/@mindlogic-ai/logician-ui/eslint/rules …`
+with `rules: { 'no-deprecated-tokens': 'warn' }`. The rule names the replacement
+for each deprecated alias and flags removed raw primitives.
+Rule and codemod match the dotted name (`'primary.lighter'`), Chakra's token
+reference form with its `colors.` prefix (`'{colors.success.main}'`,
+`token('colors.success.main')`, kept in the output), and the CSS variable in
+the kebab-case form Chakra emits (`var(--chakra-colors-primary-fill-strong)` →
+`var(--chakra-colors-primary-hover)`; `primary.washActive` is
+`--chakra-colors-primary-wash-active`, never `…-washActive`).
+
+### Mapping (deprecated alias → 5.0)
+
+| 4.x                                                                                                                                | 5.0                                                                                                                                                                                                                                                                          |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `primary.lightest`, `primary.extralight`                                                                                           | `primary.wash` — review: a tinted surface becomes neutral gray                                                                                                                                                                                                               |
+| `primary.lighter`                                                                                                                  | `primary.washActive`                                                                                                                                                                                                                                                         |
+| `primary.light`                                                                                                                    | `border.strong`                                                                                                                                                                                                                                                              |
+| `primary.dark`, `primary.darker`                                                                                                   | `fg.default`                                                                                                                                                                                                                                                                 |
+| `primary.fill`, `primary.fillStrong`                                                                                               | `primary.main`, `primary.hover` — review: blue bands become black; move announcement bands to `Modal headerTone="brand"` / `bg.muted` + `secondary.border` by hand                                                                                                           |
+| `secondary.lightest` · `extralight` · `lighter` · `light` · `main` · `dark`/`darker`                                               | `secondary.1` · `secondary.surface` · `secondary.surfaceStrong` · `secondary.border` · `secondary.fg` · `secondary.fgStrong` — review: `secondary.surface*` is tint-only, **not a background**; a `bg` of `extralight`/`lighter` → `bg.muted` (page-level band: `bg.subtle`) |
+| `{danger,success,warning}.lightest`/`extralight` · `lighter`/`light` · `main` · `dark`/`darker`                                    | `.bg` · `.border` · `.solid` · `.fg`                                                                                                                                                                                                                                         |
+| `warning.fill`                                                                                                                     | `warning.solid`                                                                                                                                                                                                                                                              |
+| `bg.selected`                                                                                                                      | `primary.selected`                                                                                                                                                                                                                                                           |
+| `fg.accent`                                                                                                                        | `primary.main` (links: `fg.link`)                                                                                                                                                                                                                                            |
+| `slate.0`/`50` · `100` · `200` · `300` · `400` · `500`/`600` · `700` · `800`/`900` · `1000`/`1100` · `1200`/`1300` · `1400`/`1500` | `neutral.1` · `2` · `3` · `5` · `6` · `7` · `8` · `9` · `10` · `11` · `12`                                                                                                                                                                                                   |
+
+Unchanged names with new values: `primary.main`, `bg.*` (`canvas`, `surface`,
+`subtle`, `muted`, `sunken`, `track`, `raised`, `inverse`, `panel`), `fg.default`
+/ `muted` / `subtle` / `emphasized` / `inverse`, `border.subtle` / `default` /
+`strong`, `bg.invalid.subtle`, `bg.highlighted`.
+
+### Removed raw primitives
+
+`blue`, `violet`, `rose`, `gold`, `green` (numeric steps), the golden-ratio
+`gray` 0–1500 and `grayDark`, and the legacy `purple` / `red` / `yellow` steps.
+A leftover `blue.500` does not error — it falls through to Chakra's default
+palette — so let the lint rule find them. `gray.N` → `neutral.N` per the slate
+row above; for the rest pick the role by use (`primary.*`, a status family,
+`category.*`).
+
+### New tokens
+
+`layer.1–3` (+`.hover`/`.active`), `border.control`, `fg.icon`,
+`fg.placeholder`, `fg.onPrimary`, `fg.link`/`fg.linkHover`,
+`primary.{hover,active,wash,washActive,selected}`,
+`secondary.{surface,surfaceStrong,border,fg,fgStrong}`, `action.*`, `send.*`,
+`count.*`, `disabled.*`, `focus.ring`, `info.*`, status
+`{bg,border,fg,solid,onSolid}` (+`danger.solidHover/solidActive`), `tooltip.*`,
+`category.{hue}.{surface,fg}`, `neutral.1–12`, `secondary.1–12`. High-contrast
+values apply under `prefers-contrast: more`.
+
+### Theme options
+
+```tsx
+<LogicianProvider />                          // BAZE: neutral ink, secondary sand
+<LogicianProvider theme={{ neutral: 'slate' }} /> // cool gray (4.x temperature)
+createSystem(defaultConfig, createLogicianTheme({ neutral: 'slate' }))
+```
+
+### Overriding roles from your app
+
+Every Logician role is emitted as `{ _light, _dark }`, and Chakra's `_light`
+outranks `base`. A 4.x-style override `primary.main: { value: { base: X,
+_dark: Y } }` would therefore keep the library's light value. `LogicianProvider
+config={…}` fixes this for you (`normalizeSemanticOverrides`); if you call
+`createSystem` yourself, wrap your config: `createSystem(defaultConfig,
+createLogicianTheme(), normalizeSemanticOverrides(appConfig))`.
+
+`secondary.main` aliases `secondary.fg`, which clears 4.5:1 on `bg.canvas` but
+not on `layer.1` / `bg.muted` (≈4.2:1 in light). Text on those surfaces should
+use `secondary.fgStrong` or `fg.muted`.
+
+## 3. Components
+
+| Component                      | 4.x                                                                                                     | 5.0                                                                                                                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Button**                     | `colorPalette` × `variant` (solid/outline/ghost/soft); default rendered `soft` while documented `solid` | `variant`: `primary` · `action` · `secondary` · `subtle` (default) · `ghost` · `danger`; `isDestructive` for danger text on secondary/subtle/ghost. `colorPalette` removed from the types |
+| **IconButton**                 | same grid, default neutral ghost                                                                        | `variant`: `ghost` (default) · `secondary` · `primary` · `danger` · `action` (coral send); `isDestructive`                                                                                |
+| **Badge**                      | 6 variants, default `primary`                                                                           | `neutral` (default, `bg.muted` + `secondary.fgStrong`) · `success` · `warning` · `danger` · `info`; `primary`/`secondary` removed                                                         |
+| **CountBadge**                 | — (app's UnreadCountBadge)                                                                              | new: `count`, `max` (99+), `dot`, `showZero`, `label`                                                                                                                                     |
+| **Tag**                        | `colorPalette` × `variant`                                                                              | `tone` (`neutral` default · `success` · `warning` · `danger` · `info`), `selected`, `category` (12 hues), `icon`                                                                          |
+| **Chip**                       | separate component                                                                                      | deprecated alias of Tag (removed in 6.0) — `<Chip>` → `<Tag>`; the codemod keeps its pill shape (`borderRadius="xl" px={3} py={2} fontWeight="medium"`)                                   |
+| **Card**                       | `gradient` variant                                                                                      | removed; `wash` = `bg.muted` (neutral, borderless)                                                                                                                                        |
+| **Modal**                      | —                                                                                                       | `headerTone="brand"` (`layer.3` band + `secondary.border` rule), `ModalHeader subtitle`                                                                                                   |
+| **Banner**                     | info/success/warning/danger                                                                             | + `neutral`; 1px border + 3px left bar; `info` uses `info.*` (was primary)                                                                                                                |
+| **Toast**                      | default `success`                                                                                       | + `neutral` (now the default); `info` uses `info.*`                                                                                                                                       |
+| **PageLoader / SectionLoader** | —                                                                                                       | `variant="thinking"` (coral dots); both now `role="status"`                                                                                                                               |
+| **Link**                       | `primary.main`, no underline                                                                            | `fg.link` + underline (1px, hover 2px), weight 500                                                                                                                                        |
+| **Avatar**                     | untinted fallback                                                                                       | fallback tinted by `category.*` from a name hash; `colorHue` override                                                                                                                     |
+| **Typography**                 | some `primary.*` emphasis colours                                                                       | `fg.*` only                                                                                                                                                                               |
+| **focusRing util**             | white inner band                                                                                        | `bg.canvas` inner band                                                                                                                                                                    |
+| **Disabled**                   | `opacity: 0.5`                                                                                          | fixed `disabled.bg` / `disabled.fg`                                                                                                                                                       |
+
+Untyped / `as any` callers passing the old Button/IconButton/Badge/Tag/Chip props
+still render — they are mapped at runtime with a one-time development warning —
+but the types no longer accept them.
+
+Kept as `@deprecated` exports: `ButtonColorPalette`, `buttonColorPalettes`,
+`buttonColorPaletteStyles`, `IconButtonColorPalette`, `iconButtonColorPalettes`,
+`iconButtonColorPaletteStyles` (+ the `*ColorScheme*` aliases), `Chip`,
+`ChipProps`, `ChipOwnProps`, `LegacyBadgeVariant`. Removed: `tagColorPalettes`,
+`tagColorPaletteStyles`, `tagColorSchemes`, `tagColorSchemeStyles`,
+`tagVariants`, Chip's `colorSchemes` / `colorSchemeStyles` / `getChipStyles` /
+`variants`. Changed signatures: `getButtonStyles(variant, isDestructive)`,
+`getIconButtonStyles(variant, isDestructive)`, `getTagStyles({ tone, selected,
+category, interactive })`. `LINK_RAMP` entries are plain token strings now.
+
+## 4. After the codemod — what a human checks
+
+- Call sites the codemod reported (dynamic props, spreads, raw primitives).
+- `primary.lightest`/`extralight` used as a _coloured_ surface — now gray.
+- `primary.fill` bands (modal/notice headers) — now black; use
+  `Modal headerTone="brand"`, or `bg.muted` with a `secondary.border` edge.
+  Not `secondary.surface`/`surfaceStrong` — the sand tint is accent-only and
+  reads peach as a background.
+- The app theme override (`src/theme/index.ts` in factchat-nextjs): delete
+  overrides that duplicate the new defaults.

package/USAGE.md

@@ -78,7 +78,7 @@ function Dashboard() {
           <GridItem>
             <Card>
               <Typography variant="h3">Total Users</Typography>
-              <Typography variant="h1" color="blue.500">
+              <Typography variant="h1" color="fg.link">
                 1,234
               </Typography>
               <Badge variant="success">+12%</Badge>
@@ -297,3 +297,20 @@ function App() {
   Responsive Button
 </Button>
 ```
+
+### 5. Actions in Feedback Surfaces
+
+- A toast takes at most one action, through the `action` prop; dismiss is the ×
+- Never put a `<Button>` inside a toast's `description`
+- Inside a tinted toast or banner, the action uses the status color
+- Panes and dialogs carry buttons: ink solid primary + outline neutral
+
+Full rules and the surface matrix: Storybook → **Guidelines / Actions in feedback surfaces** (`src/guidelines/FeedbackActions.mdx`).
+
+```tsx
+showToast({
+  status: 'error',
+  description: '크레딧이 부족합니다.',
+  action: { label: '크레딧 구매', onClick: openCreditPurchaseModal },
+});
+```

package/codemods/5.0/README.md

@@ -0,0 +1,244 @@
+# logician-ui 5.0 codemod
+
+jscodeshift transforms that move an app from logician-ui 4.x to 5.0. They
+cover the static half of the migration: the 4.x `colorPalette × variant` grids
+on Button, IconButton, Badge, Tag and Chip, `Card variant="gradient"`, and the
+renamed colour tokens. Anything they cannot decide on their own is left in place
+and listed in a report.
+
+Plain CommonJS with no build step. jscodeshift 17 loads the files as they are.
+
+## Run everything
+
+```sh
+# preview: changes nothing, prints the diff of each file and the report
+npx jscodeshift -t node_modules/@mindlogic-ai/logician-ui/codemods/5.0/index.js \
+  --parser=tsx --extensions=tsx,ts --dry --print src/
+
+# apply
+npx jscodeshift -t node_modules/@mindlogic-ai/logician-ui/codemods/5.0/index.js \
+  --parser=tsx --extensions=tsx,ts src/
+```
+
+After applying, run Prettier, then `tsc` and the logician-ui ESLint rule
+(`logician-ui/no-deprecated-tokens`). Read every `TODO(logician-ui 5.0)` comment
+and every report line.
+
+### Runner with a summary table
+
+jscodeshift prints one `REP` line per site. It has no end-of-run hook, so it
+cannot print a combined table itself. With `--dry` it does print per-kind counts
+under `Stats:`. For the full table, run `index.js` with node. This needs
+`jscodeshift` installed in the app (`npm i -D jscodeshift`):
+
+```sh
+node node_modules/@mindlogic-ai/logician-ui/codemods/5.0/index.js --dry src/   # preview
+node node_modules/@mindlogic-ai/logician-ui/codemods/5.0/index.js src/         # apply
+#   --print            print transformed files (with --dry)
+#   --only=a,b         run only these transforms
+#   --cpus=N           worker count (default: all cores)
+#   --extensions=tsx,ts  (default tsx,ts,jsx,js; node_modules and *.d.ts are ignored)
+```
+
+The runner exits with code 0 even when some sites need a person, because the
+report is the expected output. Exit code 1 means a crash.
+
+## Run one transform
+
+| transform         | file                 | what it does                                                                                                 |
+| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `button-variants` | `button-variants.js` | `<Button>` / `<IconButton>`: `colorPalette`(or `colorScheme`) × `variant` → role `variant` + `isDestructive` |
+| `badge-variants`  | `badge-variants.js`  | `<Badge variant="primary\|secondary\|neutral">` → no variant (neutral). success/warning/danger/info stay     |
+| `tag-chip`        | `tag-chip.js`        | `<Chip>` → `<Tag>` (import fixed/merged) and the Tag colour grid → `tone` / `selected`                       |
+| `card-gradient`   | `card-gradient.js`   | `<Card variant="gradient">` → variant removed + TODO                                                         |
+| `token-renames`   | `token-renames.js`   | deprecated 4.x token names in strings → 5.0 names                                                            |
+
+```sh
+npx jscodeshift -t node_modules/@mindlogic-ai/logician-ui/codemods/5.0/token-renames.js \
+  --parser=tsx --extensions=tsx,ts src/
+# or: … /index.js --only=button-variants,tag-chip …
+```
+
+Only elements imported from `@mindlogic-ai/logician-ui` are touched, including
+aliases (`import { Button as LButton }`) and namespace imports
+(`<LUI.Button>`). Another library's `Button` or `Tag` is left alone.
+
+## Mappings
+
+"—" means the prop is absent. The Button and Tag/Chip mappings are the same
+tables as the runtime back-compat in `src/components/Button/Button.legacy.ts`
+and `mapLegacyTagProps` (`src/components/Tag/Tag.styles.ts`), so a call site
+looks the same whether or not the codemod has run on it. A parity test in
+`codemods.test.ts` runs both over the whole palette × variant grid. Every pair
+the runtime warns about as having no exact 5.0 equivalent also gets a **TODO**.
+
+**Button** (4.x default variant was `soft`)
+
+| colorPalette / variant                       | 5.0                                                                |
+| -------------------------------------------- | ------------------------------------------------------------------ |
+| primary · neutral · — / solid                | `variant="primary"`                                                |
+| danger / solid                               | `variant="danger"`                                                 |
+| neutral · — · primary · secondary / outline  | `variant="secondary"`                                              |
+| danger / outline                             | `variant="secondary" isDestructive`                                |
+| neutral · — · primary / ghost                | `variant="ghost"`                                                  |
+| danger / ghost                               | `variant="ghost" isDestructive`                                    |
+| primary · neutral · secondary · — / soft · — | `variant="subtle"` (written out even though it is the 5.0 default) |
+| danger / soft · —                            | `variant="subtle" isDestructive`                                   |
+| secondary · warning · success / solid        | `variant="primary"` + **TODO**                                     |
+| unknown variant (`link`, `plain`, …)         | `variant="subtle"` (+ `isDestructive` if danger) + **TODO**        |
+| other off-table pairs (e.g. success/outline) | same as the runtime table + **TODO**                               |
+
+**IconButton** (4.x default was neutral ghost; 5.0 default is ghost)
+
+| colorPalette / variant                                                | 5.0                             |
+| --------------------------------------------------------------------- | ------------------------------- |
+| — · neutral · primary · warning / ghost · —, neutral · primary / soft | no `variant` (ghost)            |
+| neutral · — / outline                                                 | `variant="secondary"`           |
+| primary · neutral · — / solid                                         | `variant="primary"`             |
+| danger / solid                                                        | `variant="danger"`              |
+| danger / ghost · soft · —                                             | `isDestructive` (ghost)         |
+| anything else                                                         | runtime-table result + **TODO** |
+
+`colorPalette` and `colorScheme` are always removed. Elements that already
+use a 5.0 role variant with no colour prop are left unchanged, so running the
+codemod twice is safe.
+
+**Tag / Chip** (Chip 4.x default was primary/soft; Tag 4.x default was neutral/soft)
+
+| colour / variant                                       | 5.0                                               |
+| ------------------------------------------------------ | ------------------------------------------------- |
+| primary · secondary · neutral · — / soft · — · outline | plain `<Tag>`                                     |
+| danger · success · warning / soft · —                  | `tone="danger"` etc.                              |
+| primary · secondary · neutral · — / solid              | `selected` (reported as `selected`, see below)    |
+| danger · success · warning / solid                     | `tone="…"` + **TODO** (5.0 Tag has no fill)       |
+| danger · success · warning / outline                   | plain `<Tag>` + **TODO** (5.0 Tag has no outline) |
+| unknown colour or variant                              | plain `<Tag>` + **TODO**                          |
+
+The colour is what the runtime reads: on a Chip `colorScheme ?? colorPalette`
+(then the primary default), on a Tag `colorPalette` only. A `colorScheme` on a
+Tag was never read, so it is removed with a **TODO**. An explicit `tone` or
+`selected` already on the element wins over the mapping.
+
+Unmigrated, a solid pair gets the selected _look_ only. The explicit `selected`
+prop the codemod writes also makes the tag a toggle (hover border, pointer,
+`aria-pressed` on `as="button"`) — Tag has no public prop for the look without
+that — so every such site is listed under `selected` in the report.
+
+A converted `<Chip>` keeps Chip's pill shape, which the deprecated `Chip` alias
+renders and a plain `<Tag>` does not (Tag is `md` radius, semibold):
+`borderRadius="xl"` (the 32px token Chip uses) `px={3} py={2}
+fontWeight="medium"`, placed first so a spread or a later prop still wins. A
+prop the call site already sets is kept (`rounded` counts as `borderRadius`;
+`p`/`padding` count as both paddings). Drop them by hand if the screen should
+take the 5.0 Tag shape.
+
+For Chip, the import specifier becomes `Tag`. If the file already imports
+`Tag`, the two imports are merged and `TagLabel` and the rest are kept. If
+`Tag` is already bound to something else in the file, the codemod imports
+`Tag as LuiTag`.
+
+**Tokens.** The map comes from `src/theme/deprecatedColorTokens.json`, the same
+file the theme aliases and the ESLint rule use. Matching uses whole tokens only,
+with the rule's boundaries: `primary.light` does not match inside
+`primary.lighter`, `foo.primary.light` or `theme.colors.primary.light`, and
+`slate.100` does not match inside `slate.1000`. The one prefix allowed is
+Chakra's own token reference, `colors.`, when it starts the string or follows
+`{`, a quote or `token(`: `'{colors.success.main}'`,
+`'color-mix(in oklab, {colors.warning.fill} 70%, black)'`,
+`token('colors.danger.main')` and a plain `'colors.primary.light'` are renamed
+with the prefix kept (`{colors.success.solid}`); `{colors.grayDark.200}` is
+reported as a primitive. The transform rewrites string literals, JSX string
+attributes and template-literal parts, in dotted form (`slate.300` →
+`neutral.5`) and CSS-var form (`--chakra-colors-slate-300` →
+`--chakra-colors-neutral-5`). CSS variable names are matched and written the
+way Chakra emits them, kebab-case: `var(--chakra-colors-primary-fill-strong)`
+→ `var(--chakra-colors-primary-hover)`, `var(--chakra-colors-primary-lighter)`
+→ `var(--chakra-colors-primary-wash-active)` (never `…-washActive`, which
+names no variable), `--chakra-colors-gray-dark-200` is a `grayDark` primitive. `gray.N` → `neutral.N`. `fg.accent` →
+`primary.main`, except on the `color` attribute of a `<Link>` or `<a>`, where
+it becomes `fg.link`.
+
+## Reading the report
+
+Each site appears as:
+
+```
+ REP src/foo.tsx [button-variants] L42 <Button> variant — dynamic (not migrated): variant={kind}
+```
+
+The `node index.js` runner adds a table at the end:
+
+```
+── logician-ui 5.0 codemod summary ──
+
+Migrated automatically:
+  button-variants · elements migrated          6
+  tag-chip · Chip → Tag                        2
+  token-renames · tokens renamed               4
+
+Needs a human: 6 site(s)
+  button-variants · dynamic                    1
+  button-variants · spread                     1
+  button-variants · todo                       1
+  card-gradient · todo                         1
+  tag-chip · selected                          1
+  token-renames · primitive                    1
+
+location        component  prop                  kind       source
+--------------  ---------  --------------------  ---------  ------
+src/a.tsx:8     LButton    colorPalette+variant  todo       <LButton colorPalette="secondary" variant="solid">   ← … → variant="primary"
+src/a.tsx:9     LButton    variant               dynamic    variant={kind}   ← not migrated
+src/a.tsx:10    LButton    {...spread}           spread     {...p}   ← may carry colorPalette/variant — check by hand
+…
+```
+
+| kind        | meaning                                                                                                                                                                                         | what to do                                                                    |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `dynamic`   | the prop is an expression (`variant={x}`, `colorPalette={a ? 'danger' : 'primary'}`). The element is **left exactly as it was**                                                                 | Map the values by hand using the tables above. This is the "동적 호출부" list |
+| `spread`    | `{...props}` on the element may carry `colorPalette` or `variant`. The static props were still migrated                                                                                         | Check what the spread contains                                                |
+| `todo`      | converted so it compiles, but no exact 5.0 equivalent exists. A `/* TODO(logician-ui 5.0): … */` comment is on the element                                                                      | Choose a role with a designer, then delete the comment                        |
+| `selected`  | a solid Tag/Chip became `selected`, which also makes it interactive (hover border, pointer). The unmigrated tag only had the look                                                               | Keep it if the tag is a toggle; otherwise pick a tone or drop `selected`      |
+| `primitive` | raw `blue.N`, `violet.N`, `rose.N`, `gold.N`, `green.N`, `grayDark.N`, `purple.N`, `red.N`, `yellow.N`. These are **not renamed**, because the right 5.0 name depends on what the colour is for | Choose `primary.*`, `neutral.N`, a status family or `category.*`              |
+| `key`       | a deprecated token used as an object key or computed access (`{ 'slate.800': … }`, `colors['slate.800']`). Not renamed, because that would change what the key defines                          | Usually an app theme override. Delete it or rename it by hand                 |
+| `reference` | `Chip` used outside JSX (`styled(Chip)`). Renamed to `Tag`, but props passed there were not migrated and Chip's pill shape is not added                                                         | Check the props; add the shape if needed                                      |
+| `type`      | an import of `ChipProps` / `ChipVariant` / …                                                                                                                                                    | Switch to the `Tag*` types                                                    |
+
+The runner also writes the raw report as JSON lines (path printed at the end)
+so it can be filtered with `jq`.
+
+## What it does not do
+
+- It does not migrate dynamic values, spreads, or props passed through wrapper
+  components (`<MyButton colorPalette="danger">` where MyButton forwards to
+  Button). The report lists them.
+- It does not rename raw primitives other than `gray.N`, hard-coded hex values
+  (`#1F687E`), or tokens inside non-string code such as `colors.blue[500]` or
+  string concatenation (`'slate.' + n`).
+- It does not touch object keys, `.css`/`.scss` files or MDX. Run it on
+  `.tsx,.ts` (and `.jsx,.js` if you have them).
+- It does not treat `fg.accent` as a link outside a direct `color` attribute
+  on `<Link>` or `<a>`. Inside `_hover={{ color: 'fg.accent' }}` on a Link, or
+  on a component that renders a link, it becomes `primary.main`. Grep for
+  `primary.main` near links afterwards.
+- It does not format code. New attributes and TODO comments come out in
+  jscodeshift's layout, so run Prettier afterwards.
+- Under `index.js`, line numbers reported by later transforms refer to the
+  file after earlier transforms ran. TODO comments can shift lines by one or
+  two.
+- It is not meant to run on logician-ui's own `src/`. The library imports its
+  components by relative path, so only token renames would apply, and the
+  stories that show deprecated names on purpose would be rewritten.
+
+## Tests
+
+```sh
+npx vitest run --config codemods/vitest.config.ts
+```
+
+Fixtures are in `__testfixtures__/<transform>.input.tsx` / `.output.tsx`. For
+`tag-chip`, the `tag-chip-*.input.tsx` variants cover import merging and name
+conflicts. `index.*` runs every transform together. The test compares each
+pair, checks that each output is a fixed point (idempotent), asserts the
+report sites (dynamic, spread, todo, primitive, key, type, reference), checks
+every alias in the token map, and runs the `node index.js` runner end to end
+in `--dry` mode.

package/codemods/5.0/__testfixtures__/badge-variants.input.tsx

@@ -0,0 +1,20 @@
+import { Badge, Badge as Pill } from '@mindlogic-ai/logician-ui';
+
+export const Badges = ({ v, rest }: any) => (
+  <>
+    <Badge>—</Badge>
+    <Badge variant="neutral">neutral</Badge>
+    <Badge variant="primary">primary</Badge>
+    <Badge variant="secondary" mr={2}>
+      secondary
+    </Badge>
+    <Badge variant="success">success</Badge>
+    <Badge variant="warning">warning</Badge>
+    <Badge variant="danger">danger</Badge>
+    <Badge variant="info">info</Badge>
+    <Pill variant="primary">alias</Pill>
+    <Badge variant="purple">unknown</Badge>
+    <Badge variant={v}>dynamic</Badge>
+    <Badge {...rest}>spread</Badge>
+  </>
+);

package/codemods/5.0/__testfixtures__/badge-variants.output.tsx

@@ -0,0 +1,21 @@
+import { Badge, Badge as Pill } from '@mindlogic-ai/logician-ui';
+
+export const Badges = ({ v, rest }: any) => (
+  <>
+    <Badge>—</Badge>
+    <Badge>neutral</Badge>
+    <Badge>primary</Badge>
+    <Badge mr={2}>secondary</Badge>
+    <Badge variant="success">success</Badge>
+    <Badge variant="warning">warning</Badge>
+    <Badge variant="danger">danger</Badge>
+    <Badge variant="info">info</Badge>
+    <Pill>alias</Pill>
+    <Badge /* TODO(logician-ui 5.0): Badge variant="purple" is not a 5.0 variant; removed (neutral) */
+    >
+      unknown
+    </Badge>
+    <Badge variant={v}>dynamic</Badge>
+    <Badge {...rest}>spread</Badge>
+  </>
+);

package/codemods/5.0/__testfixtures__/button-variants.input.tsx

@@ -0,0 +1,124 @@
+import { Button, IconButton as IB } from '@mindlogic-ai/logician-ui';
+import { Button as LButton } from '@mindlogic-ai/logician-ui';
+import * as LUI from '@mindlogic-ai/logician-ui';
+import { Button as OtherButton } from 'some-other-lib';
+
+export const Buttons = ({ kind, palette, rest, ok }: any) => (
+  <>
+    {/* Button — solid */}
+    <Button colorPalette="primary" variant="solid">
+      primary/solid
+    </Button>
+    <Button variant="solid">—/solid</Button>
+    <Button colorPalette="neutral" variant="solid">
+      neutral/solid
+    </Button>
+    <Button colorPalette="danger" variant="solid">
+      danger/solid
+    </Button>
+    {/* Button — outline */}
+    <Button colorPalette="neutral" variant="outline">
+      neutral/outline
+    </Button>
+    <Button variant="outline">—/outline</Button>
+    <Button colorPalette="primary" variant="outline">
+      primary/outline
+    </Button>
+    <Button colorPalette="secondary" variant="outline">
+      secondary/outline
+    </Button>
+    <Button colorPalette="danger" variant="outline">
+      danger/outline
+    </Button>
+    {/* Button — ghost */}
+    <Button colorPalette="neutral" variant="ghost">
+      neutral/ghost
+    </Button>
+    <Button variant="ghost" colorPalette="primary">
+      primary/ghost
+    </Button>
+    <Button colorPalette="danger" variant="ghost">
+      danger/ghost
+    </Button>
+    {/* Button — soft / default */}
+    <Button colorPalette="danger" variant="soft">
+      danger/soft
+    </Button>
+    <Button colorPalette="danger">danger/—</Button>
+    <Button>—/—</Button>
+    <Button colorPalette="primary">primary/—</Button>
+    <Button colorPalette="secondary">secondary/—</Button>
+    <Button colorPalette="primary" variant="soft">
+      primary/soft
+    </Button>
+    <Button colorPalette="neutral" variant="soft">
+      neutral/soft
+    </Button>
+    <Button colorPalette="secondary" variant="soft">
+      secondary/soft
+    </Button>
+    {/* colorScheme (Chakra v2 name) is treated like colorPalette */}
+    <Button colorScheme="danger" variant="outline" onClick={ok}>
+      colorScheme
+    </Button>
+    <Button colorPalette={'primary'} variant={`solid`}>
+      static expressions
+    </Button>
+    {/* No exact 5.0 role → TODO + report */}
+    <Button colorPalette="secondary" variant="solid">
+      secondary/solid
+    </Button>
+    <Button colorPalette="warning" variant="solid">
+      warning/solid
+    </Button>
+    <Button colorPalette="primary" variant="link">
+      unknown variant
+    </Button>
+    <Button colorPalette="danger" variant="plain">
+      unknown variant, danger
+    </Button>
+    {/* Dynamic → untouched + report */}
+    <Button variant={kind}>dynamic variant</Button>
+    <Button colorPalette={ok ? 'danger' : 'primary'} variant="solid">
+      dynamic palette
+    </Button>
+    {/* Spread → migrated, reported */}
+    <Button {...rest} colorPalette="primary" variant="solid">
+      spread
+    </Button>
+    {/* Already 5.0 → untouched */}
+    <Button variant="primary">already</Button>
+    <Button variant="ghost" isDestructive>
+      already
+    </Button>
+    {/* Aliases and namespaces */}
+    <LButton colorPalette="primary" variant="solid">
+      alias
+    </LButton>
+    <LUI.Button colorPalette="danger" variant="ghost">
+      namespace
+    </LUI.Button>
+    {/* Not logician-ui → untouched */}
+    <OtherButton colorPalette="primary" variant="solid">
+      other
+    </OtherButton>
+
+    {/* IconButton (aliased as IB) */}
+    <IB aria-label="a" />
+    <IB aria-label="a" colorPalette="neutral" variant="ghost" />
+    <IB aria-label="a" variant="ghost" />
+    <IB aria-label="a" colorPalette="neutral" variant="soft" />
+    <IB aria-label="a" colorPalette="primary" variant="soft" />
+    <IB aria-label="a" colorPalette="primary" variant="ghost" />
+    <IB aria-label="a" colorPalette="warning" variant="ghost" />
+    <IB aria-label="a" colorPalette="neutral" variant="outline" />
+    <IB aria-label="a" variant="outline" />
+    <IB aria-label="a" colorPalette="primary" variant="solid" />
+    <IB aria-label="a" colorPalette="danger" variant="solid" />
+    <IB aria-label="a" colorPalette="danger" variant="ghost" />
+    <IB aria-label="a" colorPalette="danger" variant="soft" />
+    <IB aria-label="a" colorPalette="secondary" variant="solid" />
+    <IB aria-label="a" colorPalette={palette} />
+    <IB aria-label="a" variant="secondary" />
+  </>
+);