@scattered-light/loomiere 0.3.0 → 0.4.0

package/exporters/figma.mjs

@@ -1,100 +1,806 @@
 /**
- * Figma variables, one collection per builder step so each step can sync on its own:
- *   Brand   palettes, data colors, space, radius, stroke, type   (step 1)
- *   Pairs   each pair's colors, light and dark                   (step 2)
- *   Theme   surfaces, text, borders, scopes and emphasis levels  (step 3)
- * Pairs and Theme alias Brand, and Theme aliases itself the way the tokens do
- * (emphasis → scope → palette step), so changing a role in Figma moves everything that uses it.
- * Values that are math in CSS (color-mix) are resolved to colors. Every variable carries its
- * CSS variable as WEB code syntax. The file is data for a sync script that writes the
- * variables with the Figma plugin API; it isn't a Figma import format.
+ * Figma variables, text styles and effect styles: figma.json, the file the Figma sync reads (figma/README.md).
+ *
+ * Hidden collections hold raw values, with a group per variant; published ones are what
+ * designers pick from and switch. Figma resolves each collection's mode on its own (a mode can't
+ * pick another collection's mode), so a variant that one switch must change lives as a group in
+ * a hidden collection, and the published collection's modes point at the right group.
+ *
+ * Collections, in the order they alias each other:
+ *   Brand        hidden, one mode. Fonts, and a complete group of the brand's colors per theme:
+ *                default/color/…, then deuteranopia/color/… and the other color vision themes,
+ *                where a color the theme doesn't change points at default's. The data colors are
+ *                here by name (color/data/violet…).
+ *   Scale        hidden, one mode. The space, radius, stroke and icon size scales, and the font
+ *                sizes as desktop/, tablet/ and mobile/font-size/… (each clamp() at that width).
+ *   Size         the sizes designers pick: the semantic and component sizes and the font sizes.
+ *                Modes: Desktop, Tablet, Mobile.
+ *   Theme        every semantic color, the palette scopes, each brand pair's parts (pair/<name>/…)
+ *                and the data series slots (data/1…), each pointing at a named data color. Modes:
+ *                Light, Dark, Light high contrast, Dark high contrast, and one per color vision
+ *                theme (Deuteranopia…), each a light theme of its own: the modes are data-theme
+ *                in CSS. Scopes and pairs have no scopes, so only Status reaches them.
+ *   Status       what each emphasis level is in each status: a brand pair the brand file picked
+ *                (roles.status) or the level's style in a palette. Modes: Default, Info, Success,
+ *                Warning, Error (data-status), then Neutral: the chrome palette, as
+ *                data-color="neutral". No scopes; Emphasis reads it.
+ *   Emphasis     the emphasis parts components paint with. Modes: Bold, Standard, Subtle, Quiet
+ *                (data-emphasis), each pointing at its level in Status.
+ * So a frame can be Dark, Warning and Subtle at once, as the CSS can.
+
+ * Plans with one mode per collection (Figma Starter) get `flat` instead: Brand, Color Pair, Theme
+ * and "Theme dark", each color resolved for its mode.
+ *
+ * Values are a hex, a number, a string, or { alias: "Collection:variable/name" }. Values that
+ * are math in CSS (color-mix) are resolved to colors. Every variable carries its CSS variable
+ * as WEB code syntax. Text styles name the variables their font family and size follow; effect styles name
+ * the Theme variables their shadow colors follow.
  */
-import { formatHex, formatHex8, interpolate, parse } from 'culori';
+import { formatHex, formatHex8, interpolate, parse } from "culori";
+
+import { px, valueIn } from "./theme.mjs";
+import { STYLES, withDefaults } from "../generator/roles.mjs";
+
+export const FORMAT = "loomiere-figma";
+export const VERSION = 2;
 
 /** #rrggbb, or #rrggbbaa when the color is see-through. */
 const hex = (c) => ((c.alpha ?? 1) < 1 ? formatHex8(c) : formatHex(c));
 
-import { px, valueIn } from './theme.mjs';
-
 /** color-mix(in oklab|srgb, A p%, B) → a hex; anything else parse() understands → a hex. */
 function solve(value) {
-  const mix = String(value).match(/^color-mix\(in (\w+),\s*(.+?)\s+([\d.]+)%,\s*(.+)\)$/);
-  if (mix) return hex(interpolate([solve(mix[4]), solve(mix[2])], mix[1] === 'srgb' ? 'rgb' : mix[1])(Number(mix[3]) / 100));
-  if (value === 'transparent') return '#00000000';
+  const mix = String(value).match(
+    /^color-mix\(in (\w+),\s*(.+?)\s+([\d.]+)%,\s*(.+)\)$/,
+  );
+  if (mix)
+    return hex(
+      interpolate(
+        [solve(mix[4]), solve(mix[2])],
+        mix[1] === "srgb" ? "rgb" : mix[1],
+      )(Number(mix[3]) / 100),
+    );
+  if (value === "transparent") return "#00000000";
   const c = parse(value);
   return c ? hex(c) : null;
 }
 
