Migrate consumers to @workflowbuilder/ui (2/3: consumers)

.changeset/move-ui-library-in-repo.md

@@ -0,0 +1,7 @@
+---
+'@workflowbuilder/sdk': minor
+---
+
+Consume the UI component library from the in-repo `@workflowbuilder/ui` (Base UI) instead of the published `@synergycodes/overflow-ui`.
+
+The SDK previously bundled `@synergycodes/overflow-ui@1.0.0-beta.27` (built on MUI / Mantine / Emotion / Floating UI). It now bundles the in-repo `@workflowbuilder/ui@2.0.0`, rebuilt on [Base UI](https://base-ui.com/). `@base-ui/react` is now a regular dependency of the SDK (installed automatically, not bundled) rather than an inlined implementation detail. Bundled component visuals and interaction details change accordingly; the SDK's exported symbols are unchanged, but public types deriving from the UI library (`InputControlProps`, `TextAreaControlProps`) now build on `@workflowbuilder/ui` type shapes (picked keys unchanged), and the internal DOM structure and class names of all bundled UI changed (MUI Base + Mantine → Base UI) — styles or tests written against those internal class names may need updating. Modal open/close now runs its enter and exit fade transitions (previously the dialog appeared and disappeared instantly).

.changeset/sdk-date-picker-trigger-height.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': patch
+---
+
+Date and datetime variable inputs regained their intended `2.5rem` trigger height and left-aligned text; the style override now matches the new DatePicker markup.

.changeset/sdk-single-top-layer.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': minor
+---
+
+The SDK stylesheet now declares a single top-level cascade layer: XYFlow's stylesheet and the SDK resets moved from the `ext-lib` / `reset` layers into `ui.base`, and the file opens with the same `@layer ui.base, ui.component;` statement as every `@workflowbuilder/ui` stylesheet. Component styling no longer depends on stylesheet load order. If you targeted the removed `reset` / `ext-lib` layer names, plain unlayered CSS wins over all library layers.

.changeset/sdk-ssr-modal-portal.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': patch
+---
+
+`ModalProvider` no longer touches `document` during server-side rendering; the modal portal mounts after hydration. Fixes `ReferenceError: document is not defined` when the editor renders in SSR frameworks such as Next.js.

.changeset/ui-base-ui-1-7.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/ui': minor
+---
+
+`@base-ui/react` dependency moved from `1.4.1` to `1.7.0` (still exact-pinned). Overlay transitions (Modal, Menu, Select, Tooltip, DatePicker) were re-validated on the 1.7 line.

CLAUDE.md

@@ -24,6 +24,8 @@ Three onboarding paths (A installs from npm; B, C run the repo locally). README
 
 Path B is UI-only and does not need Docker. Path C requires `pnpm infra:up` before backend/worker can start; the backend applies pending migrations automatically at boot.
 
+App builds and dev servers consume the prebuilt `packages/ui/dist` (created on install). After editing `packages/ui/src`, run `pnpm build:ui` (or keep `pnpm --filter @workflowbuilder/ui dev` watching) - app commands do not rebuild it.
+
 ### Agent signals
 
 Long-running processes already emit stable log lines that scripts and agents can grep for:

apps/ai-studio/package.json

@@ -13,15 +13,19 @@
     "test:watch": "vitest --passWithNoTests"
   },
   "dependencies": {
+    "@base-ui/react": "catalog:",
+    "@jsonforms/core": "^3.4.1",
+    "@jsonforms/react": "^3.4.1",
     "@phosphor-icons/react": "^2.1.7",
-    "@synergycodes/overflow-ui": "1.0.0-beta.27",
     "@workflow-builder/types": "workspace:*",
+    "@workflowbuilder/ui": "workspace:*",
     "@xyflow/react": "catalog:",
     "clsx": "^2.1.1",
     "html-to-image": "1.11.11",
     "immer": "^10.1.1",
     "mermaid": "^11.15.0",
-    "react": "^19.1.0",
+    "react": "catalog:",
+    "react-is": "catalog:",
     "react-dom": "catalog:",
     "react-i18next": "^15.4.1",
     "react-markdown": "^10.1.0",

apps/ai-studio/src/components/controls/ai-studio-controls.tsx

@@ -1,5 +1,5 @@
-import { NavButton } from '@synergycodes/overflow-ui';
 import { Icon, getStoreEdges, getStoreNodes } from '@workflowbuilder/sdk';
+import { NavButton } from '@workflowbuilder/ui';
 import clsx from 'clsx';
 import { useCallback } from 'react';
 

apps/ai-studio/src/plugins/undo-redo/components/buttons-undo-redo/buttons-undo-redo.tsx

@@ -1,5 +1,5 @@
-import { NavButton } from '@synergycodes/overflow-ui';
 import { Icon, useStore } from '@workflowbuilder/sdk';
+import { NavButton } from '@workflowbuilder/ui';
 import { useTranslation } from 'react-i18next';
 
 import { redo, undo, useUndoRedoStore } from '../../stores/use-undo-redo-store';

apps/ai-studio/vite.config.mts

@@ -5,20 +5,12 @@ import { defineConfig } from 'vite';
 import svgr from 'vite-plugin-svgr';
 
 export default defineConfig(() => {
-  const shouldUseLocalOverflowUI = process.env.LOCAL_OVERFLOW_UI === 'true';
-
   const sdkDirectory = path.resolve(import.meta.dirname, '../../packages/sdk');
 
   return {
     plugins: [svgr(), react()],
     resolve: {
       alias: [
-        ...(shouldUseLocalOverflowUI
-          ? Object.entries(getLocalOverflowUIAliases()).map(([find, replacement]) => ({
-              find,
-              replacement,
-            }))
-          : []),
         {
           find: /^@workflowbuilder\/sdk\/style\.css$/,
           replacement: path.resolve(sdkDirectory, 'src/index.css'),
@@ -27,14 +19,6 @@ export default defineConfig(() => {
           find: /^@workflowbuilder\/sdk$/,
           replacement: path.resolve(sdkDirectory, 'src/index.ts'),
         },
-        // overflow-ui doesn't expose ./dist/index.css via package.json exports
-        {
-          find: 'overflow-ui-css',
-          replacement: path.resolve(
-            sdkDirectory,
-            'node_modules/@synergycodes/overflow-ui/dist/index.css',
-          ),
-        },
         // SDK source files use @/ to refer to their own root (packages/sdk/src/...).
         // AI Studio files do not use @/ (they import via @workflowbuilder/sdk subpaths),
         // so it's safe to point @/ at the SDK root for cross-package alias parity.
@@ -56,12 +40,3 @@ export default defineConfig(() => {
     },
   };
 });
-
-function getLocalOverflowUIAliases(): Record<string, string> {
-  const distribution = path.resolve(import.meta.dirname, '../../../overflow-ui/packages/ui/dist');
-
-  return {
-    '@synergycodes/overflow-ui/tokens.css': path.join(distribution, 'tokens.css'),
-    '@synergycodes/overflow-ui': path.join(distribution, 'overflow-ui.js'),
-  };
-}

apps/backend/README.md

@@ -79,7 +79,6 @@ All scripts run from the monorepo root. Grouped by purpose:
 | `dev:backend`   | Backend only (Hono server with `tsx watch`)                                                              |
 | `dev:worker`    | Execution worker only (Temporal worker with `tsx watch`)                                                 |
 | `dev:docs`      | Docs site (Astro)                                                                                        |
-| `dev:local`     | Demo frontend with `LOCAL_OVERFLOW_UI=true` (linked local overflow-ui)                                   |
 
 ### Infra (Docker lifecycle)
 

apps/demo/package.json

@@ -16,9 +16,12 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@base-ui/react": "catalog:",
+    "@jsonforms/core": "^3.4.1",
+    "@jsonforms/react": "^3.4.1",
     "@microsoft/clarity": "^1.0.0",
     "@phosphor-icons/react": "^2.1.7",
-    "@synergycodes/overflow-ui": "1.0.0-beta.27",
+    "@workflowbuilder/ui": "workspace:*",
     "@xyflow/react": "catalog:",
     "ajv": "catalog:",
     "clsx": "^2.1.1",
@@ -28,7 +31,7 @@
     "immer": "^10.1.1",
     "jspdf": "^3.0.1",
     "libavoid-js": "0.4.0-beta.1",
-    "react": "^19.1.0",
+    "react": "catalog:",
     "react-dom": "catalog:",
     "react-i18next": "^15.4.1",
     "remeda": "^2.19.2",

apps/demo/src/app/components/multi-port-node/multi-port-node-template.tsx

@@ -1,6 +1,6 @@
-import { NodeDescription, NodeIcon, NodePanel } from '@synergycodes/overflow-ui';
 import { Icon, defineNodeTemplate, getHandleId, statusOptions } from '@workflowbuilder/sdk';
 import type { NodeDataProperties, WorkflowNodeTemplateProps } from '@workflowbuilder/sdk';
+import { NodeDescription, NodeIcon, NodePanel } from '@workflowbuilder/ui';
 import { Handle, Position } from '@xyflow/react';
 import clsx from 'clsx';
 import { memo, useMemo } from 'react';

apps/demo/src/app/plugins/undo-redo/components/buttons-undo-redo/buttons-undo-redo.tsx

@@ -1,5 +1,5 @@
-import { NavButton } from '@synergycodes/overflow-ui';
 import { Icon, useStore } from '@workflowbuilder/sdk';
+import { NavButton } from '@workflowbuilder/ui';
 import { useTranslation } from 'react-i18next';
 
 import { redo, undo, useUndoRedoStore } from '../../stores/use-undo-redo-store';

apps/demo/vite.config.mts

@@ -16,7 +16,6 @@ import {
 export default defineConfig(({ mode }) => {
   const isProduction = mode === 'production';
   const isAnalyze = process.env.ANALYZE === 'true';
-  const shouldUseLocalOverflowUI = process.env.LOCAL_OVERFLOW_UI === 'true';
 
   const plugins: PluginOption[] = [];
 
@@ -52,12 +51,6 @@ export default defineConfig(({ mode }) => {
     plugins,
     resolve: {
       alias: [
-        ...(shouldUseLocalOverflowUI
-          ? Object.entries(getLocalOverflowUIAliases()).map(([find, replacement]) => ({
-              find,
-              replacement,
-            }))
-          : []),
         {
           find: /^@workflowbuilder\/sdk\/style\.css$/,
           replacement: path.resolve(sdkDirectory, 'src/index.css'),
@@ -66,14 +59,6 @@ export default defineConfig(({ mode }) => {
           find: /^@workflowbuilder\/sdk$/,
           replacement: path.resolve(sdkDirectory, 'src/index.ts'),
         },
-        // overflow-ui doesn't expose ./dist/index.css via package.json exports
-        {
-          find: 'overflow-ui-css',
-          replacement: path.resolve(
-            sdkDirectory,
-            'node_modules/@synergycodes/overflow-ui/dist/index.css',
-          ),
-        },
         // SDK source files use @/ to refer to their own root (packages/sdk/src/...).
         // Demo files do not use @/ (they import via @workflowbuilder/sdk subpaths),
         // so it's safe to point @/ at the SDK root for cross-package alias parity with sdk's vite.config.
@@ -96,15 +81,6 @@ export default defineConfig(({ mode }) => {
   };
 });
 
-function getLocalOverflowUIAliases(): Record<string, string> {
-  const distribution = path.resolve(import.meta.dirname, '../../../overflow-ui/packages/ui/dist');
-
-  return {
-    '@synergycodes/overflow-ui/tokens.css': path.join(distribution, 'tokens.css'),
-    '@synergycodes/overflow-ui': path.join(distribution, 'overflow-ui.js'),
-  };
-}
-
 type EnvMode = 'demo' | 'production' | 'development' | 'staging';
 const fileReplacementsMap: Record<EnvMode, FileReplacement[]> = {
   demo: [],

apps/docs/src/content/docs/get-started/theming.md

@@ -23,4 +23,4 @@ Provide the font yourself (via `@font-face`, `@fontsource/<font>`, etc.) — the
 
 ## Other tokens
 
-The SDK exposes a small surface of `--wb-*` variables (background, scrollbar, transitions) plus the larger `--ax-*` design-token set re-exported from `@synergycodes/overflow-ui`. See [Design System & Customization](/overview/features/design-system-and-customization/) for the full token map.
+The SDK exposes a small surface of `--wb-*` variables (background, scrollbar, transitions) plus the larger `--ax-*` design-token set re-exported from `@workflowbuilder/ui`. See [Design System & Customization](/overview/features/design-system-and-customization/) for the full token map.

apps/docs/src/content/docs/guides/add-a-custom-node.mdx

@@ -197,9 +197,9 @@ The built-in renderer gives every node a header and one input + one output handl
 `my-node-template.tsx`:
 
 ```tsx
-import { NodeDescription, NodeIcon, NodePanel } from '@synergycodes/overflow-ui';
 import { Icon, getHandleId } from '@workflowbuilder/sdk';
 import type { WorkflowNodeTemplateProps } from '@workflowbuilder/sdk';
+import { NodeDescription, NodeIcon, NodePanel } from '@workflowbuilder/ui';
 import { Handle, Position } from '@xyflow/react';
 import { memo, useMemo } from 'react';
 
@@ -230,7 +230,7 @@ export const MyNodeTemplate = memo(
 );
 ```
 
-The example composes the node from `@synergycodes/overflow-ui` primitives (`NodePanel.Root`, `NodePanel.Header`, `NodePanel.Handles`) — the same building blocks Workflow Builder uses for its own node renderers, so the result matches the editor's visual language out of the box.
+The example composes the node from `@workflowbuilder/ui` primitives (`NodePanel.Root`, `NodePanel.Header`, `NodePanel.Handles`) — the same building blocks Workflow Builder uses for its own node renderers, so the result matches the editor's visual language out of the box.
 
 The component receives [`WorkflowNodeTemplateProps`](/api/components/workflownodetemplateprops/). Use [`getHandleId`](/api/utilities/gethandleid/) for handle IDs and pass `innerId` when a node has more than one handle of the same type. If your template needs typed access to `data.properties`, wrap the component in [`defineNodeTemplate`](/api/components/definenodetemplate/) to bind a schema-derived properties type.
 

apps/docs/src/content/docs/node-schemas/form-layouts.md

@@ -97,11 +97,11 @@ Text-only elements that don't bind to a property. Use them when the property pan
 
 Plain text label — uses the editor's default body styling.
 
-| Prop       | Type     | Required | Notes                                                                                          |
-| ---------- | -------- | -------- | ---------------------------------------------------------------------------------------------- |
-| `text`     | string   | yes      | The label text.                                                                                |
-| `required` | boolean  | no       | Append a `*` to indicate the following section contains required fields.                       |
-| `size`     | ItemSize | no       | Visual size — `'small'`, `'medium'` (default), `'large'`. Type re-exported from `overflow-ui`. |
+| Prop       | Type     | Required | Notes                                                                                                  |
+| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `text`     | string   | yes      | The label text.                                                                                        |
+| `required` | boolean  | no       | Append a `*` to indicate the following section contains required fields.                               |
+| `size`     | ItemSize | no       | Visual size — `'small'`, `'medium'` (default), `'large'`. Type re-exported from `@workflowbuilder/ui`. |
 
 ```ts
 { type: 'Label', text: 'Connection details' }

docs/how-to-change-css-tokens.md

@@ -1,7 +1,38 @@
-# How to change css tokens?
+# How to change CSS tokens?
 
-You can use our enterprise version with available figma design kit. We store tokens (colors) in `packages/sdk/src/index.css`, you'll find a CSS import: `@import '@synergycodes/overflow-ui/tokens.css';` with our figma you replace that import with generated from figma desing kit.
+All colors, spacing, and radii resolve through `--ax-*` custom properties
+defined in `@workflowbuilder/ui/tokens.css` (imported by the SDK's stylesheet).
+The shipped defaults live inside the `ui.base` cascade layer, so a plain
+unlayered override in your own stylesheet always wins - import order does not
+matter.
 
-Alternatively, if you want to stay with community version and do not pay for the licenses, you can look inside `node_modules` at `packages/sdk/node_modules/@synergycodes/overflow-ui/dist/tokens.css`, check the variable names, and manually set some or all of the colors in your repository to overwrite them.
+## Consuming from npm (SDK or UI package)
 
-`@synergycodes/overflow-ui` is our library for UI elements [overflow-ui](https://github.com/synergycodes/overflow-ui)
+Override the variables you care about in any stylesheet of your app:
+
+```css
+:root {
+  --ax-button-primary-bg-default: #0f62fe;
+  --ax-ui-bg-tertiary-default: #f4f4f4;
+}
+```
+
+To discover variable names, inspect elements in devtools or browse
+`node_modules/@workflowbuilder/ui/dist/tokens.css`. Theme-specific values are
+keyed on `html[data-theme='light' | 'dark']`, so scope your overrides the same
+way when they should apply to one theme only.
+
+## Working in this monorepo
+
+The source of truth is `packages/tokens/tokens.json` (a Figma Tokens Studio
+export) plus the build in `packages/tokens/src`. Edit the export (or re-export
+from Figma) and run `pnpm build:ui`.
+
+Do **not** edit `packages/ui/dist/tokens.css` - it is generated output and the
+next build overwrites it.
+
+## Enterprise
+
+The enterprise version ships a Figma design kit; its generated stylesheet
+replaces the `@import '@workflowbuilder/ui/tokens.css';` line in
+`packages/sdk/src/index.css`.

package.json

@@ -11,7 +11,6 @@
     "dev:backend": "pnpm --filter backend dev",
     "dev:worker": "pnpm --filter execution-worker dev",
     "dev:docs": "pnpm --filter @workflow-builder/docs dev",
-    "dev:local": "LOCAL_OVERFLOW_UI=true pnpm --filter @workflow-builder/demo dev",
     "infra:up": "docker compose -f apps/backend/docker-compose.yml up -d",
     "infra:down": "docker compose -f apps/backend/docker-compose.yml down",
     "infra:wait": "node tools/wait-for-temporal.mjs",

packages/sdk/DECISION-LOG.md

@@ -11,7 +11,13 @@
 > `<WorkflowBuilder.Root>`. References below to `Editor`, `createWorkflowBuilder`,
 > `WorkflowBuilderConfig`, `WorkflowBuilderInstance` describe symbols that no
 > longer exist; see current SDK exports in `packages/sdk/src/index.ts` for the
-> post-refactor surface. The notes are retained for historical context only.
+> post-refactor surface. The UI library was later swapped from the npm package
+> `@synergycodes/overflow-ui` to the in-repo `@workflowbuilder/ui`: the
+> `overflow-ui-css` Vite alias and the `@import` layout in sections 3-4 no
+> longer exist, and the "Vite doesn't extract CSS from bundled node_modules"
+> claim in section 3 turned out to be false (bundled chunk CSS imports ARE
+> extracted - the SDK now relies on exactly that). The notes are retained for
+> historical context only.
 
 ## Context