Ai week semantic with codemod

.changeset/green-planes-shine.md

@@ -0,0 +1,5 @@
+---
+'@kaizen/components': patch
+---
+
+add semantic colours

.changeset/semantic-colour-tokens.md

@@ -0,0 +1,9 @@
+---
+'@kaizen/design-tokens': minor
+'@kaizen/tailwind': minor
+'@kaizen/components': patch
+---
+
+feat: add semantic colour tokens (background, text, foreground, border) and expand the gray primitive ramp with `gray-550` and `gray-700`. Exposes the tokens as CSS variables (inlined into `variables.css`), SCSS, JS exports, and Tailwind preset utilities.
+
+`@kaizen/tailwind` depends on `@kaizen/design-tokens` (a regular runtime dependency, installed transitively): the semantic Tailwind utilities emit `var(--<token>)` references whose definitions live in `@kaizen/design-tokens`. Consumers using the Tailwind preset do not need to install `@kaizen/design-tokens` themselves — they only need to load its CSS variables once at runtime (handled by `KaizenProvider`).

.claude/skills/semantic-border-migration/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: semantic-border-migration
+description: Migrate a component's border styles to the new semantic border tokens. Runs the migrateBorderColorsToSemanticTokens codemod first, then falls back to a guided manual migration only after the user confirms the codemod was incomplete. Use when asked to migrate borders to semantic tokens, apply border semantic tokens, or run the border token migration for a component.
+---
+
+## Semantic Border Migration
+
+Use this skill to migrate a component's borders from hard-coded **primitive**
+colors — CSS `var(--color-gray-500)`, SCSS `$color-gray-500`, or Tailwind
+`border-gray-500` — to the new **semantic
+border tokens** (`--border-primary`, `--border-secondary`, `--border-secondary_alt`,
+`--border-tertiary`, `--border-brand`, `--border-brand_alt`, `--border-error`,
+`--border-error_subtle`).
+
+This runs in **two stages with a hard gate between them**. Stage 1 is the
+deterministic codemod. Stage 2 is a guided manual migration that you only enter
+**after the user has verified Stage 1 failed or is incomplete**. Never jump
+straight to Stage 2, and never run Stage 2 automatically off the back of Stage 1.
+
+## Preconditions
+
+- Package manager: `pnpm`. Repo uses Changesets + Buildkite/GitHub Actions CI.
+- `@kaizen/components` is installed (ships the `kaizen-codemod` bin).
+- Know the **target component / directory** to migrate.
+- If the consumer repo sets a Tailwind `prefix`, know its value (e.g. `goals-`
+  or `EP:`) so the codemod preserves it.
+
+## Reference
+
+- Codemod: [`migrateBorderColorsToSemanticTokens`](../../../packages/components/codemods/migrateBorderColorsToSemanticTokens/README.md) — the single source of truth for the confident mapping table and CLI usage.
+- Semantic token definitions: [`semanticColorTokens.ts`](../../../packages/design-tokens/src/js/semanticColorTokens.ts) (the `border` group).
+
+---
+
+## Stage 1 — Attempt the codemod (deterministic)
+
+1. **Confirm the target** directory/component with the user, and the Tailwind
+   prefix if any.
+2. **Run the codemod:**
+   ```sh
+   pnpm kaizen-codemod <dir> migrateBorderColorsToSemanticTokens
+   ```
+   If there is a Tailwind prefix, pass it via the env var:
+   ```sh
+   KAIZEN_TW_PREFIX=goals- pnpm kaizen-codemod <dir> migrateBorderColorsToSemanticTokens
+   ```
+3. **Tidy rewrites:** run prettier/lint over the changed files (e.g.
+   `pnpm prettier --write <dir>`), since AST/text rewrites may need reformatting.
+4. **Surface the report.** The codemod prints a **`✅ Converted N`** count and,
+   crucially, a **`⚠️ SKIPPED`** list of border colors it could not confidently
+   map (`file:line — detail`). Show this to the user, along with the diff.
+5. **STOP and ask the user to verify.** Explicitly ask:
+
+   > Did Stage 1 fully migrate this component's borders, or are there skipped /
+   > incomplete / ambiguous cases still to resolve?
+
+   Do **not** proceed. Only continue to Stage 2 if the user confirms Stage 1 is
+   incomplete or failed. If the user says it's complete, verify (below) and stop.
+
+---
+
+## Stage 2 — Guided manual fallback (only after user verification)
+
+Enter this stage **only** when the user has confirmed Stage 1 left work behind.
+Work through the codemod's `SKIPPED` report plus anything the user flagged.
+
+1. **Resolve each skipped border color.** For each entry, decide the correct
+   semantic border token using the intent of the border and the mappings in
+   [`semanticColorTokens.ts`](../../../packages/design-tokens/src/js/semanticColorTokens.ts).
+   Apply the change by hand (CSS `var(--color-*)` → `var(--border-*)`; SCSS
+   `$color-*` → `$border-*`, importing `@kaizen/design-tokens/sass/semantic` if
+   the `$border-*` var isn't already available; Tailwind `border-*` → the
+   semantic utility, preserving any prefix/variant).
+2. **Handle what the codemod can't:**
+   - **No direct equivalent** (yellow / orange / green / purple borders, alpha /
+     `rgb()` usages, raw hex). These often need a **design decision** — do not
+     force a mapping. Propose the closest semantic token and flag it for
+     designer/user sign-off rather than guessing silently.
+   - **Dynamic / computed class names** (template literals, variables) the
+     codemod skipped.
+   - **Unusual selectors or non-standard files** not covered by the walk.
+3. **Record decisions** for ambiguous cases (what you chose and why) so reviewers
+   can check them.
+
+---
+
+## Verification (either stage)
+
+- **Tests:** `pnpm --filter @kaizen/components test` (or scope to the component).
+- **Build:** `pnpm build`.
+- **Visual:** Storybook + Chromatic to confirm no border regressions on the
+  migrated component.
+- **Summarise** what was auto-migrated (Stage 1), what was hand-migrated
+  (Stage 2), and anything deferred for design sign-off.
+
+## Do / Don't
+
+- **Do** keep the change scoped to one component/directory and add a changeset if
+  it ships to consumers.
+- **Do** preserve Tailwind prefixes and variant chains exactly.
+- **Don't** enter Stage 2 without explicit user verification that Stage 1 is
+  incomplete.
+- **Don't** guess a semantic token for a color with no confident mapping — surface
+  it for a design decision.

