@sorb/seed 0.2.0 → 0.3.0

package/src/emit/sorbFormat.js

@@ -0,0 +1,313 @@
+// Sorb custom Style Dictionary outputs.
+//
+// The key piece of the token pipeline: a "resolved bindable map" that Sorb's
+// bridge serves, capture annotates against, and the plugin syncs to Figma. One
+// build, one map — this is what retires the runtime esbuild-eval resolver and
+// fixes the "two token lists" problem.
+//
+// Promoted here from `sorb-demo/sd/sorb-format.js` (component-compat-roadmap
+// P0, part 2) — these formats used to live copy-locally in the demo app.
+// `@sorb/seed` is the shared home so target adapters (Tailwind/shadcn/
+// Mantine/… per the roadmap) IMPORT these formats instead of copy-pasting
+// them again. Pure functions of Style Dictionary's `{ dictionary, options }`
+// shape — no dependency on `style-dictionary` itself, so this file has zero
+// new deps for `@sorb/seed`. `sorb-demo/sd/sorb-format.js` now re-exports
+// from here for back-compat.
+
+/**
+ * Derive the token tier from the source file a token came from.
+ * @param {string} filePath
+ * @returns {'primitive'|'semantic'|'component'|'unknown'}
+ */
+export const tierOfFile = (filePath = '') =>
+  /primitive\./.test(filePath) ? 'primitive'
+  : /semantic\./.test(filePath) ? 'semantic'
+  : /component\./.test(filePath) ? 'component'
+  // bs.json — the bootstrap-styled brand overlay. Classified as `semantic` (a
+  // core-valid tier) so its `--bs-*` roles group + bind alongside the other
+  // semantic roles rather than falling through to an unranked `unknown` tier.
+  : /bs\./.test(filePath) ? 'semantic'
+  : 'unknown'
+
+export const SORB_RESOLVED = 'sorb/resolved-map'
+export const SORB_THEME_NESTED = 'sorb/theme-nested'
+export const SORB_ALIASES = 'sorb/aliases-css'
+export const SORB_VERSIONS = 'sorb/versions'
+export const SORB_SET_META = 'sorb/set-meta'
+export const SORB_TAILWIND = 'sorb/tailwind-theme'
+export const SORB_TAILWIND_V3 = 'sorb/tailwind-v3-preset'
+export const SORB_TOKENSET = 'sorb/tokenset-esm'
+
+// ─── set-level metadata parser ───────────────────────────────────────────────
+// Per-set `$version` lives at each token file's root. SD merges all sources
+// into one tree, so three root `$version` keys collide ("token collision")
+// during merge — and per-set versions wouldn't survive anyway. This parser runs
+// PER FILE before the merge: it lifts `$version` out (stashing it by file) and
+// strips it from the tree, so the merge is clean and versions are preserved for
+// the `sorb/versions` output. (A preprocessor runs post-merge — too late.)
+const _setVersions = {}
+export const sorbSetMeta = {
+  name: SORB_SET_META,
+  pattern: /\.json$/,
+  parser: ({ filePath, contents }) => {
+    const obj = JSON.parse(contents)
+    if (obj.$version != null) {
+      _setVersions[tierOfFile(filePath)] = obj.$version
+      delete obj.$version
+    }
+    return obj
+  },
+}
+
+/** format: sorb/versions — { primitive, semantic, component } → version. */
+export const sorbVersions = () =>
+  JSON.stringify(_setVersions, null, 2) + '\n'
+
+const cssNameOf = (id) => '--' + String(id).split('.').join('-')
+
+/**
+ * format: sorb/resolved-map
+ * Emits the bindable map: one entry per token. Schema:
+ * { id, cssVar, value, tier, type } plus { deprecated, replacedBy } when set.
+ */
+/**
+ * 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`.
+ */
+export const sorbTokenSet = ({ dictionary }) => {
+  const out = {}
+  for (const t of dictionary.allTokens) {
+    out[t.path.join('-')] = t.$value ?? t.value
+  }
+  return 'export const tokens = ' + JSON.stringify(out, null, 2) + '\n'
+}
+
+export const sorbResolved = ({ dictionary }) => {
+  const deprecated = []
+  const out = dictionary.allTokens.map((t) => {
+    const entry = {
+      id: t.path.join('.'), //            color.action.primary
+      cssVar: '--' + t.path.join('-'), // --color-action-primary
+      value: t.$value ?? t.value, //      resolved (refs followed); SD v4 DTCG → $value
+      tier: tierOfFile(t.filePath), //    primitive | semantic | component
+      type: t.$type ?? t.type, //         color | dimension | fontWeight | …
+    }
+    if (t.$deprecated) {
+      entry.deprecated = true
+      const rb = t.$extensions && t.$extensions.sorb && t.$extensions.sorb.replacedBy
+      if (rb) entry.replacedBy = rb
+      deprecated.push(entry.id + (rb ? ` → ${rb}` : ''))
+    }
+    return entry
+  })
+  if (deprecated.length) {
+    console.warn(`  ⚠ ${deprecated.length} deprecated token(s): ` + deprecated.join(', '))
+  }
+  return JSON.stringify(out, null, 2) + '\n'
+}
+
+/**
+ * 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.
+ */
+export const sorbAliases = ({ dictionary, options }) => {
+  const aliases = (options && options.aliases) || {}
+  const known = new Set(dictionary.allTokens.map((t) => t.path.join('.')))
+  const lines = ['/* AUTO-GENERATED legacy alias layer — @deprecated, remove after migration. */', ':root {']
+  const missing = []
+  for (const legacy of Object.keys(aliases)) {
+    if (legacy.startsWith('$')) continue // skip $comment / metadata keys
+    const targetId = aliases[legacy]
+    if (!known.has(targetId)) { missing.push(`${legacy} → ${targetId}`); continue }
+    lines.push(`  --${legacy}: var(${cssNameOf(targetId)}); /* @deprecated → ${targetId} */`)
+  }
+  lines.push('}', '')
+  if (missing.length) {
+    console.warn(`  ⚠ aliases.json: ${missing.length} unknown target(s) skipped: ` + missing.join(', '))
+  }
+  return lines.join('\n')
+}
+
+/**
+ * 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.
+ */
+export const sorbThemeNested = ({ dictionary }) => {
+  const root = {}
+  for (const t of dictionary.allTokens) {
+    const cssVar = '--' + t.path.join('-')
+    let node = root
+    for (let i = 0; i < t.path.length - 1; i++) {
+      const k = t.path[i]
+      node[k] = node[k] || {}
+      node = node[k]
+    }
+    node[t.path[t.path.length - 1]] = `var(${cssVar}, ${t.$value ?? t.value})`
+  }
+  return (
+    '// AUTO-GENERATED by Style Dictionary — do not edit.\n' +
+    'export default ' +
+    JSON.stringify(root, null, 2) +
+    '\n'
+  )
+}
+
+/**
+ * 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`.
+ * @param {{path: string[], $type?: string, type?: string}} t
+ * @returns {{key: string, ref: string}}
+ */
+export const tailwindThemeEntry = (t) => {
+  const slug = t.path.join('-') //               color-action-primary | button-radius
+  const ref = `var(--${slug})` //                points back at the Sorb css var
+  const type = t.$type ?? t.type
+  const strip = (re) => slug.replace(re, '').replace(/^-+|-+$/g, '')
+
+  if (type === 'color') {
+    // semantic/primitive already start with `color-`; component colors
+    // (button-primary-bg-default) keep their full path under the color family.
+    const name = slug.startsWith('color-') ? slug.slice('color-'.length) : slug
+    return { key: `--color-${name}`, ref }
+  }
+  if (type === 'fontWeight') {
+    return { key: `--font-weight-${strip(/font-weight-?/)}`, ref }
+  }
+  if (type === 'dimension') {
+    if (t.path.includes('radius')) {
+      // radius-100 → 100 ; button-radius → button  (→ rounded-100 / rounded-button)
+      return { key: `--radius-${strip(/-?radius-?/) || 'DEFAULT'}`, ref }
+    }
+    if (t.path.includes('space') || t.path.includes('spacing')) {
+      return { key: `--spacing-${strip(/space-?/)}`, ref }
+    }
+    if (t.path.includes('size')) {
+      return { key: `--text-${strip(/font-size-?|size-?/)}`, ref }
+    }
+    return { key: `--spacing-${slug}`, ref } // unknown dimension → spacing family
+  }
+  return { key: `--sorb-${slug}`, ref } // anything else: registered, no utility family
+}
+
+/**
+ * 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).
+ */
+export const sorbTailwind = ({ dictionary }) => {
+  const seen = new Map() // key → originating token id (collision guard)
+  const dupes = []
+  const lines = []
+  for (const t of dictionary.allTokens) {
+    const { key, ref } = tailwindThemeEntry(t)
+    const id = t.path.join('.')
+    if (seen.has(key)) { dupes.push(`${key} (${seen.get(key)} vs ${id})`); continue }
+    seen.set(key, id)
+    lines.push(`  ${key}: ${ref};`)
+  }
+  if (dupes.length) {
+    console.warn(`  ⚠ tailwind: ${dupes.length} duplicate theme key(s) skipped: ` + dupes.join(', '))
+  }
+  return (
+    '/* AUTO-GENERATED by Style Dictionary (sorb/tailwind-theme) — do not edit.\n' +
+    '   Tailwind v4 theme mapped onto Sorb\'s runtime CSS vars. Import order in your\n' +
+    '   entry CSS:\n' +
+    '       @import "tailwindcss";\n' +
+    '       @import "./variables.css";       sorb tokens — the bridge swaps these live\n' +
+    '       @import "./tailwind-theme.css";  this file\n' +
+    '   `@theme inline` makes utilities reference var(--token) directly, so a\n' +
+    '   POST /preview recolors Tailwind-classed elements with no extra code. */\n' +
+    '@theme inline {\n' +
+    lines.join('\n') +
+    '\n}\n'
+  )
+}
+
+/**
+ * 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.
+ * @param {{path: string[], $type?: string, type?: string}} t
+ * @returns {{category: string, keyPath: string[], ref: string}|null}
+ */
+export const tailwindV3Slot = (t) => {
+  const ref = `var(--${t.path.join('-')})`
+  const type = t.$type ?? t.type
+  const without = (seg) => t.path.filter((p) => p !== seg)
+
+  if (type === 'color') {
+    // strip a leading `color` segment (semantic/primitive); component colors keep full path
+    const keyPath = t.path[0] === 'color' ? t.path.slice(1) : t.path.slice()
+    return { category: 'colors', keyPath, ref }
+  }
+  if (type === 'fontWeight') {
+    return { category: 'fontWeight', keyPath: t.path.filter((p) => p !== 'font' && p !== 'weight'), ref }
+  }
+  if (type === 'dimension') {
+    if (t.path.includes('radius')) return { category: 'borderRadius', keyPath: without('radius'), ref }
+    if (t.path.includes('space') || t.path.includes('spacing'))
+      return { category: 'spacing', keyPath: t.path.filter((p) => p !== 'space' && p !== 'spacing'), ref }
+    if (t.path.includes('size'))
+      return { category: 'fontSize', keyPath: t.path.filter((p) => p !== 'font' && p !== 'size'), ref }
+    return { category: 'spacing', keyPath: t.path.slice(), ref } // unknown dimension → spacing
+  }
+  return null // unknown type → no v3 utility family
+}
+
+/**
+ * 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.
+ */
+export const sorbTailwindV3 = ({ dictionary }) => {
+  const theme = { colors: {}, borderRadius: {}, spacing: {}, fontSize: {}, fontWeight: {} }
+  const skipped = []
+  for (const t of dictionary.allTokens) {
+    const slot = tailwindV3Slot(t)
+    if (!slot) { skipped.push(t.path.join('.')); continue }
+    let node = theme[slot.category]
+    for (let i = 0; i < slot.keyPath.length - 1; i++) {
+      const k = slot.keyPath[i]
+      node[k] = node[k] || {}
+      node = node[k]
+    }
+    node[slot.keyPath[slot.keyPath.length - 1]] = slot.ref
+  }
+  if (skipped.length) {
+    console.warn(`  ⚠ tailwind-v3: ${skipped.length} token(s) with no v3 family skipped: ` + skipped.join(', '))
+  }
+  return (
+    '// AUTO-GENERATED by Style Dictionary (sorb/tailwind-v3-preset) — do not edit.\n' +
+    '// Tailwind v3 preset of var(--token) refs from Sorb\'s resolved map. Usage:\n' +
+    '//   presets: [require(\'./tailwind-sorb-preset.cjs\')]\n' +
+    '// Import variables.css globally so the vars resolve; the bridge swaps them live.\n' +
+    'module.exports = ' +
+    JSON.stringify({ theme: { extend: theme } }, null, 2) +
+    '\n'
+  )
+}

