Skip to the content

Output Formats

Every output is a pure projection of one token IR, so the formats never disagree. JSON is the interop surface with structured values; CSS, TypeScript and Tailwind are resolved surfaces with ready-to-use strings. Paths below are relative to the --out directory.
Token Build
manifest.json           # sha256 per file, configHash, gitCommit
css/<variant>.css       # custom properties per variant
css/font.css            # text-size levels, switched by data-apollion-text-size
ts/<variant>.d.ts       # typed literals
json/resolver.json      # DTCG resolver over the sets (base, color, spacing.<dimension>, font.<textSize>)
tailwind/preset.mjs     # Tailwind preset over the CSS variables
tailwind/tw-merge.mjs   # tailwind-merge extension
tokens-studio/          # Tokens Studio for Figma sync tree + $themes.json / $metadata.json
design/<brand>.design.md

JSON

DTCG tokens with structured values: a color carries its OKLch components and an sRGB hex fallback (alpha only below 1); a dimension is { value, unit }, usually rem.

{ "$type": "color", "$value": { "colorSpace": "oklch", "components": [0.55, 0.18, 25], "hex": "#c8102e" } }

CSS

Per variant, resolved values under the --apollion- prefix, such as --apollion-bg-paper, --apollion-text-primary, --apollion-edge-border and --apollion-spacing-md.

With output.cssModes the build also writes css/<brand>.<surface>.<dimension>.modes.css, carrying both modes scoped exactly as the core mode engine scopes them. A page without React flips it with the same attribute, using getModeScript() or syncDocumentMode() from @apollion-dsi/core/themes/mode.

:root,
html[data-apollion-mode='light'] {
  color-scheme: light;
  --apollion-bg-paper: #ffffff;
}
html[data-apollion-mode='dark'] {
  color-scheme: dark;
  --apollion-bg-paper: #181818;
}

TypeScript

ts/<variant>.d.ts declares the resolved values as readonly literals. A token's $description and $deprecated metadata become JSDoc, so a deprecated token such as bg.info shows struck through with its migration hint in the editor.

Tailwind

tailwind/preset.mjs maps foundation token names to Tailwind theme keys through var(--apollion-*), so one preset serves every variant and theme switching stays in CSS. Import both modules from your output directory:

// tailwind.config.js
import apollion from './dist/tokens/tailwind/preset.mjs';

export default { presets: [apollion] }; // class="bg-bg-primary/50 p-md text-tx-main"

tw-merge.mjs exports twMergeExtension for extendTailwindMerge. For the /50 opacity form the flag adds -rgb companion variables (--apollion-bg-primary-rgb: 0 55 80) for opaque colors; tokens that already carry alpha keep a plain var() entry. The preset needs the variant's CSS file on the page.

Figma (Tokens Studio)

output.tokensStudio writes tokens-studio/, the same sets as the JSON surface in the Tokens Studio for Figma (opens in a new tab) format. Point the plugin's folder sync (GitHub, GitLab or a local path) at that directory.

tokens-studio/base.json                          # border, breakpoints, container sizes, layout, motion
tokens-studio/spacing/<dimension>.json
tokens-studio/font/<textSize>.json
tokens-studio/color/<brand>/<mode>/<surface>.json
tokens-studio/$themes.json                       # theme groups: base · dimension · textSize · color
tokens-studio/$metadata.json                     # tokenSetOrder

Each axis is a theme group, and each set is one theme of its group, so Tokens Studio PRO exports a Figma variable collection per axis with one mode per value (for example color → default / dark / positive). Every set resolves its own aliases, so no theme needs a source set.

Values use the plugin's dialect, with value and type keys:

  • Colors are hex, with 8 digits when translucent.
  • Dimensions are "16px" or "1rem" strings.
  • Aliases keep the {group.path} form.
  • Shadows are boxShadow objects.
  • Line heights and letter spacing are percentages.

Types follow the token's role: fontSizes, spacing, borderRadius, borderWidth, sizing.

{ "bg": { "primary": { "value": "{color.primary.base}", "type": "color" } } }

Font style, the circular radius and the deprecated font.<dimension> sets have no Tokens Studio type and are not exported.

Design.md

output.designMd writes design/<brand>.design.md: YAML frontmatter with every variant's resolved values for AI assistants, and the same values as tables for people. The package's llms.txt teaches the rules; this file supplies the values, generated from your seeds.

Determinism

The same config with the same Node version and platform produces a byte-identical output directory, and manifest.json records a sha256 per file. apollion-tokens build --check compares against it, which makes the manifest a reliable CI gate and cache key.

See also