Token References with Fallbacks API

Complete API reference for token references with fallback support.

Overview

Token references with fallbacks allow you to reference other tokens with a fallback value if the reference is missing.

Syntax

{
  "token": { "value": "{reference.path || fallback}" }
}

Fallback Types

String Fallback

{
  "color": {
    "accent": { "value": "{color.secondary || #FF6B6B}" }
  }
}

Number Fallback

{
  "spacing": {
    "base": { "value": "{spacing.default || 16}" }
  }
}

Nested Reference Fallback

{
  "color": {
    "text": { "value": "{color.textPrimary || {color.primary} || #000000}" }
  }
}

Reference Resolver

Resolve References

import { ReferenceResolver } from '@tokiforge/core';

const result = ReferenceResolver.resolve(
  '{color.primary || #000000}',
  tokens,
  ['color', 'text']
);

Usage in TokenParser

Fallback references are automatically processed when parsing tokens:

import { TokenParser } from '@tokiforge/core';

const tokens = TokenParser.parse('./tokens.json', {
  processFallbacks: true, // Default: true
});

Examples

Color Fallbacks

{
  "color": {
    "primary": { "value": "#7C3AED" },
    "accent": { "value": "{color.secondary || {color.primary} || #FF6B6B}" },
    "text": { "value": "{color.textPrimary || #000000}" }
  }
}

Spacing Fallbacks

{
  "spacing": {
    "base": { "value": "1rem" },
    "small": { "value": "{spacing.sm || {spacing.base} || 0.5rem}" }
  }
}