@styleframe/cli 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # @styleframe/cli
 
+## 4.0.0
+
+### Major Changes
+
+- [#211](https://github.com/styleframe-dev/styleframe/pull/211) [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - **BREAKING**: rename `styleframe figma export` → `styleframe dtcg export`.
+
+  The CLI command now lives under a top-level `dtcg` subcommand to reflect that it produces a generic spec-conformant DTCG document, not a Figma-specific format. The DTCG → Figma value conversion (rem→px, ms passthrough, etc.) lives in the `@styleframe/figma` plugin, which consumes the JSON.
+
+  `styleframe figma import` is unchanged — it generates Styleframe TypeScript code from a Figma-flavoured DTCG export.
+
+  Migration:
+
+  ```diff
+  - styleframe figma export -o tokens.json
+  + styleframe dtcg export -o tokens.json
+  ```
+
+  The `--baseFontSize` flag has been removed from the export — base font size is applied by the Figma plugin during import (default 16). Any CI scripts referring to the old command must be updated.
+
+### Minor Changes
+
+- [#213](https://github.com/styleframe-dev/styleframe/pull/213) [`24eebba`](https://github.com/styleframe-dev/styleframe/commit/24eebba87c8fa6fc6822e18d67f4c0412192e793) Thanks [@alexgrozav](https://github.com/alexgrozav)! - **BREAKING**: rename `styleframe figma import` → `styleframe dtcg import`.
+
+  The CLI command now lives under the `dtcg` subcommand alongside `dtcg export`. The command takes a generic spec-conformant DTCG JSON file (whether produced by the `@styleframe/figma` plugin or any other DTCG-compatible tool) and generates Styleframe TypeScript code — there is nothing Figma-specific about it. The top-level `figma` subcommand has been removed; the namespace is reserved for future commands that genuinely interact with the Figma API.
+
+  All flags are unchanged (`--input`/`-i`, `--output`/`-o`, `--composables`, `--rem`, `--baseFontSize`, `--instanceName`).
+
+  Migration:
+
+  ```diff
+  - styleframe figma import -i tokens.json
+  + styleframe dtcg import -i tokens.json
+  ```
+
+  Any CI scripts referring to the old command must be updated.
+
+### Patch Changes
+
+- [#211](https://github.com/styleframe-dev/styleframe/pull/211) [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Fix DTCG export from `@styleframe/cli`: variables now get the correct `$type` and references are preserved as aliases.
+
+  The previous CLI flow piped Styleframe AST through a lossy `FigmaExportFormat` intermediate, then through `figmaTypeToDtcg("STRING") → "fontFamily"` — so most variables ended up tagged as `fontFamily` in the resulting JSON. References were silently replaced with empty strings, and CSS template expressions like `${ref(a)} * ${ref(b)}` were joined into garbage like `" * "`.
+
+  **`@styleframe/dtcg`** gains a new `classifyValue(value, {path?})` helper plus `parseCubicBezier` and `easingKeywordToBezier`. The classifier combines value-content detection with optional path heuristics so callers get a single canonical `{type, value}` pair without per-package guessing.
+
+  **`@styleframe/cli`** now builds the DTCG document directly from the Styleframe `Root`. A small evaluator pre-resolves `Reference` chains and pure-arithmetic CSS templates so computed variables (e.g. `scale.min-powers.*`) emit concrete numbers instead of being skipped or corrupted. Unevaluable expressions (involving `clamp()`, `vw`, etc.) are preserved with a `dev.styleframe.expression` extension, surfaced in a diagnostics summary at the end of the run.
+
+  **`@styleframe/figma`** uses the same classifier with the Figma variable name as a path hint. `figmaTypeToDtcg("STRING")` no longer claims everything is a `fontFamily`; instead callers should use the new `classifyFigmaVariable(variable, value)` which correctly identifies durations under `duration/*`, easings under `easing/*`, stroke styles, and font weights. STRING values whose name gives no usable hint are emitted with a `dev.styleframe.unknownType` extension rather than silently mistyped.
+
+  Round-trip lossiness across Styleframe ↔ DTCG ↔ Figma is now documented in `tooling/dtcg/AGENTS.md`.
+
+- [#211](https://github.com/styleframe-dev/styleframe/pull/211) [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Fix `dtcg export`: fluid font-size tokens (and any other tokens whose value reduces to a `calc()` mixing `100vw`, `rem`, and `px` literals) are now normalised to a concrete pixel value using the project's `fluid.max-width` (default 1440) instead of being emitted as opaque `calc(...)` expressions with a `dev.styleframe.unknownType` extension.
+
+  Previously every `font-size.*` token in a config that used `useFluidFontSizeDesignTokens` shipped to Figma as a useless `STRING` variable holding the raw `calc(...)` formula. They now ship as spec-conformant `dimension` tokens (`{value, unit: "px"}`) that the Figma plugin renders as real numeric variables (`font-size/md = 18`, `font-size/lg = 22.5`, etc.).
+
+  The substitution runs only as a fallback after the standard arithmetic check fails, so well-formed numeric expressions are unaffected. Affected tokens carry a `dev.styleframe.fluidBound: "max"` extension so the derivation is auditable. The export run reports `Normalised <n> fluid token(s) using max viewport (<n>px).`
+
+- [#211](https://github.com/styleframe-dev/styleframe/pull/211) [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Fix dark mode round-trip from Styleframe → DTCG → Figma.
+
+  Previously, `styleframe dtcg export` emitted a `tokens.resolver.json` that the Figma plugin had no way to consume — the plugin UI accepted only one file and its import handler always called the single-mode `fromDTCG()`. As a result, dark mode values never reached Figma. The exported resolver was also malformed: `default` referenced a non-existent context, and the resolver lacked a `set` linking to the base `tokens.json`, so any spec-conformant consumer would have failed too.
+
+  **`@styleframe/cli`** — `buildDTCG` now emits a self-contained resolver: `resolutionOrder` begins with a `set` referencing the base tokens file (controllable via `tokensSourceRef`), every theme contributes a capitalized context (`dark` → `Dark`), and a `Default` context (with no overrides) covers the unthemed mode. `default` correctly points at `Default`. Override tokens also carry `$type` so the `mergeDocuments` token-level replacement preserves typing — without this, dark color values lost their `color` type and downstream consumers (e.g. Figma) couldn't convert them, falling back to default white.
+
+  **`@styleframe/figma`** — the plugin UI exposes a second drop slot for `tokens.resolver.json`. When a resolver is provided, `code.ts` routes through `fromDTCGResolver` with an in-memory file loader so each declared context becomes a Figma mode populated with the correct per-mode values.
+
+- [#211](https://github.com/styleframe-dev/styleframe/pull/211) [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Fix two regressions in DTCG export uncovered by dogfooding the storybook config:
+
+  **Keyword-classification ambiguity.** The previous classifier matched `FONT_WEIGHT_KEYWORDS` and `STROKE_STYLE_KEYWORDS` on value content alone — but `"normal"` is a perfectly valid value for `letter-spacing`, `font-style`, and `line-height`, not just `font-weight`. Same for `"thin"`/`"medium"`/`"thick"` which are CSS border-width shorthand keywords. The result was that `border-width`, `font-style`, `letter-spacing`, and similar tokens were misclassified as `fontWeight` whenever their alias chain bottomed out at one of these CSS keywords.
+
+  The fix: keyword-based detectors now only fire when the path also indicates the corresponding category (`font-weight` segment for fontWeight, `border-style`/`outline-style`/`stroke` for strokeStyle, `font-family` for fontFamily). Callers that don't supply a path still get the keyword-based behaviour for back-compat. Tokens with no resolvable type emit a `dev.styleframe.unknownType` extension instead of a wrong `$type`.
+
+  **Parent/child path collisions wiped out children.** Styleframe configs commonly define both a parent variable (e.g. `border-width` aliased to `border-width.thin`) AND its child variants (`border-width.thin`, `border-width.medium`, `border-width.thick`). The previous `setNestedToken` logic unconditionally overwrote the slot, so depending on processing order either the parent or all the children were silently lost.
+
+  The fix: `setNestedToken` now uses the spec's reserved `$root` slot for parent tokens that coexist with siblings — a pattern explicitly defined in the Format Module 2025.10 for "group with a base value plus variants". Children survive alongside the parent, and the walker / validator / Figma plugin import all recognise `$root` as the parent's effective leaf.
+
+  The CLI also gains a one-line tip in its diagnostic output explaining that "untyped" tokens are usually CSS keywords with no DTCG equivalent.
+
+  **Numeric-string misclassification as colour.** `classifyValue("100")` and similar 3-character numeric strings were incorrectly classified as `$type: "color"` because culori's `parse()` interprets them as shorthand CSS hex (`"100"` → `#100`). Z-index tokens like `z-index.dropdown = "100"` consequently appeared as sRGB color variables in the exported JSON.
+
+  The fix: `classifyValue` now only forwards strings to culori that structurally look like CSS colors — those starting with `#`, containing `(` (function notation), or beginning with an ASCII letter (named color). Plain numeric strings are excluded before reaching the parser.
+
+  **Plugin import crash on viewport-relative units.** Importing a `tokens.json` that contained any `{value: 100, unit: "vw"}` dimension token caused the entire Figma plugin import to throw `Cannot convert "100vw" to a Figma FLOAT`. The exception propagated through the entire import, leaving all variables (including colors) at their default `#FFFFFF`.
+
+  The fix: `dtcgDimensionToFloat` now returns `undefined` for unsupported units (vw, vh, dvw, svw, etc.) instead of throwing, and `fromDTCG` silently skips variables whose value cannot be converted rather than crashing the whole batch. Colors and other tokens now import correctly even when the document contains fluid/viewport tokens.
+
+  **Out-of-gamut sRGB clamping.** Converting oklch colours to Figma's sRGB RGBA could produce slightly negative channel values (e.g. `r = -4.21e-15`) due to floating-point rounding in the matrix multiplication. The fix clamps `r`, `g`, and `b` to `[0, 1]` in `dtcgColorToFigmaRgba`.
+
+- Updated dependencies [[`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f), [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f), [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f), [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f), [`8826eda`](https://github.com/styleframe-dev/styleframe/commit/8826edad3fcb2e969024a586a20c2059229d958f)]:
+  - @styleframe/dtcg@1.1.0
+  - @styleframe/figma@2.0.0
+
 ## 3.0.0
 
 ### Major Changes

package/dist/build-BIWOTFZD.cjs

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const path = require("node:path");
+const loader = require("@styleframe/loader");
+const citty = require("citty");
+const consola = require("consola");
+const build = citty.defineCommand({
+  meta: {
+    name: "build",
+    description: "Build Styleframe project from source files"
+  },
+  args: {
+    entry: {
+      type: "positional",
+      description: "Entry point file(s) for the build",
+      default: "styleframe.config.ts",
+      valueHint: "path"
+    },
+    outputDir: {
+      type: "string",
+      description: "Output directory for built files",
+      default: "styleframe",
+      alias: ["o", "out"],
+      valueHint: "path"
+    },
+    clean: {
+      type: "boolean",
+      description: "Clean output directory before build",
+      default: false
+    }
+  },
+  async run({ args }) {
+    consola.info(
+      `Loading configuration from "${path.relative(process.cwd(), path.resolve(args.entry))}"...`
+    );
+    const instance = await loader.loadConfiguration({ entry: args.entry });
+    consola.info("Building styleframe...");
+    try {
+      await loader.build(instance, {
+        outputDir: args.outputDir,
+        clean: args.clean
+      });
+      consola.success("Styleframe built successfully!");
+    } catch (error) {
+      consola.error("Failed to build Styleframe:", error);
+    }
+  }
+});
+exports.default = build;

package/dist/{build-BFZSJ2Zh.js → build-CANA04j1.js}

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { l as loadConfiguration, b as build$1 } from "./index-DtEAy_us.js";
+import { loadConfiguration, build as build$1 } from "@styleframe/loader";
 import { defineCommand } from "citty";
 import consola from "consola";
 const build = defineCommand({

package/dist/export-BMneJTdq.cjs

@@ -0,0 +1,517 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const promises = require("node:fs/promises");
+const path = require("node:path");
+const loader = require("@styleframe/loader");
+const citty = require("citty");
+const consola = require("consola");
+const dtcg = require("@styleframe/dtcg");
+function isReference(value) {
+  return typeof value === "object" && value !== null && "type" in value && value.type === "reference";
+}
+function isCss(value) {
+  return typeof value === "object" && value !== null && "type" in value && value.type === "css";
+}
+function isPrimitive(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function resolveReferenceTarget(ref, context) {
+  const visited = context.visited ?? /* @__PURE__ */ new Set();
+  if (visited.has(ref.name)) {
+    return {
+      resolved: null,
+      reason: `Reference cycle: ${[...visited, ref.name].join(" → ")}`
+    };
+  }
+  const target = context.variables.get(ref.name);
+  if (!target) {
+    if (ref.fallback !== void 0 && ref.fallback !== null) {
+      return evaluateValue(ref.fallback, context);
+    }
+    return { resolved: null, reason: `Unknown reference target: ${ref.name}` };
+  }
+  const nextContext = {
+    variables: context.variables,
+    visited: /* @__PURE__ */ new Set([...visited, ref.name]),
+    maxViewport: context.maxViewport
+  };
+  return evaluateValue(target.value, nextContext);
+}
+function evaluateCss(css, context) {
+  const parts = [];
+  let unevaluable = false;
+  let unevaluableReason;
+  for (const part of css.value) {
+    if (typeof part === "string") {
+      parts.push({ kind: "literal", text: part });
+      continue;
+    }
+    const evaluated = evaluateValue(part, context);
+    if (evaluated.resolved === null) {
+      unevaluable = true;
+      unevaluableReason = evaluated.reason;
+      parts.push({ kind: "value", text: "" });
+      continue;
+    }
+    const text = String(evaluated.resolved);
+    const numeric = typeof evaluated.resolved === "number" ? evaluated.resolved : void 0;
+    parts.push({ kind: "value", text, numeric });
+  }
+  const folded = parts.map((p) => p.text).join("");
+  if (unevaluable) {
+    return {
+      resolved: null,
+      cssExpression: folded,
+      reason: unevaluableReason ?? "Computed expression includes an unresolvable reference"
+    };
+  }
+  const isPureArithmetic = parts.every((p) => {
+    if (p.kind === "value") return p.numeric !== void 0;
+    return /^[\d.\s+\-*/()]*$/.test(p.text);
+  });
+  if (isPureArithmetic && parts.some((p) => p.kind === "value")) {
+    try {
+      const result = safeArithmetic(folded.trim());
+      if (typeof result === "number" && Number.isFinite(result)) {
+        return { resolved: result };
+      }
+    } catch (err) {
+      return {
+        resolved: null,
+        cssExpression: folded,
+        reason: `Arithmetic evaluation failed: ${err.message}`
+      };
+    }
+  }
+  const subResult = substituteFluidUnits(folded, context.maxViewport ?? 1440);
+  if (subResult && /^[\d.\s+\-*/()]+$/.test(subResult.rebased)) {
+    try {
+      const result = safeArithmetic(subResult.rebased.trim());
+      if (typeof result === "number" && Number.isFinite(result)) {
+        return {
+          resolved: result,
+          ...subResult.substituted ? { normalisationSource: "fluid-max" } : {}
+        };
+      }
+    } catch {
+    }
+  }
+  return { resolved: folded };
+}
+function substituteFluidUnits(expression, maxViewport) {
+  let substituted = false;
+  let rebased = expression.replace(/\bcalc\b/g, "");
+  if (rebased.includes("100vw")) {
+    rebased = rebased.replace(/100vw/g, String(maxViewport));
+    substituted = true;
+  }
+  if (/(-?\d*\.?\d+)\s*rem/.test(rebased)) {
+    rebased = rebased.replace(/(-?\d*\.?\d+)\s*rem/g, "($1 * 16)");
+    substituted = true;
+  }
+  if (/(-?\d*\.?\d+)\s*px/.test(rebased)) {
+    rebased = rebased.replace(/(-?\d*\.?\d+)\s*px/g, "$1");
+    substituted = true;
+  }
+  if (/[a-zA-Z%]/.test(rebased)) return null;
+  return { rebased, substituted };
+}
+function safeArithmetic(expression) {
+  if (!/^[\d.\s+\-*/()]+$/.test(expression)) {
+    throw new Error(`Disallowed characters in expression: "${expression}"`);
+  }
+  const fn = new Function(`return (${expression});`);
+  return fn();
+}
+function evaluateValue(value, context) {
+  if (value === null || value === void 0) {
+    return { resolved: null, reason: "Value is null/undefined" };
+  }
+  if (isPrimitive(value)) {
+    return { resolved: value };
+  }
+  if (isReference(value)) {
+    const targetResolution = resolveReferenceTarget(value, context);
+    const isTopLevel = !context.visited || context.visited.size === 0;
+    if (isTopLevel && targetResolution.resolved !== null) {
+      return { ...targetResolution, aliasTarget: value.name };
+    }
+    return targetResolution;
+  }
+  if (isCss(value)) {
+    return evaluateCss(value, context);
+  }
+  if (Array.isArray(value)) {
+    return {
+      resolved: null,
+      reason: "Heterogeneous array — DTCG composite encoding not yet implemented"
+    };
+  }
+  return {
+    resolved: null,
+    reason: `Unsupported value shape: ${typeof value}`
+  };
+}
+const TOKENS_SCHEMA_URL = "https://design-tokens.org/schemas/2025.10/tokens.json";
+const RESOLVER_SCHEMA_URL = "https://www.designtokens.org/schemas/2025.10/resolver.json";
+function buildVariableMap(root) {
+  const map = /* @__PURE__ */ new Map();
+  for (const v of root.variables) map.set(v.name, v);
+  for (const theme of root.themes) {
+    for (const v of theme.variables) {
+      if (!map.has(v.name)) map.set(v.name, v);
+    }
+  }
+  return map;
+}
+function processVariable(variable, context) {
+  const evaluation = evaluateValue(variable.value, context);
+  const classification = classifyValueForVariable(variable.name, evaluation);
+  return { name: variable.name, evaluation, classification };
+}
+function classifyValueForVariable(name, evaluation) {
+  if (evaluation.resolved === null) return void 0;
+  return dtcg.classifyValue(evaluation.resolved, { path: name });
+}
+function setNestedToken(doc, dotPath, token) {
+  const segments = dotPath.split(".");
+  let cursor = doc;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const next = cursor[segment];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      cursor[segment] = {};
+    } else if ("$value" in next) {
+      cursor[segment] = { $root: next };
+    }
+    cursor = cursor[segment];
+  }
+  const leaf = segments[segments.length - 1];
+  const existing = cursor[leaf];
+  if (typeof existing === "object" && existing !== null && !Array.isArray(existing) && !("$value" in existing)) {
+    existing.$root = token;
+  } else {
+    cursor[leaf] = token;
+  }
+}
+function setNestedOverride(context, dotPath, value, type) {
+  const segments = dotPath.split(".");
+  let cursor = context;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const next = cursor[segment];
+    if (typeof next !== "object" || next === null || Array.isArray(next) || "$value" in next) {
+      cursor[segment] = {};
+    }
+    cursor = cursor[segment];
+  }
+  const token = { $value: value };
+  if (type !== void 0) token.$type = type;
+  cursor[segments[segments.length - 1]] = token;
+}
+function makeAliasToken(target, type, description) {
+  const token = { $value: dtcg.formatAlias(target) };
+  if (type !== void 0) token.$type = type;
+  return token;
+}
+function makeValueToken(classification, description, fluidBound) {
+  const token = {
+    $value: classification.value,
+    $type: classification.type
+  };
+  if (fluidBound) {
+    token.$extensions = {
+      "dev.styleframe": { fluidBound }
+    };
+  }
+  return token;
+}
+function makeExpressionToken(expression, description) {
+  const token = {
+    $value: expression,
+    $extensions: {
+      "dev.styleframe": { expression }
+    }
+  };
+  return token;
+}
+function valuesEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (typeof a === "object") return JSON.stringify(a) === JSON.stringify(b);
+  return false;
+}
+function capitalizeContextName(name) {
+  if (name.length === 0) return name;
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function buildDTCG(root, options = {}) {
+  const includeSchema = options.includeSchema ?? true;
+  const schemaUrl = options.schemaUrl ?? TOKENS_SCHEMA_URL;
+  const modifierName = options.modifierName ?? "theme";
+  const collectionName = options.collectionName ?? "Design Tokens";
+  const defaultModeName = options.defaultModeName ?? "Default";
+  const tokensSourceRef = options.tokensSourceRef ?? "tokens.json";
+  const variableMap = buildVariableMap(root);
+  const fluidMaxVariable = variableMap.get("fluid.max-width");
+  const fluidMaxResolved = fluidMaxVariable ? evaluateValue(fluidMaxVariable.value, { variables: variableMap }).resolved : null;
+  const maxViewport = typeof fluidMaxResolved === "number" ? fluidMaxResolved : 1440;
+  const context = { variables: variableMap, maxViewport };
+  const processed = /* @__PURE__ */ new Map();
+  const typeMap = /* @__PURE__ */ new Map();
+  for (const variable of root.variables) {
+    const p = processVariable(variable, context);
+    processed.set(variable.name, p);
+    if (p.classification) typeMap.set(variable.name, p.classification.type);
+  }
+  const resolveTypeFromAliasChain = (name, seen) => {
+    if (seen.has(name)) return void 0;
+    const direct = typeMap.get(name);
+    if (direct) return direct;
+    const p = processed.get(name);
+    if (p?.evaluation.aliasTarget) {
+      return resolveTypeFromAliasChain(
+        p.evaluation.aliasTarget,
+        /* @__PURE__ */ new Set([...seen, name])
+      );
+    }
+    return void 0;
+  };
+  const tokens = {};
+  if (includeSchema) tokens.$schema = schemaUrl;
+  tokens.$extensions = {
+    "dev.styleframe": { collection: collectionName }
+  };
+  const diagnostics = [];
+  let emittedCount = 0;
+  let fluidNormalisedCount = 0;
+  for (const variable of root.variables) {
+    const p = processed.get(variable.name);
+    if (!p) continue;
+    const { evaluation, classification } = p;
+    if (evaluation.aliasTarget) {
+      const targetType = resolveTypeFromAliasChain(
+        evaluation.aliasTarget,
+        /* @__PURE__ */ new Set()
+      );
+      setNestedToken(
+        tokens,
+        variable.name,
+        makeAliasToken(evaluation.aliasTarget, targetType)
+      );
+      emittedCount++;
+      continue;
+    }
+    if (classification) {
+      const fluidBound = evaluation.normalisationSource === "fluid-max" ? "max" : void 0;
+      const promoted = fluidBound && classification.type === "number" && typeof classification.value === "number" ? {
+        type: "dimension",
+        value: { value: classification.value, unit: "px" }
+      } : classification;
+      setNestedToken(
+        tokens,
+        variable.name,
+        makeValueToken(promoted, void 0, fluidBound)
+      );
+      if (fluidBound) fluidNormalisedCount++;
+      emittedCount++;
+      continue;
+    }
+    if (evaluation.cssExpression) {
+      setNestedToken(
+        tokens,
+        variable.name,
+        makeExpressionToken(evaluation.cssExpression)
+      );
+      diagnostics.push({
+        name: variable.name,
+        level: "warn",
+        reason: evaluation.reason ?? "Computed expression — preserved as dev.styleframe.expression extension"
+      });
+      emittedCount++;
+      continue;
+    }
+    if (evaluation.resolved !== null && typeof evaluation.resolved !== "boolean") {
+      setNestedToken(tokens, variable.name, {
+        $value: String(evaluation.resolved),
+        $extensions: { "dev.styleframe": { unknownType: true } }
+      });
+      diagnostics.push({
+        name: variable.name,
+        level: "warn",
+        reason: "Could not infer DTCG $type — emitted as untyped string"
+      });
+      emittedCount++;
+      continue;
+    }
+    diagnostics.push({
+      name: variable.name,
+      level: "warn",
+      reason: evaluation.reason ?? "Unrepresentable value — skipped"
+    });
+  }
+  const themedThemes = root.themes.filter(
+    (t) => t.variables.length > 0
+  );
+  let resolver;
+  if (themedThemes.length > 0) {
+    const contexts = {};
+    for (const theme of themedThemes) {
+      const contextDoc = {};
+      for (const variable of theme.variables) {
+        const themeProcessed = processVariable(variable, context);
+        const defaultProcessed = processed.get(variable.name);
+        let themeValue;
+        let themeType;
+        if (themeProcessed.evaluation.aliasTarget) {
+          themeValue = dtcg.formatAlias(themeProcessed.evaluation.aliasTarget);
+          themeType = resolveTypeFromAliasChain(
+            themeProcessed.evaluation.aliasTarget,
+            /* @__PURE__ */ new Set()
+          );
+        } else if (themeProcessed.classification) {
+          themeValue = themeProcessed.classification.value;
+          themeType = themeProcessed.classification.type;
+        }
+        if (themeValue === void 0) continue;
+        let defaultValue;
+        if (defaultProcessed?.evaluation.aliasTarget) {
+          defaultValue = dtcg.formatAlias(defaultProcessed.evaluation.aliasTarget);
+        } else if (defaultProcessed?.classification) {
+          defaultValue = defaultProcessed.classification.value;
+        }
+        if (defaultValue !== void 0 && valuesEqual(themeValue, defaultValue)) {
+          continue;
+        }
+        setNestedOverride(
+          contextDoc,
+          variable.name,
+          themeValue,
+          themeType
+        );
+      }
+      contexts[capitalizeContextName(theme.name)] = contextDoc;
+    }
+    for (const key of Object.keys(contexts)) {
+      if (Object.keys(contexts[key]).length === 0)
+        delete contexts[key];
+    }
+    const themeContextNames = Object.keys(contexts);
+    if (themeContextNames.length > 0) {
+      const allContexts = {
+        [defaultModeName]: []
+      };
+      for (const name of themeContextNames) {
+        allContexts[name] = [contexts[name]];
+      }
+      resolver = {
+        $schema: RESOLVER_SCHEMA_URL,
+        version: "2025.10",
+        modifiers: {
+          [modifierName]: {
+            contexts: allContexts,
+            default: defaultModeName
+          }
+        },
+        resolutionOrder: [
+          { type: "set", sources: [{ $ref: tokensSourceRef }] },
+          { $ref: `#/modifiers/${modifierName}` }
+        ]
+      };
+    }
+  }
+  return {
+    tokens,
+    resolver,
+    diagnostics,
+    emittedCount,
+    fluidNormalisedCount,
+    maxViewport
+  };
+}
+const _export = citty.defineCommand({
+  meta: {
+    name: "export",
+    description: "Export Styleframe variables to spec-conformant DTCG JSON"
+  },
+  args: {
+    config: {
+      type: "string",
+      description: "Path to the Styleframe config file",
+      default: "styleframe.config.ts",
+      alias: ["c"],
+      valueHint: "path"
+    },
+    output: {
+      type: "string",
+      description: "Output JSON file path",
+      default: "tokens.json",
+      alias: ["o"],
+      valueHint: "path"
+    },
+    collection: {
+      type: "string",
+      description: "Collection name embedded in the export",
+      default: "Design Tokens",
+      alias: ["n", "name"]
+    }
+  },
+  async run({ args }) {
+    const configPath = path.resolve(args.config);
+    const outputPath = path.resolve(args.output);
+    consola.info(
+      `Loading configuration from "${path.relative(process.cwd(), configPath)}"...`
+    );
+    const instance = await loader.loadConfiguration({ entry: configPath });
+    const root = instance.root;
+    consola.info("Building DTCG document...");
+    const {
+      tokens,
+      resolver,
+      diagnostics,
+      emittedCount,
+      fluidNormalisedCount,
+      maxViewport
+    } = buildDTCG(root, {
+      collectionName: args.collection,
+      tokensSourceRef: path.basename(outputPath)
+    });
+    await promises.writeFile(outputPath, `${JSON.stringify(tokens, null, 2)}
+`);
+    consola.info(
+      `Wrote ${emittedCount} tokens to "${path.relative(process.cwd(), outputPath)}"`
+    );
+    if (fluidNormalisedCount > 0) {
+      consola.info(
+        `Normalised ${fluidNormalisedCount} fluid token(s) using max viewport (${maxViewport}px).`
+      );
+    }
+    if (resolver) {
+      const resolverPath = outputPath.replace(/\.json$/, ".resolver.json");
+      await promises.writeFile(resolverPath, `${JSON.stringify(resolver, null, 2)}
+`);
+      consola.info(
+        `Wrote resolver to "${path.relative(process.cwd(), resolverPath)}"`
+      );
+    }
+    const warnings = diagnostics.filter((d) => d.level === "warn");
+    if (warnings.length > 0) {
+      consola.warn(
+        `${warnings.length} variable(s) needed special handling — see Styleframe ↔ DTCG round-trip notes`
+      );
+      for (const w of warnings.slice(0, 10)) {
+        consola.info(`  - ${w.name}: ${w.reason}`);
+      }
+      if (warnings.length > 10) {
+        consola.info(`  ... and ${warnings.length - 10} more`);
+      }
+      consola.info(
+        'Tip: untyped tokens are usually CSS keywords (e.g. "normal", "thin", "italic") with no DTCG equivalent — they round-trip to Figma as STRING variables.'
+      );
+    }
+    consola.success(
+      `Exported ${emittedCount} tokens in DTCG format to "${path.relative(process.cwd(), outputPath)}"`
+    );
+  }
+});
+exports.default = _export;