Sage Design Engine

Make it lovable. AI-Native components for velocity.

Who Is This For?

Developers

Build faster with TypeScript-first components, comprehensive examples, and a ~2KB syntax parser that just works.

Designers

Explore live components, customize themes with the built-in Customizer, and see design tokens as importable JavaScript objects.

→ Explore Tokens and Components

AI Agents

All components include prop interfaces, usage examples, and transparent documentation. Built with AI collaboration from day one.

→ Read AGENTS.md

Learners

Study functional component organization, understand design tokens, and see how philosophy translates to production code.

→ Start with How It Works

What's Included

Everything you need to build beautiful, accessible, user-controlled interfaces

100 Components

Component Library

7 functional categories covering actions, forms, navigation, overlays, feedback, data display, and layout.

Explore Components →

3 Themes

Themes

Studio, Terra, and Volt themes with light and dark modes. Each with unique personality and complete token systems.

Explore Themes →

Motion System

User-Controlled Motion

0-10 intensity scale respecting prefers-reduced-motion. Text effects, backgrounds, cursors, and micro-interactions.

Explore Motion →

Blocks

Composed Blocks

Pre-built page sections like Hero, OpenGraph cards, code blocks, and navigation patterns.

View Blocks →

React Hooks

Hooks & Utilities

useTheme, useMotionPreference, useForm, and more. Complete utilities for theme and motion control.

View Hooks →

AI-Native

MCP Server

AI-powered component discovery and code generation for Claude Desktop, Cursor, and compatible editors.

Setup MCP →

Philosophy in Action

These aren't abstract principles. They're design decisions you can see, touch, and fork.

Component-First Architecture

Sage Design Engine encapsulates design tokens inside components rather than exposing them as CSS classes. This approach is the foundation of the entire system and provides several key advantages:

Ensures consistency - Impossible to use wrong token combinations or values

Simplifies API - <Text> instead of remembering text-[var(--color-text-primary)]

Enables smart defaults - Components choose appropriate tokens automatically

Improves DX - TypeScript autocomplete for semantic props like variant and size

Don't do this:

<span className="text-[var(--color-text-primary)]">Text</span>

Do this instead:

<Text>Text</Text>

→ See Usage Guide for complete component-first documentation

Emotionally Resonant

Touch hearts, don't just solve problems. Every interaction should feel like it was made by someone who genuinely cares.

In practice:

Three distinct themes (Studio, Terra, Volt) with unique personalities. Motion that enhances rather than distracts. Color palettes that respect accessibility while expressing emotion.

User Control & Freedom

The user is the controller of their own experience. From motion controls to theme preferences, nothing forced, everything explained.

In practice:

User-controlled motion scale (0-10) with automatic prefers-reduced-motion support. Theme and mode switching with localStorage persistence. Built-in Customizer for real-time experimentation.

Transparent by Design

Show the receipts. AI collaboration documented, design tokens exposed, code that teaches.

In practice:

Design tokens as importable JavaScript objects. Comprehensive prop tables and examples for every component. AI collaboration history documented in AGENTS.md.

Generous by Design

Open source. Teachable. Accessible to all. MIT License from day one.

In practice:

MIT licensed, fully documented, with commented code that explains the "why." WCAG AA compliance. Detailed architecture documentation. Fork-friendly structure.

Read the full Design Philosophy →

What Makes This Different

Automatic Syntax Parser

A ~2KB regex-based tokenizer with 14 token types, zero dependencies, and automatic theme awareness. No heavy libraries like Prism or Highlight.js required.

Automatically detects TypeScript, JavaScript, JSX, TSX

Theme-aware colors adapt to light/dark mode

Built-in copy button and collapsible code blocks

import { parseCode } from '@thesage/ui';

const code = `function hello() {
  return "world";
}`;

const tokens = parseCode(code, 'typescript');
// Returns 14 classified token types

User-Controlled Motion

A 0-10 scale motion system that respects user preferences. Automatically honors prefers-reduced-motion while allowing fine-grained control.

System preference override (0 = respects OS setting)

Granular control from subtle (1-3) to playful (8-10)

Accessible by default, customizable by choice

import { useMotionPreference } from '@thesage/ui';

export function MotionAwareComponent() {
  const { scale, shouldAnimate } = useMotionPreference();

  return (
    <div>
      <p>Motion Scale: {scale} (0-10)</p>
      <p>Animations Enabled: {shouldAnimate ? 'Yes' : 'No'}</p>
    </div>
  );
}

Three Living Themes

