democrito

name

democrito

description

Use this skill when working with the democrito design system — generating UI components, applying design tokens, or following atomic-design conventions. Triggers on mentions of democrito, design system, design tokens, atomic design, shadcn component, theme, color system, typography, or "build a component" for any React + Tailwind + shadcn project that has adopted democrito. Provides tokens, principles, component inventory, and three-theme guidance so Claude produces on-system code from the first attempt.

democrito — Claude Skill

democrito is a general-purpose, themeable Atomic Design System for data-dense, IDE-inspired applications — dashboards, editors, AI tools, and internal platforms. This skill gives Claude the full design-system context needed to generate on-system UI code from the first attempt.

Trigger this skill when: generating React + Tailwind + shadcn UI in any project that has adopted democrito; applying tokens; composing atoms/molecules/organisms/templates; rebranding via theme tokens.

Do not trigger this skill for: application logic, data modeling, business rules, or any product-specific feature work. This skill covers the design-system layer only.

---

Reference Files

Read these bundled files on-demand when you need deeper context:

File	When to read
principles.md	Before any visual / structural decision — the 6 design principles behind every token and component choice
tokens.md	Whenever you need the exact HSL value, Tailwind class, or purpose of a design token (surfaces, text, accent, semantic, typography, spacing, motion)
components.md	Before creating a new component — check the inventory across Atoms, Molecules, Organisms, and Templates to avoid duplicates
agent-usage.md	For prompting strategies and the compact token block to hand to other AI tools

---

Methodology

When generating or reviewing democrito code, apply this order:

1. Tokens first. Never hardcode colors, spacing, or radii. Every visual value comes from tokens/index.css CSS custom properties, exposed via the CSS-first @theme block in tokens/index.css. Use Tailwind utility classes bound to tokens (bg-surface, text-foreground-muted, border-border) — never bg-gray-800 or text-white.
2. Three-surface hierarchy. Build depth with --background → --surface → --card, in that order. Inputs must not share a surface with their containing card.
3. Three-font system. font-display for headings, font-body for prose, font-mono for all data, code, user-generated content, and tokens/commands.
4. Three-theme compliance. Every new color token must be defined in all three themes: :root (warm, default), .dark, and .light.
5. Principles gate. Changes must respect the six principles from principles.md:
   1. Monochromatic + Accent
   2. 3-Surface Hierarchy
   3. Typography as Hierarchy
   4. Progressive Disclosure
   5. Accessible by Default
   6. IDE-Inspired

---

Architecture — Atomic Design

Level	Directory	Description	Examples
Atoms	registry/atoms/	Single-purpose building blocks	Code, CodeBlock, CopyButton, Heading, Kbd, Link, Logo, Spinner, StatusBadge, Tag, Text
Molecules	registry/molecules/	Compositions of 2+ atoms	FormField, SearchBar, StatCard, TokenCounter, TabNav, EmptyState, TokenReferenceCard
Organisms	registry/organisms/	Major UI sections	TopBar, DataTable, FilterBar, DashboardStats, AuthForm, SidebarNav, UserMenu
Templates	registry/templates/	Page layout shells — no business logic	AppShell, EditorLayout, LibraryLayout, DetailLayout, DashboardLayout

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

---

Coding Rules

1. Check existing components first — verify the component doesn't already exist in atoms/, molecules/, or ui/ before creating anything new.
2. TypeScript with explicit prop interfaces — every component must declare an interface for its props with JSDoc descriptions.
3. PascalCase filenames, one component per file.
4. Extend shadcn/ui primitives via CVA variants — compose them into atoms/molecules, never rebuild from scratch.
5. User-editable content uses font-mono — all code, data values, and user-generated content.
6. Semantic color only — use bg-card, text-muted-foreground, border-border. Never bg-gray-800 or text-white.

---

Technology Stack

• React 18 + TypeScript 5
• Vite 5
• Tailwind CSS v4
• shadcn/ui (Radix primitives)
• React Router v6

---

Key Files (in host repos adopting democrito)

File	Purpose
tokens/index.css	CSS custom properties + @theme block — source of truth for all design tokens
CLAUDE.md	Auto-read context file for AI agents working in the repo
docs/reference/theming.md	How to customize the system for a specific brand
CONTRIBUTING.md	Development workflow and conventions

---

See the companion files in this skill folder for detailed token, component, principle, and usage references.