Getting started

0 runtime design tokens generator for modern style systems.

WARNING

CSSForge is an experimental library and its API will change while I figure out a schema that makes sense. That being said, when the schema change, you should be able to search and replace your variables names.

Why

CSS forge is library that leverages modern CSS features and conventions to help you generate CSS custom properties (css variables).

At the core of CSSforge is the schema : A serializable configuration object.

CSSforge has 0 runtime and generate at build time raw CSS, Typescript or JSON.

This intentionally keeps things simple and flexible, and allows you to integrate it with any framework or CSS workflow.

In the future, CSSforge will try to integrate with popular design tools such as Figma.

Features

• 🎨 Colors: Create palettes, gradients and themes. Automatically convert to OKLCH.
• 📐 Typography: Generate fluid typography
• 📏 Spacing: Organise spacing utilities
• 📦 Primitives: Define custom design tokens
• 🎯 Zero Runtime: All processing happens at build time
• 🔄 Watch Mode: Auto-regenerate when your config changes
• 🔌 Framework Agnostic: Use with any CSS workflow

Installation

CSS Forge requires Node 24 or newer. It loads cssforge.config.ts with the native TypeScript support of that runtime, so no extra loader or tsx installation is needed. Configuration files use ES module syntax; add "type": "module" to your package.json to load them without Node's module type detection warning.

# Using npm
npm install --save-dev @hebilicious/cssforge

# Using pnpm
pnpm add -D @hebilicious/cssforge

The package installs a cssforge executable:

pnpm cssforge --mode all # pnpm
npx cssforge --mode all # npm

The rest of this document writes commands as cssforge <args>.

Alternative installation (Deno and JSR)

CSS Forge is also published to JSR at the same version as npm. Use it for Deno projects and for JSR-native imports:

# Deno
deno add jsr:@hebilicious/cssforge

# npm (10.9 +) or pnpm
npx jsr add @hebilicious/cssforge
pnpm i jsr:@hebilicious/cssforge

The jsr: specifier replaces the package name in imports, and the published CLI entry point runs directly with Deno:

deno run -A jsr:@hebilicious/cssforge/cli --mode all

import { defineConfig } from "jsr:@hebilicious/cssforge";

Quick Start

1. Create a configuration file (cssforge.config.ts):

import { defineConfig } from "@hebilicious/cssforge";

export default defineConfig({
  spacing: {
    custom: {
      size: {
        value: {
          1: "0.25rem",
          2: "0.5rem",
          3: "0.75rem",
          4: "1rem",
        },
      },
    },
  },
  typography: {
    fluid: {
      arial: {
        value: {
          minWidth: 320,
          minFontSize: 14,
          minTypeScale: 1.25,
          maxWidth: 1435,
          maxFontSize: 16,
          maxTypeScale: 1.25,
          positiveSteps: 5,
          negativeSteps: 3,
        },
      },
    },
  },
  colors: {
    palette: {
      value: {
        coral: {
          value: {
            100: { hex: "#FF7F50" },
          },
        },
        mint: {
          value: {
            100: { hex: "#4ADE80" },
          },
        },
        indigo: {
          value: {
            100: { hex: "#4F46E5" },
          },
        },
      },
    },
  },
});

2. Run CSS Forge with the CLI :

cssforge # Basic usage
cssforge --help # To see all options
cssforge --watch # To watch for changes

3. Use the generated variables in your CSS:

The CLI writes ./.cssforge/output.css by default. From a consumer stylesheet placed at the project root, import that file as a layer :

/* Relative to a consumer stylesheet placed at the project root. */
@import "./.cssforge/output.css" layer(cssforge);

.button {
  background-color: var(--palette-coral-100);
  padding: var(--spacing-size-2) var(--spacing-size-4);
}

!IMPORTANT Do not manually edit the generated CSS file, edit the configuration file instead and regenerate.

4. Use the generated css in your JS/TS :

The CLI also writes ./.cssforge/output.ts, which exports every token as a fully typed cssForge object :

import { cssForge } from "./.cssforge/output.ts";

// Fully typed token : cssForge.spacing.custom.size["2"] is
// { key: "--spacing-size-2", value: "0.5rem", variable: "--spacing-size-2: 0.5rem;" }
export const spacing2 = cssForge.spacing.custom.size["2"];

export { cssForge };

The generated file is a .ts module, so importing it needs "allowImportingTsExtensions": true (with "noEmit": true) in your tsconfig.json.