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 app-democrito && npm install`
- Dev server: `npm run dev` (localhost:5173)
- Lint + test: `npm run lint && npm run test`

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

## Token rules
- 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, barrel index.ts at each atomic level
- 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 @src/index.css for token questions and component generation — it carries the complete @theme block and all three theme overrides.

@src/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/tokens.md @src/components/atoms/Heading.tsx
Add a new size variant "4xl" following the existing pattern.

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