fix(ui,sdk): correct namespace migration contract

Author: librowski

.changeset/css-variable-namespaces-ui.md

@@ -2,4 +2,4 @@
 '@workflowbuilder/ui': major
 ---
 
-Generated Figma design tokens move from `--wb-<token>` to `--wb-ds-<token>` with no compatibility aliases. Replace the generated-token prefix in consumer overrides; `--wb-public-*` component variables are unchanged.
+Generated Figma design tokens move from `--ax-<token>` to `--wb-ds-<token>` with no compatibility aliases. Replace the generated-token prefix in consumer overrides; public component variables migrate separately from `--ax-public-*` to `--wb-public-*`.

.changeset/public-variable-namespace.md

@@ -3,4 +3,4 @@
 '@workflowbuilder/sdk': major
 ---
 
-Public component CSS variables use the `--wb-public-*` prefix with no compatibility aliases. Replace the legacy public prefix in consumer overrides.
+Public component CSS variables move one-to-one from `--ax-public-*` to `--wb-public-*`, with no compatibility aliases. Replace that prefix in consumer overrides.

apps/docs/src/components/ui-examples/form-fields.module.css

@@ -1,7 +1,7 @@
 .example-stack {
   display: flex;
   flex-direction: column;
-  gap: var(--wb-space-100);
+  gap: var(--wb-ds-space-100);
 }
 
 .example-wrap {

packages/sdk/sdk-restructuring.decision-log.md

@@ -6,6 +6,8 @@
 
 > **Status: archival.** This log describes the factory-based public API (`createWorkflowBuilder({...})`) that was the SDK entry point as of 22.04.2026. Superseded by `refactor/wb-root-context` — `createWorkflowBuilder`, `Editor`, `WorkflowBuilderConfig`, `WorkflowBuilderInstance(Props)`, and `defineNodeTemplate` are all gone; the entry point is now `<WorkflowBuilder.Root>`. References below describe the world as of the decision date and are intentionally not rewritten — see current SDK exports in `packages/sdk/src/index.ts` for the post-refactor surface.
 
+> **CSS namespace note:** `--wb-background-color` references below preserve the historical name. The supported control is now `--wb-public-background-color`.
+
 ## Context
 
 Phase 1 of the SDK work shipped `@workflowbuilder/sdk` as a thin facade over `apps/frontend`: the SDK's `src/index.ts` barrel just re-exported `Editor` and `createWorkflowBuilder` from the frontend via `@workflow-builder/frontend/app/*` tsconfig paths and Vite aliases. That worked as a distribution shell but left a mess underneath — "frontend" was simultaneously an SPA and the canonical source of the editor component, and the SDK looked like it was what it wasn't.
@@ -136,7 +138,7 @@ Two regressions and one gap became visible only once an external consumer app ac
 
 - **i18n regression (Phase 3a side-effect).** Plugins used to register translations via module-load side effects, which populated the shared `pluginsResource` before `i18n.init()` read it. Phase 3a moved plugin registration into the `createWorkflowBuilder({ plugins: [...] })` factory call, which executes **after** the SDK module graph has initialized i18next — so `registerPluginTranslation` updates a module-level object that i18next no longer consults. Plugin keys (`plugins.flowRunner.groupFlow`, `plugins.help.helpSupport`, etc.) surfaced as raw strings in the UI. Fix: `registerPluginTranslation` now calls `i18n.addResourceBundle(lang, 'translation', { plugins: ... }, true, true)` in addition to updating `pluginsResource`. Works regardless of when plugins register relative to i18next init.
 
-- **CSS incompleteness — SDK's `index.css` was a partial copy of demo's `global.css`.** Missing `body { margin: 0; background-color: var(--wb-public-background-color); overflow: hidden; }` rule left consumer apps with a white canvas instead of the tokenized grey background. Missing `@layer ui { @layer base, component; }` sub-layer declaration. Missing Google Fonts `@import` for Poppins left consumers with `sans-serif` fallback (since SDK's font stack was `'Poppins', sans-serif`). All three folded into [`packages/sdk/src/index.css`](./src/index.css). The Poppins `@import` plus a widened fallback chain (`system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif`) means consumers get a correct render without wiring up Google Fonts themselves.
+- **CSS incompleteness — SDK's `index.css` was a partial copy of demo's `global.css`.** Missing `body { margin: 0; background-color: var(--wb-background-color); overflow: hidden; }` rule left consumer apps with a white canvas instead of the tokenized grey background. Missing `@layer ui { @layer base, component; }` sub-layer declaration. Missing Google Fonts `@import` for Poppins left consumers with `sans-serif` fallback (since SDK's font stack was `'Poppins', sans-serif`). All three folded into [`packages/sdk/src/index.css`](./src/index.css). The Poppins `@import` plus a widened fallback chain (`system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif`) means consumers get a correct render without wiring up Google Fonts themselves.
 
 - **CSS `@import` ordering.** CSS spec requires `@import` before every other statement except `@charset` and _empty_ `@layer` declarations. The sub-layer block (`@layer ui { @layer base, component; }`) has a body and therefore counts as a statement — it must come **after** all `@import`s. PostCSS flagged this in demo's build. Reordered.
 
@@ -164,7 +166,7 @@ Smaller follow-ups from the next review pass. None are architectural; together t
 
 - **`@xyflow/react` peer-dep range tightened.** `>=12.0.0` accepted any future major; replaced with `^12.0.0` to keep semver-major changes from auto-installing into consumer apps without us having validated the SDK against them.
 
-- **CSS body reset documented.** `packages/sdk/src/index.css` resets `body` (`margin: 0`, `background-color: var(--wb-public-background-color)`, `overflow: hidden`) inside `@layer reset` — the lowest-precedence layer in the SDK's cascade, so consumer rules win without `!important`. The behaviour is still a surprise to a consumer who imports `style.css`, especially the `overflow: hidden` (which prevents page-level scrolling outside the editor). Added a `packages/sdk/README.md` documenting the resets, what they do, and how to override. The README is intentionally minimal — broader consumer docs (install / usage / screenshots) ride on the npm-publish prep that's still deferred.
+- **CSS body reset documented.** `packages/sdk/src/index.css` resets `body` (`margin: 0`, `background-color: var(--wb-background-color)`, `overflow: hidden`) inside `@layer reset` — the lowest-precedence layer in the SDK's cascade, so consumer rules win without `!important`. The behaviour is still a surprise to a consumer who imports `style.css`, especially the `overflow: hidden` (which prevents page-level scrolling outside the editor). Added a `packages/sdk/README.md` documenting the resets, what they do, and how to override. The README is intentionally minimal — broader consumer docs (install / usage / screenshots) ride on the npm-publish prep that's still deferred.
 
 **Why:** the schema move closes the gap left after § 8 — once the public barrel is curated, anything still in it has to clear the same scope-boundary bar. The default-export cleanup is hygiene against a lint convention that wasn't enforced as a rule. The peer-dep tightening protects consumers against drive-by majors. The README closes the most likely "I imported your CSS and now my page can't scroll" support ticket.
 

packages/tokens/src/css-variable-name.spec.ts

@@ -0,0 +1,18 @@
+import type { TransformedToken } from 'style-dictionary';
+import { describe, expect, it } from 'vitest';
+
+import { cssVariableName } from './css-variable-name';
+
+describe('cssVariableName', () => {
+  it('moves the wb prefix into the design-system namespace', () => {
+    const token = { path: ['wb', 'colors', 'brand'] } as TransformedToken;
+
+    expect(cssVariableName(token)).toBe('wb-ds-colors-brand');
+  });
+
+  it('rejects names outside the wb namespace', () => {
+    const token = { path: ['colors', 'brand'] } as TransformedToken;
+
+    expect(() => cssVariableName(token)).toThrow('Expected token name to start with "wb-", received "colors-brand"');
+  });
+});

packages/tokens/src/css-variable-name.ts

@@ -3,5 +3,9 @@ import StyleDictionary, { TransformedToken } from 'style-dictionary';
 const kebabName = StyleDictionary.hooks.transforms['name/kebab'].transform;
 
 export function cssVariableName(token: TransformedToken): string {
-  return String(kebabName(token, {}, {})).replace(/^wb-/, 'wb-ds-');
+  const name = String(kebabName(token, {}, {}));
+  if (!name.startsWith('wb-')) {
+    throw new Error(`Expected token name to start with "wb-", received "${name}"`);
+  }
+  return name.replace(/^wb-/, 'wb-ds-');
 }

packages/ui/CHANGELOG.md

@@ -25,7 +25,7 @@ Workflow Builder SDK.
   IconSwitch, Checkbox, RadioButton, SegmentPicker, DatePicker, Accordion,
   Avatar, Snackbar, Status, Separator, plus the NodePanel / NodeIcon /
   NodeDescription / EdgeLabel diagram primitives.
-- **Theming** via `--wb-ds-*` design tokens, isolated in cascade layers
+- **Theming** via `--ax-*` design tokens, isolated in cascade layers
   (`@layer ui.base, ui.component`) so app styles win without `!important` and
   components retheme cleanly.
 - **Multi-entry build** with per-component subpath exports

packages/ui/src/components/date-picker/date-picker.module.css

@@ -29,7 +29,7 @@
 
   .calendar {
     composes: wb-text-body-s from global;
-    font-size: var(--wb-font-size-150);
+    font-size: var(--wb-ds-font-size-150);
     font-weight: 400;
     line-height: 130%;
     background: var(--wb-public-date-picker-dropdown-background);
@@ -59,13 +59,13 @@
   }
 
   .calendar :global(.rdp-weekday) {
-    font-size: var(--wb-font-size-150);
+    font-size: var(--wb-ds-font-size-150);
     font-weight: 400;
     line-height: 130%;
   }
 
   .calendar :global(.rdp-month_caption) {
-    font-size: var(--wb-font-size-150);
+    font-size: var(--wb-ds-font-size-150);
     font-weight: 600;
     line-height: 130%;
   }
@@ -84,7 +84,7 @@
   .calendar :global(.rdp-selected .rdp-day_button) {
     background-color: var(--wb-public-date-picker-date-selected-background-color);
     color: var(--wb-public-date-picker-date-selected-color);
-    font-size: var(--wb-font-size-150);
+    font-size: var(--wb-ds-font-size-150);
     font-weight: 600;
     line-height: 130%;
   }