synergycodes · librowski · Aug 24, 2026
@@ -0,0 +1,6 @@
+---
+'@workflowbuilder/sdk': major
+'@workflowbuilder/ui': minor
+---
+
+SDK text now binds explicit type roles, while deprecated UI typography classes carry their bundled Poppins family, allowing the document-wide font reset to be removed without mixed editor typography. `--wb-font-family` no longer rethemes built-in editor text; apply it explicitly to consumer-owned surfaces that need it.
@@ -1,6 +1,6 @@
 ---
 title: Theming
-description: Customise the editor's visual style — fonts, background, tokens — via CSS variables on :root.
+description: Customise the editor's visual style — background, tokens, and consumer-owned typography — via CSS variables.
 sidebar:
   order: 5
 ---
@@ -9,17 +9,21 @@ The aggregated `style.css` ships with the SDK's default visual layer. Override C
 
 ## Typography
 
-Poppins is bundled into `style.css` as inline base64 woff2 (latin + latin-ext, weights 300–700). No external font CDN is contacted at runtime — works under strict CSP, behind GDPR-controlled consent flows, and in air-gapped deployments.
+Built-in text uses bundled type styles: semantic `wb-text-*` roles on migrated surfaces and Poppins-backed deprecated classes on remaining UI primitives. `wb-text-code` uses Inter for token names and IDs; fixed-width editors retain a monospace family. The used Poppins faces are inlined and the remaining bundled faces ship as local woff2 assets, so no external font CDN is contacted at runtime.
 
-Override `--wb-font-family` to use a different face:
+`--wb-font-family` remains available for consumer-owned surfaces that opt into it; built-in roles do not read this variable:
 
 ```css
 :root {
   --wb-font-family: 'Inter', system-ui, -apple-system, sans-serif;
 }
+
+.my-workflow-surface {
+  font-family: var(--wb-font-family);
+}
 ```
 
-Provide the font yourself (via `@font-face`, `@fontsource/<font>`, etc.) — the SDK only consumes the variable.
+Provide any replacement font yourself via `@font-face`, `@fontsource/<font>`, or an equivalent local source.
 
 ## Other tokens
 

@@ -33,6 +33,8 @@ Regular to 400.
 Every family except UI/Code doubles with an `-emphasized` variant
 (`wb-text-title-m-emphasized`), for 39 styles total.
 
+`wb-text-code` is proportional Inter. Editors whose cursor model requires fixed-width glyphs, such as Ace, keep a monospace family while using the role's size, weight, and line-height.
+
 Which role to reach for:
 
 | Context                         | Recommended role                 |
@@ -55,6 +57,6 @@ rem). Until the token export ships them through
 `@workflowbuilder/ui/tokens.css`, the classes define these primitives
 themselves — the migration swaps the source without touching consumers.
 
-The pre-2.0 `ax-public-*` typography classes are deprecated: components move
-to `wb-text-*` as they are redesigned, and the old classes are removed in
-3.0.0. Do not adopt them in new code.
+The pre-2.0 `ax-public-*` typography classes are deprecated and retained only
+for compatibility while components move to `wb-text-*`. Do not adopt them in
+new code; their removal will be announced with a future major release.
@@ -205,12 +205,11 @@ The editor exposes a small set of CSS custom properties for top-level styling. O
 ```css
 :root {
   --wb-background-color: #fafafa;
-  --wb-font-family: 'Inter', system-ui, sans-serif;
   --wb-transition: 0.15s ease-in;
 }
 ```
 
