@3fn/core 14.1.0 → 15.0.0

package/dist/generators/DTCGFormatGenerator.d.ts

@@ -290,12 +290,22 @@ export declare class DTCGFormatGenerator {
      */
     private generateDimensionGroup;
     /**
-     * Resolve a color token's RGBA value from its mode/theme structure.
-     * Uses light.base as the default resolved value for DTCG output.
+     * Resolve a color token's value for DTCG output.
+     *
+     * OKLCH-sourced primitives (Spec 112, `composedColorMap`) are checked FIRST —
+     * mirroring `SemanticValueResolver.resolveColorPrimitive()` — and converted to
+     * sRGB hex via `oklchToExportHex` (CSS Color Level 4 gamut mapping). This keeps
+     * DTCG/Figma export in agreement with the OKLCH source of record that drives
+     * CSS/Swift/Kotlin, closing the dual-color-source divergence (see
+     * `.kiro/issues/2026-08-25-dual-color-source-divergence.md`, Option A).
+     *
+     * Only primitives absent from `composedColorMap` (the four legacy-only shadow
+     * primitives: shadowBlack100, shadowBlue100, shadowOrange100, shadowGray100)
+     * fall through to the legacy RGBA `light.base` path.
      *
      * @param token - The primitive color token to resolve
-     * @param tokenName - Optional token name for error messages
-     * @returns Resolved color string (e.g., "rgba(255, 0, 0, 1)")
+     * @param tokenName - Optional token name for error messages / composedColorMap lookup fallback
+     * @returns Resolved color string (e.g., "#818b9c" or "rgba(255, 0, 0, 1)")
      * @throws Error if the resolved color value is not a valid color format
      */
     private resolveColorValue;

package/dist/generators/DTCGFormatGenerator.js

@@ -57,6 +57,8 @@ const index_2 = require("../tokens/semantic/index");
 // Primitive token imports
 const SpacingTokens_1 = require("../tokens/SpacingTokens");
 const ColorTokens_1 = require("../tokens/ColorTokens");
+const color_1 = require("../tokens/color");
+const OklchExportUtils_1 = require("./oklch/OklchExportUtils");
 const FontSizeTokens_1 = require("../tokens/FontSizeTokens");
 const FontWeightTokens_1 = require("../tokens/FontWeightTokens");
 const FontFamilyTokens_1 = require("../tokens/FontFamilyTokens");
@@ -319,6 +321,13 @@ class DTCGFormatGenerator {
         for (const [key, token] of Object.entries(ColorTokens_1.colorTokens)) {
             const colorValue = this.resolveColorValue(token, key);
             const extensions = this.buildPrimitiveExtensions(token, 'color');
+            // Spec 112 traceability: record the OKLCH source of record for primitives
+            // that resolved through composedColorMap, so consumers can see the value
+            // this hex was derived from (nice-to-have; hex $value is the requirement).
+            const composed = color_1.composedColorMap.get(token.name || key);
+            if (composed) {
+                extensions.oklch = { ...composed.resolved };
+            }
             group[key] = this.toDTCGToken(colorValue, 'color', token.description, extensions);
         }
         return group;
@@ -543,7 +552,10 @@ class DTCGFormatGenerator {
             const extensions = {
                 family: 'color',
             };
-            // Spec 080: emit mode contexts for Level 2 overrides or Level 1 primitive differences
+            // Spec 080: emit mode contexts for Level 2 overrides.
+            // (Level 1 — "does the primitive itself carry distinct light/dark values" —
+            // was removed here: zero legacy primitives ever satisfied that predicate,
+            // per `.kiro/issues/2026-08-25-dual-color-source-divergence.md`. It never fired.)
             const override = SemanticOverrides_1.darkSemanticOverrides[key];
             if (override) {
                 // Level 2: semantic override swaps primitive name in dark mode
@@ -560,19 +572,6 @@ class DTCGFormatGenerator {
                     extensions.modes.dark = darkVal;
                 }
             }
-            else {
-                // Level 1: check if primitive itself has distinct light/dark values
-                const primitiveToken = ColorTokens_1.colorTokens[primaryRef];
-                if (primitiveToken) {
-                    const colorVal = primitiveToken.platforms.web.value;
-                    if (colorVal?.light?.base && colorVal?.dark?.base && colorVal.light.base !== colorVal.dark.base) {
-                        if (!extensions.modes)
-                            extensions.modes = {};
-                        extensions.modes.light = colorVal.light.base;
-                        extensions.modes.dark = colorVal.dark.base;
-                    }
-                }
-            }
             // If token has separate color + opacity composition, note it
             if (refs.color && refs.opacity) {
                 extensions.primitiveRefs = { color: refs.color, opacity: refs.opacity };
@@ -1132,15 +1131,33 @@ class DTCGFormatGenerator {
         return group;
     }
     /**
-     * Resolve a color token's RGBA value from its mode/theme structure.
-     * Uses light.base as the default resolved value for DTCG output.
+     * Resolve a color token's value for DTCG output.
+     *
+     * OKLCH-sourced primitives (Spec 112, `composedColorMap`) are checked FIRST —
+     * mirroring `SemanticValueResolver.resolveColorPrimitive()` — and converted to
+     * sRGB hex via `oklchToExportHex` (CSS Color Level 4 gamut mapping). This keeps
+     * DTCG/Figma export in agreement with the OKLCH source of record that drives
+     * CSS/Swift/Kotlin, closing the dual-color-source divergence (see
+     * `.kiro/issues/2026-08-25-dual-color-source-divergence.md`, Option A).
+     *
+     * Only primitives absent from `composedColorMap` (the four legacy-only shadow
+     * primitives: shadowBlack100, shadowBlue100, shadowOrange100, shadowGray100)
+     * fall through to the legacy RGBA `light.base` path.
      *
      * @param token - The primitive color token to resolve
-     * @param tokenName - Optional token name for error messages
-     * @returns Resolved color string (e.g., "rgba(255, 0, 0, 1)")
+     * @param tokenName - Optional token name for error messages / composedColorMap lookup fallback
+     * @returns Resolved color string (e.g., "#818b9c" or "rgba(255, 0, 0, 1)")
      * @throws Error if the resolved color value is not a valid color format
      */
     resolveColorValue(token, tokenName) {
+        const lookupName = token.name || tokenName;
+        if (lookupName) {
+            const composed = color_1.composedColorMap.get(lookupName);
+            if (composed) {
+                const { l, c, h } = composed.resolved;
+                return (0, OklchExportUtils_1.oklchToExportHex)(l, c, h).hex;
+            }
+        }
         const webValue = token.platforms.web.value;
         let resolved;
         if (typeof webValue === 'string') {

package/dist/generators/TokenFileGenerator.js

@@ -1167,34 +1167,34 @@ class TokenFileGenerator {
      */
     generateMotionSection(platform) {
         const lines = [];
-        // Import platform builders for motion token generation
-        const { WebBuilder } = require('../build/platforms/WebBuilder');
-        const { iOSBuilder } = require('../build/platforms/iOSBuilder');
-        const { AndroidBuilder } = require('../build/platforms/AndroidBuilder');
-        // Select appropriate builder based on platform
-        let builder;
+        // Import platform motion-token formatters
+        const { WebMotionTokenFormatter } = require('../build/platforms/WebMotionTokenFormatter');
+        const { iOSMotionTokenFormatter } = require('../build/platforms/iOSMotionTokenFormatter');
+        const { AndroidMotionTokenFormatter } = require('../build/platforms/AndroidMotionTokenFormatter');
+        // Select appropriate formatter based on platform
+        let formatter;
         switch (platform) {
             case 'web':
-                builder = new WebBuilder();
+                formatter = new WebMotionTokenFormatter();
                 break;
             case 'ios':
-                builder = new iOSBuilder();
+                formatter = new iOSMotionTokenFormatter();
                 break;
             case 'android':
-                builder = new AndroidBuilder();
+                formatter = new AndroidMotionTokenFormatter();
                 break;
             default:
                 return lines;
         }
         // Generate primitive motion tokens
-        const durationLines = builder.generateDurationTokens(tokens_1.durationTokens);
-        const easingLines = builder.generateEasingTokens(tokens_1.easingTokens);
-        const scaleLines = builder.generateScaleTokens(tokens_1.scaleTokens);
+        const durationLines = formatter.generateDurationTokens(tokens_1.durationTokens);
+        const easingLines = formatter.generateEasingTokens(tokens_1.easingTokens);
+        const scaleLines = formatter.generateScaleTokens(tokens_1.scaleTokens);
         lines.push(durationLines);
         lines.push(easingLines);
         lines.push(scaleLines);
         // Generate semantic motion tokens
-        const semanticMotionLines = builder.generateSemanticMotionTokens(semantic_1.motionTokens);
+        const semanticMotionLines = formatter.generateSemanticMotionTokens(semantic_1.motionTokens);
         lines.push(semanticMotionLines);
         return lines;
     }

package/dist/generators/generateTokenIndex.d.ts

@@ -36,7 +36,21 @@ export interface TokenIndexInput {
      * same source the application MCP already reads via `COMPONENTS_DIR`).
      */
     componentSchemaDir: string;
+    /**
+     * Absolute path to the LIVE token tier this index's data came from (e.g.
+     * `config.tokenSourceRoot` — the consumer's own tier when born, or the package's
+     * `src/tokens` in package-mode). Written into `token-index/meta.json` as `tierDir`
+     * so the application MCP's theme readers can find `themes/dark/SemanticOverrides.ts`
+     * relative to the SERVED index, not a guessed project root (Spec 123 Task 1.5, DD24).
+     */
+    tierDir?: string;
 }
+/**
+ * `tierDir` as written into `meta.json`: relative to the index directory, `/`-separated
+ * (`'.'` when they coincide). `undefined` stays `undefined`, so the key is omitted.
+ * @internal Exported for testing.
+ */
+export declare function relativeTierDir(indexDir: string, tierDir: string | undefined): string | undefined;
 /**
  * Generate the token index YAML files.
  *

package/dist/generators/generateTokenIndex.js

@@ -42,6 +42,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.relativeTierDir = relativeTierDir;
 exports.generateTokenIndex = generateTokenIndex;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -50,6 +51,17 @@ const PrimitiveToken_1 = require("../types/PrimitiveToken");
 const WebFormatGenerator_1 = require("../providers/WebFormatGenerator");
 const iOSFormatGenerator_1 = require("../providers/iOSFormatGenerator");
 const AndroidFormatGenerator_1 = require("../providers/AndroidFormatGenerator");
+/**
+ * `tierDir` as written into `meta.json`: relative to the index directory, `/`-separated
+ * (`'.'` when they coincide). `undefined` stays `undefined`, so the key is omitted.
+ * @internal Exported for testing.
+ */
+function relativeTierDir(indexDir, tierDir) {
+    if (tierDir === undefined)
+        return undefined;
+    const rel = path.relative(path.resolve(indexDir), path.resolve(tierDir));
+    return rel === '' ? '.' : rel.split(path.sep).join('/');
+}
 /** Build the mode-nested OKLCH value + sibling channel metadata for a color primitive. */
 function buildOklchEntry(modes) {
     // Match dist's exact OKLCH string format (WebFormatGenerator.formatOklchColor):
@@ -213,6 +225,17 @@ function generateTokenIndex(tokenIndexDir = 'token-index', input) {
     fs.writeFileSync(path.join(outputDir, 'primitives.yaml'), yaml.dump({ tokens: primitivesIndex }, { lineWidth: -1 }), 'utf-8');
     fs.writeFileSync(path.join(outputDir, 'semantics.yaml'), yaml.dump({ tokens: semanticsIndex }, { lineWidth: -1 }), 'utf-8');
     fs.writeFileSync(path.join(outputDir, 'components.yaml'), yaml.dump({ tokens: componentTokensIndex }, { lineWidth: -1 }), 'utf-8');
+    // Spec 123 Task 1.5 (DD24): record the live tier this index's data came from, so
+    // the application MCP's theme readers can find `themes/dark/SemanticOverrides.ts`
+    // relative to whichever index actually got served, not a guessed project root.
+    // Written RELATIVE to the index directory, with `/` separators, so the file is
+    // machine-independent: an absolute value shipped the publishing machine's path in
+    // the package (`.kiro/issues/2026-10-02-token-index-meta-ships-absolute-path.md`, F2).
+    // The package's own index records `../src/tokens`, which resolves inside the
+    // installed package because `src/tokens/**` ships. The resolver
+    // (`application-mcp-server/src/indexer/resolveThemeTierRoot.ts`) resolves it against
+    // the index directory. Key omitted when no tier is passed.
+    fs.writeFileSync(path.join(outputDir, 'meta.json'), JSON.stringify({ tierDir: relativeTierDir(outputDir, input.tierDir) }, null, 2) + '\n', 'utf-8');
     const counts = {
         primitives: Object.keys(primitivesIndex).length,
         semantics: Object.keys(semanticsIndex).length,

package/dist/generators/transformers/FigmaTransformer.d.ts

@@ -127,6 +127,17 @@ export declare class FigmaTransformer implements ITokenTransformer {
      * @requirements Req 2
      */
     private generateSemanticsCollection;
+    /**
+     * Derive a collection's declared modes from the modes its variables actually carry.
+     *
+     * The declaration and the emitted `valuesByMode` keys must agree — a collection that
+     * declares a mode no variable carries (or carries one it never declares) produces an
+     * invalid Figma payload. `light` and `dark` are always present because every variable
+     * emits both; additional modes appear only when the DTCG source supplies them
+     * (`$extensions.designerpunk.modes`), so a future `wcag` emission flows through with
+     * no change here.
+     */
+    private collectModes;
     /**
      * Recursively extract variables from a DTCG group.
      * Handles nested groups (e.g., semanticSpace.grouped.none).
@@ -240,6 +251,30 @@ export declare class FigmaTransformer implements ITokenTransformer {
      * Strips units from dimensions, passes numbers through, stringifies arrays.
      */
     resolveDirectValue(value: unknown, tokenType: DTCGType | undefined): unknown;
+    /**
+     * Resolve a per-mode override value from `$extensions.designerpunk.modes`.
+     *
+     * Mode overrides arrive in whatever form the DTCG generator resolved them to:
+     * an alias (`{color.white100}`), an `oklch(…)` string (the current semantic-color
+     * form — `DTCGFormatGenerator` resolves both modes to concrete values and does not
+     * retain the overriding primitive's name), or an `rgba()`/hex literal.
+     *
+     * Aliases stay aliases. Concrete colors convert to the hex form Figma expects.
+     * Anything unrecognised falls back to the base value rather than shipping a string
+     * Figma cannot parse.
+     *
+     * Note: a concrete override loses the primitive→semantic link for that mode — the
+     * variable references a primitive in light and carries a literal in dark. Restoring
+     * the link needs the overriding primitive's NAME in the DTCG extension, which the
+     * generator does not currently emit.
+     */
+    resolveModeValue(rawValue: unknown, tokenType: DTCGType | undefined, fallback: unknown): unknown;
+    /**
+     * Convert an `oklch(L C H)` or `oklch(L C H / A)` string to hex, gamut-clamped
+     * to sRGB. Alpha below 1 produces the 8-digit form, matching `rgbaToHex`.
+     * Returns null when the string cannot be parsed.
+     */
+    private oklchToHex;
     /**
      * Resolve an alias reference value for semantic tokens.
      * Preserves the alias format for Figma variable references.

package/dist/generators/transformers/FigmaTransformer.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FigmaTransformer = void 0;
+const OklchConverter_1 = require("../../color/OklchConverter");
 /**
  * Top-level DTCG groups that contain primitive tokens (direct values).
  * These become the Primitives collection in Figma.
@@ -154,7 +155,7 @@ class FigmaTransformer {
         }
         return {
             name: 'Primitives',
-            modes: ['light', 'dark'],
+            modes: this.collectModes(variables),
             variables,
         };
     }
@@ -175,10 +176,31 @@ class FigmaTransformer {
         }
         return {
             name: 'Semantics',
-            modes: ['light', 'dark', 'wcag'],
+            modes: this.collectModes(variables),
             variables,
         };
     }
+    /**
+     * Derive a collection's declared modes from the modes its variables actually carry.
+     *
+     * The declaration and the emitted `valuesByMode` keys must agree — a collection that
+     * declares a mode no variable carries (or carries one it never declares) produces an
+     * invalid Figma payload. `light` and `dark` are always present because every variable
+     * emits both; additional modes appear only when the DTCG source supplies them
+     * (`$extensions.designerpunk.modes`), so a future `wcag` emission flows through with
+     * no change here.
+     */
+    collectModes(variables) {
+        const seen = new Set(['light', 'dark']);
+        for (const variable of variables) {
+            for (const mode of Object.keys(variable.valuesByMode)) {
+                seen.add(mode);
+            }
+        }
+        // Stable order: the base pair first, then any additional modes alphabetically.
+        const extra = [...seen].filter((m) => m !== 'light' && m !== 'dark').sort();
+        return ['light', 'dark', ...extra];
+    }
     /**
      * Recursively extract variables from a DTCG group.
      * Handles nested groups (e.g., semanticSpace.grouped.none).
@@ -194,29 +216,32 @@ class FigmaTransformer {
             // If it has $value, it's a token
             if ('$value' in value && value.$value !== undefined) {
                 const token = value;
-                // Read WCAG mode override from extensions
+                // Mode overrides from extensions (e.g. { light: '…', dark: '…' })
                 const ext = token.$extensions?.designerpunk;
                 const modes = ext?.modes;
-                const wcagAlias = modes?.wcag;
                 const tokenType = token.$type ?? inheritedType;
                 const figmaName = this.toFigmaVariableName(parentPath, key);
                 const figmaType = this.dtcgTypeToFigmaType(tokenType);
                 const resolvedValue = isSemantic
                     ? this.resolveAliasValue(token.$value)
                     : this.resolveDirectValue(token.$value, tokenType);
-                // Resolve WCAG value if present, otherwise fall back to default
-                const wcagValue = wcagAlias && isSemantic
-                    ? this.resolveAliasValue(wcagAlias)
-                    : resolvedValue;
+                // The base value carries the primitive alias (semantics) or the literal
+                // (primitives). `light` keeps it so the primitive→semantic link survives
+                // into Figma; any mode the DTCG source overrides gets its own value.
+                const valuesByMode = {
+                    light: resolvedValue,
+                    dark: resolvedValue,
+                };
+                for (const [modeName, modeValue] of Object.entries(modes ?? {})) {
+                    if (modeName === 'light')
+                        continue; // the alias is strictly more useful
+                    valuesByMode[modeName] = this.resolveModeValue(modeValue, tokenType, resolvedValue);
+                }
                 const description = this.buildVariableDescription(token);
                 variables.push({
                     name: figmaName,
                     resolvedType: figmaType,
-                    valuesByMode: {
-                        light: resolvedValue,
-                        dark: resolvedValue,
-                        wcag: wcagValue,
-                    },
+                    valuesByMode,
                     ...(description ? { description } : {}),
                 });
             }
@@ -591,6 +616,69 @@ class FigmaTransformer {
         // Fallback: return as-is
         return value;
     }
+    /**
+     * Resolve a per-mode override value from `$extensions.designerpunk.modes`.
+     *
+     * Mode overrides arrive in whatever form the DTCG generator resolved them to:
+     * an alias (`{color.white100}`), an `oklch(…)` string (the current semantic-color
+     * form — `DTCGFormatGenerator` resolves both modes to concrete values and does not
+     * retain the overriding primitive's name), or an `rgba()`/hex literal.
+     *
+     * Aliases stay aliases. Concrete colors convert to the hex form Figma expects.
+     * Anything unrecognised falls back to the base value rather than shipping a string
+     * Figma cannot parse.
+     *
+     * Note: a concrete override loses the primitive→semantic link for that mode — the
+     * variable references a primitive in light and carries a literal in dark. Restoring
+     * the link needs the overriding primitive's NAME in the DTCG extension, which the
+     * generator does not currently emit.
+     */
+    resolveModeValue(rawValue, tokenType, fallback) {
+        if (typeof rawValue !== 'string') {
+            return rawValue ?? fallback;
+        }
+        // Alias reference — preserve the Figma variable link
+        if (rawValue.startsWith('{') && rawValue.endsWith('}')) {
+            return this.resolveAliasValue(rawValue);
+        }
+        if (rawValue.startsWith('oklch(')) {
+            const hex = this.oklchToHex(rawValue);
+            return hex ?? fallback;
+        }
+        if (rawValue.startsWith('rgb')) {
+            return this.rgbaToHex(rawValue);
+        }
+        if (rawValue.startsWith('#')) {
+            return rawValue;
+        }
+        // Non-color modes (dimensions, durations, …) resolve like direct values
+        if (tokenType && tokenType !== 'color') {
+            return this.resolveDirectValue(rawValue, tokenType);
+        }
+        return fallback;
+    }
+    /**
+     * Convert an `oklch(L C H)` or `oklch(L C H / A)` string to hex, gamut-clamped
+     * to sRGB. Alpha below 1 produces the 8-digit form, matching `rgbaToHex`.
+     * Returns null when the string cannot be parsed.
+     */
+    oklchToHex(value) {
+        const match = value.match(/^oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*(?:\/\s*([\d.]+)\s*)?\)$/i);
+        if (!match)
+            return null;
+        const l = parseFloat(match[1]);
+        const c = parseFloat(match[2]);
+        const h = parseFloat(match[3]);
+        const a = match[4] !== undefined ? parseFloat(match[4]) : 1;
+        if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h) || !Number.isFinite(a)) {
+            return null;
+        }
+        const hex = (0, OklchConverter_1.toSrgbHex)(l, c, h).toUpperCase();
+        if (a < 1) {
+            return hex + Math.round(a * 255).toString(16).padStart(2, '0').toUpperCase();
+        }
+        return hex;
+    }
     /**
      * Resolve an alias reference value for semantic tokens.
      * Preserves the alias format for Figma variable references.

package/dist/generators/types/DTCGTypes.d.ts

@@ -57,6 +57,16 @@ export interface DesignerPunkExtensions {
     }>;
     /** Theme-conditional mode overrides (e.g., { wcag: '{color.teal300}' }) */
     modes?: Record<string, string>;
+    /**
+     * OKLCH source of record for a color primitive resolved via `composedColorMap`
+     * (Spec 112). Traceability only — `$value` hex correctness is the requirement,
+     * this is the channel data it was derived from.
+     */
+    oklch?: {
+        l: number;
+        c: number;
+        h: number;
+    };
 }
 /**
  * A single DTCG token with value, type, description, and optional extensions.