Appearance
Using CSS Forge
CLI Usage
On a terminal, each command writes text for a person. For a script, in CI or for a coding agent, it writes JSON on stdout. --agent writes JSON and --human writes text, wherever it runs (also --output agent|human, or -o).
bash
# Basic usage: write every output of ./cssforge.config.ts
cssforge
# Watch mode: build now, then after each change of the config or a module it imports.
# In JSON, each build is one line.
cssforge --watch
# Custom paths and output
cssforge --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 --root ./site
# Style Dictionary JSON with final values (default)
cssforge --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json
# Keep CSS variables as values for usage matching
cssforge --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 --color-formats hex --color-formats rgb
# Print one output without writing a file
cssforge generate --format css
# Validate a config and list its warnings
cssforge check
# Every command, with its flags
cssforge list
# Force JSON on a terminal
cssforge build --agentbuild, generate, check and --watch are short names for the commands tokens build, tokens generate, config check and watch tokens.built. --watch comes before the other flags: cssforge --watch --mode css.
| Command | JSON result on stdout |
|---|---|
build | { files, diagnostics, dependencies }: the files written, the warnings and the files the config loaded |
generate | { format, content, diagnostics, dependencies } |
check | { diagnostics, dependencies } |
--watch | 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 has 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);A call prints nothing: the warnings are in result.value.diagnostics when result.ok is true, and the caller reports them:
typescript
if (result.ok) {
for (const { path, message } of result.value.diagnostics) {
console.warn(`warning ${path}: ${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