Download the PHP package n5s/dtcg-tokens without Composer

n5s/dtcg-tokens

Read, resolve, and render DTCG design tokens at runtime in PHP. It implements the Design Tokens Community Group specification and is PHP-first, with optional Symfony bridges.

Install

Requires PHP 8.4 or newer.

Quick start (plain PHP)

Tokens is an immutable, iterable (IteratorAggregate) and countable collection keyed by dot-separated token path. Build it from one or many files, or from an already-decoded array:

Other methods: has(string $path): bool, all(): array<string, TokenValueInterface>, and get(string $path, ?string $mode = null). Unknown paths throw a TokenException. Per-token metadata is available via metadata(string $path): ?TokenMetadata and allMetadata() (carrying $description and $deprecated).

Supported token types

The parser handles the following DTCG $type values:

Color spaces

ColorValue accepts hex strings (#rrggbb and #rrggbbaa) and DTCG color objects. Colors are stored losslessly in their authored color space — the components (with null representing a CSS none / powerless channel) and alpha are kept verbatim, never squashed to sRGB at parse time.

The accepted color spaces match the CSS Color 4 / terrazzo set: srgb, srgb-linear, display-p3, a98-rgb, prophoto-rgb, rec2020, lab, lab-d65, lch, oklab, oklch, okhsv, hsl, hwb, xyz, xyz-d50, xyz-d65. An unknown space throws.

fontWeight keywords (thin, light, regular, medium, semi-bold, bold, black, …) are mapped to their numeric equivalents; an unknown keyword, or a numeric weight outside 1–1000, throws a TokenException.

CSS serialization (toCss() / (string))

Casting to string emits faithful CSS Color 4 — no gamut conversion:

A null component renders as none; alpha below 1 is appended as / A inside the function. okhsv has no CSS function, so toCss() emits the author-provided hex fallback if present, otherwise it throws.

Conversion to sRGB (toHex() / toRgb())

These reduce a color to 8-bit sRGB:

• srgb, hsl, oklch (and hex): computed directly.
• Any other space: uses the author-provided hex fallback if present, else throws — wide-gamut values are never silently approximated.

For example, display-p3 [1 0 0] serializes to color(display-p3 1 0 0); toHex() throws unless the token also carries a "hex" fallback (e.g. "#fd0000"), in which case that value is returned verbatim.

Value objects

Every token resolves to an immutable value object implementing TokenValueInterface extends \Stringable. Casting to string produces a CSS-ready representation, so value objects can be dropped straight into templates or stylesheets.

Color tokens additionally expose toHex() and toRgb(?float $alpha = null):

Theming / modes

Mode-specific values are declared under $extensions.mode.<name>:

Resolve a mode by passing it to get(), or get a mode-bound value object via forMode():

An unknown mode falls back to the base value rather than throwing.

Modes work for every standard DTCG token type — color, dimension, number, fontFamily, fontWeight, duration, cubicBezier, strokeStyle, border, transition, shadow, gradient, and typography. (The non-spec boolean, string, and link extras are not mode-aware and always return their base value.)

Aliases and modes

Aliases are resolved per mode: an alias resolves to its target's value in the same mode, falling back to the target's base when the target does not declare that mode. A token that aliases a themed token but declares no modes of its own hoists the target's modes:

Hoisting also works through composites (e.g. a border whose color aliases a themed color becomes mode-aware on that channel) and transitively along alias chains. When a token declares its own modes, those take precedence and no extra modes are hoisted. This mirrors Terrazzo's mode resolution.

Twig

The TokenExtension exposes a token() function plus hex and rgb filters.

In a Symfony app it is registered automatically (see Symfony). For plain Twig, wire it as an attribute extension with a runtime loader:

Then in templates:

The hex and rgb filters only accept color tokens and throw a LogicException otherwise.

Symfony

Enable the bundle:

Configure it under the dtcg_tokens key:

files is required (at least one entry); multiple files are merged in order. cache is optional — point it at any PSR-6 cache pool service to cache the parsed token tree.

Then inject n5s\DtcgTokens\Tokens into any service or controller:

The Twig token() function and hex / rgb filters are registered automatically when Twig is installed.

CSS export

CssExporter renders a Tokens collection as CSS custom properties:

The constructor takes an optional prefix and selector:

Token paths are slugged by replacing . and spaces with -; values use each value object's string form.

Caching

CachedTokenFactory wraps a loader and an optional PSR-6 pool. It parses tokens once, caches the result, and — in debug mode — invalidates the cache when any source file's mtime changes:

Without a cache pool it simply parses on first create() and reuses the result in-process. The Symfony bundle wires this factory for you.

Development

Built and tested against PHP 8.4. PHPStan runs at max level with strict rules; ECS and Rector enforce style and modernization.

Limitations

This is a runtime library. It deliberately leaves some things out:

Credits

Feature scope was informed by Terrazzo, the state-of-the-art JavaScript reference for DTCG tooling.

License

MIT.