@sorb/seed 0.2.0 → 0.4.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/emit/sorbMantine.js

@@ -0,0 +1,116 @@
+// Sorb Mantine v7 CSS-var override format (`sorb/mantine-vars`).
+//
+// PROMOTED from `sorb-demo-mantine/sd/mantine-format.js` (P2 spike →
+// framework-targets-productization T2, first of the six JJ-demo formats to
+// graduate into `@sorb/seed`). The demo file stays in place for now (T8
+// retrofit is founder-gated); this is the canonical, generalized home.
+//
+// GENERALIZATION (T0 semantic-role contract): the spike hardcoded Janes
+// Jeans' own token ids as the map's left-hand column. Promotion makes that
+// column ROLE-RESOLVED — a non-JJ kit passes `options.roleMap` (role id →
+// its own token id) instead of forking this file. Resolution is the same
+// shape as `@sorb/core`'s `resolveRole` (see `sorb-core/src/index.js`
+// `DEFAULT_ROLE_IDS`/`resolveRole`), inlined here rather than imported so
+// this format degrades gracefully against an older published `@sorb/core`
+// that predates the role contract (same feature-detect posture as the
+// TargetAdapter registration side — see `sorb-leaf/src/targets/mantine.js`).
+// Not every key below is one of `@sorb/core`'s canonical `DEFAULT_ROLE_IDS`
+// — several (`button.primary.bg.*`, `button.radius`, `card.radius`) are
+// Janes-Jeans component-tier ids with no canonical role counterpart yet
+// (kit-private, per the productization spec's "contract scope = the union
+// of the six maps' role columns, not a kit's full token tree"). They still
+// go through the same `roleMap` resolution for consistency and so a kit
+// that DOES want to override them can.
+//
+// The `--mantine-*` right-hand column is Mantine's own documented CSS
+// surface — universal, and stays baked (not role-resolved).
+//
+// PRECEDENCE FINDINGS (carried verbatim from the P2 spike header — this is
+// the load-bearing reason every declaration below is `!important`, so don't
+// drop it in a future edit): Mantine's OWN core stylesheet declares these
+// vars on `:root[data-mantine-color-scheme="light"]` — an attribute-selector
+// rule, specificity (0,2,0) — and `MantineProvider` injects that stylesheet
+// as a runtime `<style>` tag whose position in `<head>` is NOT guaranteed to
+// precede ours. A first attempt used `:where(html) { ... }`, which carries
+// ZERO specificity by definition and lost outright (confirmed via Playwright:
+// overriding the underlying Sorb var had no effect on the Button's computed
+// background). The fix is a plain `:root` block with `!important` on every
+// declaration — `!important` author declarations win over normal-importance
+// declarations regardless of specificity or source order, which is exactly
+// the guarantee needed against a dynamically-injected, order-unstable
+// stylesheet. Zero-dep, zero-JS (Mechanism A): a static CSS file of `var()`
+// refs, reacting to a live bridge push the same way `variables.css` already
+// does.
+
+export const SORB_MANTINE_VARS = 'sorb/mantine-vars'
+
+/**
+ * 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.
+ */
+export const MANTINE_VAR_MAP = {
+  'color.surface': '--mantine-color-body',
+  'color.ink': '--mantine-color-text',
+  'color.ink-muted': '--mantine-color-placeholder',
+  'color.brand': '--mantine-color-anchor',
+  'color.danger': '--mantine-color-error',
+  'color.border': '--mantine-default-border-color',
+
+  'button.primary.bg.default': '--mantine-primary-color-filled',
+  'button.primary.bg.hover': '--mantine-primary-color-filled-hover',
+
+  'color.surface-raised': '--mantine-primary-color-light',
+  'color.surface-sunken': '--mantine-primary-color-light-hover',
+
+  'radius.control': '--mantine-radius-default',
+  'button.radius': '--mantine-radius-md',
+  'card.radius': '--mantine-radius-lg',
+  'radius.pill': '--mantine-radius-xl',
+}
+
+const cssVarOf = (id) => '--' + String(id).split('.').join('-')
+
+// Same shape as `@sorb/core`'s `resolveRole` — inlined per the promotion
+// spec so this format has no hard runtime dependency on a core version that
+// ships the role contract (see file header).
+const resolveRoleId = (roleId, roleMap) => (roleMap && roleMap[roleId]) || roleId
+
+/**
+ * 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.
+ * @param {{dictionary: {allTokens: Array}, options?: {roleMap?: Record<string,string>}}} args
+ * @returns {string} the generated CSS.
+ */
+export const sorbMantineVars = ({ dictionary, options }) => {
+  const roleMap = options && options.roleMap
+  const byId = new Map(dictionary.allTokens.map((t) => [t.path.join('.'), t]))
+  const lines = []
+  const missing = []
+  for (const [roleId, mantineVar] of Object.entries(MANTINE_VAR_MAP)) {
+    const tokenId = resolveRoleId(roleId, roleMap)
+    const t = byId.get(tokenId)
+    if (!t) { missing.push(tokenId); continue }
+    // !important is load-bearing here — see file header "Precedence findings".
+    lines.push(`  ${mantineVar}: var(${cssVarOf(tokenId)}) !important;`)
+  }
+  if (missing.length) {
+    console.warn(`  ⚠ sorb/mantine-vars: ${missing.length} unmapped token id(s) skipped: ` + missing.join(', '))
+  }
+  return (
+    '/* AUTO-GENERATED by Style Dictionary (sorb/mantine-vars) — do not edit.\n' +
+    '   Overrides Mantine v7 core CSS vars with var(--token) refs so a Sorb bridge\n' +
+    '   push re-themes Mantine components with zero component-level code changes.\n' +
+    '   !important is required — see this format\'s header "Precedence findings":\n' +
+    '   Mantine\'s :root[data-mantine-color-scheme] rule otherwise wins regardless\n' +
+    '   of this file\'s load order (its <style> is injected by MantineProvider at\n' +
+    '   runtime, not statically ordered in <head>). */\n' +
+    ':root {\n' +
+    lines.join('\n') +
+    '\n}\n'
+  )
+}