Each theme has its own personality, typography pairing, and emotional resonance. All components automatically adapt via CSS custom properties.

import { useTheme } from '@thesage/ui';

export function ThemeSwitcher() {
  const { theme, setTheme, mode, setMode } =

import { useTheme } from '@thesage/ui';

export function ThemeSwitcher() {
  const { theme, setTheme, mode, setMode } = useTheme();

  return (
    <>
      <button onClick={() => setTheme('terra')}>Sage</button>
      <button onClick={() => setMode('dark')}>Dark Mode</button>
    </>
  );
}

Built-in Customizer

A floating panel that lets users experiment with themes, motion, and preferences in real-time. All changes persist to localStorage.

Live theme and mode switching

Motion scale control with instant feedback

Preferences saved across sessions

Two modes: full-featured or lightweight

→ Full documentation: Navigate to Patterns > Customization > Customizer in the sidebar for interactive demos and code examples.

Interactive preview - click the button to explore

Try the interactive preview above, then explore the full component documentation in the sidebar

Choose Your Path

Different starting points for different goals.

"I want to start building"

Jump straight to installation, grab components, and start shipping.

1. Quick Start →2. Browse Components →3. GitHub Repository →

"I want to understand the system"

Learn the architecture, philosophy, and design decisions.

1. Usage Guide →2. Explore Tokens →3. Design Philosophy →

"I want to extend or fork this"

Understand the file structure, add components, or create your own theme.

1. Architecture Guide →2. Component Workflow →3. Fork on GitHub →

"I'm an AI agent"

Access structured documentation, prop tables, and integration patterns.

1. AGENTS.md →2. Usage Guide →3. Component Catalog →

How It Works

Token-Driven Design

All design decisions are encoded as importable JavaScript objects, not locked in Figma. This makes them version-controllable, type-safe, and usable in code.

Important: Tokens are consumed through components, not applied directly. Use <Button> instead of manually styling with className="bg-[var(--color-primary)]".

import { colorTokens, spacingTokens } from '@thesage/ui/tokens';

// Tokens are available for reference
const primaryColor = colorTokens.studio.light.primary;
const spacing = spacingTokens.lg; // "1.5rem" (24px)

// But consumed through components:
import { Button, Text } from '@thesage/ui';
<Button variant="default">Click me</Button>  // ✅ Correct
<Text>Hello</Text>                           // ✅ Correct

// NOT manually applied:
// <button className="bg-[var(--color-primary)]">...</button> // ❌ Wrong

Functional Organization

Components are organized by what they do, not by abstract hierarchy. This eliminates classification ambiguity and improves developer discoverability.

Actions (3) — Interactive elements that trigger behaviors (Button, Toggle, ToggleGroup)

Forms (11) — Input controls for data collection (Input, Select, Checkbox, Switch, Slider...)

Navigation (6) — Moving through content hierarchy (Breadcrumb, Tabs, Pagination, Command...)

Overlays (9) — Contextual content above main UI (Dialog, Sheet, Popover, Tooltip, Drawer...)

Feedback (5) — Communicating system state (Alert, Toast, Progress, Skeleton, Sonner)

Data Display (6) — Presenting information (Table, DataTable, Card, Avatar, Badge, Calendar)

Layout (8) — Spatial organization (Accordion, Carousel, ScrollArea, Separator...)

File Structure

Everything lives in a monorepo with clear separation between the design system package and consuming applications.

ecosystem/
├── packages/
│   ├── ui/                      # @thesage/ui - Component library
│   │   └── src/
│   │       ├── components/
│   │       │   ├── actions/     # Button, Toggle, ToggleGroup
│   │       │   ├── forms/       # Input, Select, Checkbox, etc. (11 components)
│   │       │   ├── navigation/  # Breadcrumb, Tabs, Pagination, etc. (6 components)
│   │       │   ├── overlays/    # Dialog, Sheet, Popover, etc. (9 components)
│   │       │   ├── feedback/    # Alert, Toast, Progress, etc. (5 components)
│   │       │   ├── data-display/ # Card, Table, Avatar, etc. (6 components)
│   │       │   └── layout/      # Accordion, Carousel, Separator, etc. (8 components)
│   │       ├── lib/             # Utilities, validation, animations, stores
│   │       ├── hooks/           # useTheme, useMotionPreference, useForm
│   │       └── providers/       # ThemeProvider
│   └── tokens/                  # @thesage/tokens - Design system tokens
│
└── apps/
    ├── web/      # This documentation site
    ├── portfolio/               # Example consumer app
    └── creative-powerup/        # Example consumer app

Get Started in 5 Minutes

Prerequisites

System Requirements

Node.js 18.0.0 or later
Package Manager: pnpm 8.15.0+ (or npm 9+, yarn 3+)
React 18+ or React 19+ (React 19 recommended)
Tailwind CSS 3.0.0 or later

Compatible Frameworks

Sage Design Engine works with:

Next.js 15+ (App Router or Pages Router)
Vite 5+
Remix 2+
Create React App (with Tailwind)
Any React framework with Tailwind CSS support

TypeScript (Optional)

TypeScript 5.0+ for full type support. All components include TypeScript definitions.

Install dependencies

Sage Design Engine requires React and Framer Motion as peer dependencies:

pnpm add react framer-motion @thesage/ui
# or
npm install react framer-motion @thesage/ui
# or
yarn add react framer-motion @thesage/ui

Configure Tailwind CSS

Add Sage Design Engine to your Tailwind content paths:

// tailwind.config.ts
import type { Config } from 'tailwindcss';

export default {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@thesage/ui/**/*.{js,ts,jsx,tsx}', // Add this line
  ],
  // ... rest of your config
} satisfies Config;

