An open source, dark-first design system and agentic workflow primitives. Monochromatic backbone with a configurable accent color. Three presets. No bloat. Still evolving.
Every design system I've used was built for CRUD apps: forms, tables, dashboards. When I started designing AI-native products, the gaps became obvious. There were no components for approval gates where a human decides whether an agent proceeds. No reasoning traces that show users why an AI made a decision. No confidence indicators, no token counters, no execution timelines.
Teams were either building these from scratch on every project or bolting AI features onto systems that weren't designed for them. The results were inconsistent, inaccessible, and hard to maintain.
Charcoal exists because AI products have fundamentally different interaction patterns than traditional software. Agents need approval gates. Users need transparency into what the AI is doing and why. Costs need to be visible. And all of it needs to work within a cohesive design language that scales.
The system is a work in progress, built to flex as the AI landscape shifts. What matters now is getting the primitives right.
The token system is the core of Charcoal. A single source file defines the dark monochromatic palette, accent color ramp generation, spacing scale, typography, and semantic colors. Everything is organized into categories that components consume through a React context provider.
Tokens are organized into semantic categories: colors (neutral darks, accent ramp, status), spacing (4px base unit, 13-step scale), typography (Inter for UI, JetBrains Mono for code), radius, shadows, and animation (durations, easing functions).
What makes the token system unique are the AI-specific namespaces. Agent state, confidence levels, tool status indicators, and cost tracking are all first-class tokens. These aren't ad-hoc CSS variables. They're part of the design language.
All tokens are emitted as --ch-* CSS custom properties via a TokenProvider. Components consume them through a useTokens() hook internally. Swap the provider and every component in the tree updates.
Components are organized into four layers. Each builds on the previous without redundancy. Layer 1 handles standard UI. Layers 2-4 are what make Charcoal different: primitives purpose-built for AI products that no other design system ships. The component inventory is actively evolving.
When an AI agent takes an action in the real world, sends an email, queries a database, writes code, there needs to be a moment where a human can see what's about to happen and decide whether to proceed. That's not a modal with an "OK" button. It's an approval gate that shows the action, the consequences of approving, the consequences of rejecting, and the confidence level of the agent making the request.
When multiple agents are working in parallel, each calling different tools, each at different stages of completion, users need a way to see the full picture without getting overwhelmed. That's Agent Status Cards and Parallel Thread Views, not a list of log entries.
When an agent hands off work to another agent, users need to see what was passed, what context was included, and what was left out. That's the Agent Handoff Chain, not an invisible backend event.
These aren't edge cases. They're the core interaction patterns of agentic products. Every team building with LLMs hits these problems. Charcoal gives them production-ready components instead of starting from scratch.
Individual components are building blocks. Patterns show how they compose into real interfaces. Each pattern uses components from multiple layers to demonstrate how the system works as a whole, not just as a parts catalog.
Charcoal is a work in progress. The foundation is set: token architecture, four component layers, and a dark monochromatic visual language with configurable accent that stays out of the way. What comes next is driven by real usage and the patterns that emerge as AI products mature.