Core Philosophy
Substrate UI is a neobrutalistdesign system. Neobrutalism draws from raw, unpolished web aesthetics — bold borders, hard shadows, high contrast, and unapologetic visual weight. The result is interfaces that feel tangible and direct.
Hard pixel-offset shadows, 2px solid borders, and high-contrast colors. Every element should feel deliberate and present.
All corners are square (--radius: 0). Add the .with-radius class to opt into 0.5rem rounding.
Colors, spacing, typography, shadows, and motion are defined as CSS custom properties. Change a token once and every component updates.
Every interactive component wraps a Radix UI primitive, inheriting keyboard navigation, focus management, and ARIA attributes for free.
Component Anatomy
Every Substrate UI component follows a consistent visual recipe.
| Layer | Pattern | Example |
|---|---|---|
| Border | 2px solid, uses --border | border-2 border-border |
| Shadow | Hard pixel offset from the shadow scale, no blur | shadow-md (4px 4px 0 0) |
| Radius | 0 by default; 0.5rem with .with-radius | rounded-[var(--radius)] |
| Colors | Semantic tokens only — never raw hex in components | bg-primary text-primary-foreground |
| Interaction | Shadow reduces and element translates on press (“push down” effect) | hover:shadow-none hover:translate-x-[4px] |
When to Use Which Variant
Guidance for choosing between component variants.
Button
| Variant | When to use |
|---|---|
| default | Primary call to action — one per section/view |
| secondary | Secondary actions alongside a primary button |
| outline | Tertiary or less prominent actions |
| ghost | De-emphasized actions, toolbar items |
| link | Inline navigation that looks like a text link |
Alert / Badge
| Variant | When to use |
|---|---|
| default | Neutral information or status |
| success | Positive outcome or completion |
| warning | Caution — something needs attention |
| destructive | Error, danger, or irreversible action |
Spacing Philosophy
All spacing is based on a 4px grid. Use the spacing scale consistently to maintain visual rhythm.
| Context | Recommended tokens |
|---|---|
| Tight internal padding (badges, chips) | --spacing-1 to --spacing-2 (4px–8px) |
| Standard component padding | --spacing-3 to --spacing-4 (12px–16px) |
| Gap between related elements | --spacing-4 to --spacing-6 (16px–24px) |
| Section spacing | --spacing-8 to --spacing-12 (32px–48px) |
| Major layout spacing (hero, page gaps) | --spacing-16 to --spacing-28 (64px–112px) |
Typography Hierarchy
Three font families serve distinct roles. Use the size scale to establish clear hierarchy.
| Family | Token | Use for |
|---|---|---|
| Archivo Black | --font-head | Headings, labels, navigation |
| Space Grotesk | --font-sans | Body text, descriptions, UI copy |
| Space Mono | --font-mono | Code, technical values, token names |
Size Guidance
| Context | Recommended sizes |
|---|---|
| Page titles / hero headings | text-4xl to text-6xl (or fluid variants) |
| Section headings | text-2xl to text-3xl |
| Sub-headings | text-lg to text-xl |
| Body text | text-base to text-lg |
| Captions, labels, fine print | text-xs to text-sm |
For responsive headings, use the fluid tokens (--text-3xl-fluid through --text-6xl-fluid) which scale smoothly between breakpoints via clamp().
Color Usage
Always use semantic color tokens. Never use raw hex values in components.
| Token | Purpose |
|---|---|
| --primary / --primary-foreground | Primary actions, active states, key UI elements |
| --secondary / --secondary-foreground | Secondary surfaces, alternative backgrounds |
| --destructive | Danger, delete, irreversible actions |
| --success / --warning / --info / --error | Feedback and status communication |
| --muted / --muted-foreground | De-emphasized content, placeholders, secondary text |
| --primary-50 to --primary-900 | Extended palette for gradients, subtle backgrounds, and detailed UI |
Every semantic color has a -foreground companion designed for text placed on that color. Both light and dark themes override these tokens automatically.
Shadows & Depth
The shadow scale communicates elevation and interactivity. Larger shadows = more elevated / more interactive.
| Context | Shadow | Behavior |
|---|---|---|
| Interactive at rest (buttons, cards) | shadow-md (4px) | Reduces to shadow-none + translate on hover/press |
| Static elevated (panels, callouts) | shadow-sm to shadow (2px–3px) | No state change |
| High emphasis (dialogs, drawers) | shadow-lg to shadow-xl (6px–10px) | Overlay context |
| Subtle / inline | shadow-xs (1px) | Minimal lift for inputs, dividers |
Accessibility
Substrate UI is built on accessible foundations.
All interactive components wrap Radix UI, providing keyboard navigation, focus management, screen reader announcements, and correct ARIA attributes out of the box.
Semantic color pairings (e.g. --primary-foreground on --primary) are designed to meet WCAG AA contrast ratios. See the contrast audit on the Tokens page for the full matrix.
All animations and transitions are disabled when the user has prefers-reduced-motion: reduce enabled in their OS settings.
Light and dark themes are fully supported via the ThemeProvider component. The system preference is respected by default.