package/src/emit/sorbFormat.test.js

@@ -0,0 +1,133 @@
+// Tests for the Sorb Tailwind v4 theme format (`sorb/tailwind-theme`).
+// Run: node --test  (zero-dep, Node's built-in runner — matches the workspace convention).
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { tailwindThemeEntry, sorbTailwind, tailwindV3Slot, sorbTailwindV3 } from './sorbFormat.js'
+
+// Helper: a token as Style Dictionary hands it to a format (path + $type).
+const tok = (id, type) => ({ path: id.split('.'), $type: type })
+
+test('color tokens map to the Tailwind --color-* family, value = var(self)', () => {
+  // semantic: leading `color.` is the namespace, not doubled
+  assert.deepEqual(tailwindThemeEntry(tok('color.action.primary', 'color')), {
+    key: '--color-action-primary',
+    ref: 'var(--color-action-primary)',
+  })
+  // primitive ramp
+  assert.deepEqual(tailwindThemeEntry(tok('color.blue.300', 'color')), {
+    key: '--color-blue-300',
+    ref: 'var(--color-blue-300)',
+  })
+})
+
+test('component colors keep their full path under the color family', () => {
+  // button.primary.bg.default has $type color but path does NOT start with `color`
+  assert.deepEqual(tailwindThemeEntry(tok('button.primary.bg.default', 'color')), {
+    key: '--color-button-primary-bg-default',
+    ref: 'var(--button-primary-bg-default)', // ref always points at the token's own css var
+  })
+})
+
+test('radius dimensions map to --radius-* (→ rounded-* utilities)', () => {
+  assert.deepEqual(tailwindThemeEntry(tok('radius.100', 'dimension')), {
+    key: '--radius-100',
+    ref: 'var(--radius-100)',
+  })
+  // component radius is remapped into the radius family so rounded-button works
+  assert.deepEqual(tailwindThemeEntry(tok('button.radius', 'dimension')), {
+    key: '--radius-button',
+    ref: 'var(--button-radius)',
+  })
+})
+
+test('space → --spacing-*, font.size → --text-*, fontWeight → --font-weight-*', () => {
+  assert.equal(tailwindThemeEntry(tok('space.200', 'dimension')).key, '--spacing-200')
+  assert.equal(tailwindThemeEntry(tok('space.200', 'dimension')).ref, 'var(--space-200)')
+  assert.equal(tailwindThemeEntry(tok('font.size.300', 'dimension')).key, '--text-300')
+  assert.equal(tailwindThemeEntry(tok('font.weight.semibold', 'fontWeight')).key, '--font-weight-semibold')
+})
+
+test('the ref is ALWAYS a var() reference, never a baked literal (live-preview invariant)', () => {
+  // This is the property that makes the bridge's runtime var-swap recolor
+  // Tailwind utilities with no Tailwind-specific code. Every entry must be var(…).
+  for (const t of [
+    tok('color.action.primary', 'color'),
+    tok('button.radius', 'dimension'),
+    tok('space.100', 'dimension'),
+  ]) {
+    assert.match(tailwindThemeEntry(t).ref, /^var\(--[a-z0-9-]+\)$/)
+  }
+})
+
+test('sorbTailwind emits an `@theme inline` block, one entry per token', () => {
+  const dictionary = {
+    allTokens: [
+      tok('color.action.primary', 'color'),
+      tok('button.radius', 'dimension'),
+      tok('space.100', 'dimension'),
+    ],
+  }
+  const css = sorbTailwind({ dictionary })
+  assert.match(css, /@theme inline \{/)
+  assert.match(css, /\}\s*$/)
+  assert.match(css, /^ {2}--color-action-primary: var\(--color-action-primary\);$/m)
+  assert.match(css, /^ {2}--radius-button: var\(--button-radius\);$/m)
+  // exactly 3 entries
+  assert.equal((css.match(/: var\(/g) || []).length, 3)
+})
+
+test('duplicate theme keys are skipped (collision guard), not emitted twice', () => {
+  const dictionary = {
+    // two distinct tokens that would collapse to the same theme key
+    allTokens: [tok('color.action.primary', 'color'), tok('color.action.primary', 'color')],
+  }
+  const css = sorbTailwind({ dictionary })
+  assert.equal((css.match(/--color-action-primary: /g) || []).length, 1)
+})
+
+// ─── Tailwind v3 preset (sorb/tailwind-v3-preset) ────────────────────────────
+
+test('v3 slot: colors strip leading `color`, components keep full path', () => {
+  assert.deepEqual(tailwindV3Slot(tok('color.action.primary', 'color')), {
+    category: 'colors', keyPath: ['action', 'primary'], ref: 'var(--color-action-primary)',
+  })
+  assert.deepEqual(tailwindV3Slot(tok('button.primary.bg.default', 'color')), {
+    category: 'colors', keyPath: ['button', 'primary', 'bg', 'default'], ref: 'var(--button-primary-bg-default)',
+  })
+})
+
+test('v3 slot: dimensions/weights map to the right v3 categories', () => {
+  assert.deepEqual(tailwindV3Slot(tok('radius.100', 'dimension')), { category: 'borderRadius', keyPath: ['100'], ref: 'var(--radius-100)' })
+  assert.deepEqual(tailwindV3Slot(tok('button.radius', 'dimension')), { category: 'borderRadius', keyPath: ['button'], ref: 'var(--button-radius)' })
+  assert.deepEqual(tailwindV3Slot(tok('space.200', 'dimension')), { category: 'spacing', keyPath: ['200'], ref: 'var(--space-200)' })
+  assert.deepEqual(tailwindV3Slot(tok('font.size.300', 'dimension')), { category: 'fontSize', keyPath: ['300'], ref: 'var(--font-size-300)' })
+  assert.deepEqual(tailwindV3Slot(tok('font.weight.regular', 'fontWeight')), { category: 'fontWeight', keyPath: ['regular'], ref: 'var(--font-weight-regular)' })
+})
+
+test('v3 slot: unknown type → null (no v3 family)', () => {
+  assert.equal(tailwindV3Slot({ path: ['z', 'index'], $type: 'number' }), null)
+})
+
+test('sorbTailwindV3 emits a requireable preset with nested theme.extend of var() refs', () => {
+  const dictionary = {
+    allTokens: [
+      tok('color.action.primary', 'color'),
+      tok('button.primary.bg.default', 'color'),
+      tok('button.radius', 'dimension'),
+      tok('space.100', 'dimension'),
+    ],
+  }
+  const src = sorbTailwindV3({ dictionary })
+  assert.match(src, /^module\.exports = /m)
+  // evaluate the generated CommonJS to prove it's a valid, requireable preset
+  const mod = { exports: {} }
+  new Function('module', 'exports', src)(mod, mod.exports)
+  const ext = mod.exports.theme.extend
+  assert.equal(ext.colors.action.primary, 'var(--color-action-primary)') // → bg-action-primary
+  assert.equal(ext.colors.button.primary.bg.default, 'var(--button-primary-bg-default)')
+  assert.equal(ext.borderRadius.button, 'var(--button-radius)') // → rounded-button
+  assert.equal(ext.spacing['100'], 'var(--space-100)') // → p-100
+  // every leaf is a var() ref (the live-preview invariant), never a literal
+  const leaves = (o) => Object.values(o).flatMap((v) => (typeof v === 'string' ? [v] : leaves(v)))
+  for (const v of leaves(ext)) assert.match(v, /^var\(--[a-z0-9-]+\)$/)
+})

package/src/index.js

@@ -5,3 +5,30 @@
 // so the old `resolveBindableTokens` export is gone. What remains useful as a
 // library is the token-annotation layer used by `capture`.
 export { buildTokenIndex, annotateTree, matchColor, matchDimension } from './annotateTokens.js'
+
+// Sorb's custom Style Dictionary outputs (component-compat-roadmap P0, part
+// 2) — promoted from sorb-demo's copy-local `sd/sorb-format.js` so target
+// adapters import these formats instead of duplicating them. A consumer's
+// `sd.config.js` registers these with `StyleDictionary.registerFormat`/
+// `registerParser` the same way sorb-demo's does.
+export {
+  tierOfFile,
+  SORB_RESOLVED,
+  SORB_THEME_NESTED,
+  SORB_ALIASES,
+  SORB_VERSIONS,
+  SORB_SET_META,
+  SORB_TAILWIND,
+  SORB_TAILWIND_V3,
+  SORB_TOKENSET,
+  sorbSetMeta,
+  sorbVersions,
+  sorbTokenSet,
+  sorbResolved,
+  sorbAliases,
+  sorbThemeNested,
+  tailwindThemeEntry,
+  sorbTailwind,
+  tailwindV3Slot,
+  sorbTailwindV3,
+} from './emit/sorbFormat.js'

package/src/sources/figmaPlugin.js

@@ -0,0 +1,83 @@
+// `figma-plugin` SourceConnector — the DEFAULT Figma tokens source (all
+// tiers; no Enterprise gate). spec/sorb/figma-source-connector.md §1a.
+//
+// Unlike `storybook-dom` (a local Playwright/Node process this package drives
+// directly), this connector's data does NOT come from a locally-callable API.
+// It comes from the Figma plugin (`sorb-canopy`), which reads
+// `figma.variables.*` **in-file** (via the shared token-mapping walk —
+// `sorb-canopy/lib/token-mapping.js`), maps it to Sorb's resolved-map shape,
+// and PUSHES it to the juice bridge (`POST /tokens/figma`, the plugin's
+// "Export variables" action). So this connector is a BRIDGE CLIENT, not a
+// Figma caller — spec's flagged riskiest coupling ("the plugin is the
+// executor, the seed-side connector is a bridge client"). `readTokens()`
+// reads the latest pushed artifact back via `GET /tokens/figma`.
+//
+// v1 scope is tokens-first (figma-source-connector.md §1a Fork F /
+// §R "Cut"): `listUnits`/`captureGeometry` need a geometry-capable bridge
+// endpoint the plugin doesn't push yet (component/node geometry, not just
+// variables) — that's a deferred follow-on phase, so they throw a clear,
+// actionable error instead of pretending to call Figma directly.
+//
+// No local token-mapping fork: this connector does no Figma-value mapping of
+// its own — the resolved-map entries it reads back already match
+// `@sorb/core`'s `ResolvedToken` shape because `sorb-canopy/lib/token-
+// mapping.js` produced them before the push. There is nothing to share/
+// extract on the seed side (the mapping stays owned by canopy, the one place
+// that actually touches `figma.variables.*`).
+
+import { registerSource } from '@sorb/core'
+
+// sorb.config.json may set seed.bridgeOrigin (mirrors storybookUrlOf's
+// seed.storybookUrl convention). Falls back to juice's default dev port.
+export const bridgeOriginOf = (config) =>
+  ((config && config.seed && config.seed.bridgeOrigin) || (config && config.bridgeOrigin) || 'http://localhost:7777').replace(
+    /\/$/,
+    '',
+  )
+
+const readTokens = async (config) => {
+  const origin = bridgeOriginOf(config)
+  const url = `${origin}/tokens/figma`
+  let res
+  try {
+    res = await fetch(url)
+  } catch (e) {
+    throw new Error(
+      `figma-plugin source: could not reach the bridge at ${origin} (${e.message}). ` +
+        'Run `sorb dev` first.',
+    )
+  }
+  if (res.status === 404) {
+    throw new Error(
+      'figma-plugin source: no Figma export yet — in the Sorb Figma plugin, run ' +
+        `"Export variables" (bridge: ${origin}).`,
+    )
+  }
+  if (!res.ok) {
+    throw new Error(`figma-plugin source: bridge GET /tokens/figma failed — HTTP ${res.status}`)
+  }
+  const artifact = await res.json()
+  return Array.isArray(artifact.tokens) ? artifact.tokens : []
+}
+
+const GEOMETRY_NOT_YET_IMPLEMENTED =
+  'figma-plugin source: listUnits/captureGeometry are not implemented in v1 (tokens-first — ' +
+  'see spec/sorb/figma-source-connector.md §1a Fork F). Use readTokens() for the token half; ' +
+  'geometry capture from Figma is a deferred follow-on phase.'
+
+const listUnits = async () => {
+  throw new Error(GEOMETRY_NOT_YET_IMPLEMENTED)
+}
+
+const captureGeometry = async () => {
+  throw new Error(GEOMETRY_NOT_YET_IMPLEMENTED)
+}
+
+export const figmaPluginConnector = {
+  id: 'figma-plugin',
+  listUnits,
+  captureGeometry,
+  readTokens,
+}
+
+registerSource(figmaPluginConnector)

package/src/sources/figmaPlugin.test.js

@@ -0,0 +1,65 @@
+// Tests for the `figma-plugin` SourceConnector (figma-source-connector.md
+// §1a). Mirrors the contract-registration style of sorb-core's
+// connectors.test.js dummy-source test, plus exercises readTokens() as a
+// bridge CLIENT against a mocked `fetch` (no real juice server needed —
+// the contract is "GET /tokens/figma returns { tokens: ResolvedToken[] }").
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { connectors, getSource } from '@sorb/core'
+import { figmaPluginConnector, bridgeOriginOf } from './figmaPlugin.js'
+
+test('registers under id "figma-plugin" and round-trips via getSource (contract dispatch)', () => {
+  assert.equal(getSource('figma-plugin'), figmaPluginConnector)
+  assert.equal(connectors.source.get('figma-plugin'), figmaPluginConnector)
+})
+
+test('bridgeOriginOf: defaults to the juice dev port, honors seed.bridgeOrigin, strips trailing slash', () => {
+  assert.equal(bridgeOriginOf({}), 'http://localhost:7777')
+  assert.equal(bridgeOriginOf(), 'http://localhost:7777')
+  assert.equal(bridgeOriginOf({ seed: { bridgeOrigin: 'http://localhost:9999/' } }), 'http://localhost:9999')
+  assert.equal(bridgeOriginOf({ bridgeOrigin: 'http://example.com/' }), 'http://example.com')
+})
+
+test('readTokens: reads the resolved-map array back from GET /tokens/figma', async (t) => {
+  const tokens = [{ id: 'color.bg.primary', cssVar: '--color-bg-primary', value: '#ffffff', tier: 'primitive', type: 'color' }]
+  const calls = []
+  const realFetch = global.fetch
+  global.fetch = async (url) => {
+    calls.push(url)
+    return { ok: true, status: 200, json: async () => ({ fileKey: 'abc', exportedAt: '2026-08-29T00:00:00Z', tokens }) }
+  }
+  t.after(() => { global.fetch = realFetch })
+
+  const got = await figmaPluginConnector.readTokens({ seed: { bridgeOrigin: 'http://localhost:7777' } })
+  assert.deepEqual(got, tokens)
+  assert.equal(calls[0], 'http://localhost:7777/tokens/figma')
+})
+
+test('readTokens: 404 (no export yet) throws an actionable "Export variables" error', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => ({ ok: false, status: 404, json: async () => ({ error: 'No Figma export yet.' }) })
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /Export variables/)
+})
+
+test('readTokens: non-2xx, non-404 → surfaces the HTTP status', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => ({ ok: false, status: 500, json: async () => ({}) })
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /HTTP 500/)
+})
+
+test('readTokens: network failure (bridge not running) → actionable error naming the origin', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => { throw new Error('ECONNREFUSED') }
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /could not reach the bridge at http:\/\/localhost:7777/)
+})
+
+test('listUnits/captureGeometry: v1 tokens-first scope — throw a clear not-yet-implemented error, not a silent no-op', async () => {
+  await assert.rejects(() => figmaPluginConnector.listUnits({}), /not implemented in v1/)
+  await assert.rejects(() => figmaPluginConnector.captureGeometry({ id: 'u1' }, {}), /not implemented in v1/)
+})