Appearance
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| Command | Result 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.built | One 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
@layerto manage specificity - Config First: Always edit the config file, never edit the generated files