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.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 |
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 |