-const COLLECTION_OF = (t) => {
-  if (t.layer === 'primitive' && !t.path.startsWith('vision.') && !/^color\.(accent|chrome)\./.test(t.path)) return 'Brand';
-  if (t.layer === 'semantic' && t.type === 'color') return t.path.startsWith('pair.') ? 'Pairs' : 'Theme';
-  return null;
+const SCOPES = {
+  surface: ["FRAME_FILL", "SHAPE_FILL"],
+  text: ["TEXT_FILL"],
+  border: ["STROKE_COLOR"],
+  color: ["ALL_FILLS", "STROKE_COLOR"],
+  space: ["GAP", "WIDTH_HEIGHT"],
+  gap: ["GAP"],
+  spacing: ["GAP"],
+  inset: ["GAP"],
+  radius: ["CORNER_RADIUS"],
+  stroke: ["STROKE_FLOAT"],
+  "font-size": ["FONT_SIZE"],
+  "font-family": ["FONT_FAMILY"],
+  "icon-size": ["WIDTH_HEIGHT"],
+};
+const scopesOf = (path, type) => {
+  const top = path.split(".")[0];
+  if (SCOPES[top]) return SCOPES[top];
+  if (type === "COLOR") return ["ALL_FILLS", "STROKE_COLOR", "EFFECT_COLOR"];
+  // Semantic sizes: the last word says what they size.
+  if (/opacity/.test(path)) return ["OPACITY"];
+  if (/radius/.test(path)) return ["CORNER_RADIUS"];
+  if (/border-width|stroke/.test(path)) return ["STROKE_FLOAT"];
+  if (/gap|padding|inset|margin/.test(path)) return ["GAP"];
+  return ["WIDTH_HEIGHT", "GAP"];
+};
+
+const figmaName = (path) => path.replace(/\./g, "/");
+const refOf = (r) =>
+  typeof r === "string" ? r.match(/^\{([^}]+)\}$/)?.[1] : undefined;
+
+/** Theme modes: the CSS mode blocks each one sees, last wins (build-tokens.mjs MODES order). */
+const THEMES = {
+  Light: [],
+  Dark: ["dark"],
+  "Light high contrast": ["contrast-more"],
+  "Dark high contrast": ["dark", "contrast-more", "dark-contrast-more"],
 };
+const SIZES = ["Desktop", "Tablet", "Mobile"];
+/** The width Figma's Tablet mode stands for: where a fluid size is read for tablet frames. */
+const TABLET_WIDTH = 768;
 
-const SCOPES = {
-  surface: ['FRAME_FILL', 'SHAPE_FILL'],
-  text: ['TEXT_FILL'],
-  border: ['STROKE_COLOR'],
-  color: ['ALL_FILLS', 'STROKE_COLOR'],
-  space: ['GAP', 'WIDTH_HEIGHT'],
-  radius: ['CORNER_RADIUS'],
-  stroke: ['STROKE_FLOAT'],
-  'font-size': ['FONT_SIZE'],
-  'font-family': ['FONT_FAMILY'],
+/** A token's expression in a theme mode: the last mode block that sets it, references kept. */
+function expressionIn(t, mode) {
+  for (const block of [...(THEMES[mode] ?? [])].reverse()) {
+    if (t.modes?.[block] !== undefined)
+      return t.modeReferences?.[block] ?? t.modes[block];
+  }
+  return t.references ?? t.value;
+}
+
+/**
+ * "clamp(0.875rem, 0.8333rem + 0.2083vw, 1rem)" → { Desktop: 16, Tablet: 15, Mobile: 14 }, the
+ * Tablet value read at TABLET_WIDTH; "0.5rem" → 8 in all three.
+ */
+function sizes(value) {
+  const m = String(value).match(/^clamp\(\s*([^,]+),\s*([^,]+),\s*([^,)]+)\)$/);
+  if (!m) {
+    const v = px(value);
+    return v === undefined ? null : { Desktop: v, Tablet: v, Mobile: v };
+  }
+  const [small, large] = [px(m[1].trim()), px(m[3].trim())];
+  if (small === undefined || large === undefined) return null;
+  const fluid = m[2].match(/^([\d.]+(?:rem|px))\s*\+\s*([\d.]+)vw$/);
+  const at = fluid
+    ? px(fluid[1]) + (Number(fluid[2]) * TABLET_WIDTH) / 100
+    : (small + large) / 2;
+  const tablet = Math.round(Math.min(large, Math.max(small, at)) * 100) / 100;
+  return { Desktop: large, Tablet: tablet, Mobile: small };
+}
+
+const SIZE_TOPS = new Set([
+  "space",
+  "radius",
+  "stroke",
+  "font-size",
+  "icon-size",
+]);
+const NOT_SIZES = new Set([
+  "breakpoint",
+  "container",
+  "measure",
+  "letter-spacing",
+  "z-index",
+  "font-weight",
+  "line-height",
+  "font",
+]);
+
+const WEIGHT_STYLES = {
+  100: "Thin",
+  200: "ExtraLight",
+  300: "Light",
+  400: "Regular",
+  500: "Medium",
+  600: "SemiBold",
+  700: "Bold",
+  800: "ExtraBold",
+  900: "Black",
 };
