@designid/tokens 0.4.6 → 1.0.0

package/types/design-tokens.ts

@@ -0,0 +1,1083 @@
+/**
+ * W3C Design Tokens Format Module - TypeScript Types
+ * Based on the Design Tokens Community Group Draft (September 2025)
+ * https://deploy-preview-298--designtokensorg.netlify.app/tr/drafts/format/
+ * 
+ * This file provides complete TypeScript type definitions for the W3C Design Tokens specification,
+ * including all basic types, composite types, references, aliases, and group structures.
+ */
+
+// ============================================================================
+// CORE DESIGN TOKEN INTERFACES
+// ============================================================================
+
+/**
+ * Base properties available on all design tokens
+ */
+export interface DesignTokenBase {
+  /** The token's type - required if not inherited from parent groups */
+  $type?: string;
+  
+  /** Human-readable description of the token's purpose */
+  $description?: string;
+  
+  /** Enhanced vendor-specific extensions with mode and generators support */
+  $extensions?: EnhancedExtensionData;
+  
+  /** Deprecation status and optional explanation */
+  $deprecated?: boolean | string;
+}
+
+/**
+ * A design token with an explicit value
+ */
+export interface DesignToken<T = unknown> extends DesignTokenBase {
+  /** The token's value */
+  $value: T;
+}
+
+/**
+ * Reference to another token using curly brace syntax
+ */
+export type TokenReference = `{${string}}`;
+
+/**
+ * JSON Pointer reference using $ref property
+ */
+export interface JsonPointerReference {
+  $ref: string;
+}
+
+/**
+ * Composite string value that can contain multiple references and literal values
+ * Examples: 
+ * - "{a.b.c}, 16px" (token reference + literal)
+ * - "{a.b} {a.c}" (multiple token references)
+ * - "16px {#/ref}" (literal + JSON pointer)
+ * - "{token.ref} solid {#/colors/primary}" (mixed reference types)
+ */
+export type CompositeStringValue = string & {
+  readonly __brand: 'CompositeStringValue';
+};
+
+/**
+ * Union type for values that can be explicit, references, or composite strings
+ */
+export type ValueOrReference<T> = T | TokenReference | JsonPointerReference | CompositeStringValue;
+
+// ============================================================================
+// BASIC TYPES
+// ============================================================================
+
+/**
+ * Color value in sRGB color space
+ * @see https://deploy-preview-298--designtokensorg.netlify.app/tr/drafts/color
+ */
+export interface ColorValue {
+  /** Color space identifier */
+  colorSpace: 'srgb';
+  /** RGB components as numbers between 0 and 1 */
+  components: [number, number, number];
+  /** Optional alpha channel (0-1) */
+  alpha?: number;
+  /** Hex representation (optional, for convenience) */
+  hex?: string;
+}
+
+/**
+ * Extended color value supporting additional color spaces and string formats
+ * Supports OKLCH, CSS color functions, and hex strings commonly used in design systems
+ */
+export type ExtendedColorValue = 
+  | ColorValue 
+  | string; // OKLCH string like "oklch(100% 0 236.74)" or hex like "#ff0000"
+
+/**
+ * Color design token with extended color space support
+ */
+export interface ColorToken extends DesignToken<ValueOrReference<ExtendedColorValue>> {
+  $type: 'color';
+}
+
+/**
+ * Dimension value with numeric value and unit
+ */
+export interface DimensionValue {
+  /** Numeric value (integer or floating-point) */
+  value: number;
+  /** Unit of measurement */
+  unit: 'px' | 'rem';
+}
+
+/**
+ * Dimension design token
+ */
+export interface DimensionToken extends DesignToken<ValueOrReference<DimensionValue>> {
+  $type: 'dimension';
+}
+
+/**
+ * Font family value - string or array of strings
+ */
+export type FontFamilyValue = string | string[];
+
+/**
+ * Font family design token
+ */
+export interface FontFamilyToken extends DesignToken<ValueOrReference<FontFamilyValue>> {
+  $type: 'fontFamily';
+}
+
+/**
+ * Font weight numeric values
+ */
+export type FontWeightNumeric = number; // Range [1, 1000]
+
+/**
+ * Font weight string aliases
+ */
+export type FontWeightString = 
+  | 'thin' | 'hairline'           // 100
+  | 'extra-light' | 'ultra-light' // 200
+  | 'light'                       // 300
+  | 'normal' | 'regular' | 'book' // 400
+  | 'medium'                      // 500
+  | 'semi-bold' | 'demi-bold'     // 600
+  | 'bold'                        // 700
+  | 'extra-bold' | 'ultra-bold'   // 800
+  | 'black' | 'heavy'             // 900
+  | 'extra-black' | 'ultra-black'; // 950
+
+/**
+ * Font weight value
+ */
+export type FontWeightValue = FontWeightNumeric | FontWeightString;
+
+/**
+ * Font weight design token
+ */
+export interface FontWeightToken extends DesignToken<ValueOrReference<FontWeightValue>> {
+  $type: 'fontWeight';
+}
+
+/**
+ * Font face style values (CSS font-style property)
+ */
+export type FontFaceStyleValue = 'normal' | 'italic' | 'oblique';
+
+/**
+ * Font face format values
+ */
+export type FontFaceFormatValue = 'woff2' | 'woff' | 'ttf' | 'otf' | 'eot' | 'svg';
+
+/**
+ * Base font face properties
+ */
+interface BaseFontFace {
+  /** Font family name */
+  family: string;
+  /** Font style description */
+  style: string;
+  /** CSS font-style property value */
+  faceStyle: FontFaceStyleValue;
+  /** Font weight numeric value */
+  weight: FontWeightNumeric;
+  /** Font file format */
+  format: FontFaceFormatValue;
+}
+
+/**
+ * Font face value with conditional directory field
+ * - If src is a URL (starts with http:// or https://), directory is optional
+ * - If src is a file path, directory is required
+ */
+export type FontFaceValue = BaseFontFace & (
+  | {
+      /** HTTP or HTTPS URL to font file */
+      src: `http://${string}` | `https://${string}`;
+      /** Directory is optional for URLs */
+      directory?: string;
+    }
+  | {
+      /** File path or filename */
+      src: string;
+      /** Directory is required for file paths */
+      directory: string;
+    }
+);
+
+/**
+ * Font face design token for web font definitions
+ */
+export interface FontFaceToken extends DesignToken<ValueOrReference<FontFaceValue>> {
+  $type: 'fontFace';
+}
+
+/**
+ * Font face collection value - array of font face definitions
+ */
+export type FontFaceCollectionValue = FontFaceValue[];
+
+/**
+ * Font face collection design token for multiple web font definitions
+ */
+export interface FontFaceCollectionToken extends DesignToken<ValueOrReference<FontFaceCollectionValue>> {
+  $type: 'fontFaceCollection';
+}
+
+/**
+ * Duration value with numeric value and unit
+ */
+export interface DurationValue {
+  /** Numeric value (integer or floating-point) */
+  value: number;
+  /** Unit of time */
+  unit: 'ms' | 's';
+}
+
+/**
+ * Duration design token
+ */
+export interface DurationToken extends DesignToken<ValueOrReference<DurationValue>> {
+  $type: 'duration';
+}
+
+/**
+ * Cubic Bézier value as array of four control points
+ */
+export type CubicBezierValue = [number, number, number, number];
+
+/**
+ * Cubic Bézier design token
+ */
+export interface CubicBezierToken extends DesignToken<ValueOrReference<CubicBezierValue>> {
+  $type: 'cubicBezier';
+}
+
+/**
+ * Number value
+ */
+export type NumberValue = number;
+
+/**
+ * Number design token
+ */
+export interface NumberToken extends DesignToken<ValueOrReference<NumberValue>> {
+  $type: 'number';
+}
+
+/**
+ * String value that can be literal or composite with references
+ */
+export type StringValue = string;
+
+/**
+ * String design token - supports literal strings and composite strings with references
+ * @example 
+ * // Literal string
+ * { $type: 'string', $value: 'bold' }
+ * 
+ * // Composite string with token reference
+ * { $type: 'string', $value: '{font.weight.bold}, 16px' }
+ * 
+ * // Composite string with multiple token references
+ * { $type: 'string', $value: '{font.weight} {font.size}px' }
+ * 
+ * // Composite string with JSON pointer
+ * { $type: 'string', $value: '16px {#/colors/primary}' }
+ * 
+ * // Mixed reference types in one string
+ * { $type: 'string', $value: '{font.weight} solid {#/colors/border}' }
+ */
+export interface StringToken extends DesignToken<ValueOrReference<StringValue>> {
+  $type: 'string';
+}
+
+// ============================================================================
+// COMPOSITE TYPES
+// ============================================================================
+
+/**
+ * Stroke style string values
+ */
+export type StrokeStyleString = 
+  | 'solid'
+  | 'dashed'
+  | 'dotted'
+  | 'double'
+  | 'groove'
+  | 'ridge'
+  | 'outset'
+  | 'inset';
+
+/**
+ * Line cap values for stroke style
+ */
+export type LineCap = 'round' | 'butt' | 'square';
+
+/**
+ * Stroke style object value
+ */
+export interface StrokeStyleObject {
+  /** Array of dash lengths alternating between dashes and gaps */
+  dashArray: ValueOrReference<DimensionValue>[];
+  /** Line cap style */
+  lineCap: LineCap;
+}
+
+/**
+ * Stroke style value - string or object
+ */
+export type StrokeStyleValue = StrokeStyleString | StrokeStyleObject;
+
+/**
+ * Stroke style design token
+ */
+export interface StrokeStyleToken extends DesignToken<ValueOrReference<StrokeStyleValue>> {
+  $type: 'strokeStyle';
+}
+
+/**
+ * Border value object
+ */
+export interface BorderValue {
+  /** Border color */
+  color: ValueOrReference<ExtendedColorValue>;
+  /** Border width */
+  width: ValueOrReference<DimensionValue>;
+  /** Border style */
+  style: ValueOrReference<StrokeStyleValue>;
+}
+
+/**
+ * Border design token
+ */
+export interface BorderToken extends DesignToken<ValueOrReference<BorderValue>> {
+  $type: 'border';
+}
+
+/**
+ * Transition value object
+ */
+export interface TransitionValue {
+  /** Duration of the transition */
+  duration: ValueOrReference<DurationValue>;
+  /** Delay before transition begins */
+  delay: ValueOrReference<DurationValue>;
+  /** Timing function for the transition */
+  timingFunction: ValueOrReference<CubicBezierValue>;
+}
+
+/**
+ * Transition design token
+ */
+export interface TransitionToken extends DesignToken<ValueOrReference<TransitionValue>> {
+  $type: 'transition';
+}
+
+/**
+ * Shadow value object
+ */
+export interface ShadowValue {
+  /** Shadow color */
+  color: ValueOrReference<ExtendedColorValue>;
+  /** Horizontal offset */
+  offsetX: ValueOrReference<DimensionValue>;
+  /** Vertical offset */
+  offsetY: ValueOrReference<DimensionValue>;
+  /** Blur radius */
+  blur: ValueOrReference<DimensionValue>;
+  /** Spread radius */
+  spread: ValueOrReference<DimensionValue>;
+  /** Whether this is an inner shadow */
+  inset?: boolean;
+}
+
+/**
+ * Shadow design token - supports single shadow or array of shadows
+ */
+export interface ShadowToken extends DesignToken<ValueOrReference<ShadowValue | ShadowValue[]>> {
+  $type: 'shadow';
+}
+
+/**
+ * Gradient stop object
+ */
+export interface GradientStop {
+  /** Color at this stop */
+  color: ValueOrReference<ExtendedColorValue>;
+  /** Position along gradient axis (0-1) */
+  position: ValueOrReference<NumberValue>;
+}
+
+/**
+ * Gradient value as array of stops
+ */
+export type GradientValue = GradientStop[];
+
+/**
+ * Gradient design token
+ */
+export interface GradientToken extends DesignToken<ValueOrReference<GradientValue>> {
+  $type: 'gradient';
+}
+
+/**
+ * Typography value object
+ */
+export interface TypographyValue {
+  /** Font family */
+  fontFamily: ValueOrReference<FontFamilyValue>;
+  /** Font size */
+  fontSize: ValueOrReference<DimensionValue>;
+  /** Font weight */
+  fontWeight: ValueOrReference<FontWeightValue>;
+  /** Letter spacing */
+  letterSpacing: ValueOrReference<DimensionValue>;
+  /** Line height as multiplier */
+  lineHeight: ValueOrReference<NumberValue>;
+}
+
+/**
+ * Typography design token
+ */
+export interface TypographyToken extends DesignToken<ValueOrReference<TypographyValue>> {
+  $type: 'typography';
+}
+
+// ============================================================================
+// TOKEN UNION TYPES
+// ============================================================================
+
+/**
+ * Union of all basic token types
+ */
+export type BasicTokenType = 
+  | ColorToken
+  | DimensionToken
+  | FontFamilyToken
+  | FontWeightToken
+  | FontFaceToken
+  | FontFaceCollectionToken
+  | DurationToken
+  | CubicBezierToken
+  | NumberToken
+  | StringToken;
+
+/**
+ * Union of all composite token types
+ */
+export type CompositeTokenType = 
+  | StrokeStyleToken
+  | BorderToken
+  | TransitionToken
+  | ShadowToken
+  | GradientToken
+  | TypographyToken;
+
+/**
+ * Token type string literals
+ */
+export type TokenType = 
+  | 'color'
+  | 'dimension'
+  | 'fontFamily'
+  | 'fontWeight'
+  | 'fontFace'
+  | 'fontFaceCollection'
+  | 'duration'
+  | 'cubicBezier'
+  | 'number'
+  | 'string'
+  | 'strokeStyle'
+  | 'border'
+  | 'transition'
+  | 'shadow'
+  | 'gradient'
+  | 'typography'
+  | 'composition';
+
+/**
+ * Union of all token types
+ */
+export type AnyToken = BasicTokenType | CompositeTokenType;
+
+// ============================================================================
+// GROUP DEFINITIONS
+// ============================================================================
+
+/**
+ * Base properties available on groups
+ */
+export interface GroupBase {
+  /** Group type for type inheritance */
+  $type?: TokenType;
+  
+  /** Group description */
+  $description?: string;
+  
+  /** Group extension reference */
+  $extends?: TokenReference | JsonPointerReference;
+  
+  /** Group deprecation status */
+  $deprecated?: boolean | string;
+  
+  /** Enhanced vendor-specific extensions with mode and generators support */
+  $extensions?: EnhancedExtensionData;
+}
+
+/**
+ * Root token within a group using reserved $root name
+ * Can be any token type, identified by the $root key in groups
+ */
+export type RootToken = AnyToken;
+
+/**
+ * Group containing tokens and nested groups
+ */
+export interface TokenGroup extends GroupBase {
+  /** Root token for the group */
+  $root?: RootToken;
+  
+  /** Nested tokens and groups */
+  [key: string]: AnyToken | TokenGroup | unknown;
+}
+
+// ============================================================================
+// FILE FORMAT DEFINITIONS
+// ============================================================================
+
+/**
+ * Design tokens file structure
+ */
+export interface DesignTokensFile extends GroupBase {
+  /** Tokens and groups at the root level */
+  [tokenOrGroupName: string]: AnyToken | TokenGroup | unknown;
+}
+
+/**
+ * Media type for design token files
+ */
+export const DESIGN_TOKENS_MEDIA_TYPE = 'application/design-tokens+json';
+
+/**
+ * Recommended file extensions
+ */
+export const DESIGN_TOKENS_EXTENSIONS = ['.tokens', '.tokens.json'] as const;
+
+// ============================================================================
+// UTILITY TYPES
+// ============================================================================
+
+/**
+ * Extract the value type from a token
+ */
+export type ExtractTokenValue<T> = T extends DesignToken<infer V> ? V : never;
+
+/**
+ * Check if a value is a token reference
+ */
+export type IsTokenReference<T> = T extends TokenReference ? true : false;
+
+/**
+ * Check if a value is a JSON Pointer reference
+ */
+export type IsJsonPointerReference<T> = T extends JsonPointerReference ? true : false;
+
+/**
+ * Resolve a value or reference to its actual type
+ */
+export type ResolveValue<T> = T extends ValueOrReference<infer V> ? V : T;
+
+/**
+ * Type guard for token references
+ */
+export function isTokenReference(value: unknown): value is TokenReference {
+  if (typeof value !== 'string' || !value.startsWith('{') || !value.endsWith('}')) {
+    return false;
+  }
+  
+  // Exclude composite strings (contain multiple references or non-reference text)
+  // A single token reference should only contain one set of braces
+  const innerContent = value.slice(1, -1);
+  return !innerContent.includes('{') && !innerContent.includes('}') && innerContent.trim() !== '';
+}
+
+/**
+ * Type guard for JSON Pointer references
+ */
+export function isJsonPointerReference(value: unknown): value is JsonPointerReference {
+  return typeof value === 'object' && value !== null && '$ref' in value;
+}
+
+/**
+ * Type guard for composite string values
+ */
+export function isCompositeStringValue(value: unknown): value is CompositeStringValue {
+  if (typeof value !== 'string') return false;
+  
+  // Check for token references {a.b.c} or JSON pointer references {#/path}
+  const tokenRefPattern = /\{[^}]+\}/g;
+  const matches = value.match(tokenRefPattern);
+  
+  // Must contain at least one reference and have additional content
+  return !!(matches && matches.length > 0 && value.length > matches.join('').length);
+}
+
+/**
+ * Extract all references from a composite string value
+ */
+export function extractReferencesFromCompositeString(value: CompositeStringValue): (TokenReference | JsonPointerReference)[] {
+  const tokenRefPattern = /\{[^}]+\}/g;
+  const matches = value.match(tokenRefPattern) || [];
+  
+  return matches.map(match => {
+    if (match.startsWith('{#/')) {
+      // JSON Pointer reference
+      return { $ref: match.slice(2, -1) } as JsonPointerReference;
+    } else {
+      // Token reference
+      return match as TokenReference;
+    }
+  });
+}
+
+/**
+ * Parse a composite string into parts (references and literals)
+ */
+export function parseCompositeString(value: CompositeStringValue): Array<{ type: 'reference' | 'literal'; value: string; ref?: TokenReference | JsonPointerReference }> {
+  const parts: Array<{ type: 'reference' | 'literal'; value: string; ref?: TokenReference | JsonPointerReference }> = [];
+  const tokenRefPattern = /\{[^}]+\}/g;
+  let lastIndex = 0;
+  let match;
+
+  while ((match = tokenRefPattern.exec(value)) !== null) {
+    // Add literal part before the reference
+    if (match.index > lastIndex) {
+      const literalValue = value.slice(lastIndex, match.index);
+      if (literalValue) {
+        parts.push({ type: 'literal', value: literalValue });
+      }
+    }
+
+    // Add the reference part
+    const refValue = match[0];
+    if (refValue.startsWith('{#/')) {
+      // JSON Pointer reference - ref contains the JsonPointerReference object
+      parts.push({ 
+        type: 'reference', 
+        value: refValue,
+        ref: { $ref: refValue.slice(2, -1) } as JsonPointerReference
+      });
+    } else {
+      // Token reference - ref contains the TokenReference (same as value for token refs)
+      parts.push({ 
+        type: 'reference', 
+        value: refValue,
+        ref: refValue as TokenReference
+      });
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add any remaining literal part
+  if (lastIndex < value.length) {
+    const literalValue = value.slice(lastIndex);
+    if (literalValue) {
+      parts.push({ type: 'literal', value: literalValue });
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Type guard for mode extensions
+ */
+export function hasModeExtension(token: AnyToken): token is AnyToken & { $extensions: { $mode: ModeExtension } } {
+  return !!(token.$extensions?.$mode);
+}
+
+/**
+ * Type guard for generator extensions
+ */
+export function hasGeneratorExtension(token: AnyToken): token is AnyToken & { $extensions: { $generators: GeneratorsExtension } } {
+  return !!(token.$extensions?.$generators && Array.isArray(token.$extensions.$generators));
+}
+
+/**
+ * Type guard for breakpoint extensions
+ */
+export function hasBreakpointExtension(token: AnyToken): token is AnyToken & { $extensions: { $breakpoints: BreakpointsExtension } } {
+  return !!(token.$extensions?.$breakpoints && typeof token.$extensions.$breakpoints === 'object');
+}
+
+/**
+ * Extract mode value for a specific mode
+ */
+export function getModeValue<T>(token: AnyToken, mode: keyof ModeExtension): ValueOrReference<T> | undefined {
+  if (!hasModeExtension(token)) return undefined;
+  return token.$extensions.$mode[mode] as ValueOrReference<T> | undefined;
+}
+
+/**
+ * Get all generator suffixes for a token
+ */
+export function getGeneratorSuffixes(token: AnyToken): string[] {
+  if (!hasGeneratorExtension(token)) return [];
+  
+  return token.$extensions.$generators.flatMap(generator => 
+    Object.keys(generator.value)
+  );
+}
+
+/**
+ * Get all breakpoint media queries for a token
+ */
+export function getBreakpointQueries(token: AnyToken): string[] {
+  if (!hasBreakpointExtension(token)) return [];
+  
+  return Object.keys(token.$extensions.$breakpoints);
+}
+
+/**
+ * Get breakpoint value for a specific media query
+ */
+export function getBreakpointValue<T>(token: AnyToken, mediaQuery: string): ValueOrReference<T> | undefined {
+  if (!hasBreakpointExtension(token)) return undefined;
+  
+  const breakpointConfig = token.$extensions.$breakpoints[mediaQuery];
+  return breakpointConfig?.$value as ValueOrReference<T> | undefined;
+}
+
+/**
+ * Get breakpoint configuration for a specific media query
+ */
+export function getBreakpointConfig(token: AnyToken, mediaQuery: string) {
+  if (!hasBreakpointExtension(token)) return undefined;
+  
+  return token.$extensions.$breakpoints[mediaQuery];
+}
+
+/**
+ * Extract token references from media query strings
+ */
+export function extractTokenReferencesFromMediaQuery(mediaQuery: string): (TokenReference | JsonPointerReference)[] {
+  // Treat media query as a composite string to extract references
+  const compositeValue = mediaQuery as CompositeStringValue;
+  return extractReferencesFromCompositeString(compositeValue);
+}
+
+/**
+ * Generate derived token name with suffix
+ * @example generateDerivedTokenName("gray.n0", "@alpha1") => "gray.n0@alpha1"
+ */
+export function generateDerivedTokenName(baseName: string, suffix: string): string {
+  return `${baseName}${suffix}`;
+}
+
+/**
+ * Type guard for design tokens
+ */
+export function isDesignToken(value: unknown): value is AnyToken {
+  return typeof value === 'object' && value !== null && '$value' in value;
+}
+
+/**
+ * Type guard for groups
+ */
+export function isTokenGroup(value: unknown): value is TokenGroup {
+  return typeof value === 'object' && value !== null && !('$value' in value);
+}
+
+// ============================================================================
+// VALIDATION TYPES
+// ============================================================================
+
+/**
+ * Validation error for design tokens
+ */
+export interface ValidationError {
+  /** Path to the invalid token or property */
+  path: string;
+  /** Error message */
+  message: string;
+  /** Error code for programmatic handling */
+  code: string;
+  /** Severity level */
+  severity: 'error' | 'warning';
+}
+
+/**
+ * Validation result for design token files
+ */
+export interface ValidationResult {
+  /** Whether the file is valid */
+  valid: boolean;
+  /** List of validation errors and warnings */
+  errors: ValidationError[];
+  /** Successfully parsed tokens */
+  tokens: Record<string, AnyToken>;
+  /** Successfully parsed groups */
+  groups: Record<string, TokenGroup>;
+}
+
+/**
+ * Character restrictions for token and group names
+ * Names MUST NOT:
+ * - Begin with '$' (reserved for spec properties)
+ * - Contain '{', '}', or '.' (conflicts with reference syntax)
+ */
+export type ValidTokenName = string & {
+  readonly __brand: 'ValidTokenName';
+};
+
+/**
+ * Path to a token within a group structure
+ */
+export type TokenPath = string & {
+  readonly __brand: 'TokenPath';
+};
+
+// ============================================================================
+// REFERENCE RESOLUTION TYPES
+// ============================================================================
+
+/**
+ * Reference resolution context
+ */
+export interface ResolutionContext {
+  /** The current file being processed */
+  file: DesignTokensFile;
+  /** Stack of references being resolved (for circular detection) */
+  resolutionStack: string[];
+  /** Root path for relative references */
+  rootPath?: string;
+}
+
+/**
+ * Reference resolution result
+ */
+export interface ResolutionResult<T = unknown> {
+  /** Whether resolution was successful */
+  success: boolean;
+  /** Resolved value (if successful) */
+  value?: T;
+  /** Error message (if unsuccessful) */
+  error?: string;
+  /** Path of the resolved token */
+  resolvedPath?: string;
+}
+
+// ============================================================================
+// ADVANCED GROUP FEATURES
+// ============================================================================
+
+/**
+ * Group inheritance semantics for $extends
+ */
+export interface InheritanceRules {
+  /** Local properties override inherited properties at same path */
+  overrideAtSamePath: true;
+  /** Properties at different paths are merged */
+  mergeAtDifferentPaths: true;
+  /** Complete property replacement (not property-by-property merge) */
+  completeReplacement: true;
+}
+
+/**
+ * Processing order for group resolution
+ */
+export type ProcessingOrder = [
+  'localTokens',      // Direct children with $value
+  'rootTokens',       // Tokens with $root names
+  'extendedTokens',   // Inherited via $extends
+  'nestedGroups'      // Process recursively
+];
+
+/**
+ * Type inheritance precedence order
+ */
+export type TypeInheritancePrecedence = [
+  'tokenExplicitType',    // Token's explicit $type property
+  'resolvedGroupType',    // Resolved group's $type (after extension)
+  'parentGroupType',      // Parent group's $type (walking up hierarchy)
+  'invalid'               // Token is invalid if no type determined
+];
+
+// ============================================================================
+// EXTENSION AND PLUGIN TYPES
+// ============================================================================
+
+/**
+ * Extension data structure for vendor-specific data
+ */
+export interface ExtensionData {
+  /** Vendor identifier (reverse domain notation recommended) */
+  [vendorKey: string]: unknown;
+}
+
+/**
+ * Tool-specific extension interface
+ */
+export interface ToolExtension {
+  /** Tool identifier */
+  toolId: string;
+  /** Tool version */
+  version?: string;
+  /** Extension data */
+  data: unknown;
+}
+
+/**
+ * Mode-specific token values for theming (e.g., light/dark mode)
+ * Values can be explicit values or token references
+ * When referencing tokens, the referenced token's mode value is used if available
+ * Used as $extensions.$mode in design tokens
+ */
+export interface ModeExtension {
+  /** Dark mode value - can be explicit value or token reference */
+  dark?: ValueOrReference<unknown>;
+  /** Light mode value - can be explicit value or token reference */
+  light?: ValueOrReference<unknown>;
+  /** High contrast mode value */
+  'high-contrast'?: ValueOrReference<unknown>;
+  /** Custom mode values */
+  [modeName: string]: ValueOrReference<unknown> | undefined;
+}
+
+/**
+ * Generator types for creating derived tokens
+ */
+export type GeneratorType = 
+  | 'alpha'        // Alpha/opacity variations
+  | 'hue'          // Hue variations  
+  | 'saturation'   // Saturation variations
+  | 'lightness'    // Lightness variations
+  | 'scale'        // Scale variations for dimensions
+  | string;        // Custom generator types
+
+/**
+ * Generator configuration for creating derived tokens
+ * The key (e.g., "@alpha1", "@scale2x") becomes a suffix for the generated token name
+ * Original token "gray.n0" with "@alpha1": 1 generates "gray.n0@alpha1"
+ */
+export interface GeneratorConfig {
+  /** Generator type */
+  type: GeneratorType;
+  /** 
+   * Generator values where key becomes token suffix and value is the generator parameter
+   * @example { "@alpha1": 1, "@alpha50": 50, "@alpha90": 90 }
+   * @example { "@scale2x": 2, "@scale05": 0.5 }
+   */
+  value: Record<string, number | string>;
+}
+
+/**
+ * Generators extension for creating derived tokens
+ * Used as $extensions.$generators in design tokens
+ */
+export type GeneratorsExtension = GeneratorConfig[];
+
+/**
+ * Breakpoint-specific token values for responsive design
+ * Keys are CSS media queries (can contain token references)
+ * Values follow the same structure as regular design tokens
+ * Used as $extensions.$breakpoints in design tokens
+ */
+export interface BreakpointsExtension {
+  /** 
+   * CSS media query as key (supports token references in composite strings)
+   * @example "(min-width: {foundation.breakpoint.lg})"
+   * @example "(prefers-color-scheme: dark)"
+   * @example "(min-width: 768px) and (orientation: landscape)"
+   * @example "@container (min-width: {container.sizes.md})"
+   */
+  [mediaQuery: string]: {
+    /** Token type (can override base type) */
+    $type?: TokenType;
+    /** Token value for this breakpoint */
+    $value: ValueOrReference<unknown>;
+    /** Token description */
+    $description?: string;
+    /** Nested extensions (like mode) for this breakpoint */
+    $extensions?: EnhancedExtensionData;
+  };
+}
+
+/**
+ * Enhanced extension data with mode, generators, and breakpoints support
+ * Uses $ prefix for reserved/standardized extensions
+ */
+export interface EnhancedExtensionData extends ExtensionData {
+  /** Mode-specific values for theming */
+  $mode?: ModeExtension;
+  /** Generator configurations for derived tokens */
+  $generators?: GeneratorsExtension;
+  /** Breakpoint-specific values for responsive design */
+  $breakpoints?: BreakpointsExtension;
+}
+
+/**
+ * Common extension patterns
+ */
+export interface CommonExtensions {
+  /** Mode-specific token values */
+  $mode?: ModeExtension;
+  
+  /** Generator configurations for derived tokens */
+  $generators?: GeneratorsExtension;
+  
+  /** Breakpoint-specific values for responsive design */
+  $breakpoints?: BreakpointsExtension;
+  
+  /** Figma-specific data */
+  'com.figma'?: {
+    node?: {
+      nodeId?: string;
+      styleId?: string;
+      [key: string]: unknown;
+    };
+  } | {
+    /** SVG-specific data to be loaded into Figma */
+    svg?: {
+      id: string;
+      [svgName: string]: string;
+    };
+  };
+}
+
+// ============================================================================
+// EXPORT ALL TYPES
+// ============================================================================
+
+/**
+ * Default export containing all types and utilities
+ */
+export default {
+  // Constants
+  DESIGN_TOKENS_MEDIA_TYPE,
+  DESIGN_TOKENS_EXTENSIONS,
+  
+  // Type guards
+  isTokenReference,
+  isJsonPointerReference,
+  isCompositeStringValue,
+  isDesignToken,
+  isTokenGroup,
+  hasModeExtension,
+  hasGeneratorExtension,
+  hasBreakpointExtension,
+  
+  // Utilities
+  getModeValue,
+  getGeneratorSuffixes,
+  getBreakpointQueries,
+  getBreakpointValue,
+  getBreakpointConfig,
+  generateDerivedTokenName,
+  extractReferencesFromCompositeString,
+  extractTokenReferencesFromMediaQuery,
+  parseCompositeString,
+};