Design System

Visual foundations for building consistent interfaces.

Design Principles

Simple over clever

Prefer readable, obvious solutions. Avoid complex animations or interactions that don't add value.

Consistent and predictable

Use the same patterns everywhere. Users and AI agents should be able to predict behavior.

Accessible by default

All components follow ARIA patterns. Color contrast meets WCAG AA.

AI-friendly

Components are easy for AI to understand and modify. Avoid magic.

Proof-Led UX

In Catalyst, design supports validation. Every UI element should help stakeholders understand what's being built and make decisions. Polish is secondary to clarity in POC stage.

Technology Stack

shadcn/ui — Component collection (not a library)
@base-ui/react — Unstyled, accessible primitives
Tailwind CSS 4 — Utility-first styling
CSS Variables — Theme tokens in globals.css

Token Approach

We use a two-layer CSS variable system:

:root (Raw Values)

Color scales, spacing, and base values. AI can regenerate these.

--primary-500: oklch(...)

@theme (Semantic Tokens)

Maps raw values to meanings. Components use these names.

--color-primary: var(--primary-500)

See app/globals.css for the complete token definitions.

Theme Strategy

Catalyst supports light and dark modes via class-based switching:

html element gets .dark class for dark mode
CSS variables automatically switch based on class
Use next-themes for theme management

Explore

Colors — Theme colors, scales, and usage
Typography — Font scales and text styles
Layout — Spacing, sections, and page templates
Content Patterns — Narrative patterns for websites, presentations, and apps