-const scopesOf = (path) => SCOPES[path.split('.')[0]] ?? ['ALL_FILLS', 'STROKE_COLOR', 'EFFECT_COLOR'];
 
 export default {
-  id: 'figma',
-  name: 'Figma variables',
-  file: 'figma.json',
-  for: 'Syncing to Figma variables: Brand, Pairs and Theme collections with light and dark modes. Ask Claude to sync a step.',
+  id: "figma",
+  name: "Figma variables",
+  file: "figma.json",
+  for: "Figma variables, text styles and effect styles (elevation and focus shadows): hidden Brand and Scale collections, and Size, Theme, Status and Emphasis, with modes for desktop, tablet and mobile, light and dark, high contrast, color vision, statuses and emphasis. Ask Claude to sync, run loomiere figma push, or import it with the Loomiere Figma plugin.",
   build(theme) {
     const byPath = new Map(theme.tokens.map((t) => [t.path, t]));
-    const figmaName = (path) => path.replace(/\./g, '/');
-    const refOf = (r) => r?.match(/^\{([^}]+)\}$/)?.[1];
-    // Follow accent/chrome aliases (they aren't variables in Figma) to the palette step.
-    const target = (path) => {
-      let t = byPath.get(path);
-      while (t && /^color\.(accent|chrome)\./.test(t.path)) t = byPath.get(refOf(t.references));
-      return t && COLLECTION_OF(t) ? `${COLLECTION_OF(t)}:${figmaName(t.path)}` : null;
+
+    // Which collection a token's variable lives in, if any.
+    const isPaletteAlias = (p) => /^color\.(accent|chrome)\./.test(p);
+    // The numbered data series are slots in Theme; the named data colors are Brand's.
+    const isDataSlot = (p) => /^color\.data\.\d+$/.test(p);
+    const home = (t) => {
+      if (!t) return null;
+      if (isDataSlot(t.path)) return null;
+      if (/^(status-level|emphasis)\./.test(t.path)) return null;
+      if (
+        t.layer === "primitive" &&
+        t.type === "color" &&
+        !t.path.startsWith("vision.") &&
+        !isPaletteAlias(t.path)
+      )
+        return "Brand";
+      if (t.path.startsWith("font-family.")) return "Brand";
+      if (t.layer === "semantic" && t.type === "color") return "Theme";
+      if (
+        t.type === "color" ||
+        t.type === "shadow" ||
+        NOT_SIZES.has(t.path.split(".")[0])
+      )
+        return null;
+      if (t.layer === "primitive")
+        return SIZE_TOPS.has(t.path.split(".")[0]) && sizes(t.value)
+          ? "Scale"
+          : null;
+      return sizes(t.value) ? "Size" : null;
     };
-    const valueFor = (t, mode) => {
-      const ref = mode === 'Dark' ? refOf(t.modeReferences?.dark) ?? (t.modes?.dark === undefined ? refOf(t.references) : null) : refOf(t.references);
-      const alias = ref && target(ref);
-      if (alias) return { alias };
-      const raw = mode === 'Dark' ? valueIn(byPath, t.path, 'dark') : t.value;
-      return t.type === 'color' ? solve(raw) : raw;
+    // color.accent.* and color.chrome.* aren't variables; follow them to the palette step.
+    const follow = (p) => {
+      let t = byPath.get(p);
+      while (t && isPaletteAlias(t.path)) t = byPath.get(refOf(t.references));
+      return t;
+    };
+
+    // Color vision themes are Light with the brand's colors swapped for the theme's own.
+    const visions = [
+      ...new Set(
+        theme.tokens
+          .filter((t) => t.path.startsWith("vision."))
+          .map((t) => t.path.split(".")[1]),
+      ),
+    ];
+    const visionMode = (v) => v[0].toUpperCase() + v.slice(1);
+    const themeModes = [...Object.keys(THEMES), ...visions.map(visionMode)];
+    const visionOf = (mode) => visions.find((v) => visionMode(v) === mode);
+    // The theme's own version of a brand color, when it differs from the brand's.
+    const visionAlt = (t, mode) => {
+      const v = visionOf(mode);
+      const alt =
+        v && home(t) === "Brand"
+          ? byPath.get(`vision.${v}.${t.path}`)
+          : undefined;
+      return alt && solve(alt.value) !== solve(t.value) ? alt : undefined;
+    };
+
+    /**
+     * The variable a reference points at in a mode: a theme mode picks the Brand group, a size
+     * mode picks the font size group.
+     */
+    const target = (p, mode = "Light") => {
+      const t = follow(p);
+      const c = home(t);
+      if (!c) return null;
+      const name = figmaName(t.path);
+      if (c === "Brand" && t.type === "color")
+        return `Brand:${visionOf(mode) ?? "default"}/${name}`;
+      if (c === "Scale" && t.path.startsWith("font-size."))
+        return `Scale:${SIZES.includes(mode) ? mode.toLowerCase() : "desktop"}/${name}`;
+      return `${c}:${name}`;
+    };
+
+    /**
+     * A color token in a theme mode: { alias, hex } when it is one other variable, { hex } when
+     * it is math or a literal.
+     */
+    const colorIn = (p, mode) => {
+      const t = follow(p);
+      if (!t) throw new Error(`Figma export: no token ${p}`);
+      const alt = visionAlt(t, mode);
+      if (alt) return { hex: solve(alt.value) };
+      const expr =
+        home(t) === "Brand" ? (t.references ?? t.value) : expressionIn(t, mode);
+      const ref = refOf(expr);
+      if (ref) {
+        const inner = colorIn(ref, mode);
+        const alias = target(ref, mode);
+        return alias ? { alias, hex: inner.hex } : inner;
+      }
+      if (typeof expr === "string" && expr.includes("{"))
+        return {
+          hex: solve(
+            expr.replace(/\{([^}]+)\}/g, (_, r) => colorIn(r, mode).hex),
+          ),
+        };
+      return { hex: solve(expr) };
     };
+    const value = (v) => (v.alias ? { alias: v.alias } : v.hex);
+    const variable = (name, type, values, t, extra = {}) => ({
+      name,
+      type,
+      values,
+      scopes:
+        extra.scopes ?? scopesOf(t?.path ?? name.replace(/\//g, "."), type),
+      ...(extra.code !== null && t && { code: `var(${extra.code ?? t.name})` }),
+      ...((extra.description ?? t?.description) && {
+        description: extra.description ?? t.description,
+      }),
+    });
 
-    const collections = { Brand: [], Pairs: [], Theme: [] };
+    // Brand: fonts, then the brand's colors once per theme. Hidden, so nothing here is picked.
+    const brandColors = theme.tokens.filter(
+      (t) => home(t) === "Brand" && t.type === "color",
+    );
+    const brandVars = [];
     for (const t of theme.tokens) {
-      const c = COLLECTION_OF(t);
-      if (!c) continue;
-      const top = t.path.split('.')[0];
-      let type, value;
-      if (t.type === 'color' || top === 'color') type = 'COLOR';
-      else if (['space', 'radius', 'stroke', 'font-size'].includes(top)) {
-        // Fluid sizes go in at their large-screen size; Figma variables hold one number.
-        const m = String(t.value).match(/,\s*([\d.]+rem)\)$/);
-        value = px(m ? m[1] : t.value);
-        if (value === undefined) continue;
-        type = 'FLOAT';
-      } else if (top === 'font-family') {
-        type = 'STRING';
-        value = String(t.value).split(',')[0].replace(/['"]/g, '').trim();
-      } else continue;
-      const modes = c === 'Brand' ? { Value: value ?? valueFor(t, 'Light') } : { Light: valueFor(t, 'Light'), Dark: valueFor(t, 'Dark') };
-      collections[c].push({ name: figmaName(t.path), type, modes, scopes: scopesOf(t.path), code: `var(${t.name})`, ...(t.description && { description: t.description }) });
+      if (home(t) !== "Brand" || t.type === "color") continue;
+      const family = String(t.value).split(",")[0].replace(/['"]/g, "").trim();
+      const ref = refOf(t.references);
+      brandVars.push(
+        variable(
+          figmaName(t.path),
+          "STRING",
+          { Default: ref && target(ref) ? { alias: target(ref) } : family },
+          t,
+          { scopes: [] },
+        ),
+      );
     }
+    for (const t of brandColors)
+      brandVars.push(
+        variable(
+          `default/${figmaName(t.path)}`,
+          "COLOR",
+          { Default: value(colorIn(t.path, "Light")) },
+          t,
+          { scopes: [] },
+        ),
+      );
+    for (const v of visions) {
+      for (const t of brandColors) {
+        const alt = visionAlt(t, visionMode(v));
+        const description = alt
+          ? `${t.path} in the ${visionMode(v)} theme.`
+          : `${t.path} in the ${visionMode(v)} theme: the same as default.`;
+        const values = {
+          Default: alt
+            ? solve(alt.value)
+            : { alias: `Brand:default/${figmaName(t.path)}` },
+        };
+        brandVars.push(
+          variable(`${v}/${figmaName(t.path)}`, "COLOR", values, t, {
+            scopes: [],
+            description,
+          }),
+        );
+      }
+    }
+
+    // Scale: the raw steps. Hidden; font sizes once per size mode, so Size can switch them.
+    const scaleVars = [];
+    const fontSizes = [];
+    for (const t of theme.tokens) {
+      if (home(t) !== "Scale") continue;
+      const ref = refOf(t.references);
+      const s = sizes(t.value);
+      if (t.path.startsWith("font-size.")) {
+        fontSizes.push(t);
+        for (const m of SIZES) {
+          const alias =
+            ref && target(ref, m)?.startsWith("Scale:")
+              ? { alias: target(ref, m) }
+              : null;
+          scaleVars.push(
+            variable(
+              `${m.toLowerCase()}/${figmaName(t.path)}`,
+              "FLOAT",
+              { Default: alias ?? s[m] },
+              t,
+              {
+                scopes: [],
+                description: `${t.description ?? t.path} (${m.toLowerCase()})`,
+              },
+            ),
+          );
+        }
+      } else {
+        const alias =
+          ref && target(ref)?.startsWith("Scale:")
+            ? { alias: target(ref) }
+            : null;
+        scaleVars.push(
+          variable(
+            figmaName(t.path),
+            "FLOAT",
+            { Default: alias ?? s.Desktop },
+            t,
+            { scopes: [] },
+          ),
+        );
+      }
+    }
+
+    // Size: the font sizes, then the semantic and component sizes, fluid ones at both ends.
+    const sizeVars = fontSizes.map((t) =>
+      variable(
+        figmaName(t.path),
+        "FLOAT",
+        Object.fromEntries(SIZES.map((m) => [m, { alias: target(t.path, m) }])),
+        t,
+      ),
+    );
+    for (const t of theme.tokens) {
+      if (home(t) !== "Size") continue;
+      const ref = refOf(t.references);
+      // Figma reads a bound opacity as a percent, CSS as a fraction: 0.5 is 50 in Figma.
+      const opacity = /opacity/.test(t.path);
+      const s = opacity
+        ? Object.fromEntries(
+            Object.entries(sizes(t.value)).map(([m, n]) => [
+              m,
+              Math.round(n * 1000) / 10,
+            ]),
+          )
+        : sizes(t.value);
+      sizeVars.push(
+        variable(
+          figmaName(t.path),
+          "FLOAT",
+          Object.fromEntries(
+            SIZES.map((m) => [
+              m,
+              ref && /^(Scale|Size):/.test(target(ref, m) ?? "")
+                ? { alias: target(ref, m) }
+                : s[m],
+            ]),
+          ),
+          t,
+        ),
+      );
+    }
+
+    // Theme: every semantic color in each theme mode. Scopes and pair parts are what Status points
+    // at, not what designers pick, so they get no scopes.
+    const themeTokens = theme.tokens.filter((t) => home(t) === "Theme");
+    const themeVars = themeTokens.map((t) =>
+      variable(
+        figmaName(t.path),
+        "COLOR",
+        Object.fromEntries(
+          themeModes.map((m) => [m, value(colorIn(t.path, m))]),
+        ),
+        t,
+        /^(scope|pair)\./.test(t.path) ? { scopes: [] } : {},
+      ),
+    );
+
+    // Data series: data/<n> points at the named data color each theme puts in that place, as
+    // --sl-color-data-<n> does in CSS.
+    const slots = theme.tokens.filter((t) => isDataSlot(t.path));
+    for (const t of slots) {
+      const n = t.path.split(".")[2];
+      const values = {};
+      for (const m of themeModes) {
+        const v = visionOf(m);
+        const slot = (v && byPath.get(`vision.${v}.color.data.${n}`)) || t;
+        const name = refOf(slot.references)?.split(".").at(-1);
+        values[m] = { alias: `Brand:${v ?? "default"}/color/data/${name}` };
+      }
+      themeVars.push(
+        variable(`data/${n}`, "COLOR", values, t, {
+          scopes: ["ALL_FILLS", "STROKE_COLOR"],
+        }),
+      );
+    }
+
+    // Status: each level's parts per status, pointing at a scope slot or a pair part in Theme.
+    const statusTokens = theme.tokens.filter((t) =>
+      t.path.startsWith("status-level."),
+    );
+    const statuses = [
+      ...new Set(statusTokens.map((t) => t.path.split(".")[1])),
+    ];
+    const modeName = (n) => n[0].toUpperCase() + n.slice(1);
+    const roles = withDefaults(theme.brand?.roles);
+    const statusVars = [
+      ...new Set(statusTokens.map((t) => t.path.split(".").slice(2).join("."))),
+    ].map((levelPart) => {
+      const [level, part] = levelPart.split(".");
+      const values = {};
+      for (const status of statuses) {
+        const t = byPath.get(`status-level.${status}.${levelPart}`);
+        const ref = refOf(t.references);
+        values[modeName(status)] = ref
+          ? { alias: `Theme:${figmaName(ref)}` }
+          : solve(t.value);
+      }
+      // Neutral: the level's style in the chrome palette, as data-color="neutral" (palette="neutral") does in CSS.
+      const slot = STYLES[roles.emphasis[level].style][part];
+      values.Neutral =
+        slot === "transparent"
+          ? solve("transparent")
+          : { alias: `Theme:scope/chrome/${slot}` };
+      return {
+        name: `${level}/${part}`,
+        type: "COLOR",
+        values,
+        scopes: [],
+        description: `The ${part} of ${level} emphasis in each status (data-status; Neutral is data-color="neutral").`,
+      };
+    });
+
+    // Emphasis: data-emphasis. Each level is its row in Status, so it follows the status in effect.
+    const levels = [
+      ...new Set(
+        theme.tokens
+          .filter((t) => t.path.startsWith("emphasis."))
+          .map((t) => t.path.split(".")[1]),
+      ),
+    ];
+    const parts = [
+      ...new Set(
+        theme.tokens
+          .filter((t) => t.path.startsWith("emphasis."))
+          .map((t) => t.path.split(".")[2]),
+      ),
+    ];
+    const emphasisVars = parts.map((part) => ({
+      name: `emphasis/${part}`,
+      type: "COLOR",
+      values: Object.fromEntries(
+        levels.map((level) => [
+          modeName(level),
+          { alias: `Status:${level}/${part}` },
+        ]),
+      ),
+      scopes: /border/.test(part)
+        ? ["STROKE_COLOR"]
+        : /fg/.test(part)
+          ? ["TEXT_FILL", "STROKE_COLOR"]
+          : ["FRAME_FILL", "SHAPE_FILL"],
+      code: `var(--${theme.prefix}-e-${part})`,
+      description: `The ${part} of the emphasis level (data-emphasis), in the status in effect (data-status).`,
+    }));
+
+    // Text styles: one per text style token, following the font family and the Size font size.
+    const sizeVariable = (ref) => {
+      const t = follow(ref);
+      return ["Scale", "Size"].includes(home(t))
+        ? `Size:${figmaName(t.path)}`
+        : null;
+    };
+    const styleNames = [
+      ...new Set(
+        theme.tokens
+          .filter((t) => /^font\.[^.]+\.font-size$/.test(t.path))
+          .map((t) => t.path.split(".")[1]),
+      ),
+    ];
+    const textStyles = styleNames.map((name) => {
+      const part = (p) => byPath.get(`font.${name}.${p}`);
+      const family = part("font-family");
+      const size = part("font-size");
+      const weight = Number(part("font-weight").value);
+      const lineHeight = String(part("line-height").value);
+      const letterSpacing = String(part("letter-spacing").value);
+      const transform = part("text-transform")?.value;
+      const em = letterSpacing.match(/^(-?[\d.]+)em$/);
+      const familyRef = refOf(family.references);
+      const sizeRef = refOf(size.references);
+      const font = byPath.get(`font.${name}.font`);
+      return {
+        name,
+        family: String(family.value).split(",")[0].replace(/['"]/g, "").trim(),
+        ...(familyRef &&
+          target(familyRef) && { familyVariable: target(familyRef) }),
+        weight,
+        style: WEIGHT_STYLES[weight] ?? "Regular",
+        size: sizes(size.value),
+        ...(sizeRef &&
+          sizeVariable(sizeRef) && { sizeVariable: sizeVariable(sizeRef) }),
+        lineHeight: /^[\d.]+$/.test(lineHeight)
+          ? {
+              unit: "PERCENT",
+              value: Math.round(Number(lineHeight) * 1000) / 10,
+            }
+          : { unit: "PIXELS", value: px(lineHeight) },
+        letterSpacing: em
+          ? { unit: "PERCENT", value: Math.round(Number(em[1]) * 1000) / 10 }
+          : { unit: "PIXELS", value: px(letterSpacing) ?? 0 },
+        ...(transform && {
+          textCase:
+            { uppercase: "UPPER", lowercase: "LOWER", capitalize: "TITLE" }[
+              transform
+            ] ?? "ORIGINAL",
+        }),
+        description: `${(font?.description ?? name).replace(/ As a font shorthand;.*$/, "")}\nCSS: .text-style-${name} or @sl-pattern text-${name};`,
+      };
+    });
+
+    // Effect styles: a shadow is several values at once, so it can't be a variable. Each
+    // elevation step and focus look is an effect style; colors that are Theme tokens stay bound.
+    const colorOf = (css) => {
+      const ref = css.match(/^\{([^}]+)\}$/)?.[1];
+      if (!ref) return { hex: solve(css) };
+      return { hex: colorIn(ref, "Light").hex, variable: target(ref) };
+    };
+    const layersOf = (value, references) => {
+      const split = (v) =>
+        String(v)
+          .split(/,(?![^(]*\))/)
+          .map((x) => x.trim());
+      const refs = references ? split(references) : [];
+      return split(value).map((layer, i) => {
+        const m = layer.match(
+          /^(inset\s+)?(-?[\d.]+)(?:px)?\s+(-?[\d.]+)(?:px)?\s+(-?[\d.]+)(?:px)?(?:\s+(-?[\d.]+)(?:px)?)?\s+(.+)$/,
+        );
+        if (!m) throw new Error(`Figma export: can't read the shadow ${layer}`);
+        const colorRef = refs[i]?.match(/(\{[^}]+\})\s*$/)?.[1];
+        const color = colorOf(colorRef ?? m[6]);
+        return {
+          type: m[1] ? "INNER_SHADOW" : "DROP_SHADOW",
+          x: Number(m[2]),
+          y: Number(m[3]),
+          blur: Number(m[4]),
+          spread: Number(m[5] ?? 0),
+          color: color.hex,
+          ...(color.variable && { colorVariable: color.variable }),
+        };
+      });
+    };
+    const ring = (spread, ref) => ({
+      type: "DROP_SHADOW",
+      x: 0,
+      y: 0,
+      blur: 0,
+      spread,
+      color: colorIn(ref, "Light").hex,
+      ...(target(ref) && { colorVariable: target(ref) }),
+    });
+    const pxOf = (p) =>
+      String(byPath.get(p).value)
+        .match(/-?[\d.]+/g)
+        .reduce((a, n) => a + Number(n), 0);
+    const gap = pxOf("a11y.focus-outline-offset");
+    const ringEdge = gap + pxOf("a11y.focus-outline-width");
+    const STEPS = ["xs", "sm", "base", "md", "lg", "xl", "2xl"];
+    const css = (path) =>
+      `\nCSS: var(--${theme.prefix}-${path.replace(/\./g, "-")})`;
+    const effectStyles = [
+      ...theme.tokens
+        .filter((t) => /^elevation\.[^.]+$/.test(t.path))
+        .sort(
+          (a, b) =>
+            STEPS.indexOf(a.path.split(".")[1]) -
+            STEPS.indexOf(b.path.split(".")[1]),
+        )
+        .map((t) => ({
+          name: figmaName(t.path),
+          effects: layersOf(t.value),
+          description: `${t.description ?? `Elevation ${t.path.split(".")[1]}`}.${css(t.path)}`,
+        })),
+      {
+        name: "focus/ring",
+        effects: [
+          ring(gap, "surface.canvas"),
+          ring(ringEdge, "focus.ring"),
+          ring(
+            pxOf("focus.halo-spread"),
+            refOf(byPath.get("focus.halo-color").references),
+          ),
+        ],
+        description: `Keyboard focus: a ${gap}px gap, a ${ringEdge - gap}px ring, then a soft halo. In CSS the ring is an outline, so it follows the element's corners.\nCSS: @sl-pattern focus-ring;`,
+      },
+      ...[
+        ["focus/field", "focus.shadow-3px-primary"],
+        ["focus/field-error", "focus.shadow-3px-error"],
+      ].map(([name, path]) => ({
+        name,
+        effects: layersOf(byPath.get(path).value, byPath.get(path).references),
+        description: `${byPath.get(path).description}${css(path)}`,
+      })),
+    ];
+
     const out = {
+      format: FORMAT,
+      version: VERSION,
       brand: theme.brand,
+      prefix: theme.prefix,
       collections: [
-        { name: 'Brand', step: 'brand', modes: ['Value'], variables: collections.Brand },
-        { name: 'Pairs', step: 'pairs', modes: ['Light', 'Dark'], variables: collections.Pairs },
-        { name: 'Theme', step: 'roles', modes: ['Light', 'Dark'], variables: collections.Theme },
+        {
+          name: "Brand",
+          modes: ["Default"],
+          hidden: true,
+          variables: brandVars,
+        },
+        {
+          name: "Scale",
+          modes: ["Default"],
+          hidden: true,
+          variables: scaleVars,
+        },
+        { name: "Size", modes: SIZES, variables: sizeVars },
+        { name: "Theme", modes: themeModes, variables: themeVars },
+        {
+          name: "Status",
+          modes: [...statuses.map(modeName), "Neutral"],
+          variables: statusVars,
+        },
+        {
+          name: "Emphasis",
+          modes: levels.map(modeName),
+          variables: emphasisVars,
+        },
       ],
+      textStyles,
+      effectStyles,
+      flat: flat(theme, byPath),
     };
     return `${JSON.stringify(out)}\n`;
   },
 };
+
+/**
+ * One mode per collection, for Figma Starter: Brand (no vision themes), Color Pair, Theme and
+ * "Theme dark", with sizes at their desktop value in Brand.
+ */
+function flat(theme, byPath) {
+  const inCollection = (t) => {
+    if (
+      t.layer === "primitive" &&
+      !t.path.startsWith("vision.") &&
+      !/^color\.(accent|chrome)\./.test(t.path)
+    )
+      return "Brand";
+    if (t.layer === "semantic" && t.type === "color")
+      return t.path.startsWith("pair.") ? "Color Pair" : "Theme";
+    return null;
+  };
+  const target = (path) => {
+    let t = byPath.get(path);
+    while (t && /^color\.(accent|chrome)\./.test(t.path))
+      t = byPath.get(refOf(t.references));
+    return t && inCollection(t)
+      ? `${inCollection(t)}:${figmaName(t.path)}`
+      : null;
+  };
+  const valueFor = (t, mode) => {
+    const ref =
+      mode === "Dark"
+        ? (refOf(t.modeReferences?.dark) ??
+          (t.modes?.dark === undefined ? refOf(t.references) : null))
+        : refOf(t.references);
+    const alias = ref && target(ref);
+    // Theme dark is its own collection, so its aliases into Theme point at Theme dark.
+    if (alias)
+      return {
+        alias:
+          mode === "Dark" && alias.startsWith("Theme:")
+            ? alias.replace("Theme:", "Theme dark:")
+            : alias,
+      };
+    const raw = mode === "Dark" ? valueIn(byPath, t.path, "dark") : t.value;
+    return t.type === "color" ? solve(raw) : raw;
+  };
+  const collections = {
+    Brand: [],
+    "Color Pair": [],
+    Theme: [],
+    "Theme dark": [],
+  };
+  for (const t of theme.tokens) {
+    const c = inCollection(t);
+    if (!c) continue;
+    const top = t.path.split(".")[0];
+    let type, value;
+    if (t.type === "color" || top === "color") type = "COLOR";
+    else if (["space", "radius", "stroke", "font-size"].includes(top)) {
+      value = sizes(t.value)?.Desktop;
+      if (value === undefined) continue;
+      type = "FLOAT";
+    } else if (top === "font-family") {
+      type = "STRING";
+      value = String(t.value).split(",")[0].replace(/['"]/g, "").trim();
+    } else continue;
+    const base = {
+      name: figmaName(t.path),
+      type,
+      scopes: scopesOf(t.path, type),
+      code: `var(${t.name})`,
+      ...(t.description && { description: t.description }),
+    };
+    if (c === "Brand")
+      collections.Brand.push({
+        ...base,
+        values: { Value: value ?? valueFor(t, "Light") },
+      });
+    else if (c === "Color Pair")
+      collections["Color Pair"].push({
+        ...base,
+        values: { Value: valueFor(t, "Light") },
+      });
+    else {
+      collections.Theme.push({
+        ...base,
+        values: { Light: valueFor(t, "Light") },
+      });
+      collections["Theme dark"].push({
+        ...base,
+        values: { Dark: valueFor(t, "Dark") },
+      });
+    }
+  }
+  return {
+    collections: [
+      { name: "Brand", modes: ["Value"], variables: collections.Brand },
+      {
+        name: "Color Pair",
+        modes: ["Value"],
+        variables: collections["Color Pair"],
+      },
+      { name: "Theme", modes: ["Light"], variables: collections.Theme },
+      {
+        name: "Theme dark",
+        modes: ["Dark"],
+        variables: collections["Theme dark"],
+      },
+    ],
+  };
+}