@sorb/seed reference

When you finish this page you know the sorb-seed CLI, the Style Dictionary formats it registers, and the library exports for scripting your own token pipeline or hardcoded-style scan. You need Node 20 and, for resolve, a style-dictionary config; capture additionally needs a running Storybook and Playwright's Chromium.

npm install -D @sorb/seed style-dictionary

capture needs Playwright's Chromium browser separately — npm install playwright && npx playwright install chromium — an optional peer dependency so a plain resolve-only install stays light.

CLI commands

sorb-seed --help / -h prints usage; --version / -v prints the installed version. There is no annotate command — annotateTree is the internal binder capture calls, not a CLI verb.

The smallest sd.config.js

resolve reads whatever style-dictionary config your sorb.config.json points at (default sd.config.js). The smallest one that produces a resolved map:

// sd.config.js
import StyleDictionary from 'style-dictionary'
import { SORB_RESOLVED, sorbResolved, SORB_SET_META, sorbSetMeta } from '@sorb/seed'

StyleDictionary.registerParser(sorbSetMeta)
StyleDictionary.registerFormat({ name: SORB_RESOLVED, format: sorbResolved })

export default {
  source: ['tokens/primitive.json', 'tokens/semantic.json', 'tokens/component.json'],
  parsers: [SORB_SET_META],
  platforms: {
    sorb: {
      transformGroup: 'css',
      buildPath: '.sorb/',
      files: [{ destination: 'resolved.json', format: SORB_RESOLVED }],
    },
  },
}

sorb dev (from @sorb/juice) serves the resulting .sorb/resolved.json at GET /tokens/resolved; the Sorb plugin's Sync Variables button and capture's annotator both read it. A real app's sd.config.js — lifted verbatim from the reference app — also emits variables.css, a styled-components theme, and the framework format(s) below; see sorb-demo/sd.config.js.

Style Dictionary formats

Every format below is a StyleDictionary.registerFormat({ name, format }) call (or registerParser for the one parser); reference it in a platforms.<key>.files[] entry the same way as any other Style Dictionary format.

Semantic-role contract. Every framework format (SORB_MANTINE_VARS, SORB_SHADCN, SORB_MUI_VARS, SORB_MAT_SYS_VARS, SORB_PRIMEVUE_PRESET) resolves a canonical set of role ids (color.brand, radius.control, …) through an optional options.roleMap, defaulting to identity for a kit that already uses the canonical ids as its own token ids. See @sorb/core's role-id contract and each format's options typedef in the types table below. SORB_MUI_VARS additionally requires options.seedValues (a literal fallback per role) — MUI's createTheme({ cssVariables: true }) needs a real color to compute contrast/tonal variants.

Adapt: find hardcoded styles and map them to tokens

sorb-seed adapt scans an existing React codebase for hardcoded color/dimension style literals (JSX inline style={{ }}, styled-components template literals, plain style objects) and maps each one to the nearest token in your resolved map — the on-ramp for a codebase that predates Sorb. A value already written as var(--…) is never flagged.

sorb-seed adapt                                # report mode, default glob
sorb-seed adapt --mode codemod --write         # rewrite matched sites in place

Each detected site scores auto (one unambiguous on-role candidate), review (bound but ambiguous — off-role or multiple candidates), or unmapped (no token matched), via the single AUTO_THRESHOLD (0.9) cut. --mode codemod only ever rewrites auto-status sites.

Library exports for scripting the adapter:

Exports

buildTokenIndex

const buildTokenIndex = (resolved)

Build value→[token] indexes (colors, dims) from the resolved bindable map.

Returns { colors: Map, dims: Map, dropped: {id, value, reason: [] }} dropped (REC-1/2/6) records every token whose value normalized to null — unresolved-alias / cycle / unparseable-color / no-match — so a silent vanish becomes observable. Backward-compatible: {colors, dims} destructure still works.

tierOfFile

const tierOfFile = (filePath = '')

Derive the token tier from the source file a token came from.

Returns 'primitive'\|'semantic'\|'component'\|'unknown'.

sorbTokenSet

const sorbTokenSet = ({ dictionary })

Flat TokenSet ESM module for @sorb/leaf's SorbProvider — one entry per token, keyed by the CSS-var name WITHOUT the leading -- (leaf's applyTokens re-adds it via setProperty('--' + key, value)). This is the committed token set bundled into the app at build time: export const tokens = { 'color-action-primary': '#0f65ef', ... } Same names/values as variables.css and resolved.json (one source, many surfaces). Consumed by main.jsx / src/sorbConfig.js.

sorbAliases

const sorbAliases = ({ dictionary, options })

format: sorb/aliases-css — legacy back-compat layer (migration window). Reads options.aliases ({ legacyName: "new.dtcg.id" }) and emits --legacyName: var(--new-dtcg-id); Each target is validated against the built tokens; unknown targets warn and are skipped. Drop this platform once nothing references the legacy names.

sorbThemeNested

const sorbThemeNested = ({ dictionary })

format: sorb/theme-nested Emits a nested object of var(--kebab, <fallback>) strings so a styled-components theme can read theme.color.action.primary. The fallback is the committed value, so with no preview active rendering is unchanged.