-Available `--wb-*` tokens: `--wb-background-color`, `--wb-font-family`, `--wb-transition`, plus scrollbar styling (`--wb-scroll-width`, `--wb-scroll-radius`, `--wb-scroll-thumb-color`, `--wb-scroll-track-color`).
+Available `--wb-*` tokens: `--wb-background-color`, `--wb-transition`, plus scrollbar styling (`--wb-scroll-width`, `--wb-scroll-radius`, `--wb-scroll-thumb-color`, `--wb-scroll-track-color`). Built-in editor text uses bundled type styles: semantic `wb-text-*` roles on migrated surfaces and Poppins-backed deprecated classes on remaining UI primitives. `--wb-font-family` remains available for consumer-owned surfaces that opt into `font-family: var(--wb-font-family)`; overriding it no longer rethemes built-in text.
 
 Deeper color and spacing customization goes through the generated `--wb-*` design-token layer from `@workflowbuilder/ui`. Hand-authored overrides use `--wb-public-*`. The UI Library's component pages include generated CSS-variable tables for component-local UI overrides. Full guide: [Design system and customization](https://www.workflowbuilder.io/docs/overview/features/design-system-and-customization/).
 

@@ -29,12 +29,12 @@
   }
 
   .large {
-    composes: ax-public-p10 from global;
+    composes: wb-text-body-s from global;
   }
 
   .medium,
   .small {
-    composes: ax-public-p11 from global;
+    composes: wb-text-label-s from global;
   }
   .title {
     font-weight: 600;

@@ -39,7 +39,7 @@ html[data-theme='dark'] .container--warning {
 }
 
 .content {
-  composes: ax-public-p11 from global;
+  composes: wb-text-body-s from global;
 
   padding-top: 1px;
 }
@@ -22,7 +22,6 @@
     align-items: center;
     width: 100%;
     height: 100%;
-    font-size: 1.25rem;
   }
 }
 

@@ -29,7 +29,7 @@ export const Loader = memo(({ isLoading, isSemiTransparent }: LoaderType) => {
 
   return (
     <div className={clsx(styles['container'], visibilityClassName)} style={setLoaderBackgroundOpacityVariable}>
-      <div className={styles['loader']}>{t('loader.text')}</div>
+      <div className={clsx(styles['loader'], 'wb-text-headline-s')}>{t('loader.text')}</div>
     </div>
   );
 });
