Using CSS Forge

CLI Usage

# Basic usage
cssforge

# Watch mode
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

# 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
cssforge --color-formats hex,rgb

Build warnings, such as a fluid type step below the legibility floor, are printed to stderr before the outputs are written, one line each as cssforge: warning: <message>. They do not fail the build: the outputs are still written and the exit code stays 0.

Programmatic Usage

You can also use CSS Forge programmatically:

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:

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 also returns its 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