tailwindThemeEntry

const tailwindThemeEntry = (t)

Map one Sorb token to a Tailwind v4 @theme entry: { key, ref }. key is the theme variable name — its prefix picks the Tailwind utility family (--color-*→bg/text/border, --radius-*→rounded, --spacing-*→ p/m/gap/w/h, --text-*→font-size, --font-weight-*→font weight). ref is always var(<the token's own --css-var>) so the value stays a reference to the same runtime-swappable var the bridge overrides — never a baked literal. Because Sorb already names color vars --color-* (colliding with Tailwind's own namespace), the format emits @theme inline, where Tailwind uses the ref expression directly in utilities instead of redefining the key in :root.

Returns {key: string, ref: string: }

sorbTailwind

const sorbTailwind = ({ dictionary })

format: sorb/tailwind-theme Emits a Tailwind v4 @theme inline { … } block — one entry per resolved token, each value a var(--token) reference. Pair it with variables.css (which defines those vars) so Tailwind utilities resolve through the exact CSS vars the bridge swaps at runtime → live preview works with zero Tailwind-specific bridge code. Duplicate theme keys are skipped (warned).

tailwindV3Slot

const tailwindV3Slot = (t)

Classify one Sorb token into a Tailwind v3 theme.extend slot. Returns the category (colors|borderRadius|spacing|fontSize|fontWeight), the nested key path within it (Tailwind v3 flattens nested keys with -, so colors.action.primary → utility bg-action-primary), and the var() ref. Returns null for token types with no v3 utility family.

Returns {category: string, keyPath: string[], ref: string: |null}

sorbTailwindV3

const sorbTailwindV3 = ({ dictionary })

format: sorb/tailwind-v3-preset Emits a Tailwind v3 preset (CommonJS) — theme.extend.{colors,borderRadius, spacing,fontSize,fontWeight} whose leaves are var(--token) strings grouped by tier/role. Consumer: presets: [require('./tailwind-sorb-preset.cjs')]. Same live-preview behavior as v4 — utilities reference the runtime-swappable Sorb vars.

MANTINE_VAR_MAP

const MANTINE_VAR_MAP

role id (JJ id when unmapped) → Mantine CSS var name. Left side is resolved through options.roleMap at format time (identity when the kit uses these ids directly — the JJ reference); right side is the Mantine v7 documented variable it overrides.

sorbMantineVars

const sorbMantineVars = ({ dictionary, options })

format: sorb/mantine-vars Emits a CSS file that redeclares the mapped --mantine-* vars as var(--<kit-token>) !important refs. options.roleMap (role id → kit token id) lets a non-JJ kit reuse this format unmodified; defaults to the canonical/JJ ids (identity resolution) when omitted.

Returns string: the generated CSS.

sorbShadcn

const sorbShadcn = ({ dictionary, options } = {})

format: sorb/shadcn-theme Emits ONE CSS artifact: shadcn's :root{} semantic-var map (chained onto Sorb tokens via the role contract) followed by the @theme inline{} Tailwind-utility binding block — reproducing what sorb-demo-tailwind/src/tokens/shadcn-map.css + shadcn-theme.css hand- authored. Pair with variables.css (defines the Sorb vars this format references) in the consumer's CSS import order: @import "tailwindcss"; @import "./variables.css"; sorb tokens — the bridge swaps these live @import "./shadcn-theme.css"; this file

Returns string.

shadcnRootLines

const shadcnRootLines = (options = {}, knownTokenIds)

Build the :root{} shadcn-var → Sorb-token map, resolving roles through options.roleMap (defaulting to identity — the JJ reference kit already uses canonical role ids).

Returns string[]: lines

MUI_VAR_MAP

const MUI_VAR_MAP

role id (JJ id when unmapped) → MUI CSS var name. Left side is resolved through options.roleMap at format time (identity when the kit uses these ids directly — the JJ reference); right side is the MUI v6 documented cssVariables:true var it overrides.

sorbMuiVars

const sorbMuiVars = ({ dictionary, options })

format: sorb/mui-vars Emits a CSS file that redeclares the mapped --mui-* vars as var(--<kit-token>, <seed-fallback>) !important refs. options.roleMap (role id → kit token id) lets a non-JJ kit reuse this format unmodified; defaults to the canonical/JJ ids (identity resolution) when omitted. options.seedValues (role id → literal fallback) is REQUIRED to avoid baking any one kit's hex values into the public format — a role with no seedValues entry emits var(--kit-token) with no fallback.

Returns string: the generated CSS.

MAT_SYS_MAP

const MAT_SYS_MAP

Angular Material --mat-sys-* CSS var name → role id (JJ id when unmapped). The role id is resolved through options.roleMap at format time (identity when the kit uses these ids directly — the JJ reference). Semantic-tier-first per the field corrections carried from P2/P4: only the handful of system roots Material's own components actually cascade from — not every --mat-sys-* var Material defines (many, e.g. per-component elevation/state-layer opacities, aren't part of the kit's vocabulary and are intentionally left at Material's own defaults).

sorbMatSysVars