Note: Sage Design Engine uses CSS custom properties for theming. No additional Tailwind configuration required—themes are injected at runtime by the ThemeProvider.

Import and use components

import { Button, Card, Badge } from '@thesage/ui';

export function MyComponent() {
  return (
    <Card>
      <h2>Hello, Sage!</h2>
      <Badge variant="success">New</Badge>
      <Button variant="default" size="lg">
        Get Started
      </Button>
    </Card>
  );
}

Wrap your app with ThemeProvider

import { ThemeProvider } from '@thesage/ui/providers';

export default function App({ children }) {
  return (
    <ThemeProvider>
      {children}
    </ThemeProvider>
  );
}

ThemeProvider Props

Prop	Type	Required	Description
`children`	`ReactNode`	Required	Your application content

Default Theme & Mode

The ThemeProvider starts with theme: "volt" and mode: "dark" by default. User preferences are automatically persisted to localStorage.

Programmatic Control

Use the useTheme() hook to control theme and mode:

import { useTheme } from '@thesage/ui/hooks';
import { useEffect } from 'react';

export function MyApp() {
  const { setTheme

import { useTheme } from '@thesage/ui/hooks';
import { useEffect } from 'react';

export function MyApp() {
  const { setTheme, setMode } = useTheme();

  // Set initial theme/mode on mount
  useEffect(() => {
    setTheme('studio');
    setMode('light');
  }, []);

  return <YourContent />;
}

Available Options

Themes: "studio", "terra", "volt"
Modes: "light", "dark"
Storage: Automatically persists to localStorage key "ecosystem-theme"

Control themes and motion

import { useTheme, useMotionPreference } from '@thesage/ui/hooks';

export function Controls() {
  const { theme, setTheme, mode, setMode } = useTheme();
  const { scale, shouldAnimate } = useMotionPreference();

  return (
    <div>
      <button onClick={() => setTheme('sage')}>Sage Theme</button>
      <button onClick={() => setMode('dark')}>Dark Mode</button>
      <p>Motion Scale: {scale}/10 - Animations {shouldAnimate ? 'enabled' : 'disabled'}</p>
    </div>
  );
}

Understanding the Motion System

Sage Design Engine uses a 0-10 motion scale that gives users fine-grained control over animation intensity. This respects accessibility needs while allowing users who enjoy motion to customize their experience.

Implementation Status: The motion system API is complete and functional, but currently only a subset of animated components use it. Integration is ongoing - developers should use useMotionPreference() when implementing new animations.

Scale	Behavior	Use Case
`0`	No animations (instant state changes)	Vestibular disorders, motion sensitivity
`1-3`	Subtle animations (~100-200ms)	Minimal, professional interfaces
`5`	Balanced animations (default)	General purpose, most users
`7-9`	Expressive animations	Engaging, playful interfaces
`10`	Maximum animation intensity	Highly interactive, game-like experiences

Automatic Accessibility

Respects prefers-reduced-motion: reduce automatically
shouldAnimate returns false when scale is 0 OR system preference is reduce
Motion scale 0 must work perfectly - no broken layouts or missing UI states
No additional code needed - the hook handles everything

How Users Set Motion Preferences

1. The Customizer Component (Recommended)

Add the built-in Customizer for a complete user control panel:

import { CustomizerPanel } from '@thesage/ui';

export function App() {
  return (
    <>
      <YourContent />
      <CustomizerPanel

import { CustomizerPanel } from '@thesage/ui';

export function App() {
  return (
    <>
      <YourContent />
      <CustomizerPanel /> {/* Floating panel with motion slider */}
    </>
  );
}

2. Programmatically via Hook

Build your own motion controls:

import { useMotionPreference } from '@thesage/ui/hooks';

export function MotionControls() {
  const { scale, setMotionPreference

import { useMotionPreference } from '@thesage/ui/hooks';

export function MotionControls() {
  const { scale, setMotionPreference } = useMotionPreference();

  return (
    <input
      type="range"
      min="0"
      max="10"
      value={scale}
      onChange={(e) => setMotionPreference(Number(e.target.value))}
    />
  );
}

3. System Preference (Automatic)

When a user enables prefers-reduced-motion: reduce in their OS settings, shouldAnimate automatically returns false regardless of the scale value.

Persistence: Motion preferences automatically save to localStorage and sync across sessions.

Next Steps

You're all set up! Here's how to continue building with Sage Design Engine:

1. Explore Components

Browse all 89 components organized by function:

Actions•Forms•Navigation•Overlays•Feedback•Data Display•Layout

2. Try the Customizer

See how themes and motion work with a floating control panel:

import { CustomizerPanel } from '@thesage/ui';

export function App() {
  return (
    <>
      <YourApp />
      <CustomizerPanel

import { CustomizerPanel } from '@thesage/ui';

export function App() {
  return (
    <>
      <YourApp />
      <CustomizerPanel />
    </>
  );
}

3. Read the Usage Guide

Understand architecture and best practices:

• Component-First Architecture
• Common Patterns
• Theming Deep Dive

→ Read the Guide

4. Build Something!

Start with a simple page:

import { Button, Card, Badge } from '@thesage/ui';

export function Dashboard() {
  return (
    <Card>
      <h1>My Dashboard

import { Button, Card, Badge } from '@thesage/ui';

export function Dashboard() {
  return (
    <Card>
      <h1>My Dashboard</h1>
      <Badge variant="success">Active</Badge>
      <Button variant="default">Get Started</Button>
    </Card>
  );
}

Need Help?

📖 Full Documentation 🐛 Report Issues 💬 Discussions

💡Pro Tip: Navigation Shortcuts

You can use these quick shortcuts to navigate the documentation:

#quick-start → Quick Start Guide

#getting-started → Overview

#components → Component Dashboard

#resources → Templates

Documentation & Resources

Comprehensive guides organized by your role and needs.

📖

For Users

Building with the design system

→ Usage Guide

Complete guide to component-first architecture, component inventory, common patterns

🔧

For Contributors

Extending the design system

→ Component Workflow → Architecture Guide → CLI Commands Reference

🔍

Troubleshooting

Common issues and solutions

Components are Unstyled

Symptoms: Components render but have no styling, wrong colors, or broken layout.

Common Causes:

Tailwind CSS not configured to include Sage Design Engine paths
ThemeProvider not wrapping your app
CSS not loaded in your bundler

Solutions: Add ./node_modules/@thesage/ui/**/*.{js,ts,jsx,tsx} to Tailwind content, wrap app with <ThemeProvider>, and ensure Tailwind CSS is imported in your root file.

Motion/Animations Not Working

Symptoms: Components appear instantly without transitions.

Common Causes: ThemeProvider not wrapping your app, or motion preference set to 0.

Solutions: Wrap app with <ThemeProvider>, check motion preference using useMotionPreference() (should not be 0), and verify browser doesn't have prefers-reduced-motion: reduce enabled.

TypeScript Errors on Import

Symptoms: Cannot find module '@thesage/ui' or its corresponding type declarations

Common Causes:

Package not installed
Package installed but TypeScript declarations not built
Wrong import path

Solutions: Run pnpm install @thesage/ui, if using monorepo run pnpm build --filter @thesage/ui, and verify import uses import { Button } from '@thesage/ui' not '@thesage/ui/Button'.

Peer Dependency Warnings

Symptoms: npm WARN @thesage/ui requires a peer of react@* but none is installed

Cause: Missing required peer dependencies.

Solution: Install peer dependencies with pnpm add react framer-motion

Still Having Issues?

📖 Check the Usage Guide 🐛 Report a bug 💬 Ask a question

🎨

Working on the Studio itself?

If you're developing or modifying Sage Studio (this documentation site), start here:

→ Studio Development Guide

Ready to Build?

The design system is open source and MIT licensed. Fork it, extend it, make it yours.