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

For programmatic usage, you can install CSS Forge as a dependency:

# Using npm
npx jsr add @hebilicious/cssforge

# Using pnpm (10.9 +)
pnpm i jsr:@hebilicious/cssforge

Then to run CSS forge, add the following script to your package.json:

{
  "scripts": {
    "cssforge": "tsx ./node_modules/@hebilicious/cssforge/src/cli.ts"
  }
}

then run :

pnpm run cssforge

Quick Start

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

import { defineConfig } from "jsr:@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 :

If you're using a package.json, add the following to your scripts:

{
  "scripts": {
    "cssforge": "tsx ./node_modules/@hebilicious/cssforge/src/cli.ts"
  }
}

Then run the following command :

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

3. Use the generated variables in your CSS:

For example, you can import as a layer :

@import "cssforge.output.css" layer(cssforge);

.button {
  background-color: var(--color-primary-500);
  padding: var(--size-2) var(--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 :

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

// Use like this anywhere :
//`cssForge.colors.palette.basic.white` is fully typed { key: --myKey, value: white, variable: --key: white }

export { cssForge };