Overview

Getting started

Charcoal ships in two halves: installable packages for the stable foundation, and a copy-in registry for the fast-evolving AI layers.

1. Install the foundations

Tokens and foundation components come from npm.

npm install @charcoal/core @charcoal/tokens

2. Load the tokens once

Import the token variables and the component styles at your app root. Everything resolves from --ch-* CSS custom properties, so theming happens at the token layer.

import "@charcoal/tokens/css";
import "@charcoal/core/styles.css";

3. Use foundation components

import { Button, Card, Badge } from "@charcoal/core";

export function Toolbar() {
  return (
    <Card>
      <Badge variant="primary" dot>Agent</Badge>
      <Button variant="primary">Approve run</Button>
    </Card>
  );
}

4. Add AI, agentic, and generative components

These are distributed copy-in. The CLI writes the source straight into your repo so you own and adapt it. Each component reads the same Charcoal tokens.

npx shadcn add https://charcoal.nickcoma.io/r/approval-gate.json
npx shadcn add https://charcoal.nickcoma.io/r/reasoning-trace.json

Browse everything in the full catalog. Each registry component lists its exact install command.