package/src/emit/sorbMantine.test.js

@@ -0,0 +1,68 @@
+// Tests for the Sorb Mantine v7 CSS-var override format (`sorb/mantine-vars`).
+// 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 { SORB_MANTINE_VARS, MANTINE_VAR_MAP, sorbMantineVars } from './sorbMantine.js'
+
+// Helper: a fabricated dictionary of resolved tokens, keyed by dot-path id.
+const tok = (id) => ({ path: id.split('.') })
+const dictOf = (ids) => ({ allTokens: ids.map(tok) })
+
+test('format name constant is the documented id', () => {
+  assert.equal(SORB_MANTINE_VARS, 'sorb/mantine-vars')
+})
+
+test('emits a :root block with every mapped id present in the dictionary', () => {
+  const dictionary = dictOf(Object.keys(MANTINE_VAR_MAP))
+  const css = sorbMantineVars({ dictionary })
+  assert.match(css, /^:root \{/m)
+  assert.match(css, /\}\s*$/)
+  // one declaration per map entry
+  const declCount = (css.match(/!important;/g) || []).length
+  assert.equal(declCount, Object.keys(MANTINE_VAR_MAP).length)
+})
+
+test('each declaration maps the correct --mantine-* var to var(--kebab-id) and keeps !important', () => {
+  const dictionary = dictOf(Object.keys(MANTINE_VAR_MAP))
+  const css = sorbMantineVars({ dictionary })
+  assert.match(css, /--mantine-color-body: var\(--color-surface\) !important;/)
+  assert.match(css, /--mantine-color-text: var\(--color-ink\) !important;/)
+  assert.match(css, /--mantine-color-anchor: var\(--color-brand\) !important;/)
+  assert.match(css, /--mantine-color-error: var\(--color-danger\) !important;/)
+  assert.match(css, /--mantine-default-border-color: var\(--color-border\) !important;/)
+  assert.match(css, /--mantine-primary-color-filled: var\(--button-primary-bg-default\) !important;/)
+  assert.match(css, /--mantine-primary-color-filled-hover: var\(--button-primary-bg-hover\) !important;/)
+  assert.match(css, /--mantine-radius-default: var\(--radius-control\) !important;/)
+  assert.match(css, /--mantine-radius-md: var\(--button-radius\) !important;/)
+  assert.match(css, /--mantine-radius-lg: var\(--card-radius\) !important;/)
+  assert.match(css, /--mantine-radius-xl: var\(--radius-pill\) !important;/)
+})
+
+test('every value is a var() reference, never a baked literal (live-preview invariant)', () => {
+  const dictionary = dictOf(Object.keys(MANTINE_VAR_MAP))
+  const css = sorbMantineVars({ dictionary })
+  for (const line of css.split('\n').filter((l) => l.trim().startsWith('--mantine'))) {
+    assert.match(line, /: var\(--[a-z0-9-]+\) !important;$/)
+  }
+})
+
+test('options.roleMap remaps the JJ-token-id column without forking the format', () => {
+  // A hypothetical non-JJ kit names its surface/ink/brand roles differently.
+  const roleMap = {
+    'color.surface': 'kit.bg',
+    'color.brand': 'kit.primary',
+  }
+  const dictionary = dictOf(['kit.bg', 'kit.primary', 'color.ink'])
+  const css = sorbMantineVars({ dictionary, options: { roleMap } })
+  assert.match(css, /--mantine-color-body: var\(--kit-bg\) !important;/)
+  assert.match(css, /--mantine-color-anchor: var\(--kit-primary\) !important;/)
+  // unmapped roles fall back to their canonical/default id
+  assert.match(css, /--mantine-color-text: var\(--color-ink\) !important;/)
+})
+
+test('unmapped/missing token ids are skipped, not emitted as broken var() refs', () => {
+  const dictionary = dictOf(['color.surface']) // only one of the map's ids present
+  const css = sorbMantineVars({ dictionary })
+  assert.match(css, /--mantine-color-body: var\(--color-surface\) !important;/)
+  assert.equal((css.match(/!important;/g) || []).length, 1)
+})