Foundations
The design decisions that will keep your projects consistent.
Direction
Calm, precise, neutral interfaces with a blue action color, readable density, subtle borders, and restrained elevation. Optimize for repeated work, clear actions, and predictable behavior.
The repository's DESIGN.md is the full specification. This page summarizes the intended system; the documentation uses a customized Fumadocs layout, while Button now uses the supplied palette and shared control geometry. Other components still need refinement.
Color
Explore the Colors reference for light and dark swatches, interaction tokens, and copyable CSS values.
Use semantic roles such as background, foreground, primary, muted, border, and destructive. Every filled surface needs its matching foreground. Support both light and dark themes.
The theme maps neutral roles to a generated OKLCH gray ramp through live CSS references. It retains separate link and focus tokens and a monochrome chart palette. Automated token-pair checks cover common text, control, and sidebar surfaces; chart series and complete components still need their own validation. Theme installation is separate from component installation.
Typography
The interface uses Inter, with system sans-serif fallbacks. Explore Typography for live specimens, font families, text treatments, and copyable styles.
| Role | Size / line height | Weight |
|---|---|---|
| Page title | 24px / 32px | 600 |
| Section title | 18px / 28px | 600 |
| Component title | 16px / 24px | 600 |
| Body | 14px / 20px | 400 |
| Label | 14px / 20px | 500 |
| Caption | 12px / 16px | 400 |
| Metric | 28px / 36px | 600 |
Icons
Use Lucide consistently. Controls choose their icon sizes automatically: 14px for small, 16px for default and large controls with text, and 20px for large icon-only buttons. Explore Icons for the scale, input-group spacing, loading indicators, and accessible examples.
Spacing and shape
Use a 4px spacing rhythm: 4, 8, 12, 16, 24, 32, 48, and 64px. Form fields have a 16px gap. Field parts use 4px spacing, while FieldContent label/description pairs and fieldset legend/description pairs have no added gap. Fieldset descriptions sit 16px above the fields. Buttons and inputs share size-specific radii: small 4px, default 6px, large 8px. These control tokens are separate from the 0.625rem baseline for other surfaces.
Density
| Element | Height | Radius |
|---|---|---|
| Small button / input | 24px | 4px |
| Default button / input | 32px | 6px |
| Large button / input | 44px | 8px |
| Default table row (planned) | At least 44px | — |
| Compact table row (planned) | At least 32px | — |
Preserve readable text and usable targets. Allow rows and controls to grow when text wraps or is enlarged.
Accessibility
Design for keyboard access, visible focus, meaningful labels, clear errors, and reduced motion. Never use color as the only indication of status. Verify actual rendered contrast and interactions before publishing a component.