@formtrieb/token-resolver

Tokens-Studio JSON → CSS variables, utility classes, SCSS mixins, and Figma↔CSS lookup map. Driven by a project-local config.

Install

npm install --save-dev @formtrieb/token-resolver

Your consumer project's package.json must have "type": "module" (this package is ESM-only). The CLI loads .ts, .mjs, and .js config files.

Quick start

Create formtrieb-tokens.config.ts in your project root:

import { defineConfig } from '@formtrieb/token-resolver';
import {
  typography,
  typographyMixin,
  directional,
  container,
} from '@formtrieb/token-resolver/builders';

export default defineConfig({
  prefix: 'mp-',
  paths: {
    tokens: './tokens',
    output: './src/css',
    tokenMap: './src/tokens/token-map.json',
  },
  output: { bundle: true },
  privateTokenPrefixes: ['*'],
  themeGroups: {
    Foundation: { useReferences: false },
  },
  defaultGroupBehavior: { useReferences: true },
  typography: {
    fontVariantNumeric: {
      tabular: [['mono'], ['metric'], ['table', 'numeric']],
    },
  },
  utilities: [
    typography(),
    typographyMixin(),
    directional({
      name: 'p',
      source: 'spacing.component.*',
      property: 'padding',
      sides: ['t', 'b', 's', 'e', 'x', 'y', 'all'],
    }),
    container({
      name: 'content',
      rules: {
        'max-width': '{content.max-width}',
        'padding-inline': '{layout.grid.margin}',
        'margin-inline': 'auto',
      },
    }),
  ],
});

Build:

npx formtrieb-tokens

Watch:

npx formtrieb-tokens --watch

Output

For the example above, the generator produces:

src/css/
  variables/
    foundation.css       (raw values; useReferences: false)
    mode.css             ([data-mode="…"] selectors)
    typography.css       (with text-indent, margin-block-end, -fvn vars)
    …
  utilities/
    typography.css       (.mp-display-1, .mp-display-1--paragraph, …)
    p.css                (.mp-p-md, .mp-p-t-md, .mp-p-s-md, …)
    content.css          (.mp-content)
    _typography.scss     (SCSS @mixin partial, from typographyMixin())
  main.css               (@imports of variables/* + utilities/*)
  bundle.css             (everything inlined for library consumers)
src/tokens/
  token-map.json         (figma↔css lookup map)

bundle.css is only emitted when output.bundle !== false (default true).

Builders

| Builder | Purpose | | ------------------ | --------------------------------------------------------------- | | single | One CSS property per token, one class per token. | | directional | Property with logical-axis sides (t/b/s/e/x/y/all), RTL-aware. | | container | Multi-rule class mixing token references and CSS literals. | | typography | Type-driven typography classes with --paragraph helper. | | typographyMixin | SCSS mixin partial — same data, different output format. |

Logical-Property Side Mapping (directional)

| Side | CSS | LTR | RTL | | ----- | ------------------------------ | ------ | ------ | | t | padding-block-start | top | top | | b | padding-block-end | bottom | bottom | | s | padding-inline-start | left | right | | e | padding-inline-end | right | left | | x | padding-inline | both | both | | y | padding-block | both | both | | all | padding | all | all |

For full builder API and design rationale, see docs/specs/2026-05-08-token-resolver-package-design.md.

Typography

typography() emits utility classes; typographyMixin() emits the same data as an SCSS partial (_typography.scss) for projects that prefer @include over class names:

@use 'path/to/_typography' as t;

.headline { @include t.typography('display-1'); }
.lede     { @include t.typography-paragraph('body-base-default'); }

Both outputs cover font shorthand, letter-spacing, text-transform, text-decoration, plus text-indent / margin-block-end for the --paragraph helper.

Tabular numbers (font-variant-numeric)

Mark token families that should render with tabular-nums via typography.fontVariantNumeric.tabular. Each entry is a token-path prefix; any typography token whose path starts with one of these segments (case-insensitive) gets a --{prefix}{token}-fvn: tabular-nums; custom property, applied automatically by both typography() and typographyMixin():

typography: {
  fontVariantNumeric: {
    tabular: [
      ['mono'],              // every token under `mono.*`
      ['metric'],            // every token under `metric.*`
      ['table', 'numeric'],  // only `table.numeric.*`
    ],
  },
},

Non-tabular tokens fall back to normal via the mixin's default.

Theme Switching

Multi-theme groups in $themes.json produce [data-{group}="{name}"] selectors automatically. Toggle a theme by setting the corresponding HTML attribute — no JS framework required:

<html data-mode="dark" data-device="mobile">

CLI Reference

formtrieb-tokens [options]

Options:
  -w, --watch              Re-run pipeline on tokens/ changes
  -c, --config <path>      Override config-file location
  -h, --help               Show usage

The CLI auto-discovers formtrieb-tokens.config.{ts,mjs,js} by walking from cwd up to the filesystem root.

Config reference

| Key | Type | Default | Purpose | | ---------------------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | prefix | string | required | CSS variable + utility-class prefix (e.g. mp- → --mp-color-…, .mp-display-1). | | paths | { tokens, output, tokenMap } | required | Input tokens dir, CSS output dir, and token-map JSON path. | | output.bundle | boolean | true | Whether to emit bundle.css (everything inlined). Set false if consumers always pull main.css and you don't need the bundle. | | privateTokenPrefixes | string[] | ['*'] | Path-segment prefixes that mark a token as private — excluded from CSS output and from token-map.json. Default hides *foo segments. | | themeGroups | Record<string, { useReferences }> | {} | Per-theme-group behavior. useReferences: false inlines raw values; true emits var(...) references. | | defaultGroupBehavior | { useReferences } | — | Fallback for any group not listed in themeGroups. | | typography.fontVariantNumeric.tabular | string[][] | [] | Token-path prefixes whose typography tokens get a tabular-nums font-variant. See Typography. | | utilities | BuilderFn[] | [] | Builders that emit utility CSS / SCSS files. Order matters for output filenames only. |

Programmatic API

import { runPipeline } from '@formtrieb/token-resolver';
import config from './formtrieb-tokens.config.ts';

await runPipeline(config);
// or partial: await runPipeline(config, { only: ['utilities'] });

License

MIT