@mp3wizard/figma-console-mcp 1.25.1 → 1.28.2

package/dist/cloudflare/core/tokens/figma-converter.js

@@ -0,0 +1,195 @@
+/**
+ * Convert Figma's variables API response into our canonical TokenDocument.
+ *
+ * Input: the shape produced by `formatVariables()` in src/core/figma-api.ts
+ * (an object with `collections` and `variables` arrays, matching either the
+ * REST API's response or the Desktop Bridge plugin's `getLocalVariablesAsync`
+ * normalized payload).
+ *
+ * Output: a TokenDocument with one TokenSet per collection, paths derived
+ * from Figma variable names (slash-separated → path arrays), values
+ * normalized to our TokenValue shape, and Figma IDs preserved in
+ * $extensions["figma-console-mcp"] for round-trip non-destructiveness.
+ */
+/**
+ * Convert a Figma variables payload to our canonical TokenDocument.
+ */
+export function convertFigmaVariablesToDocument(payload, opts = {}) {
+    const warnings = [];
+    // Build a variable index for alias resolution: variableId → variable
+    const variableById = new Map();
+    for (const v of payload.variables)
+        variableById.set(v.id, v);
+    // Filter collections per scope.
+    const wantedCollections = opts.collectionIds?.length
+        ? payload.collections.filter((c) => opts.collectionIds.includes(c.id))
+        : payload.collections;
+    const sets = wantedCollections.map((collection) => convertCollection(collection, payload.variables, variableById, opts, warnings));
+    return {
+        document: {
+            $schema: "https://figma-console-mcp.southleft.com/schemas/dtcg-extended-v1.json",
+            sets,
+            meta: {
+                figmaFileKey: opts.figmaFileKey,
+                exportedAt: opts.exportedAt ?? new Date().toISOString(),
+                mcpVersion: opts.mcpVersion,
+            },
+        },
+        warnings,
+    };
+}
+function convertCollection(collection, allVariables, variableById, opts, warnings) {
+    // Mode filter: keep only modes the caller wants, intersected with what
+    // the collection actually has.
+    const wantedModes = !opts.modes || opts.modes === "all"
+        ? collection.modes
+        : collection.modes.filter((m) => opts.modes.includes(m.name));
+    // Variables in this collection.
+    const collectionVars = allVariables.filter((v) => v.variableCollectionId === collection.id);
+    const tokens = collectionVars.map((variable) => convertVariable(variable, wantedModes, variableById, opts, warnings));
+    return {
+        name: collection.name,
+        modes: wantedModes.map((m) => m.name),
+        tokens,
+        meta: {
+            figmaCollectionId: collection.id,
+        },
+    };
+}
+function convertVariable(variable, wantedModes, variableById, opts, warnings) {
+    // Derive the hierarchical path from the Figma variable name. Figma uses
+    // slashes to indicate grouping: "color/brand/primary" → ["color", "brand", "primary"].
+    let name = variable.name;
+    if (opts.stripPrefix && name.startsWith(opts.stripPrefix)) {
+        name = name.slice(opts.stripPrefix.length);
+    }
+    const path = name.split("/").filter(Boolean);
+    // Map resolvedType to TokenType.
+    const type = mapResolvedType(variable.resolvedType, variable.name, warnings);
+    // Convert each (mode → value) pair to our TokenValue shape, filtered by
+    // the wanted modes.
+    const values = {};
+    for (const mode of wantedModes) {
+        const rawValue = variable.valuesByMode[mode.modeId];
+        if (rawValue === undefined) {
+            warnings.push(`Variable "${variable.name}" has no value for mode "${mode.name}" (${mode.modeId}); skipping that mode.`);
+            continue;
+        }
+        values[mode.name] = convertValue(rawValue, variable.resolvedType, variableById, warnings);
+    }
+    return {
+        path,
+        type,
+        description: variable.description || undefined,
+        values,
+        extensions: {
+            "figma-console-mcp": {
+                variableId: variable.id,
+                collectionId: variable.variableCollectionId,
+                lastSyncedAt: new Date().toISOString(),
+                // We snapshot the synced value so future merge calls can detect
+                // two-sided conflicts.
+                lastSyncedValue: { ...values },
+            },
+        },
+    };
+}
+function mapResolvedType(resolvedType, variableName, warnings) {
+    switch (resolvedType) {
+        case "COLOR":
+            return "color";
+        case "FLOAT":
+            // Figma FLOAT covers both pure numbers and dimensions. We default to
+            // "dimension" because the typical FLOAT variable represents spacing,
+            // sizing, or radius — all dimensions. A future enhancement could
+            // sniff the variable name (e.g. "opacity/*" → "number") for better
+            // type fidelity.
+            return inferFloatType(variableName);
+        case "STRING":
+            return inferStringType(variableName);
+        case "BOOLEAN":
+            return "boolean";
+        default: {
+            const _exhaustive = resolvedType;
+            warnings.push(`Unknown resolvedType "${_exhaustive}" for variable "${variableName}"; treating as string.`);
+            return "string";
+        }
+    }
+}
+function inferFloatType(variableName) {
+    const lower = variableName.toLowerCase();
+    if (lower.includes("opacity") || lower.includes("alpha"))
+        return "number";
+    if (lower.includes("font-weight") || lower.includes("weight"))
+        return "fontWeight";
+    if (lower.includes("duration") || lower.includes("delay"))
+        return "duration";
+    // Default: treat numeric variables as dimensions (px values).
+    return "dimension";
+}
+function inferStringType(variableName) {
+    const lower = variableName.toLowerCase();
+    if (lower.includes("font-family") || lower.includes("font/family"))
+        return "fontFamily";
+    return "string";
+}
+function convertValue(rawValue, resolvedType, variableById, warnings) {
+    // Alias references: convert variable ID → path-based reference for DTCG.
+    if (isVariableAlias(rawValue)) {
+        const target = variableById.get(rawValue.id);
+        if (!target) {
+            // Cross-library alias — target is in a published library this file
+            // consumes, not in the local variable set. Preserve the original
+            // Figma variable ID in the reference syntax so round-trip can
+            // recover it AND formatters can detect this is unresolvable (vs a
+            // genuine local-path alias).
+            warnings.push(`Alias to unknown variable ID ${rawValue.id} (likely a cross-library reference). Original ID preserved in reference for round-trip.`);
+            return { reference: `{__library:${rawValue.id}}` };
+        }
+        // The DTCG alias path uses dots: "color.brand.primary".
+        const dotPath = target.name.replace(/\//g, ".");
+        return { reference: `{${dotPath}}` };
+    }
+    // Literal values per type.
+    if (resolvedType === "COLOR") {
+        if (typeof rawValue === "object" && rawValue !== null && "r" in rawValue) {
+            return { literal: rgbaToHex(rawValue) };
+        }
+        warnings.push(`COLOR value isn't an RGB object: ${JSON.stringify(rawValue)}`);
+        return { literal: String(rawValue) };
+    }
+    if (resolvedType === "FLOAT") {
+        return { literal: typeof rawValue === "number" ? rawValue : Number(rawValue) };
+    }
+    if (resolvedType === "BOOLEAN") {
+        return { literal: Boolean(rawValue) };
+    }
+    // STRING and fallthrough.
+    return { literal: typeof rawValue === "string" ? rawValue : String(rawValue) };
+}
+function isVariableAlias(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "VARIABLE_ALIAS");
+}
+/**
+ * Convert Figma's `{r, g, b, a}` floats (0–1 range) to a hex string. Returns
+ * `#RRGGBB` when alpha is 1 (or absent), `#RRGGBBAA` when alpha < 1.
+ */
+function rgbaToHex(rgba) {
+    const r = clampByte(rgba.r);
+    const g = clampByte(rgba.g);
+    const b = clampByte(rgba.b);
+    const a = rgba.a ?? 1;
+    const hex = `#${byteToHex(r)}${byteToHex(g)}${byteToHex(b)}`;
+    if (a >= 1)
+        return hex;
+    return `${hex}${byteToHex(clampByte(a))}`;
+}
+function clampByte(f) {
+    return Math.max(0, Math.min(255, Math.round(f * 255)));
+}
+function byteToHex(byte) {
+    return byte.toString(16).padStart(2, "0").toUpperCase();
+}

