@3fn/core 14.0.0 → 15.0.0

package/src/generators/DTCGFormatGenerator.ts

@@ -1,1355 +0,0 @@
-/**
- * DTCG Token Format Generator
- *
- * Transforms DesignerPunk Rosetta System tokens into DTCG (Design Tokens Community Group)
- * Format Module 2025.10 compliant JSON output. Enables integration with industry-standard
- * design tools (Figma, Style Dictionary, Tokens Studio, Terrazzo) while preserving
- * DesignerPunk's mathematical foundations and governance rules through extensions.
- *
- * Key Principle: DTCG output is a parallel export for external tools.
- * DesignerPunk components continue importing tokens from TypeScript sources.
- * Code (Rosetta) remains the source of truth.
- *
- * @see https://tr.designtokens.org/format/
- * @requirements 7.1, 10.1-10.5
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { DTCGGeneratorConfig, DEFAULT_DTCG_GENERATOR_CONFIG } from './DTCGGeneratorConfig';
-import type { DTCGTokenFile, DTCGGroup, DTCGToken, DTCGType, DesignerPunkExtensions } from './types/DTCGTypes';
-import { getAllPrimitiveTokens } from '../tokens/index';
-import { getAllSemanticTokens } from '../tokens/semantic/index';
-import type { SemanticToken } from '../types/SemanticToken';
-import type { PrimitiveToken, ColorTokenValue } from '../types/PrimitiveToken';
-
-// Primitive token imports
-import { spacingTokens, SPACING_BASE_VALUE } from '../tokens/SpacingTokens';
-import { colorTokens } from '../tokens/ColorTokens';
-import { fontSizeTokens, FONT_SIZE_BASE_VALUE } from '../tokens/FontSizeTokens';
-import { fontWeightTokens, FONT_WEIGHT_BASE_VALUE } from '../tokens/FontWeightTokens';
-import { fontFamilyTokens } from '../tokens/FontFamilyTokens';
-import { lineHeightTokens, LINE_HEIGHT_BASE_VALUE } from '../tokens/LineHeightTokens';
-import { letterSpacingTokens, LETTER_SPACING_BASE_VALUE } from '../tokens/LetterSpacingTokens';
-import { radiusTokens, RADIUS_BASE_VALUE } from '../tokens/RadiusTokens';
-import { borderWidthTokens, BORDER_WIDTH_BASE_VALUE } from '../tokens/BorderWidthTokens';
-import { tapAreaTokens, TAP_AREA_BASE_VALUE } from '../tokens/TapAreaTokens';
-import { densityTokens, DENSITY_BASE_VALUE } from '../tokens/DensityTokens';
-import { breakpointTokens, BREAKPOINT_BASE_VALUE } from '../tokens/BreakpointTokens';
-import { opacityTokens, OPACITY_BASE_VALUE } from '../tokens/OpacityTokens';
-import { durationTokens, DURATION_BASE_VALUE } from '../tokens/DurationTokens';
-import { easingTokens } from '../tokens/EasingTokens';
-import { scaleTokens, SCALE_BASE_VALUE } from '../tokens/ScaleTokens';
-import { blendTokens, BLEND_BASE_VALUE } from '../tokens/BlendTokens';
-
-// Shadow primitive token imports
-import { blur as blurTokens, BLUR_BASE_VALUE } from '../tokens/BlurTokens';
-import { sizingTokens, SIZING_BASE_VALUE } from '../tokens/SizingTokens';
-import { shadowOffsetX, shadowOffsetY, SHADOW_OFFSET_BASE_VALUE } from '../tokens/ShadowOffsetTokens';
-import { shadowOpacityTokens, SHADOW_OPACITY_BASE_VALUE } from '../tokens/ShadowOpacityTokens';
-
-// Glow primitive token imports
-import { glowOpacity, GLOW_OPACITY_BASE_VALUE } from '../tokens/GlowOpacityTokens';
-
-// Semantic token imports
-import { colorTokens as semanticColorTokens } from '../tokens/semantic/ColorTokens';
-import { spacingTokens as semanticSpacingTokens } from '../tokens/semantic/SpacingTokens';
-import { SemanticBorderWidthTokens } from '../tokens/semantic/BorderWidthTokens';
-import { SemanticRadiusTokens } from '../tokens/semantic/RadiusTokens';
-import { opacityTokens as semanticOpacityTokens } from '../tokens/semantic/OpacityTokens';
-import { blendTokens as semanticBlendTokens } from '../tokens/semantic/BlendTokens';
-import { zIndexTokens } from '../tokens/semantic/ZIndexTokens';
-import { elevationTokens } from '../tokens/semantic/ElevationTokens';
-import { gridSpacingTokens } from '../tokens/semantic/GridSpacingTokens';
-import { iconTokens } from '../tokens/semantic/IconTokens';
-import { accessibilityTokens } from '../tokens/semantic/AccessibilityTokens';
-import { motionTokens as semanticMotionTokens } from '../tokens/semantic/MotionTokens';
-import { typographyTokens } from '../tokens/semantic/TypographyTokens';
-import { progressColorTokens } from '../tokens/semantic/ColorTokens';
-import { shadowTokens as semanticShadowTokens } from '../tokens/semantic/ShadowTokens';
-import { darkSemanticOverrides } from '../tokens/themes/dark/SemanticOverrides';
-import { resolveSemanticTokenValue } from '../resolvers/SemanticValueResolver';
-import type { ThemeOverrideSet } from './TokenFileGenerator';
-
-/** Set of valid DTCG types for validation (Format Module 2025.10) */
-const VALID_DTCG_TYPES: ReadonlySet<string> = new Set([
-  'color', 'dimension', 'fontFamily', 'fontWeight', 'duration',
-  'cubicBezier', 'linearEasing', 'number', 'shadow', 'typography', 'transition',
-]);
-
-/** Minimum expected primitive token count (programmatic validation threshold) */
-const MIN_PRIMITIVE_TOKEN_COUNT = 200;
-
-/** Minimum expected semantic token count (programmatic validation threshold) */
-const MIN_SEMANTIC_TOKEN_COUNT = 180;
-
-/**
- * DTCGFormatGenerator — Main generator class that orchestrates token transformation
- * from Rosetta System tokens to DTCG Format Module 2025.10 compliant JSON.
- *
- * Usage:
- * ```typescript
- * const generator = new DTCGFormatGenerator();
- * const output = generator.generate();
- * generator.writeToFile('dist/DesignTokens.dtcg.json');
- * ```
- */
-export class DTCGFormatGenerator {
-  private readonly config: DTCGGeneratorConfig;
-
-  constructor(config: Partial<DTCGGeneratorConfig> = {}) {
-    this.config = { ...DEFAULT_DTCG_GENERATOR_CONFIG, ...config };
-  }
-
-  /**
-   * Generate DTCG-compliant JSON from Rosetta tokens.
-   *
-   * Orchestrates all token generation methods, adds root-level metadata,
-   * and validates token counts before returning the complete DTCG output.
-   *
-   * @returns Complete DTCGTokenFile ready for serialization
-   * @throws Error if token count validation fails
-   */
-  generate(): DTCGTokenFile {
-    const output: DTCGTokenFile = {
-      $schema: this.config.schemaUrl,
-    };
-
-    // Add root-level DesignerPunk extensions (version, generatedAt, rosettaVersion)
-    if (this.config.includeExtensions) {
-      output.$extensions = {
-        designerpunk: this.generateRootExtensions(),
-      };
-    }
-
-    // --- Primitive token groups ---
-    // Each method will be implemented in Task 2.2
-    output.space = this.generateSpacingTokens();
-    output.color = this.generateColorTokens();
-    output.fontSize = this.generateFontSizeTokens();
-    output.fontWeight = this.generateFontWeightTokens();
-    output.fontFamily = this.generateFontFamilyTokens();
-    output.lineHeight = this.generateLineHeightTokens();
-    output.letterSpacing = this.generateLetterSpacingTokens();
-    output.radius = this.generateRadiusTokens();
-    output.borderWidth = this.generateBorderWidthTokens();
-    output.tapArea = this.generateTapAreaTokens();
-    output.density = this.generateDensityTokens();
-    output.breakpoint = this.generateBreakpointTokens();
-    output.opacity = this.generateOpacityTokens();
-    output.duration = this.generateDurationTokens();
-    output.easing = this.generateEasingTokens();
-    output.scale = this.generateScaleTokens();
-    output.blend = this.generateBlendTokens();
-    output.blur = this.generateBlurTokens();
-    output.sizing = this.generateSizingTokens();
-
-    // --- Semantic token groups ---
-    output.semanticColor = this.generateSemanticColorTokens();
-    output.semanticSpace = this.generateSemanticSpacingTokens();
-    output.semanticBorderWidth = this.generateSemanticBorderWidthTokens();
-    output.semanticRadius = this.generateSemanticRadiusTokens();
-    output.semanticOpacity = this.generateSemanticOpacityTokens();
-    output.semanticBlend = this.generateSemanticBlendTokens();
-    output.gridSpacing = this.generateGridSpacingTokens();
-    output.icon = this.generateIconTokens();
-    output.accessibility = this.generateAccessibilityTokens();
-    output.progressColor = this.generateProgressColorTokens();
-    output.zIndex = this.generateZIndexTokens();
-    output.elevation = this.generateElevationTokens();
-
-    // --- Shadow & glow token groups (Tasks 2.4, 2.5) ---
-    output.shadow = this.generateShadowTokens();
-    output.glow = this.generateGlowTokens();
-
-    // --- Composite token groups (Task 2.6) ---
-    output.typography = this.generateTypographyTokens();
-    output.motion = this.generateMotionTokens();
-
-    // Validate token counts against expected minimums
-    this.validateTokenCounts(output);
-
-    // Post-processing: strip deprecated tokens if configured
-    if (!this.config.includeDeprecated) {
-      this.stripDeprecatedTokens(output);
-    }
-
-    return output;
-  }
-
-  /**
-   * Write generated DTCG output to a JSON file.
-   *
-   * Creates the output directory if it doesn't exist. Overwrites existing files
-   * without prompting (generation is idempotent).
-   *
-   * @param outputPath - File path for the output (e.g., 'dist/DesignTokens.dtcg.json')
-   * @throws Error if file write fails (permissions, disk full, etc.)
-   */
-  writeToFile(outputPath: string): void {
-    const output = this.generate();
-    const indent = this.config.prettyPrint ? 2 : undefined;
-    const json = JSON.stringify(output, null, indent);
-
-    try {
-      const dir = path.dirname(outputPath);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
-      fs.writeFileSync(outputPath, json, 'utf-8');
-
-      // Log generation summary
-      const primitiveCount = getAllPrimitiveTokens().length;
-      const semanticCount = getAllSemanticTokens().length;
-      console.log(
-        `✅ DTCG output written to ${outputPath} — Generated ${primitiveCount} primitive tokens, ${semanticCount} semantic tokens`
-      );
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to write DTCG output to ${outputPath}: ${message}`);
-    }
-  }
-
-  // ---------------------------------------------------------------------------
-  // Private helpers
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Generate root-level DesignerPunk extension metadata.
-   *
-   * Includes generator version, generation timestamp, and Rosetta system version
-   * for traceability and debugging.
-   */
-  private generateRootExtensions(): NonNullable<NonNullable<DTCGTokenFile['$extensions']>['designerpunk']> {
-    // Read version from package.json at runtime
-    let rosettaVersion = 'unknown';
-    try {
-      const pkgPath = path.resolve(__dirname, '../../package.json');
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-      rosettaVersion = pkg.version || 'unknown';
-    } catch {
-      // Fallback — package.json not found or unreadable
-    }
-
-    const extensions: NonNullable<NonNullable<DTCGTokenFile['$extensions']>['designerpunk']> = {
-      version: '1.0.0',
-      generatedAt: new Date().toISOString(),
-      rosettaVersion,
-    };
-
-    // Include registered theme metadata when themes are configured (Spec 094)
-    if (this.config.registeredThemes.length > 0) {
-      extensions.themes = this.config.registeredThemes;
-    }
-
-    return extensions;
-  }
-
-  /**
-   * Validate that generated token counts meet expected minimums.
-   *
-   * Uses programmatic counting via getAllPrimitiveTokens() and getAllSemanticTokens()
-   * rather than hard-coded values, so validation stays current as the token system grows.
-   *
-   * @param _output - The generated DTCGTokenFile (reserved for future per-group validation)
-   * @throws Error if primitive or semantic token counts fall below minimum thresholds
-   */
-  private validateTokenCounts(_output: DTCGTokenFile): void {
-    const primitiveCount = getAllPrimitiveTokens().length;
-    const semanticCount = getAllSemanticTokens().length;
-
-    if (primitiveCount < MIN_PRIMITIVE_TOKEN_COUNT) {
-      throw new Error(
-        `Token count validation failed. Expected at least ${MIN_PRIMITIVE_TOKEN_COUNT} primitive tokens, got ${primitiveCount}. ` +
-        `This may indicate a missing token category in the generator.`
-      );
-    }
-
-    if (semanticCount < MIN_SEMANTIC_TOKEN_COUNT) {
-      throw new Error(
-        `Token count validation failed. Expected at least ${MIN_SEMANTIC_TOKEN_COUNT} semantic tokens, got ${semanticCount}. ` +
-        `This may indicate a missing semantic token category in the generator.`
-      );
-    }
-  }
-
-  /**
-   * Remove deprecated tokens from the output when includeDeprecated is false.
-   *
-   * Recursively walks the DTCG output tree and removes any token that has
-   * `$extensions.designerpunk.deprecated: true`. This preserves the group structure
-   * while filtering out individual deprecated tokens.
-   *
-   * @param obj - The DTCG output object to filter (mutated in place)
-   */
-  private stripDeprecatedTokens(obj: Record<string, unknown>): void {
-    for (const key of Object.keys(obj)) {
-      if (key.startsWith('$')) continue; // Skip DTCG meta-properties
-      const value = obj[key];
-      if (value && typeof value === 'object') {
-        const token = value as Record<string, unknown>;
-        // Check if this is a token with deprecated extension
-        const extensions = token.$extensions as { designerpunk?: DesignerPunkExtensions } | undefined;
-        if (extensions?.designerpunk?.deprecated) {
-          delete obj[key];
-        } else {
-          // Recurse into groups
-          this.stripDeprecatedTokens(token);
-        }
-      }
-    }
-  }
-
-  // ---------------------------------------------------------------------------
-  // Token generation stubs — implemented in Tasks 2.2–2.6
-  // ---------------------------------------------------------------------------
-
-  // ---------------------------------------------------------------------------
-  // Primitive token generation (Task 2.2)
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Generate spacing primitive tokens as DTCG dimension type.
-   * Maps spacing baseValue to `{value}px` dimension format.
-   */
-  private generateSpacingTokens(): DTCGGroup {
-    return this.generateDimensionGroup(spacingTokens, 'spacing', SPACING_BASE_VALUE);
-  }
-
-  /**
-   * Generate color primitive tokens as DTCG color type.
-   * Resolves mode-aware RGBA values using light.base as default.
-   */
-  private generateColorTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'color' };
-    for (const [key, token] of Object.entries(colorTokens)) {
-      const colorValue = this.resolveColorValue(token, key);
-      const extensions = this.buildPrimitiveExtensions(token, 'color');
-      group[key] = this.toDTCGToken(colorValue, 'color', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate font size primitive tokens as DTCG dimension type.
-   * Uses baseValue (unitless) converted to `{value}px`.
-   */
-  private generateFontSizeTokens(): DTCGGroup {
-    return this.generateDimensionGroup(fontSizeTokens, 'fontSize', FONT_SIZE_BASE_VALUE);
-  }
-
-  /**
-   * Generate font weight primitive tokens as DTCG fontWeight type.
-   * Font weights are numeric values (100–900).
-   */
-  private generateFontWeightTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'fontWeight' };
-    for (const [key, token] of Object.entries(fontWeightTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'fontWeight', FONT_WEIGHT_BASE_VALUE);
-      group[key] = this.toDTCGToken(token.baseValue, 'fontWeight', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate font family primitive tokens as DTCG fontFamily type.
-   * DTCG fontFamily expects an array of font names.
-   */
-  private generateFontFamilyTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'fontFamily' };
-    for (const [key, token] of Object.entries(fontFamilyTokens)) {
-      const fontStack = String(token.platforms.web.value);
-      const families = fontStack.split(',').map(f => f.trim().replace(/^["']|["']$/g, ''));
-      const extensions = this.buildPrimitiveExtensions(token, 'fontFamily');
-      group[key] = this.toDTCGToken(families, 'fontFamily', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate line height primitive tokens as DTCG number type.
-   * Line heights are unitless multipliers.
-   */
-  private generateLineHeightTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(lineHeightTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'lineHeight', LINE_HEIGHT_BASE_VALUE);
-      group[key] = this.toDTCGToken(token.baseValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate letter spacing primitive tokens as DTCG dimension type.
-   * Letter spacing uses em units.
-   */
-  private generateLetterSpacingTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(letterSpacingTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'letterSpacing', LETTER_SPACING_BASE_VALUE);
-      group[key] = this.toDTCGToken(`${token.baseValue}em`, 'dimension', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate radius primitive tokens as DTCG dimension type.
-   * Handles special cases: radiusMax (9999px), radiusHalf (50%).
-   */
-  private generateRadiusTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(radiusTokens)) {
-      let value: string;
-      if (token.name === 'radiusHalf') {
-        value = '50%';
-      } else {
-        value = `${token.baseValue}px`;
-      }
-      const extensions = this.buildPrimitiveExtensions(token, 'radius', RADIUS_BASE_VALUE);
-      group[key] = this.toDTCGToken(value, 'dimension', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate border width primitive tokens as DTCG dimension type.
-   */
-  private generateBorderWidthTokens(): DTCGGroup {
-    return this.generateDimensionGroup(borderWidthTokens, 'borderWidth', BORDER_WIDTH_BASE_VALUE);
-  }
-
-  /**
-   * Generate tap area primitive tokens as DTCG dimension type.
-   */
-  private generateTapAreaTokens(): DTCGGroup {
-    return this.generateDimensionGroup(tapAreaTokens, 'tapArea', TAP_AREA_BASE_VALUE);
-  }
-
-  /**
-   * Generate density primitive tokens as DTCG number type.
-   * Density values are unitless multipliers.
-   */
-  private generateDensityTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(densityTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'density', DENSITY_BASE_VALUE);
-      group[key] = this.toDTCGToken(token.baseValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate breakpoint primitive tokens as DTCG dimension type.
-   */
-  private generateBreakpointTokens(): DTCGGroup {
-    return this.generateDimensionGroup(breakpointTokens, 'breakpoint', BREAKPOINT_BASE_VALUE);
-  }
-
-  /**
-   * Generate opacity primitive tokens as DTCG number type.
-   * Opacity values are unitless (0–1).
-   */
-  private generateOpacityTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(opacityTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'opacity', OPACITY_BASE_VALUE);
-      group[key] = this.toDTCGToken(token.baseValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate duration primitive tokens as DTCG duration type.
-   * DTCG duration format: `{value}ms`.
-   */
-  private generateDurationTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'duration' };
-    for (const [key, token] of Object.entries(durationTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'duration', DURATION_BASE_VALUE);
-      group[key] = this.toDTCGToken(`${token.baseValue}ms`, 'duration', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate easing primitive tokens as DTCG cubicBezier type.
-   * Parses cubic-bezier CSS string into [p1, p2, p3, p4] array.
-   */
-  private generateEasingTokens(): DTCGGroup {
-    const group: DTCGGroup = {};
-    for (const [key, token] of Object.entries(easingTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'easing');
-      if (token.easingType === 'linear' && token.stops) {
-        group[key] = this.toDTCGToken(token.stops, 'linearEasing', token.description, extensions);
-      } else {
-        const bezierStr = String(token.platforms.web.value);
-        const match = bezierStr.match(/cubic-bezier\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*\)/);
-        if (!match) {
-          throw new Error(`Invalid easing value for ${token.name}: ${bezierStr}. Expected cubic-bezier(p1, p2, p3, p4) format.`);
-        }
-        const bezierArray = [parseFloat(match[1]), parseFloat(match[2]), parseFloat(match[3]), parseFloat(match[4])];
-        group[key] = this.toDTCGToken(bezierArray, 'cubicBezier', token.description, extensions);
-      }
-    }
-    return group;
-  }
-
-  /**
-   * Generate scale primitive tokens as DTCG number type.
-   * Scale values are unitless multipliers.
-   */
-  private generateScaleTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(scaleTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'scale', SCALE_BASE_VALUE);
-      group[key] = this.toDTCGToken(token.baseValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate blur primitive tokens as DTCG dimension type.
-   */
-  private generateBlurTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(blurTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'blur', BLUR_BASE_VALUE);
-      group[key] = this.toDTCGToken(`${token.baseValue}px`, 'dimension', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate sizing primitive tokens as DTCG dimension type.
-   */
-  private generateSizingTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(sizingTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'sizing', SIZING_BASE_VALUE);
-      group[key] = this.toDTCGToken(`${token.baseValue}px`, 'dimension', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate blend primitive tokens as DTCG number type with blendType extension.
-   * Blend values are unitless (0–1) with blendType metadata.
-   */
-  private generateBlendTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(blendTokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, 'blend', BLEND_BASE_VALUE);
-      group[key] = this.toDTCGToken(token.baseValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  // ---------------------------------------------------------------------------
-  // Semantic token generation (Task 2.3)
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Generate semantic color tokens with alias references to primitive colors.
-   * Uses `{color.primitiveRef}` syntax to preserve primitive→semantic hierarchy.
-   */
-  private generateSemanticColorTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'color' };
-    for (const [key, token] of Object.entries(semanticColorTokens)) {
-      const refs = token.primitiveReferences;
-
-      // Determine alias value — use {color.primitiveRef} syntax
-      const primaryRef = refs.value || refs.color;
-      if (!primaryRef) continue;
-
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveColorAlias(primaryRef)
-        : `{color.${primaryRef}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'color',
-      };
-
-      // Spec 080: emit mode contexts for Level 2 overrides or Level 1 primitive differences
-      const override = darkSemanticOverrides[key];
-      if (override) {
-        // Level 2: semantic override swaps primitive name in dark mode
-        // Resolve both modes to concrete rgba values
-        const lightResolved = resolveSemanticTokenValue(token as any, 'light');
-        const darkToken = { ...token, primitiveReferences: override.primitiveReferences } as any;
-        const darkResolved = resolveSemanticTokenValue(darkToken, 'dark');
-        const lightVal = lightResolved.primitiveReferences?.value;
-        const darkVal = darkResolved.primitiveReferences?.value;
-        if (lightVal && darkVal && lightVal !== darkVal) {
-          if (!extensions.modes) extensions.modes = {};
-          extensions.modes.light = lightVal;
-          extensions.modes.dark = darkVal;
-        }
-      } else {
-        // Level 1: check if primitive itself has distinct light/dark values
-        const primitiveToken = (colorTokens as Record<string, PrimitiveToken>)[primaryRef];
-        if (primitiveToken) {
-          const colorVal = primitiveToken.platforms.web.value as ColorTokenValue;
-          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 };
-      }
-
-      // If token has modifier-based opacity composition, note it
-      const semanticToken = token as unknown as SemanticToken;
-      if (semanticToken.modifiers?.length) {
-        const opacityMod = semanticToken.modifiers.find((m: { type: string }) => m.type === 'opacity');
-        if (opacityMod) {
-          extensions.primitiveRefs = { color: refs.value, opacity: opacityMod.reference };
-          extensions.modifiers = semanticToken.modifiers;
-        }
-      }
-
-      group[key] = this.toDTCGToken(aliasValue, 'color', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate semantic spacing tokens with alias references to primitive spacing.
-   * Preserves hierarchical structure: grouped/related/separated/sectioned + inset.
-   */
-  private generateSemanticSpacingTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [category, levels] of Object.entries(semanticSpacingTokens)) {
-      const subGroup: DTCGGroup = { $type: 'dimension' };
-      for (const [level, token] of Object.entries(levels as Record<string, { value: string }>)) {
-        const aliasValue = this.config.resolveAliases
-          ? this.resolvePrimitiveDimensionAlias(token.value, spacingTokens)
-          : `{space.${token.value}}`;
-
-        const extensions: DesignerPunkExtensions = {
-          family: 'spacing',
-          primitiveRefs: { value: token.value },
-        };
-
-        subGroup[level] = this.toDTCGToken(aliasValue, 'dimension', `Semantic spacing: ${category}.${level}`, extensions);
-      }
-      group[category] = subGroup;
-    }
-    return group;
-  }
-
-  /**
-   * Generate semantic border width tokens with alias references to primitive border widths.
-   */
-  private generateSemanticBorderWidthTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(SemanticBorderWidthTokens)) {
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveDimensionAlias(token.value, borderWidthTokens)
-        : `{borderWidth.${token.value}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'borderWidth',
-        primitiveRefs: { value: token.value },
-      };
-
-      group[key] = this.toDTCGToken(aliasValue, 'dimension', `Semantic border width: ${key}`, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate semantic radius tokens with alias references to primitive radius.
-   */
-  private generateSemanticRadiusTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(SemanticRadiusTokens)) {
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveDimensionAlias(token.value, radiusTokens)
-        : `{radius.${token.value}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'radius',
-        primitiveRefs: { value: token.value },
-      };
-
-      group[key] = this.toDTCGToken(aliasValue, 'dimension', `Semantic radius: ${key}`, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate semantic opacity tokens with alias references to primitive opacity.
-   */
-  private generateSemanticOpacityTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(semanticOpacityTokens)) {
-      const ref = token.primitiveReferences.value;
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveNumberAlias(ref, opacityTokens)
-        : `{opacity.${ref}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'opacity',
-        primitiveRefs: { value: ref },
-      };
-
-      group[key] = this.toDTCGToken(aliasValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate semantic blend tokens with alias references to primitive blend values.
-   * Includes blendType extension for blend direction.
-   */
-  private generateSemanticBlendTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(semanticBlendTokens)) {
-      const ref = token.primitiveReferences.value;
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveNumberAlias(ref, blendTokens)
-        : `{blend.${ref}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'blend',
-        primitiveRefs: { value: ref },
-      };
-      // Map BlendDirection to DesignerPunk blendType extension
-      if (token.direction === 'darker') {
-        extensions.blendType = 'darkerBlend';
-      } else if (token.direction === 'lighter') {
-        extensions.blendType = 'lighterBlend';
-      }
-      // Deprecation metadata (e.g. blend.disabledDesaturate) — lets includeDeprecated: false strip it
-      if (token.deprecated) {
-        extensions.deprecated = true;
-        if (token.deprecatedSince) extensions.deprecatedSince = token.deprecatedSince;
-        if (token.deprecatedReason) extensions.deprecatedReason = token.deprecatedReason;
-      }
-
-      group[key] = this.toDTCGToken(aliasValue, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate z-index tokens as DTCG number type.
-   * Z-index tokens are semantic-only (no primitive layer).
-   */
-  private generateZIndexTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(zIndexTokens)) {
-      const extensions: DesignerPunkExtensions = {
-        family: 'zIndex',
-        platforms: {
-          web: { supported: true },
-          ios: { supported: true },
-          android: { supported: false, note: 'Use elevation tokens instead' },
-        },
-      };
-
-      group[key] = this.toDTCGToken(token.value, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate elevation tokens as DTCG number type with platform extensions.
-   * Elevation tokens are Android-only semantic tokens.
-   */
-  private generateElevationTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'number' };
-    for (const [key, token] of Object.entries(elevationTokens)) {
-      const extensions: DesignerPunkExtensions = {
-        family: 'elevation',
-        platforms: {
-          web: { supported: false, note: 'Use z-index + shadow tokens instead' },
-          ios: { supported: false, note: 'Use z-index + shadow tokens instead' },
-          android: { supported: true, elevation: token.value },
-        },
-      };
-
-      group[key] = this.toDTCGToken(token.value, 'number', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate grid spacing tokens with alias references to primitive spacing.
-   */
-  private generateGridSpacingTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(gridSpacingTokens)) {
-      const ref = token.primitiveReferences.spacing;
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveDimensionAlias(ref, spacingTokens)
-        : `{space.${ref}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'gridSpacing',
-        primitiveRefs: { spacing: ref },
-      };
-
-      group[key] = this.toDTCGToken(aliasValue, 'dimension', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate icon tokens as DTCG dimension type.
-   * Icon sizes are calculated from fontSize × multiplier.
-   */
-  private generateIconTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(iconTokens)) {
-      const refs = token.primitiveReferences;
-
-      // icon.strokeWidth references a borderWidth primitive
-      if (refs.value) {
-        const aliasValue = this.config.resolveAliases
-          ? this.resolvePrimitiveDimensionAlias(refs.value, borderWidthTokens)
-          : `{borderWidth.${refs.value}}`;
-
-        const extensions: DesignerPunkExtensions = {
-          family: 'icon',
-          primitiveRefs: { value: refs.value },
-        };
-
-        group[key] = this.toDTCGToken(aliasValue, 'dimension', token.description, extensions);
-      } else if (refs.fontSize && refs.multiplier) {
-        // Icon size tokens — calculated value, include formula in extensions
-        const extensions: DesignerPunkExtensions = {
-          family: 'icon',
-          primitiveRefs: { fontSize: refs.fontSize, multiplier: refs.multiplier },
-        };
-
-        // For icon sizes, use the alias to fontSize as the value
-        const aliasValue = this.config.resolveAliases
-          ? this.resolvePrimitiveDimensionAlias(refs.fontSize, fontSizeTokens)
-          : `{fontSize.${refs.fontSize}}`;
-
-        group[key] = this.toDTCGToken(aliasValue, 'dimension', token.description, extensions);
-      }
-    }
-    return group;
-  }
-
-  /**
-   * Generate accessibility tokens with alias references to their primitive sources.
-   */
-  private generateAccessibilityTokens(): DTCGGroup {
-    const group: DTCGGroup = {};
-    for (const [key, token] of Object.entries(accessibilityTokens)) {
-      const ref = token.primitiveReferences.value;
-
-      // Determine DTCG type based on what the token references
-      let dtcgType: DTCGType;
-      let aliasValue: string;
-      if (key.includes('color')) {
-        dtcgType = 'color';
-        aliasValue = this.config.resolveAliases
-          ? this.resolvePrimitiveColorAlias(ref)
-          : `{color.${ref}}`;
-      } else if (key.includes('width')) {
-        dtcgType = 'dimension';
-        aliasValue = this.config.resolveAliases
-          ? this.resolvePrimitiveDimensionAlias(ref, borderWidthTokens)
-          : `{borderWidth.${ref}}`;
-      } else {
-        // offset references a spacing primitive
-        dtcgType = 'dimension';
-        aliasValue = this.config.resolveAliases
-          ? this.resolvePrimitiveDimensionAlias(ref, spacingTokens)
-          : `{space.${ref}}`;
-      }
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'accessibility',
-        primitiveRefs: { value: ref },
-      };
-
-      group[key] = this.toDTCGToken(aliasValue, dtcgType, token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Generate progress color tokens with alias references to primitive colors.
-   */
-  private generateProgressColorTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'color' };
-    for (const [key, token] of Object.entries(progressColorTokens)) {
-      const ref = token.primitiveReferences.value;
-      const aliasValue = this.config.resolveAliases
-        ? this.resolvePrimitiveColorAlias(ref)
-        : `{color.${ref}}`;
-
-      const extensions: DesignerPunkExtensions = {
-        family: 'color',
-        primitiveRefs: { value: ref },
-      };
-
-      group[key] = this.toDTCGToken(aliasValue, 'color', token.description, extensions);
-    }
-    return group;
-  }
-
-  /**
-   * Resolve a primitive color alias to its actual value.
-   * Used when resolveAliases is true.
-   */
-  private resolvePrimitiveColorAlias(primitiveName: string): string {
-    const primitiveToken = (colorTokens as Record<string, PrimitiveToken>)[primitiveName];
-    if (primitiveToken) {
-      return this.resolveColorValue(primitiveToken, primitiveName);
-    }
-    // Fallback: return alias syntax if primitive not found
-    return `{color.${primitiveName}}`;
-  }
-
-  /**
-   * Resolve a primitive dimension alias to its actual `{value}px` value.
-   * Used when resolveAliases is true.
-   */
-  private resolvePrimitiveDimensionAlias(primitiveName: string, registry: Record<string, PrimitiveToken>): string {
-    const primitiveToken = registry[primitiveName];
-    if (primitiveToken) {
-      return `${primitiveToken.baseValue}px`;
-    }
-    // Fallback: return alias syntax if primitive not found
-    return `{${primitiveName}}`;
-  }
-
-  /**
-   * Resolve a primitive number alias to its actual numeric value.
-   * Used when resolveAliases is true for unitless tokens (opacity, blend, etc.).
-   */
-  private resolvePrimitiveNumberAlias(primitiveName: string, registry: Record<string, PrimitiveToken>): number {
-    const primitiveToken = registry[primitiveName];
-    if (primitiveToken) {
-      return primitiveToken.baseValue;
-    }
-    return 0;
-  }
-
-  // Shadow token generation (Task 2.4)
-
-  /**
-   * Generate shadow composition tokens as DTCG shadow type.
-   *
-   * Each semantic shadow token references primitives for offsetX, offsetY, blur,
-   * opacity, and color. The generator resolves these primitives, merges color+opacity
-   * into a single RGBA value (shadow opacity replaces color alpha per Design Decision 3),
-   * and outputs a DTCG shadow composite value.
-   *
-   * @requirements 5.1-5.5
-   */
-  private generateShadowTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'shadow' };
-
-    for (const [key, token] of Object.entries(semanticShadowTokens)) {
-      const refs = token.primitiveReferences;
-
-      // Resolve primitive values
-      const offsetXToken = this.resolveShadowPrimitive(refs.offsetX, shadowOffsetX);
-      const offsetYToken = this.resolveShadowPrimitive(refs.offsetY, shadowOffsetY);
-      const blurToken = this.resolveShadowPrimitive(refs.blur, blurTokens);
-      const opacityToken = this.resolveShadowPrimitive(refs.opacity, shadowOpacityTokens);
-      const colorToken = (colorTokens as Record<string, PrimitiveToken>)[refs.color];
-
-      if (!offsetXToken || !offsetYToken || !blurToken || !opacityToken || !colorToken) {
-        throw new Error(
-          `Shadow token "${key}" has unresolvable primitive references. ` +
-          `Missing: ${[
-            !offsetXToken && `offsetX(${refs.offsetX})`,
-            !offsetYToken && `offsetY(${refs.offsetY})`,
-            !blurToken && `blur(${refs.blur})`,
-            !opacityToken && `opacity(${refs.opacity})`,
-            !colorToken && `color(${refs.color})`,
-          ].filter(Boolean).join(', ')}`
-        );
-      }
-
-      // Resolve color RGBA and merge with shadow opacity (replace alpha, don't multiply)
-      const colorRgba = this.resolveColorValue(colorToken, `shadow.${key}.color`);
-      const opacityValue = opacityToken.baseValue;
-      const mergedColor = this.mergeShadowColor(colorRgba, opacityValue, key);
-
-      // Build DTCG shadow composite value
-      const shadowValue = {
-        offsetX: `${offsetXToken.baseValue}px`,
-        offsetY: `${offsetYToken.baseValue}px`,
-        blur: `${blurToken.baseValue}px`,
-        spread: '0px',
-        color: mergedColor,
-      };
-
-      // Build extensions
-      const extensions: DesignerPunkExtensions = {
-        family: 'shadow',
-        primitiveRefs: {
-          offsetX: refs.offsetX,
-          offsetY: refs.offsetY,
-          blur: refs.blur,
-          opacity: refs.opacity,
-          color: refs.color,
-        },
-      };
-
-      // Include Android elevation
-      if (token.platforms?.android?.elevation !== undefined) {
-        extensions.platforms = {
-          android: {
-            supported: true,
-            elevation: token.platforms.android.elevation,
-          },
-        };
-      }
-
-      // Use dot-separated key for DTCG group (shadow.container → container)
-      const dtcgKey = key.startsWith('shadow.') ? key.slice('shadow.'.length) : key;
-      group[dtcgKey] = this.toDTCGToken(shadowValue, 'shadow', token.description, extensions);
-    }
-
-    return group;
-  }
-
-  /**
-   * Resolve a shadow primitive token from its registry.
-   * Handles dot-notation names (e.g., 'shadowOffsetX.000' → key '000').
-   */
-  private resolveShadowPrimitive(
-    tokenName: string,
-    registry: Record<string, PrimitiveToken>
-  ): PrimitiveToken | null {
-    // Try direct lookup first
-    if (registry[tokenName]) {
-      return registry[tokenName];
-    }
-    // Handle dot notation (e.g., 'shadowOffsetX.000' → '000')
-    const dotIndex = tokenName.lastIndexOf('.');
-    if (dotIndex !== -1) {
-      const shortKey = tokenName.slice(dotIndex + 1);
-      if (registry[shortKey]) {
-        return registry[shortKey];
-      }
-    }
-    return null;
-  }
-  /**
-     * Generate glow primitive tokens as individual DTCG tokens.
-     *
-     * Glow primitives (blur, opacity) are exported individually — composed glow tokens
-     * are not yet implemented. Glows share offset primitives with shadows (shadowOffsetX,
-     * shadowOffsetY) and use the same color primitives.
-     *
-     * All glow tokens include:
-     * - `$extensions.designerpunk.glowType: "emission"` — identifies glow effect type
-     * - `$extensions.designerpunk.status: "partial"` — composed glows not yet implemented
-     *
-     * @requirements 5.6, 5.7
-     */
-    private generateGlowTokens(): DTCGGroup {
-      const group: DTCGGroup = {
-        $description: 'Glow effect primitives. Composed glows not yet implemented — glows share offset primitives with shadows (shadowOffsetX, shadowOffsetY).',
-      };
-
-      // Glow blur tokens → DTCG dimension type (blur050–blur250 from unified blur family)
-      const blur: DTCGGroup = { $type: 'dimension' };
-      const glowBlurRange = ['blur050', 'blur100', 'blur150', 'blur200', 'blur250'];
-      for (const key of glowBlurRange) {
-        const token = blurTokens[key];
-        if (!token) continue;
-        const extensions = this.buildPrimitiveExtensions(token, 'glow', BLUR_BASE_VALUE);
-        extensions.glowType = 'emission';
-        extensions.status = 'partial';
-        blur[key] = this.toDTCGToken(`${token.baseValue}px`, 'dimension', token.description, extensions);
-      }
-      group.blur = blur;
-
-      // Glow opacity tokens → DTCG number type
-      const opacity: DTCGGroup = { $type: 'number' };
-      for (const [key, token] of Object.entries(glowOpacity)) {
-        const extensions = this.buildPrimitiveExtensions(token, 'glow', GLOW_OPACITY_BASE_VALUE);
-        extensions.glowType = 'emission';
-        extensions.status = 'partial';
-        opacity[key] = this.toDTCGToken(token.baseValue, 'number', token.description, extensions);
-      }
-      group.opacity = opacity;
-
-      return group;
-    }
-
-  /**
-   * Generate typography composition tokens as DTCG typography type.
-   *
-   * Typography tokens compose primitive references (fontFamily, fontSize, fontWeight,
-   * lineHeight, letterSpacing) into DTCG typography composite values using alias syntax.
-   *
-   * @requirements 6.1, 6.5
-   */
-  private generateTypographyTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'typography' };
-
-    for (const [key, token] of Object.entries(typographyTokens)) {
-      const refs = token.primitiveReferences;
-
-      // Build DTCG typography composite value — resolve or alias based on config
-      let typographyValue: Record<string, unknown>;
-      if (this.config.resolveAliases) {
-        const ffToken = (fontFamilyTokens as Record<string, PrimitiveToken>)[refs.fontFamily];
-        const fontStack = ffToken ? String(ffToken.platforms.web.value) : refs.fontFamily;
-        const families = fontStack.split(',').map(f => f.trim().replace(/^["']|["']$/g, ''));
-
-        typographyValue = {
-          fontFamily: families,
-          fontSize: this.resolvePrimitiveDimensionAlias(refs.fontSize, fontSizeTokens),
-          fontWeight: (fontWeightTokens as Record<string, PrimitiveToken>)[refs.fontWeight]?.baseValue ?? refs.fontWeight,
-          lineHeight: (lineHeightTokens as Record<string, PrimitiveToken>)[refs.lineHeight]?.baseValue ?? refs.lineHeight,
-          letterSpacing: (letterSpacingTokens as Record<string, PrimitiveToken>)[refs.letterSpacing]
-            ? `${(letterSpacingTokens as Record<string, PrimitiveToken>)[refs.letterSpacing].baseValue}em`
-            : refs.letterSpacing,
-        };
-      } else {
-        typographyValue = {
-          fontFamily: `{fontFamily.${refs.fontFamily}}`,
-          fontSize: `{fontSize.${refs.fontSize}}`,
-          fontWeight: `{fontWeight.${refs.fontWeight}}`,
-          lineHeight: `{lineHeight.${refs.lineHeight}}`,
-          letterSpacing: `{letterSpacing.${refs.letterSpacing}}`,
-        };
-      }
-
-      // Build extensions with primitive references
-      const extensions: DesignerPunkExtensions = {
-        family: 'typography',
-        primitiveRefs: { ...refs },
-      };
-
-      // Use dot-separated key for DTCG group (typography.bodyMd → bodyMd)
-      const dtcgKey = key.startsWith('typography.') ? key.slice('typography.'.length) : key;
-      group[dtcgKey] = this.toDTCGToken(typographyValue, 'typography', token.description, extensions);
-    }
-
-    return group;
-  }
-
-  /**
-   * Generate motion composition tokens as DTCG transition type.
-   *
-   * Motion tokens compose primitive duration and easing references into DTCG transition
-   * composite values. Delay defaults to '0ms' when not defined. Scale is included in
-   * extensions when present.
-   *
-   * @requirements 6.2, 6.3, 6.4, 6.5
-   */
-  private generateMotionTokens(): DTCGGroup {
-    const group: DTCGGroup = { $type: 'transition' };
-
-    for (const [key, token] of Object.entries(semanticMotionTokens)) {
-      const refs = token.primitiveReferences;
-
-      // Build DTCG transition composite value — resolve or alias based on config
-      let transitionValue: Record<string, unknown>;
-      if (this.config.resolveAliases) {
-        const durToken = (durationTokens as Record<string, PrimitiveToken>)[refs.duration];
-        const easToken = (easingTokens as Record<string, PrimitiveToken>)[refs.easing];
-
-        // Resolve easing to cubicBezier array
-        let timingFunction: unknown = refs.easing;
-        if (easToken) {
-          const bezierStr = String(easToken.platforms.web.value);
-          const match = bezierStr.match(/cubic-bezier\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*\)/);
-          if (match) {
-            timingFunction = [parseFloat(match[1]), parseFloat(match[2]), parseFloat(match[3]), parseFloat(match[4])];
-          }
-        }
-
-        transitionValue = {
-          duration: durToken ? `${durToken.baseValue}ms` : `{duration.${refs.duration}}`,
-          timingFunction,
-          delay: '0ms',
-        };
-      } else {
-        transitionValue = {
-          duration: `{duration.${refs.duration}}`,
-          timingFunction: `{easing.${refs.easing}}`,
-          delay: '0ms',
-        };
-      }
-
-      // Build extensions with primitive references
-      const extensions: DesignerPunkExtensions = {
-        family: 'motion',
-        primitiveRefs: {
-          duration: refs.duration,
-          easing: refs.easing,
-        },
-      };
-
-      // Include scale in extensions when present (Requirement 6.4)
-      if (refs.scale) {
-        extensions.primitiveRefs!.scale = refs.scale;
-        (extensions as Record<string, unknown>).scale = this.config.resolveAliases
-          ? (scaleTokens as Record<string, PrimitiveToken>)[refs.scale]?.baseValue ?? `{scale.${refs.scale}}`
-          : `{scale.${refs.scale}}`;
-      }
-
-      // Use dot-separated key for DTCG group (motion.floatLabel → floatLabel)
-      const dtcgKey = key.startsWith('motion.') ? key.slice('motion.'.length) : key;
-      group[dtcgKey] = this.toDTCGToken(transitionValue, 'transition', token.description, extensions);
-    }
-
-    return group;
-  }
-
-  // ---------------------------------------------------------------------------
-  // Shared helpers for primitive token generation
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Generate a DTCG group of dimension tokens from a record of PrimitiveTokens.
-   * Converts baseValue to `{value}px` format.
-   */
-  private generateDimensionGroup(
-    tokens: Record<string, PrimitiveToken>,
-    family: string,
-    familyBase?: number
-  ): DTCGGroup {
-    const group: DTCGGroup = { $type: 'dimension' };
-    for (const [key, token] of Object.entries(tokens)) {
-      const extensions = this.buildPrimitiveExtensions(token, family, familyBase);
-      group[key] = this.toDTCGToken(`${token.baseValue}px`, 'dimension', token.description, extensions);
-    }
-    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.
-   *
-   * @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)")
-   * @throws Error if the resolved color value is not a valid color format
-   */
-  private resolveColorValue(token: PrimitiveToken, tokenName?: string): string {
-    const webValue = token.platforms.web.value;
-    let resolved: string;
-    if (typeof webValue === 'string') {
-      resolved = webValue;
-    } else {
-      // ColorTokenValue structure: { light: { base, wcag }, dark: { base, wcag } }
-      const colorVal = webValue as ColorTokenValue;
-      resolved = colorVal.light.base;
-    }
-
-    // Validate the resolved color is a recognizable format
-    if (!resolved || typeof resolved !== 'string') {
-      const name = tokenName || token.name || 'unknown';
-      throw new Error(
-        `Invalid token value for "${name}": ${String(resolved)}. Expected valid color format (hex, rgb, rgba).`
-      );
-    }
-
-    const isValidColor =
-      /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/.test(resolved) ||
-      /^rgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*(,\s*[\d.]+\s*)?\)$/.test(resolved);
-
-    if (!isValidColor) {
-      const name = tokenName || token.name || 'unknown';
-      throw new Error(
-        `Invalid token value for "${name}": ${resolved}. Expected valid color format (hex, rgb, rgba).`
-      );
-    }
-
-    return resolved;
-  }
-
-  /**
-   * Build DesignerPunk extension metadata for a primitive token.
-   * Includes formula, family, and baseValue when includeExtensions is true.
-   */
-  private buildPrimitiveExtensions(
-    token: PrimitiveToken,
-    family: string,
-    familyBase?: number
-  ): DesignerPunkExtensions {
-    const ext: DesignerPunkExtensions = {
-      formula: token.mathematicalRelationship,
-      family,
-    };
-    if (familyBase !== undefined && familyBase !== 0) {
-      ext.baseValue = familyBase;
-    }
-    return ext;
-  }
-
-  /**
-   * Merge shadow color and opacity into a single RGBA value.
-   *
-   * Replaces the color's alpha channel with the shadow's opacity value
-   * (does NOT multiply). Shadow opacity is authoritative per Design Decision 3.
-   *
-   * @param colorRgba - Color in rgba(r, g, b, a) format
-   * @param opacity - Shadow opacity value (0–1)
-   * @param shadowName - Optional shadow token name for error messages
-   * @returns Merged rgba string with shadow opacity as alpha
-   * @throws Error if colorRgba is not in valid rgba format
-   */
-  mergeShadowColor(colorRgba: string, opacity: number, shadowName?: string): string {
-    const match = colorRgba.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.eE+-]+\s*)?\)$/);
-    if (!match) {
-      const context = shadowName ? ` for "${shadowName}"` : '';
-      throw new Error(
-        `Shadow color merge failed${context}: ${colorRgba}. Expected rgba(r, g, b, a) format.`
-      );
-    }
-    const [, r, g, b] = match;
-    return `rgba(${r}, ${g}, ${b}, ${opacity})`;
-  }
-
-  /**
-   * Convert a Rosetta primitive token to a DTCG token with optional extensions.
-   *
-   * @param value - The token value in DTCG format
-   * @param type - The DTCG type for this token
-   * @param description - Optional token description
-   * @param extensions - Optional DesignerPunk extension metadata
-   * @returns A DTCGToken object
-   * @throws Error if the type is not a valid DTCG type
-   */
-  toDTCGToken(
-    value: unknown,
-    type: DTCGType,
-    description?: string,
-    extensions?: DesignerPunkExtensions
-  ): DTCGToken {
-    // Validate DTCG type
-    if (!VALID_DTCG_TYPES.has(type)) {
-      throw new Error(
-        `Invalid token type: "${type}". No DTCG mapping exists. ` +
-        `Valid types: ${Array.from(VALID_DTCG_TYPES).join(', ')}.`
-      );
-    }
-
-    const token: DTCGToken = {
-      $value: value,
-      $type: type,
-    };
-
-    if (description) {
-      token.$description = description;
-    }
-
-    if (this.config.includeExtensions && extensions && Object.keys(extensions).length > 0) {
-      token.$extensions = { designerpunk: extensions };
-    }
-
-    return token;
-  }
-}