@airframeui/theme

Export Airframe tokens so designers can import them into Figma. Git and CSS stay the source of truth.

Most apps never install this package. Override --af-* in your stylesheet — Theming — then run af theme export (via @airframeui/build).

Same version as @airframeui/core. Catalog names come from @airframeui/tokens/catalog.json. Extra --af-* in theme.files export as extension tokens.

Docs: Airframe → Figma · Theme package · Theming · Packages · Changelog

Remaining Figma Variables work: docs/ROADMAP.md.

Export to Figma

af theme export writes DTCG 2025.10 JSON from the tokens the app actually runs: catalog defaults, airframe.config.js breakpoints, then --af-* in theme.files.

Point theme.files at the CSS/SCSS that holds overrides. Globs are allowed. Brand palettes are discovered from [data-brand] — do not list brand ids in config. Colours and fonts stay in CSS. Later entries in theme.files win when the same token is set twice; a comma-separated [data-brand] list applies to every brand in the list.

theme.outputDir is the folder tokens/ is written into (default .airframeui). CLI -o / --out overrides. That is not top-level outputDir (optional generated CSS for PostCSS / af build).

// airframe.config.js
module.exports = {
  theme: {
    files: ['./src/tokens.css', './src/brands/*.css'],
    outputDir: '.airframeui',
  },
};

npm install -D @airframeui/build
npx af theme export
npx af theme export -o ./figma-tokens   # overrides theme.outputDir

.airframeui/
  tokens/
    default/          ← :root palette (Figma collection 1)
      light.tokens.json
      dark.tokens.json
      hc-light.tokens.json
      hc-dark.tokens.json
    delta/             ← [data-brand='delta'] (Figma collection 2)
      light.tokens.json
      dark.tokens.json
      hc-light.tokens.json
      hc-dark.tokens.json
  airframe.resolver.json

In Figma: drop the four files in tokens/default onto one collection (each file is a mode). Drop tokens/delta onto a second collection. Same four filenames in every folder so modes line up. Figma does not read airframe.resolver.json.

Each export replaces tokens/ so a brand you deleted in CSS does not linger. Other files in the output directory are left alone. Add .airframeui/ to .gitignore.

Working app: examples/theme. Product page: Airframe → Figma. Browser playground: Theme Studio.

Library (no CLI):

import { emitDtcgExport, resolveTheme } from '@airframeui/theme';

const spec = resolveTheme({ config, css });
const { palettes } = emitDtcgExport({ spec });
// palettes.default.light … palettes.delta.dark

Import (advanced)

Foreign files → --af-* CSS is best-effort. Do not expect a Tokens Studio or Figma dump to become a complete Airframe theme.

The mapper is a small alias table (primary → --af-base-primary, background → --af-color-background, plus --af-* names). A real design system uses hundreds of proprietary paths (color.blue.500, brand/500, semantic.fg.default). Those land in the unmapped report, not in CSS. Dark and high-contrast companions are often missing.

The reliable path: pick Airframe names, override --af-* in CSS, export to Figma.

Keep generate for CSS that already uses --af-*, for a round-trip of our own DTCG, or when you have renamed tokens to match the catalog. Then:

import { generateFromContent, lintThemeCss } from '@airframeui/theme';

const { css, report } = generateFromContent(tokenFileContents);
console.log(report.unmapped, report.diagnostics);
const lint = lintThemeCss(css);

npx af theme generate --from ./tokens.json -o theme.css
npx af theme lint theme.css

Import the generated theme.css after @airframeui/core. Formats: auto, dtcg, tokens-studio, css, figma-variables, style-dictionary, airframe-spec.

Install

Most apps never install this package. Use the CLI:

npm install -D @airframeui/build

Install @airframeui/theme as a dev dependency only if you import it from a script. It does not run in the browser.

npm install -D @airframeui/theme

Requires Node.js 24 or later. Still install @airframeui/core in the app — this package emits overrides and DTCG, not the runtime CSS.

Package exports

• @airframeui/theme — emitDtcgExport, resolveTheme, generateFromContent, lintThemeCss, …
• @airframeui/theme/node — resolveThemeFromFiles, generateTheme, writeOutput
• @airframeui/theme/rules — generate/lint contract
• @airframeui/theme/mapping — inbound alias table
• @airframeui/theme/theme-schema.json / @airframeui/theme/theme-mapping.json

Related

• @airframeui/core — CSS system
• @airframeui/tokens — token catalog
• @airframeui/build — af theme export CLI
• @airframeui/mcp — npx -y @airframeui/mcp
• Changelog

License

MIT