Skip to content

Using CSS Forge ​

CLI Usage ​

Each command answers with JSON on stdout.

bash
# Write every output of ./cssforge.config.ts
cssforge tokens build

# Watch mode: build now, then after each change of the config or a module it imports.
# Each build is one JSON line.
cssforge watch tokens.built

# Custom paths and output
cssforge tokens build --config ./foo/bar/custom-path.ts --css ./dist/design-tokens.css --ts ./dist/design-tokens.ts --json ./dist/design-tokens.json --style-dictionary ./dist/design-tokens.sd.json --mode all

# Resolve the relative paths against another directory
cssforge tokens build --root ./site

# Style Dictionary JSON with final values (default)
cssforge tokens build --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json

# Keep CSS variables as values for usage matching
cssforge tokens build --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json --style-dictionary-value-mode css-reference

# Generate sRGB formats next to oklch for every palette color, added to the config's formats.
# Repeat the flag, or give a JSON array.
cssforge tokens build --color-formats hex --color-formats rgb

# Print one output without writing a file
cssforge tokens generate --format css

# Validate a config and list its warnings
cssforge config check

# Every command, with its flags
cssforge list
CommandResult on stdout
tokens build{ files, diagnostics, dependencies }: the files written, the warnings and the files the config loaded
tokens generate{ format, content, diagnostics, dependencies }
config check{ diagnostics, dependencies }
watch tokens.builtOne line per build: { data: { ok: true, files, … } }, or { data: { ok: false, failure } }

Build warnings, such as a fluid type step below the legibility floor, are the diagnostics of the result. They do not fail the build: the outputs are still written and the exit code stays 0. A failure is a JSON object with a _tag and exit code 1: ConfigLoadFailed (the config is missing or cannot be evaluated), InvalidConfig (CSS Forge rejects a value) or WriteFailed. An invalid flag exits with 3 and a message on stderr. An interrupted watch exits with 130.

Code can make the same calls with types, through @hebilicious/cssforge/capabilities:

typescript
import {
  createSession,
  cssforge,
  tokensBuild,
  toJsonSchema,
} from "@hebilicious/cssforge/capabilities";

await using session = createSession(cssforge, {
  target: "library",
  context: { cwd: process.cwd() },
  toJsonSchema,
});
const result = await session.call(tokensBuild, { mode: "css" });
if (!result.ok) console.error(result.error._tag, result.error.message);

Programmatic Usage ​

You can also use CSS Forge programmatically:

typescript
import { generateCSS, generateStyleDictionaryJSON } from "@hebilicious/cssforge";

// Generate CSS string
const css = generateCSS(config);

// Add sRGB formats for this run instead of editing the config
const withFormats = generateCSS(config, { colorFormats: ["hex", "rgb"] });

// Write final values for Style Dictionary
const resolvedTokens = generateStyleDictionaryJSON(config);

// Keep var(--token) as each token's value for usage matching
const usageTokens = generateStyleDictionaryJSON(config, { valueMode: "css-reference" });

Build diagnostics ​

getDiagnostics(config, options?) returns the build warnings for a configuration without generating any output. Each one is a Diagnostic:

typescript
import { getDiagnostics } from "@hebilicious/cssforge";

for (const { code, severity, path, message } of getDiagnostics(config)) {
  // code: "typography-below-legibility-floor"
  // severity: "warning"
  // path: "typography_fluid.arial@2xs"
  // message: "Typography step typography_fluid.arial@2xs reaches 7.17px, below ..."
}

Warnings never change the generated output, and the generate* functions do not report them. A configuration that cannot be generated, such as a fluid step past 2.5× growth, throws from getDiagnostics with the same error as from the generators. processTypography and processMotion also return their warnings as diagnostics beside css and resolveMap.

Best Practices ​

  • Version Control: Commit your generated CSS files
  • CSS Layers: Use @layer to manage specificity
  • Config First: Always edit the config file, never edit the generated files

Released under the MIT License.