Use democrito with Terminal & IDEs

Clone the repo and every agent session starts with full design system context already loaded. CLAUDE.md is auto-read by Claude Code and Cursor — no manual setup, no context pasting.

The AI tooling landscape has consolidated around a small set of instruction file formats. A repository built for AI-native development should ship the right file for each tool — or at minimum document which ones to add.

AGENTS.md is the closest thing to a universal standard — originated by OpenAI Codex and now stewarded by the Linux Foundation's Agentic AI Foundation alongside Anthropic's MCP. It's in 60,000+ open-source repositories and natively supported by every tool listed above.

Claude Code reads CLAUDE.md as its primary file and falls back to AGENTS.md if no CLAUDE.md exists in the directory. The practical approach: CLAUDE.md for Claude-specific additions, AGENTS.md as the single source of truth for the shared core rules every other tool needs.

If you use tools beyond Claude Code, add AGENTS.md at the repo root. Copy the template below, add it to your fork, and every tool in the ecosystem above will pick up democrito's core rules automatically.

# AGENTS.md — democrito
Design system reference: https://democrito.design

## Setup
- Install: `cd democrito && npm install`
- Dev server: `npm run dev` (localhost:5173)
- Lint + test: `npm run lint && npm run test`

## Architecture
Atomic Design — 5 levels:
- atoms:         registry/atoms/
- molecules:     registry/molecules/
- organisms:     registry/organisms/
- templates:     registry/templates/
- ui primitives: registry/ui/ (shadcn — extend via CVA, never modify directly)
Before creating any component, check all 5 directories for existing implementations.

## Token rules
- All design tokens live in `tokens/index.css` as CSS custom properties (`@theme` block)
- Surfaces: bg-background → bg-surface → bg-card (never a 4th level)
- Fonts: font-display (headings/buttons), font-body (prose/labels),
  font-mono (ALL data values, inputs, identifiers, user-editable content)
- Colors: semantic tokens only — never bg-gray-*, text-white, dark: overrides,
  or hardcoded hex/rgb
- Every new token must be defined in all 3 themes: :root (warm), .dark, .light

## Conventions
- PascalCase filenames, one component per file, named exports only (no re-export index files)
- TypeScript strict mode, explicit props interface with JSDoc on every component
- Never commit directly to main — feature branches (feat/, fix/, chore/) + PR

## Verification
Run after every change: `npm run lint && npm run test`

For local-only overrides you don't want committed — personal tool paths, experiment flags, machine-specific settings — use AGENTS.override.md in the same directory and add it to .gitignore: echo 'AGENTS.override.md' >> .gitignore

In Cursor, prefix a file path with @ to inject its contents into the context window for that message. Use @tokens/index.css for token questions and component generation — it carries the complete @theme block and all three theme overrides.

@tokens/index.css
Build a new component following the democrito design system.
Use CSS custom properties (--background, --surface, --card, --foreground).
All user-editable content must use font-mono (JetBrains Mono).
Button labels use font-display (Plus Jakarta Sans).

For component-level work, @-reference the specific docs file alongside the component file:

@docs/reference/tokens.md @registry/atoms/Heading.tsx
Add a new size variant "4xl" following the existing pattern.

The docs/reference/ folder contains the complete reference documentation for the system. Reference specific files rather than the whole folder — agents work better with focused context.

democrito is a baseline, not a constraint. The token layer is the only branding surface — override CSS custom properties in tokens/index.css and every component in the system inherits the new identity. No component files touched. Three examples below, each starting from npx shadcn@latest add https://democrito.design/r/democrito.json.

Every customization follows the same five-step sequence. Steps 1–3 are CSS-only. Steps 4–5 update the AI context files so agents that read CLAUDE.md and DESIGN.md generate on-brand code from the first prompt.

npx shadcn@latest add https://democrito.design/r/democrito.json

/* tokens/index.css — :root (warm default, blue accent) */
--accent:             217 91% 50%;
--accent-foreground:  0 0% 100%;

/* tokens/index.css — .dark { ... } */
--accent:             217 91% 60%;
--accent-foreground:  0 0% 98%;
--background:         220 14% 6%;
--surface:            220 12% 9%;
--card:               220 10% 12%;
--border:             220 18% 16%;
--muted:              220 10% 13%;
--muted-foreground:   220 12% 52%;

/* tokens/index.css — .light { ... } */
--accent:             217 91% 50%;
--accent-foreground:  0 0% 100%;
--background:         220 20% 97%;
--surface:            220 15% 94%;
--card:               0 0% 100%;
--border:             220 14% 86%;
--muted:              220 14% 91%;
--muted-foreground:   220 10% 44%;

/* tokens/index.css — @theme { ... } */
--font-display: "Inter", system-ui, sans-serif;
--font-body:    "Inter", system-ui, sans-serif;
--font-mono:    "IBM Plex Mono", ui-monospace, monospace;

## Product context
This is [dashboard-name], a developer observability dashboard.

**Theme:** Warm default + dark/light toggle. User-toggleable.
**Accent:** Electric blue — `--accent: 217 91% 60%` (dark) / `217 91% 50%` (warm/light).
**Typography:** Inter for display/body. IBM Plex Mono for all metrics, traces,
  timestamps, and code values — tabular-nums critical.
**Use case:** High-density metric grids, trace waterfalls, error rate sparklines,
  status badges, and filterable log tables.

Surface hierarchy is strict: background → surface (sidebar, panels) → card
  (metric tiles, trace rows). Never skip a surface level.
Accent only on primary CTA and active filter chips.
Status colors (`--destructive`, `--warning`, custom `--success`) supplement
  accent — never replace it.

import { Moon, Sun } from "lucide-react";
import { Button } from "@/components/ui/button";
import { useTheme } from "@/hooks/use-theme";

export function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  const isDark = theme === "dark";

  return (
    <Button
      variant="ghost"
      size="icon"
      aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
      onClick={() => setTheme(isDark ? "light" : "dark")}
    >
      {isDark ? (
        <Sun className="h-4 w-4" />
      ) : (
        <Moon className="h-4 w-4" />
      )}
    </Button>
  );
}