package/dist/cloudflare/core/tokens/formatters/css-vars.js

@@ -0,0 +1,329 @@
+/**
+ * CSS custom properties formatter.
+ *
+ * Converts a TokenDocument to one or more CSS files containing `:root { ... }`
+ * (and optionally per-mode selectors like `.dark { ... }`). The first
+ * "real" non-DTCG output, completing the canonical-to-runtime pipeline.
+ *
+ * Behavior:
+ *   - Each token becomes a CSS custom property. Path joined with `-`,
+ *     optionally prefixed. `color/primary` → `--color-primary`.
+ *   - Aliases resolve to `var(--target-token)` so CSS cascading still works.
+ *   - Composite tokens (typography, shadow) expand into multiple primitive
+ *     custom properties since CSS doesn't natively express composites.
+ *   - Single-mode tokens go in `:root`.
+ *   - Multi-mode tokens emit per-mode selectors. Heuristic: a mode named
+ *     `Light`/`Default` becomes `:root`; `Dark` becomes `.dark` (Tailwind
+ *     convention); other modes become `[data-theme="<name>"]`.
+ *   - splitByMode emits one file per mode with just that mode's values.
+ *   - splitByCollection emits one file per set.
+ */
+export function formatCssVars(doc, opts) {
+    const warnings = [];
+    const files = [];
+    const splitByMode = opts.target.splitByMode ?? false;
+    const splitByCollection = opts.target.splitByCollection ?? false;
+    const prefix = opts.target.prefix ?? "";
+    if (splitByMode && splitByCollection) {
+        // One file per (set, mode) pair.
+        for (const set of doc.sets) {
+            for (const mode of set.modes) {
+                files.push({
+                    path: filenameFor(opts, set, mode),
+                    content: renderSingleSelector(doc.sets.filter((s) => s.name === set.name), mode, selectorFor(mode), prefix, warnings),
+                });
+            }
+        }
+    }
+    else if (splitByMode) {
+        // One file per mode, all sets combined under that mode's selector.
+        const allModes = new Set();
+        for (const set of doc.sets)
+            for (const m of set.modes)
+                allModes.add(m);
+        for (const mode of allModes) {
+            const setsWithMode = doc.sets.filter((s) => s.modes.includes(mode));
+            files.push({
+                path: filenameFor(opts, undefined, mode),
+                content: renderSingleSelector(setsWithMode, mode, selectorFor(mode), prefix, warnings),
+            });
+        }
+    }
+    else if (splitByCollection) {
+        // One file per set, all modes combined as separate selectors within.
+        for (const set of doc.sets) {
+            files.push({
+                path: filenameFor(opts, set),
+                content: renderMultiSelector([set], prefix, warnings),
+            });
+        }
+    }
+    else {
+        // Single file with everything.
+        files.push({
+            path: filenameFor(opts),
+            content: renderMultiSelector(doc.sets, prefix, warnings),
+        });
+    }
+    return { files, warnings };
+}
+function filenameFor(opts, set, mode) {
+    if (opts.target.filename)
+        return opts.target.filename;
+    const parts = [];
+    if (set)
+        parts.push(slugify(set.name));
+    if (mode)
+        parts.push(slugify(mode));
+    if (parts.length === 0)
+        parts.push("tokens");
+    return `${parts.join(".")}.css`;
+}
+function slugify(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Map a mode name to a CSS selector. Conventional defaults that match what
+ * most CSS frameworks expect:
+ *   - Default / Light / Value → `:root` (the document root, runs always)
+ *   - Dark → `.dark` (matches Tailwind's darkMode: "class" config)
+ *   - anything else → `[data-theme="<name>"]` (general escape hatch)
+ */
+function selectorFor(mode) {
+    const lower = mode.toLowerCase();
+    if (lower === "default" || lower === "light" || lower === "value") {
+        return ":root";
+    }
+    if (lower === "dark") {
+        return ".dark";
+    }
+    return `[data-theme="${slugify(mode)}"]`;
+}
+/**
+ * Render all tokens across the given sets under a single selector. Used when
+ * one file holds one mode's worth of vars (splitByMode output).
+ */
+function renderSingleSelector(sets, mode, selector, prefix, warnings) {
+    const lines = [];
+    lines.push(`/* Generated by figma-console-mcp — do not edit by hand */`);
+    lines.push(`${selector} {`);
+    for (const set of sets) {
+        for (const token of set.tokens) {
+            const value = token.values[mode];
+            if (!value)
+                continue;
+            emitTokenLines(token, value, prefix, lines, warnings);
+        }
+    }
+    lines.push(`}`);
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Render multiple sets across multiple modes in one file. Each mode gets its
+ * own selector block.
+ */
+function renderMultiSelector(sets, prefix, warnings) {
+    const lines = [];
+    lines.push(`/* Generated by figma-console-mcp — do not edit by hand */`);
+    // Collect all (mode, selector) pairs across all sets.
+    const modeToSelector = new Map();
+    for (const set of sets) {
+        for (const mode of set.modes) {
+            if (!modeToSelector.has(mode)) {
+                modeToSelector.set(mode, selectorFor(mode));
+            }
+        }
+    }
+    for (const [mode, selector] of modeToSelector) {
+        lines.push(`${selector} {`);
+        for (const set of sets) {
+            if (!set.modes.includes(mode))
+                continue;
+            for (const token of set.tokens) {
+                const value = token.values[mode];
+                if (!value)
+                    continue;
+                emitTokenLines(token, value, prefix, lines, warnings);
+            }
+        }
+        lines.push(`}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Emit one or more CSS custom property declarations for a single token.
+ * Primitives emit one line; composite tokens (typography, shadow) expand
+ * into multiple lines.
+ */
+function emitTokenLines(token, value, prefix, out, warnings) {
+    // Every path segment must be a valid CSS identifier — slugify each to
+    // normalize spaces, dots, and other special characters that show up in
+    // real Figma variable names (e.g. "tailwind colors/purple/50").
+    const cssName = `--${prefix}${pathToCssName(token.path)}`;
+    if (value.reference) {
+        // Detect the cross-library alias sentinel ({__library:VariableID:...}).
+        // Emitting var() for these produces broken CSS — the target doesn't
+        // live in this file's variable set. Emit a clear comment that names
+        // the original library variable ID instead, so the user can decide
+        // how to handle it (manual literal, library import, etc.).
+        const bareRef = value.reference.replace(/^\{|\}$/g, "");
+        const libMatch = bareRef.match(/^__library:(.+)$/);
+        if (libMatch || bareRef === "unknown") {
+            const originalId = libMatch ? libMatch[1] : "unknown";
+            warnings.push(`Skipped ${token.path.join(".")} in CSS — references cross-library variable ${originalId}.`);
+            out.push(`  /* ${cssName}: skipped — cross-library alias to ${originalId} */`);
+            return;
+        }
+        // Alias → var(--other) so CSS cascading semantics are preserved. The
+        // target path goes through the same slugify treatment as the source.
+        const refPath = bareRef.split(".");
+        const targetCssName = pathToCssName(refPath);
+        out.push(`  ${cssName}: var(--${prefix}${targetCssName});`);
+        return;
+    }
+    if (value.literal === undefined || value.literal === null) {
+        warnings.push(`Token ${token.path.join(".")} has no value — emitting nothing.`);
+        return;
+    }
+    // Composite tokens — expand into multiple primitive vars.
+    if (token.type === "typography" && typeof value.literal === "object") {
+        const t = value.literal;
+        for (const subField of ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing"]) {
+            if (t[subField] !== undefined) {
+                out.push(`  ${cssName}-${kebab(subField)}: ${formatCssValue(t[subField], token.type)};`);
+            }
+        }
+        return;
+    }
+    if (token.type === "shadow" && typeof value.literal === "object") {
+        const shadowCss = renderShadow(value.literal);
+        if (shadowCss) {
+            out.push(`  ${cssName}: ${shadowCss};`);
+        }
+        else {
+            warnings.push(`Token ${token.path.join(".")} has an unparseable shadow value — skipping.`);
+        }
+        return;
+    }
+    // Primitives.
+    out.push(`  ${cssName}: ${formatCssValue(value.literal, token.type)};`);
+}
+function kebab(s) {
+    return s.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Convert a path array to a CSS-safe custom property name. Each segment is
+ * slugified (lowercase, non-alphanumerics → hyphens) before joining.
+ *
+ * Examples:
+ *   ["color", "primary"]                  → "color-primary"
+ *   ["tailwind colors", "purple", "50"]   → "tailwind-colors-purple-50"
+ *   ["UI", "background-default"]          → "ui-background-default"
+ */
+function pathToCssName(path) {
+    return path.map((seg) => slugify(seg)).join("-");
+}
+/**
+ * Render a primitive value as a CSS literal.
+ *   - Numbers gain a "px" suffix when the token type is `dimension`.
+ *   - Color-typed strings pass through (hex, oklch, rgba, hsl).
+ *   - fontFamily-typed strings get quoted (multi-word family names are
+ *     invalid CSS otherwise — e.g. "Geist Mono" must be `"Geist Mono"`).
+ *   - Plain string tokens get quoted too, since CSS treats unquoted
+ *     identifiers as keywords. Strings that look like a CSS color or unit
+ *     stay unquoted.
+ *   - Booleans render as their string form.
+ */
+function formatCssValue(value, type) {
+    if (typeof value === "number") {
+        if (type === "dimension")
+            return `${value}px`;
+        return String(value);
+    }
+    if (typeof value === "string") {
+        // Color-typed values are always pre-formatted CSS color literals.
+        if (type === "color")
+            return value;
+        // fontFamily and plain strings need quoting unless they look like a
+        // CSS-safe identifier with no special characters. Quote conservatively
+        // — over-quoting is fine, under-quoting breaks the cascade.
+        if (type === "fontFamily" || type === "string") {
+            return needsQuoting(value) ? JSON.stringify(value) : value;
+        }
+        // Dimensions and other types: pass through (already formatted upstream).
+        return value;
+    }
+    if (typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+/**
+ * Returns true if a string value needs to be wrapped in CSS quotes. Multi-word
+ * values, values with special characters, or values that aren't pure
+ * alphanumeric identifiers all need quoting.
+ */
+function needsQuoting(s) {
+    // Anything that already has quotes is fine.
+    if (/^["']/.test(s))
+        return false;
+    // Pure-numeric or unit-bearing values don't need quotes (they're not
+    // identifiers).
+    if (/^[\d.]+([a-z%]+)?$/.test(s))
+        return false;
+    // CSS keyword identifiers (single word, alphanumerics + hyphen only).
+    if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(s)) {
+        // Reserved CSS keywords that shouldn't be quoted (the user may have
+        // legitimately written e.g. "inherit", "currentColor", "transparent").
+        const cssKeywords = new Set([
+            "inherit",
+            "initial",
+            "unset",
+            "revert",
+            "currentColor",
+            "transparent",
+            "none",
+            "auto",
+        ]);
+        if (cssKeywords.has(s))
+            return false;
+        // Any other single identifier — for font-family this is OK unquoted
+        // ("Inter" works) but it's safer to quote for clarity. Keep unquoted
+        // to match the more common convention.
+        return false;
+    }
+    // Multi-word, special chars, etc. → quote.
+    return true;
+}
+function renderShadow(shadow) {
+    if (Array.isArray(shadow)) {
+        return shadow
+            .map((s) => renderShadow(s))
+            .filter(Boolean)
+            .join(", ");
+    }
+    if (!shadow || typeof shadow !== "object")
+        return null;
+    const s = shadow;
+    const inset = s.inset ? "inset " : "";
+    const x = withPx(s.offsetX);
+    const y = withPx(s.offsetY);
+    const blur = withPx(s.blur);
+    const spread = s.spread !== undefined ? ` ${withPx(s.spread)}` : "";
+    const color = s.color;
+    if (!x || !y || !blur || typeof color !== "string")
+        return null;
+    return `${inset}${x} ${y} ${blur}${spread} ${color}`;
+}
+function withPx(v) {
+    if (typeof v === "number")
+        return `${v}px`;
+    if (typeof v === "string")
+        return v;
+    return "";
+}