Design

Overview~5 min

Visual foundations for building consistent, accessible interfaces — from color tokens to layout patterns.

Read this when you're customizing the design system or need to understand visual conventions.
Useful for designers, developers, and AI agents working on UI.

What This Section Covers

Design is about how to implement visual identity. This section covers the design system foundations: color tokens, typography scales, layout patterns, and customization workflows. It's the practical guidance for making Catalyst look like your product.

For the components that implement these patterns, see Components. For coding standards including CSS conventions, see Standards.

Design Principles

The philosophy behind Catalyst's visual language:

Simple over clever

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

Consistent and predictable

Same patterns everywhere. Users and AI agents should predict behavior without surprises.

Accessible by default

ARIA patterns, color contrast, keyboard nav. All components meet WCAG AA out of the box.

AI-friendly

Easy to understand and modify. No magic, no hidden behavior — just tokens and utilities.

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 at POC stage — invest in aesthetics as you progress toward production.

The Design System

CSS Variables (Tokens)

Colors, spacing, and typography defined in globals.css. Change a token, everything updates.

Tailwind CSS 4

Utility-first styling with CSS variable integration. Fast to write, easy to maintain.

shadcn/ui + base-ui

Accessible, unstyled primitives. You own the code, not a dependency.

Dark Mode

Class-based switching via next-themes. Variables adapt automatically.

Documentation

Everything you need to work with the design system:

Customisation

Start here

Transform Catalyst into your project. Personality presets, colour palettes, border radius, typography, and more. Copy prompts, let AI do the work.

Make it yours

Playbook

Design principles and approach. How to think about visual decisions.

Demo

Live preview of the entire design system. Validate changes at a glance.

Colours

Theme colors, semantic tokens, and usage guidelines. Where your brand lives.

Typography

Font scales, text styles, and heading hierarchy. Words matter.

Layout

Spacing scale, page templates, and grid patterns. Structure for your UI.

Patterns

Content patterns for websites, apps, and presentations. Narrative structures.

Token Architecture

:root (Raw Values)

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

--primary-500: oklch(0.65 0.2 180)

@theme (Semantic Tokens)

Maps raw values to meanings. Components reference these names.

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

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

Quick Paths

Where to go based on what you're doing:

Exploring the system?

Start with the Demo page to see everything in one place. Then dive into specific topics.

View demo

Changing the theme?

Read Customisation for prompts and workflows. Check Demo to validate changes.

Customisation guide