const sorbMatSysVars = ({ dictionary, options })

format: sorb/mat-sys-vars Emits a CSS file that redeclares the mapped --mat-sys-* vars as var(--<kit-token>) !important refs. options.roleMap (role id → kit token id) lets a non-JJ kit reuse this format unmodified; defaults to the canonical/JJ ids (identity resolution) when omitted.

Returns string: the generated CSS.

PRIMEVUE_ROLE_TREE

const PRIMEVUE_ROLE_TREE

Structural role tree describing the PrimeVue definePreset shape this format generates, mirroring jjPreset.js's hand-authored nesting exactly. Every leaf is a role id (a dot-path token id, canonical-or-JJ) resolved through options.roleMap before becoming a var(--kebab-id) ref.

sorbPrimevuePreset

const sorbPrimevuePreset = ({ dictionary, options })

format: sorb/primevue-preset Emits a JS/ESM module string: import { definePreset } from '@primeuix/themes'; import Aura from '@primeuix/themes/aura'; export const preset = definePreset(Aura, { semantic: {...}, components: {...} }); Every leaf is a var(--kebab-token-id) string — the live-preview invariant, same as every other Sorb format (no baked literals). Pure function of {dictionary, options}; zero style-dictionary dep.

Returns string: the generated ESM module source.

detectHardcoded

function detectHardcoded(source, filename)

Detect hardcoded color/dimension style sites in source.

Returns import('./types.js').AdaptSite[].

propToRole

const propToRole = (prop)

Map a CSS/JSX property name → matcher role. Accepts both kebab-case (CSS, styled-components) and camelCase (JSX inline style). Non-roled props → null (still detected, matched tier-only).

Returns import('./types.js').AdaptRole.

parseSource

const parseSource = (source)

Parse source into a Babel AST. jsx + typescript plugins so .jsx AND .tsx both parse (we parse a consumer's TS source; we never emit TS).

classifyColor

const classifyColor = (value)

Classify a value as a color.

Returns { hex: string\|null, status: 'ok'\|'no-match'\|'unparseable': } - ok: parsed → canonical hex - no-match: a clean value that just isn't a color (e.g. '4px', a dimension) - unparseable: looks color-ish (a #… / rgb(…) / named shape) but is malformed

mapToToken

function mapToToken(site, index, resolved)

Map one detected site → its nearest resolved token + confidence.

Returns import('./types.js').AdaptMapping.

statusFor

function statusFor(mapping)

Map a confidence score to a report status using the single AUTO_THRESHOLD cut.

Returns 'auto'\|'review'\|'unmapped'.

resolveCssVar

function resolveCssVar(tokenId, resolved)

Look up a token's cssVar from the resolved map (so the report carries the --var for the codemod/shim). Falls back to deriving it from the id when the resolved map isn't supplied.

Types

JSDoc typedefs. Import them in your own JSDoc with import('@sorb/seed').Name.

AdaptRole

A CSS property "role" the matcher understands. Drives property affinity in matchColor/matchDimension (annotateTokens.js). null ⇒ tier-only match.

type AdaptRole = 'bg'|'text'|'border'|'radius'|null

Source: src/adapt/types.js:7

AdaptSite

A single detected hardcoded style site in consumer source.

Source: src/adapt/types.js:13

AdaptMapping

The result of mapping one site to the nearest resolved token.

Source: src/adapt/types.js:28

AdaptRow

A fully scored report row (detect → map → score). Emitted to .sorb/adapt-report.json.

Source: src/adapt/types.js:38

DetectHardcodedResult

Return value of detectHardcoded(source, filename) — every hardcoded color/dimension style site found in one source file.

type DetectHardcodedResult = AdaptSite[]

Source: src/types.js:15

MapToTokenResult

Return value of mapToToken(site, index, resolved) — one detected site mapped to its nearest resolved token plus a confidence score. Identical shape to AdaptMapping; named for the function that produces it.

type MapToTokenResult = AdaptMapping

Source: src/types.js:21

RoleMapOptions

options accepted by every role-resolved framework format (sorb/mantine-vars, sorb/shadcn-theme, sorb/mat-sys-vars, and the base case of sorb/mui-vars / sorb/primevue-preset). Omit entirely for a kit that already uses the canonical role ids as its own token ids (identity mapping).

Source: src/types.js:28

MuiFormatOptions

options for sorb/mui-vars. MUI's createTheme({ cssVariables: true }) needs a real literal to compute contrast/tonal variants, so seedValues is REQUIRED — a role with no entry emits var(--token) with no fallback.

Source: src/types.js:37

PrimevueFormatOptions

options for sorb/primevue-preset. roleMap here maps PrimeVue's own role tree (PRIMEVUE_ROLE_TREE) entries -> your kit's token ids, not the generic color/radius/shadow/typography roles.

Source: src/types.js:46

Next

• @sorb/core — the role-id contract the framework formats resolve against.
• @sorb/leaf — SORB_TOKENSET's consumer, SorbProvider.
• The bridge — how sorb dev serves the resolved map this package builds.

Works with Figma. Not affiliated with, or endorsed by, Figma. Figma is a trademark of Figma, Inc.