.claude/skills/semantic-colours-migration/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: semantic-colours-migration
+description: Migrate a component's colours (background, text, foreground/icon, and border) to the new semantic colour tokens. Runs the migratePrimitivesToSemanticTokens codemod first (deterministic), then falls back to a guided manual migration only after the user confirms the codemod was incomplete. Use when asked to migrate colours to semantic tokens, apply semantic colour tokens, or run the semantic colour token migration for a component.
+---
+
+## Semantic Colours Migration
+
+Use this skill to migrate a component's colours from hard-coded **primitives** —
+CSS `var(--color-blue-500)`, SCSS `$color-blue-500`, or Tailwind `bg-blue-500` —
+to the new **semantic colour tokens** across all four groups:
+
+- **background** → `--bg-*` (e.g. `bg-brand-solid`, `bg-tertiary`)
+- **text** → `--text-*` (e.g. `text-primary`, `text-secondary`)
+- **foreground** (icons / glyphs) → `--fg-*` (e.g. `fg-tertiary`, `fg-brand-primary`)
+- **border** → `--border-*` (e.g. `border-secondary`, `border-brand`)
+
+This runs in **two stages with a hard gate between them**. Stage 1 is the
+deterministic codemod. Stage 2 is a guided manual migration that you only enter
+**after the user has verified Stage 1 failed or is incomplete**. Never jump
+straight to Stage 2, and never run Stage 2 automatically off the back of Stage 1.
+
+> **Borders are handled here.** This skill and its codemod fully cover the
+> `border-*` group alongside background/text/foreground — do **not** hand off to
+> the separate `/semantic-border-migration` skill or run the
+> `migrateBorderColorsToSemanticTokens` codemod. Those were the reference/basis
+> this skill and codemod were built from; treat them as prior art only.
+
+## Preconditions
+
+- Package manager: `pnpm`. Repo uses Changesets + Buildkite/GitHub Actions CI.
+- `@kaizen/components` is installed (ships the `kaizen-codemod` bin).
+- Know the **target component / directory** to migrate.
+- If the consumer repo sets a Tailwind `prefix`, know its value (e.g. `goals-`
+  or `EP:`) so the codemod preserves it.
+
+## Reference
+
+- Codemod: [`migratePrimitivesToSemanticTokens`](../../../packages/components/codemods/migratePrimitivesToSemanticTokens/README.md) — the single source of truth for the confident mapping, group-context rules, and CLI usage.
+- Semantic token definitions: [`semanticColorTokens.ts`](../../../packages/design-tokens/src/js/semanticColorTokens.ts) (the `background`, `text`, `foreground`, `border` groups).
+- Known follow-ups / outliers: [`TODO.md`](../../../packages/components/codemods/migratePrimitivesToSemanticTokens/TODO.md).
+- Prior art (reference only — **not** to be run from this skill): the border-only [`/semantic-border-migration`](../semantic-border-migration/SKILL.md) skill and [`migrateBorderColorsToSemanticTokens`](../../../packages/components/codemods/migrateBorderColorsToSemanticTokens/README.md) codemod, whose two-stage design and border mappings this skill/codemod are built on and fully supersede.
+
+---
+
+## Stage 1 — Attempt the codemod (deterministic)
+
+Stage 1 is **deterministic**: it only applies confident 1:1 primitive→semantic
+mappings and reports everything else. Do not hand-edit colours in this stage.
+
+1. **Confirm the target** directory/component with the user, and the Tailwind
+   prefix if any.
+2. **Run the codemod:**
+   ```sh
+   pnpm kaizen-codemod <dir> migratePrimitivesToSemanticTokens
+   ```
+   If there is a Tailwind prefix, pass it via the env var:
+   ```sh
+   KAIZEN_TW_PREFIX=goals- pnpm kaizen-codemod <dir> migratePrimitivesToSemanticTokens
+   ```
+3. **Tidy rewrites:** run prettier/lint over the changed files (e.g.
+   `pnpm prettier --write <dir>`), since AST/text rewrites may need reformatting.
+4. **Surface the report.** The codemod prints a **`✅ Converted N`** count and,
+   crucially, a **`⚠️ SKIPPED`** list of colours it could not confidently map
+   (`file:line — detail`). Show this to the user, along with the diff.
+5. **STOP and ask the user to verify.** Explicitly ask:
+
+   > Did Stage 1 fully migrate this component's colours, or are there skipped /
+   > incomplete / ambiguous cases still to resolve?
+
+   Do **not** proceed. Only continue to Stage 2 if the user confirms Stage 1 is
+   incomplete or failed. If the user says it's complete, verify (below) and stop.
+
+---
+
+## Stage 2 — Guided manual fallback (only after user verification)
+
+Enter this stage **only** when the user has confirmed Stage 1 left work behind.
+Work through the codemod's `SKIPPED` report plus anything the user flagged, and
+**report each missed instance back to the user** with the decision you propose.
+
+1. **Resolve each skipped colour.** For each entry, decide the correct semantic
+   token using the intent of the surface (background / text / icon / border) and
+   the mappings in
+   [`semanticColorTokens.ts`](../../../packages/design-tokens/src/js/semanticColorTokens.ts).
+   Apply the change by hand (CSS `var(--color-*)` → `var(--<token>)`; SCSS
+   `$color-*` → `$<token>`, importing `@kaizen/design-tokens/sass/semantic-color`
+   if the semantic var isn't already available; Tailwind primitive utility → the
+   semantic utility, preserving any prefix/variant).
+2. **Handle what the codemod can't (report, don't guess):**
+   - **Colliding primitives** — one primitive backing several tokens in a group
+     (e.g. `gray-200` → `bg-secondary` _or_ `bg-secondary_hover`). Pick the token
+     that matches the **intent** (resting vs hover/`_alt` state) and note why.
+   - **No direct equivalent** (colours with no mapping, alpha / `rgb()` usages,
+     raw hex, `null` tokens not yet signed off). These often need a **design
+     decision** — propose the closest semantic token and flag it for
+     designer/user sign-off rather than forcing a mapping.
+   - **Dynamic / computed class names** (template literals, variables) the codemod
+     skipped.
+   - **Out-of-scope properties** (`box-shadow`, `outline-color`, gradients) the
+     codemod does not touch.
+3. **Report the missed instances back.** Summarise every skipped case as
+   `file:line — original → proposed (rationale / needs sign-off)` so the user and
+   reviewers can check each decision.
+
+---
+
+## Verification (either stage)
+
+- **Tests:** `pnpm --filter @kaizen/components test` (or scope to the component).
+- **Build:** `pnpm build`.
+- **Visual:** Storybook + Chromatic to confirm no colour regressions on the
+  migrated component (check background, text, icon, and border surfaces, and
+  hover/focus states).
+- **Summarise** what was auto-migrated (Stage 1), what was hand-migrated
+  (Stage 2), and anything deferred for design sign-off.
+
+## Do / Don't
+
+- **Do** keep the change scoped to one component/directory and add a changeset if
+  it ships to consumers.
+- **Do** preserve Tailwind prefixes and variant chains exactly.
+- **Do** report every skipped instance in Stage 2 with a proposed mapping.
+- **Don't** enter Stage 2 without explicit user verification that Stage 1 is
+  incomplete.
+- **Don't** guess a semantic token for a colliding or unmapped colour — surface
+  it for a design decision.

