| 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:
- 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.
- Three-surface hierarchy. Build depth with
--background → --surface → --card, in that order. Inputs must not share a surface with their containing card.
- Three-font system.
font-display for headings, font-body for prose, font-mono for all data, code, user-generated content, and tokens/commands.
- Three-theme compliance. Every new color token must be defined in all three themes:
:root (warm, default), .dark, and .light.
- Principles gate. Changes must respect the six principles from
principles.md:
- Monochromatic + Accent
- 3-Surface Hierarchy
- Typography as Hierarchy
- Progressive Disclosure
- Accessible by Default
- 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
- Check existing components first — verify the component doesn't already exist in
atoms/, molecules/, or ui/ before creating anything new.
- TypeScript with explicit prop interfaces — every component must declare an
interface for its props with JSDoc descriptions.
- PascalCase filenames, one component per file.
- Extend shadcn/ui primitives via CVA variants — compose them into atoms/molecules, never rebuild from scratch.
- User-editable content uses
font-mono — all code, data values, and user-generated content.
- 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.
