Skip to content

CLAUDE.md

Latest commit

 

History

History
116 lines (81 loc) · 5.88 KB

CLAUDE.md

File metadata and controls

116 lines (81 loc) · 5.88 KB
Raw

CLAUDE.md — AI Agent Context

This file is auto-read by AI coding agents (Claude Code, Cursor, Windsurf, etc.) working with democrito, a general-purpose, themeable Atomic Design System for data-dense, IDE-inspired applications — dashboards, editors, AI tools, and internal platforms. It provides essential project context to produce consistent, on-system code from the first generation.

⚠️ Themeable system. This is a general-purpose, brandable design system. Before using default token values, check src/index.css (the @theme block) for any custom theme overrides. The accent color, font families, radius, and surface palette may differ from the defaults documented below. See docs/theming.md for the full theming guide.

Browser Baseline Target

This project targets Baseline 2024 (features interoperable across all major engines since January 2024). When suggesting APIs, CSS properties, or browser features, default to Baseline 2024 Widely Available or Newly Available. Flag anything Limited Availability explicitly before using it.

Documentation Reading Order

Before working on any component, token, or layout task, read docs/ai-context.md. It defines the reading order, decision hierarchy, and known AI bias patterns for this system.

Architecture — Atomic Design

The component library follows Atomic Design methodology with five levels:

Level Directory Description Examples
Atoms src/components/atoms/ Smallest building blocks — single-purpose, no child components Heading, Tag, Spinner, Code, CodeBlock, Kbd, Link, Logo, StatusBadge, Text
Molecules src/components/molecules/ Compositions of 2+ atoms FormField, SearchBar, StatCard, TokenCounter, TabNav, EmptyState
Organisms src/components/organisms/ Major UI sections, may include molecules TopBar, DataTable, FilterBar, DashboardStats, AuthForm, SidebarNav, UserMenu
Templates src/components/templates/ Page layout shells — no business logic AppShell, EditorLayout, LibraryLayout, DetailLayout, DashboardLayout
Pages src/pages/ Route-level components that compose templates + organisms OverviewPage, AtomsPage, MoleculesPage, TokensPage, AiPage, ManifiestoPage

UI Primitives (src/components/ui/) are shadcn/ui components — extend via CVA variants, never modify directly.

Each level has a barrel index.ts for re-exports. One component per file, PascalCase filenames.

Design Tokens

Full reference: docs/tokens.md — colors, typography, spacing, radii, motion.

Key behavioral rules:

  • All colors are HSL CSS custom properties in src/index.css, defined via CSS-first @theme in src/index.css
  • Three themes: Warm (:root, default), Dark (.dark), Light (.light)
  • 3-surface hierarchy: --background → --surface → --card
  • 3-font system: font-display (headings), font-body (text), font-mono (data/code)
  • Spacing base unit: 4px. Layout tokens: --header-height, --sidebar-width, --sidebar-collapsed, --right-panel
  • Never hardcode hex/rgb — always use semantic token classes (bg-surface, text-accent, border-border)

Rules

  1. Check existing atoms first — before creating any new component, verify it doesn't already exist in atoms/, molecules/, or ui/.
  2. Always use design tokens — never use magic numbers for colors, spacing, or radii. Use Tailwind classes mapped to CSS variables.
  3. TypeScript with proper prop types — every component must define an explicit interface for its props with JSDoc descriptions.
  4. Follow existing naming conventions — PascalCase filenames, one component per file, barrel index.ts exports.
  5. Use shadcn/ui primitives as the base — extend via CVA variants in ui/ components; compose them into atoms/molecules, never rebuild from scratch.
  6. User-editable content uses font-mono — all code, data values, and user-generated content must use the mono font family.
  7. Three-theme compliance — any new color token must be defined in all three themes (:root for warm default, .dark, .light) in src/index.css.
  8. Semantic color only — use bg-card, text-muted-foreground, border-border etc. Never write bg-gray-800 or text-white.
  9. Check for theme overrides — before assuming default token values, verify the project's src/index.css @theme block for custom theme configuration.

Git Workflow

Follow CONTRIBUTING.md for commit conventions and branch naming.

Never commit directly to main. Always create a feature branch (feat/, fix/, chore/), commit there, then create a PR.

Commit message format: <type>(<scope>): <description> — see CONTRIBUTING.md for the full spec with types, scopes, and examples.

Verification

Run after any code changes:

npm run lint && npm run test

Available test commands:

Command Purpose
npm run test Vitest unit tests (single run)
npm run test:watch Vitest in watch mode
npm run test:visual Playwright visual regression
npm run test:visual:update Update Playwright snapshots
npm run lint ESLint

Key Files

File Purpose
src/index.css CSS custom properties + CSS-first @theme — source of truth for all design tokens and Tailwind integration
docs/theming.md How to customize the system for a specific brand or product
docs/design-system.md Full design system specification and component inventory
DESIGN.md Design philosophy and visual language — the "taste layer" for AI agents
CONTRIBUTING.md Development workflow, commit conventions, component creation guide
CHANGELOG.md Version history (Keep a Changelog format)