Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .changeset/acidcat-cli-mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
"@hebilicious/cssforge": minor
---

Rewrite the CLI, and add an MCP server and typed calls from code.

- Commands: `cssforge tokens build`, `cssforge tokens generate`, `cssforge config check`, `cssforge watch tokens.built` and `cssforge list`. Each command answers with JSON on stdout.
- `cssforge mcp` serves the same commands to an agent as MCP tools, through stdio.
- `@hebilicious/cssforge/capabilities` gives the same commands to code, with types: `createSession(cssforge, { target: "library", … })`.
- The catalog of the commands ships as `cssforge.acidcat.json`.
- Breaking: `cssforge [flags]` without a command no longer builds; run `cssforge tokens build [flags]`. `-w`, `-m` and `--prefix` are removed: use `cssforge watch tokens.built`, `--mode` and `--root`. `--color-formats` takes one format per flag or a JSON array, not a comma separated list.
- Breaking: the output is JSON. Build warnings are in the `diagnostics` of the result instead of `cssforge: warning:` lines on stderr. An invalid flag exits with `3` instead of `1`, and an interrupted watch exits with `130`.
- Breaking: `build()`, `watch()`, `parseColorFormats()`, `writeFileRecursive()` and the default export of `@hebilicious/cssforge/cli` are removed. Call `tokens.build` through `@hebilicious/cssforge/capabilities` instead. The `citty` dependency is removed.
105 changes: 80 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@ pnpm add -D @hebilicious/cssforge
The package installs a `cssforge` executable:

```bash
pnpm cssforge --mode all # pnpm
npx cssforge --mode all # npm
pnpm cssforge tokens build # pnpm
npx cssforge tokens build # npm
```

The rest of this document writes commands as `cssforge <args>`.
Expand Down Expand Up @@ -152,9 +152,9 @@ export default defineConfig({
2. Run CSS Forge with the CLI :

```bash
cssforge # Basic usage
cssforge --help # To see all options
cssforge --watch # To watch for changes
cssforge tokens build # Basic usage
cssforge --help # To see all commands
cssforge watch tokens.built # To watch for changes
```

3. Use the generated variables in your CSS:
Expand Down Expand Up @@ -258,7 +258,7 @@ cssforge({
real file, or when a bundler has no CSS handling for virtual modules.

The plugin calls the same `generateCSS` implementation as the CLI, so `virtual:cssforge.css` matches
`cssforge --mode css` output byte for byte. The served stylesheet is unlayered, and
`cssforge tokens build --mode css` output byte for byte. The served stylesheet is unlayered, and
`@import "virtual:cssforge.css" layer(cssforge)` does not work because a CSS import resolves to a
file; set `write` and import the written file with `layer(cssforge)` to keep the tokens in a layer.
The CLI stays the integration path for everything else: JSR, Style Dictionary, CI steps, and tools
Expand Down Expand Up @@ -316,7 +316,7 @@ A level with one child is collapsed, so `palette: { value: { coral: ... } }` bec
The TypeScript output is a typed module. Put it in your source tree:

```bash
cssforge --mode ts --ts ./src/design-tokens.ts
cssforge tokens build --mode ts --ts ./src/design-tokens.ts
```

```typescript
Expand Down Expand Up @@ -348,7 +348,7 @@ the compiler options the Quick Start documents.
The JSON output is the same tree without the `as const` wrapper:

```bash
cssforge --mode json --json ./src/design-tokens.json
cssforge tokens build --mode json --json ./src/design-tokens.json
```

```javascript
Expand Down Expand Up @@ -1984,29 +1984,74 @@ The pow representation of a step adds a `pow` segment, as in

## CLI Usage

Each command answers with JSON on stdout.

```bash
# Basic usage
cssforge
# Write every output of ./cssforge.config.ts
cssforge tokens build

# Watch mode
cssforge --watch
# 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 --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
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 --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json
cssforge tokens build --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
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

# Generate sRGB formats next to oklch for every palette color, added to the config's formats
cssforge --color-formats hex,rgb
# Every command, with its flags
cssforge list
```

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`.
| 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

Expand Down Expand Up @@ -2060,7 +2105,7 @@ you already generate.
Use `style-dictionary` mode to generate only the token file:

```bash
cssforge --mode style-dictionary --style-dictionary ./.cssforge/tokens.json
cssforge tokens build --mode style-dictionary --style-dictionary ./.cssforge/tokens.json
```

Use `--mode all` to generate it together with the CSS, TypeScript, and regular JSON outputs.
Expand Down Expand Up @@ -2135,7 +2180,7 @@ Dictionary will transform the file.

```bash
# Keep CSS variables as values for usage matching
cssforge --mode style-dictionary --style-dictionary ./.cssforge/tokens.json --style-dictionary-value-mode css-reference
cssforge tokens build --mode style-dictionary --style-dictionary ./.cssforge/tokens.json --style-dictionary-value-mode css-reference
```

### Programmatic API
Expand Down Expand Up @@ -2167,9 +2212,19 @@ lets Musea attribute a `var(--token)` written in an art file back to its token.

## Agentic usage

CSSForge is intentionally designed to be extremely simple and integrate well with various
agents, such as Github Copilot, Gemini, Claude Code ... While there's no documentation
yet, you can add the README file to the agent context directly.
Agents can run the `cssforge` CLI like any other command: each command answers with JSON, and
`cssforge list` describes every command and its flags.

`cssforge mcp` serves the same commands as MCP tools, through standard input and output:
`tokens.build`, `tokens.generate` and `config.check`, and the event `tokens.built`. Paths
resolve against the directory where the agent starts the server, or against the `root` of a
call. To add it to Claude Code:

```bash
claude mcp add cssforge -- npx cssforge mcp
```

You can also add the README file to the agent context directly.

For most agents, this syntax works
`@https://raw.githubusercontent.com/Hebilicious/cssforge/refs/heads/main/README.md`.
Expand Down
4 changes: 2 additions & 2 deletions example/tailwind-nextjs/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
4 changes: 2 additions & 2 deletions example/tailwind-nuxt/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
4 changes: 2 additions & 2 deletions example/tailwind-solidstart/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
4 changes: 2 additions & 2 deletions example/tailwind-sveltekit/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
4 changes: 2 additions & 2 deletions example/vanilla-solid-css/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
4 changes: 2 additions & 2 deletions example/vanilla-svelte-css/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
4 changes: 2 additions & 2 deletions example/vanilla-vue-css/moon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ tasks:
command: "node"
args:
- "../../packages/cssforge/dist/cli.js"
- "--prefix"
- "."
- "tokens"
- "build"
- "--config"
- "./cssforge.config.ts"
- "--mode"
Expand Down
Loading
Loading