@@ -60,12 +60,12 @@
 
 .folder-name {
   color: var(--wb-app-bar-folder-name-color);
-  composes: ax-public-p9 from global;
+  composes: wb-text-body-m from global;
 }
 
 .title {
   color: var(--wb-app-bar-diagram-title-color);
-  composes: ax-public-p9 from global;
+  composes: wb-text-body-m from global;
   min-height: 1em;
   min-width: 1em;
   cursor: pointer;

@@ -58,6 +58,7 @@ export function EdgeLabel({
   return (
     <EdgeLabelRenderer>
       <Label
+        className="wb-text-label-m"
         data-edge-label-id={id}
         style={style}
         isHovered={hovered}

@@ -1,5 +1,5 @@
 .label {
-  composes: ax-public-p10 from global;
+  composes: wb-text-body-s from global;
 
   position: absolute;
   pointer-events: auto;

@@ -7,5 +7,5 @@
   border: 1px solid var(--wb-ui-stroke-default);
   color: var(--wb-ui-text-default);
 
-  composes: ax-public-h10 from global;
+  composes: wb-text-body-s-emphasized from global;
 }
@@ -8,7 +8,7 @@
 }
 
 .connectable-item {
-  composes: ax-public-p11 from global;
+  composes: wb-text-node-s from global;
 
   position: relative;
   display: flex;

@@ -15,5 +15,5 @@
   border: var(--wb-node-section-border-width) solid var(--wb-node-section-border-color);
   color: var(--wb-ui-text-default);
 
-  composes: ax-public-h10 from global;
+  composes: wb-text-body-s-emphasized from global;
 }
@@ -58,10 +58,10 @@ export function ImportModal() {
 
   return (
     <div className={styles['container']}>
-      <p className={clsx('ax-public-p10', styles['tip'])}>{t('importExport.importTip')}</p>
+      <p className={clsx('wb-text-body-s', styles['tip'])}>{t('importExport.importTip')}</p>
       <SyntaxHighlighterLazy value={jsonToParse} onChange={(json) => setJsonToParse(json || '{}')} />
       {(errors.length > 0 || warnings.length > 0) && (
-        <div className={clsx('ax-public-p10', styles['error'])}>
+        <div className={clsx('wb-text-body-s', styles['error'])}>
           {[...errors, ...warnings].map(({ message, messageParams }) => (
             <div key={message}>{t(message, messageParams) as string}</div>
           ))}

@@ -59,7 +59,7 @@ export function BranchCard({ branch, index, onUpdate, onRemove, enabled = true }
   return (
     <div className={styles['branch-card']}>
       <div className={styles['header']}>
-        <h1 className="ax-public-h10">{t('decisionBranches.branch', { index: index + 1 })}</h1>
+        <h1 className="wb-text-body-s-emphasized">{t('decisionBranches.branch', { index: index + 1 })}</h1>
         <div className={styles['actions']}>
           <NavButton
             aria-label={t('common.edit')}
@@ -80,7 +80,7 @@ export function BranchCard({ branch, index, onUpdate, onRemove, enabled = true }
         </FormControlWithLabel>
       </div>
       <button
-        className={clsx(styles['conditions-chip'], 'ax-public-p11', {
+        className={clsx(styles['conditions-chip'], 'wb-text-label-s', {
           [styles['no-conditions']]: conditionCount === 0,
         })}
         onClick={onClickEdit}

@@ -43,7 +43,7 @@ function DynamicConditionsControl(props: DynamicConditionsControlProps) {
   return (
     <div className={styles['container']}>
       <div className={styles['header']}>
-        <span className={clsx('ax-public-h10', styles['title'])}>{t('title')}</span>
+        <span className={clsx('wb-text-body-s-emphasized', styles['title'])}>{t('title')}</span>
         <NavButton
           aria-label={t('title')}
           size="s"

@@ -3,7 +3,7 @@
 }
 
 .container {
-  composes: ax-public-p11 from global;
+  composes: wb-text-body-s from global;
   color: var(--wb-public-form-rich-text-color);
 
   a {

@@ -13,7 +13,7 @@ function GroupLayout(props: LayoutProps<GroupLayoutElement>) {
   return (
     <LayoutWrapper {...props}>
       <div className={styles['group-layout']}>
-        <h1 className={clsx(styles['group-header'], 'ax-public-h10')}>{uischema.label}</h1>
+        <h1 className={clsx(styles['group-header'], 'wb-text-body-s-emphasized')}>{uischema.label}</h1>
         {renderElements(props)}
       </div>
     </LayoutWrapper>

@@ -11,7 +11,7 @@ import { withJsonFormsControlProps } from '@jsonforms/react';
 
 function UnknownRenderer({ uischema: { type } }: ControlProps | LayoutProps) {
   return (
-    <div className="ax-public-p10" style={{ color: 'red' }}>
+    <div className="wb-text-body-s" style={{ color: 'red' }}>
       No renderer provided for type: {type}
     </div>
   );

@@ -9,7 +9,7 @@
     font-weight: 700;
   }
 
-  composes: ax-public-p9 from global;
+  composes: wb-text-body-m from global;
   user-select: none;
 }
 

@@ -24,8 +24,8 @@ export function Tile({ icon, title, subTitle, outlined, onClick }: TileProps) {
     >
       <Icon name={icon} size="large" />
       <div className={styles['description']}>
-        <span className={clsx('ax-public-p10', styles['title'])}>{title}</span>
-        {subTitle && <span className={clsx('ax-public-p10', styles['sub-title'])}>{subTitle}</span>}
+        <span className={clsx('wb-text-body-s', styles['title'])}>{title}</span>
+        {subTitle && <span className={clsx('wb-text-body-s', styles['sub-title'])}>{subTitle}</span>}
       </div>
     </div>
   );

@@ -29,7 +29,7 @@ export function TemplateSelector() {
   return (
     <div className={styles['container']}>
       <section className={styles['header']}>
-        <span className={clsx('ax-public-p10', styles['sub-title'])}>
+        <span className={clsx('wb-text-body-s', styles['sub-title'])}>
           <Trans i18nKey="templateSelector.description" components={{ br: <br /> }} />
         </span>
       </section>

@@ -15,7 +15,7 @@ export function PaletteHeader({ onClick, isSidebarExpanded }: PaletteHeaderProps
 
   return (
     <div className={styles['container']}>
-      <span className="ax-public-h7">{t('palette.nodesLibrary')}</span>
+      <span className="wb-text-title-m-emphasized">{t('palette.nodesLibrary')}</span>
       <NavButton
         aria-label={isSidebarExpanded ? t('tooltips.closePalette') : t('tooltips.openPalette')}
         size="s"

@@ -35,8 +35,8 @@ export function PropertiesBarHeader({
         prefixIcon={<Icon name="SidebarSimple" />}
       />
       <div className={styles['text-container']}>
-        <span className={name ? 'ax-public-h9' : 'ax-public-h7'}>{header}</span>
-        {name && <p className="ax-public-p11">{name}</p>}
+        <span className={name ? 'wb-text-title-s-emphasized' : 'wb-text-title-m-emphasized'}>{header}</span>
+        {name && <p className="wb-text-label-s">{name}</p>}
       </div>
       {onDotsClick && (
         <NavButton

@@ -28,18 +28,18 @@ html[data-theme='dark'] {
 }
 
 .container {
+  composes: wb-text-code from global;
   padding: var(--wb-public-input-padding-medium);
   padding-right: 0;
   border-radius: var(--wb-public-input-border-radius-medium);
   border: var(--wb-public-input-root-border-size) solid var(--wb-public-input-root-border-color);
   /* border-bottom: 1px solid var(--wb-public-textarea-root-border-color); */
   /* transition: all var(--wb-public-transition); */
 
-  * {
-    font-family: monospace !important;
-  }
-
   :global(.ace_editor) {
+    /* Ace positions content from one measured glyph width, so its editor must remain monospaced. */
+    font: inherit !important;
+    font-family: monospace !important;
     padding: var(--wb-public-input-padding-medium);
     color: var(--wb-syntax-highlighter-color) !important;
     background-color: transparent;

@@ -27,8 +27,6 @@ export function SyntaxHighlighter(props: SyntaxHighlighterProps) {
         mode={mode}
         theme="github_light_default"
         onChange={onChange}
-        fontSize={12}
-        lineHeight={16}
         showPrintMargin={false}
         showGutter={false}
         highlightActiveLine={false}

@@ -34,6 +34,7 @@
 }
 
 .input {
+  composes: wb-text-label-m from global;
   position: relative;
   z-index: 1;
   display: block;
@@ -43,9 +44,6 @@
   border: none;
   background: transparent;
   color: unset;
-  font: inherit;
-  font-size: 0.75rem;
-  font-weight: 400;
   line-height: 140%;
   outline: none;
   resize: none;
@@ -69,13 +67,11 @@
  * which have no effect without Tailwind — we must set them manually.
  */
 .highlighter {
+  composes: wb-text-label-m from global;
   padding: var(--wb-public-input-padding-medium);
   border: none;
   background: transparent;
   color: transparent;
-  font: inherit;
-  font-size: 0.75rem;
-  font-weight: 400;
   line-height: 140%;
   box-sizing: border-box;
   overflow: hidden;
@@ -145,7 +141,7 @@ body:has(.suggestionsContainer) {
 }
 
 .suggestionsTitle {
-  composes: ax-public-h10 from global;
+  composes: wb-text-body-s-emphasized from global;
   color: var(--wb-ui-text-default);
 }
 
@@ -172,7 +168,7 @@ body:has(.suggestionsContainer) {
 }
 
 .groupHeader {
-  composes: ax-public-h10 from global;
+  composes: wb-text-body-s-emphasized from global;
   color: var(--wb-ui-text-default);
   display: flex;
   color: var(--wb-ui-text-default);
@@ -218,11 +214,11 @@ body:has(.suggestionsContainer) {
 
 .suggestionLabel {
   color: var(--wb-ui-text-default);
-  composes: ax-public-h10 from global;
+  composes: wb-text-body-s-emphasized from global;
 }
 
 .suggestionDescription {
-  composes: ax-public-p11 from global;
+  composes: wb-text-body-s from global;
   color: var(--wb-ui-text-subtle-default);
   display: -webkit-box;
   -webkit-line-clamp: 2;