.github/actions/setup/action.yml

@@ -16,7 +16,13 @@ runs:
     - name: Cache pnpm store
       uses: actions/setup-node@v4
       with:
-        node-version-file: package.json
+        # Pin to .nvmrc (single version) instead of the package.json `engines`
+        # range. A range lets setup-node float to the latest available Node,
+        # which after the 2026-06-18 security batch is a poisoned release
+        # (24.17.0 / 26.3.1) that makes node-fetch@2 throw a false
+        # ERR_STREAM_PREMATURE_CLOSE — breaking `changeset version`'s GitHub
+        # GraphQL changelog fetch. See nodejs/node#63989.
+        node-version-file: .nvmrc
         registry-url: https://npm.pkg.github.com/
         cache: 'pnpm'
 

.stylelintrc-css.mjs

@@ -4,6 +4,17 @@ export default {
   extends: 'stylelint-config-standard',
   rules: {
     'selector-class-pattern': null,
+    // Semantic colour tokens use a single `_` to introduce a state/variant
+    // segment (e.g. `--border-brand_alt`, `--bg-secondary_hover`,
+    // `--text-secondary_on-brand`). Allow one such underscore-separated variant
+    // group while still enforcing kebab-case within each segment.
+    'custom-property-pattern': [
+      '^([a-z][a-z0-9]*)(-[a-z0-9]+)*(_[a-z0-9]+(-[a-z0-9]+)*)?$',
+      {
+        message: (name) =>
+          `Expected custom property name "${name}" to be kebab-case with an optional _variant suffix`,
+      },
+    ],
     'color-function-notation': ['modern', { ignore: ['with-var-inside'] }],
     'font-family-no-missing-generic-family-keyword': [
       true,

.stylelintrc-scss.json

@@ -18,6 +18,7 @@
     ],
     "block-no-empty": true,
     "color-function-notation": "legacy",
+    "custom-property-pattern": "^([a-z][a-z0-9]*)(-[a-z0-9]+)*(_[a-z0-9]+(-[a-z0-9]+)*)?$",
     "comment-empty-line-before": [
       "always",
       {

packages/components/codemods/README.md

@@ -25,6 +25,10 @@ pnpm kaizen-codemod src migrateWellVariantToColor
 
 ## Available codemods
 
+### `migrateBorderColorsToSemanticTokens`
+
+Migrates hard-coded primitive border colors to the new semantic border tokens across CSS, SCSS, and Tailwind, via three transformers dispatched by file extension: CSS custom properties (`var(--color-gray-500)` → `var(--border-secondary)`), SCSS variables (`$color-gray-500` → `$border-secondary`, adding the `@kaizen/design-tokens/sass/semantic` import when needed), and Tailwind utilities (`border-gray-500` → `border-secondary`). Only confident border-context mappings are rewritten; ambiguous/unmapped colors and alpha/`rgb()` usages (e.g. `rgba($color-gray-600-rgb, 0.1)`) are skipped and reported. Honours a consumer Tailwind `prefix` via `KAIZEN_TW_PREFIX`. See the [README](./migrateBorderColorsToSemanticTokens/README.md), and pair it with the `/semantic-border-migration` skill for the stage-2 fallback.
+
 Released in `1.80.6`
 
 ### `runV1Codemods`