Skip to the content

Build CLI

apollion-tokens build turns apollion.config.mjs (or .js, .json) into static token files. The build is atomic and idempotent: it writes to a temporary directory and renames it into place, and the same config in the same environment produces a byte-identical output.
Token Build

Usage

yarn apollion-tokens build --config apollion.config.mjs --out dist/tokens
yarn apollion-tokens build --check --config apollion.config.mjs --out dist/tokens
Flag
Default
Role
--config
apollion.config.mjs
config path (.mjs, .js or .json)
--out
dist
output directory
--check
off
CI gate: exit 1 when the output is stale
--verbose
off
log every emitted file
Scrolls sideways inside the table. The page does not.

Exit codes: 0 success (or no drift under --check), 1 build error or drift, 2 invalid arguments.

Config

import { defineConfig } from '@apollion-dsi/tokens/config-loader';

export default defineConfig({
  brands: {
    default: { main: '#003750', primary: '#32AFDC', danger: '#E12712', baseLight: '#FCFCFC', baseDark: '#26292E' },
  },
  modes: ['light', 'dark'],
  surfaces: ['positive', 'negative'],
  dimensions: ['compact', 'normal', 'spacious'],
  textSizes: ['smaller', 'default', 'larger', 'largest'],
  output: { css: true, json: true, ts: true },
});

A .mjs or .js config runs in a sandbox: require() and dynamic import() are rejected before evaluation. A brand that omits baseLight or baseDark takes the core defaults.

Variant matrix

Each combination of brand × mode × surface × dimension becomes a variant named <brand>.<mode>.<surface>.<dimension>, such as default.light.positive.normal. With the default axes — both modes, both surfaces, three dimensions — one brand yields twelve variants.

textSizes is not a variant axis: it rescales only font sizes, so every level ships in one css/font.css (switched by data-apollion-text-size) and one JSON set per level. The list must include default.

Output flags

Every flag defaults to false; without an opt-in the build writes only manifest.json.

Flag
Emits
output.css
css/<variant>.css and css/font.css
output.cssModes
css/<brand>.<surface>.<dimension>.modes.css, both modes in one file; needs both modes
output.json
json/resolver.json and the DTCG sets
output.ts
ts/<variant>.d.ts
output.tailwind
tailwind/preset.mjs, tailwind/tw-merge.mjs and -rgb companions
output.designMd
design/<brand>.design.md, resolved values as AI context
output.tokensStudio
tokens-studio/, the sets + $themes.json for Tokens Studio for Figma
output.runtime
the ESM/CJS runtime for core's dynamic import
Scrolls sideways inside the table. The page does not.

See also