Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.humic.dev/llms.txt

Use this file to discover all available pages before exploring further.

AI coding agents work best when they understand your design system. Humic gives agents access to your tokens through the CLI, so they can generate code that uses the right values instead of hardcoding colors and spacing.

​
How it works

The Humic CLI supports --json output on every command. Agents can call these commands and parse the JSON to understand your design system — no MCP server or custom integration needed.

​
Setup

​
1. Install the CLI

Add Humic as a dev dependency so it’s available in your project: 
npm install -D @humicdev/cli

​
2. Initialize your project

npx humic init
This creates humic.config.json and writes a context file that agents can read.

​
3. Configure your agent

Add instructions to your agent’s configuration or system prompt. Here’s an example for Claude Code (in CLAUDE.md): 
## Design System

This project uses Humic for design tokens. Before writing UI code:

- Run `npx humic tokens list --json` to see available tokens
- Run `npx humic tokens guidelines --json` for usage rules
- Use CSS custom properties (e.g., `var(--color-brand-primary)`) — never hardcode values
- Run `npx humic validate --file <path>` to check your code against the design system
For Cursor, add this to .cursor/rules: 
When writing UI code, use design tokens from Humic.
Run `npx humic tokens list --json` to see available tokens.
Use CSS variables like var(--color-brand-primary) instead of hardcoded values.

​
Useful commands for agents

CommandWhat the agent gets
npx humic tokens list --jsonAll tokens with types and values
npx humic tokens list --type color --jsonJust color tokens
npx humic scales list --jsonAll color scales with hex values
npx humic tokens guidelines --jsonUsage rules and recommendations
npx humic validate --file src/Button.tsx --jsonValidation results for a specific file

​
Code validation

The validate command uses AI to check code against your design system rules. It catches:
  • Hardcoded color values that should use tokens
  • Magic numbers for spacing that should use primitives
  • Inconsistent usage patterns
This requires a Gemini API key (runs locally, no data sent to Humic): 
npx humic config set gemini-key AIza...
npx humic validate --file src/components/Card.tsx --json

{
  "score": 85,
  "issues": [
    {
      "line": 12,
      "severity": "warning",
      "message": "Hardcoded color #333. Use var(--color-neutral-900) instead."
    }
  ]
}

​
CI integration

Add validation to your CI pipeline to catch design system violations before they’re merged: 
npx humic login --token $HUMIC_CLI_TOKEN
npx humic validate --file src/**/*.tsx --json