Design System

The Design System feature is currently in Beta. We’re actively improving it based on user feedback.

The Design System lets you customize your project’s colors, typography, and effects through a visual editor—no code required.

How It Works

HelloLeo projects use CSS variables as design tokens. When Leo creates a project, it sets up a centralized design system in src/styles.css with variables for:

Colors - Primary, secondary, accent, background, text colors (written in oklch)
Typography - Body and heading fonts
Effects - Border radius, shadows

The visual editor reads these variables and lets you modify them in real-time.

Newer projects keep their design tokens in src/styles.css. Older projects use src/index.css instead—the editor auto-detects which file your project uses (it looks for styles.css first, then index.css) and writes changes back in whatever format that file already uses. Everything below works the same either way.

Using the Design Editor

Accessing the Editor

Open your project in HelloLeo
Click Settings in the top navigation bar
Select Design from the settings menu

Colors Tab

Edit your project’s color palette:

Primary - Main brand color for buttons, links, and accents
Secondary - Supporting color for less prominent elements
Accent - Highlight color for special elements
Background/Foreground - Page and text colors
Destructive/Success/Warning - Semantic colors for states

Click any color swatch to open the color picker. Changes preview instantly in the live preview. The picker uses your system color chooser, then saves the value back in the token’s original format (oklch, and on legacy projects HSL or hex)—including any transparency, like oklch(1 0 0 / 10%).

Typography Tab

Choose fonts for your project:

Body Font - Used for paragraphs and general text
Heading Font - Used for titles and headings

Select from 30+ Google Fonts organized by category (Sans Serif, Serif, Display, Monospace). Fonts load automatically in the preview. When you save, the editor updates the Google Fonts <link> in your index.html so the new fonts also load in the published app.

Effects Tab

Adjust visual effects:

Border Radius - Control corner rounding (square to fully rounded)
Shadow Intensity - Adjust shadow depth from None to Strong

Saving Changes

Click Save Changes to apply your modifications to the project. Color and effect tokens are written to your entry CSS file (src/styles.css, or src/index.css on older projects), and the font <link> in index.html is updated to match. Changes hot-reload automatically.

Light & Dark Mode

Use the toggle at the top of the editor to switch between editing:

Light mode colors (default theme)
Dark mode colors (when user enables dark mode)

Both modes can have independent color values, and each is edited separately. Behind the scenes your project stores the dark palette in two places—an explicit .dark block and an OS-default @media (prefers-color-scheme: dark) block—and the editor keeps both in sync automatically when you save, so dark mode looks the same whether it’s toggled manually or set by the device.

Troubleshooting

”No Color Tokens Found” Message

This means your project doesn’t have the HelloLeo Design System token structure yet—there are no color tokens for the editor to read. Solution: Click the “Ask Leo to Setup Design System” button, or copy this prompt and send it to Leo:

Please set up the HelloLeo Design System for this project. In src/styles.css, define
oklch color tokens in :root (light), .dark (explicit dark), and a
@media (prefers-color-scheme: dark) { :root { ... } } block (OS default), keeping all
three in sync. Map the raw tokens to Tailwind utilities in an @theme inline block
(--color-primary: var(--primary), etc.) and define --font-sans and --font-display there too.

“No Font Variables Found” Message

This means your project’s @theme inline block doesn’t define font tokens, so there’s nothing for the Typography tab to edit. Solution: Click the “Ask Leo to Setup Design System” button, or send Leo this prompt:

Please add font tokens to the @theme inline block in src/styles.css:
--font-sans for body text and --font-display for headings (use --font-heading if that's
what this project already uses). Also make sure index.html has the Google Fonts <link> in
its <head>.

Colors/Fonts Not Applying

If changes don’t appear in the preview:

Check the CSS structure - The design system needs the raw oklch color tokens in :root, .dark, and the @media (prefers-color-scheme: dark) block
Verify the @theme inline mapping - Tokens must be mapped to utilities via --color-*: var(--*)
Don’t hardcode colors - Components should use utilities like bg-primary, never hardcoded hex values

Fix prompt to share with Leo:

The Design System editor changes aren't applying. Please verify and fix in src/styles.css:
1. :root, .dark, AND @media (prefers-color-scheme: dark) { :root } all define the same
   oklch color tokens (--primary, --background, etc.) and stay in sync
2. An @theme inline block maps each raw token to a utility, e.g. --color-primary: var(--primary)
3. --font-sans and --font-display are defined in @theme inline
4. Components use the utilities (bg-background, text-foreground, etc.) and never hardcode hex

Fonts Not Loading

If fonts don’t appear in the published app:

Google Fonts <link> - index.html <head> must contain a Google Fonts <link>; the editor rewrites that existing link on save but never creates one, so older projects may need it added once
Font token value - Tokens must be in format 'Font Name', fallback and live in the @theme inline block

Fix prompt:

Fonts from the Design System aren't loading. Please ensure index.html has a Google Fonts
<link> in its <head> (preconnect tags + a css2 stylesheet link), and that --font-sans and
--font-display in the @theme inline block of src/styles.css use the format
'Font Name', system-ui, sans-serif.

Shadows Not Working

If shadow changes don’t apply:

CSS variables - Project needs --shadow-sm, --shadow, --shadow-md, --shadow-lg, --shadow-xl, --shadow-2xl
Theme mapping - These must be mapped through the @theme inline block so the shadow utilities pick them up

Fix prompt:

Shadow intensity changes aren't applying. Please add all shadow tokens (--shadow-sm through
--shadow-2xl) to src/styles.css and map them to the shadow utilities via the @theme inline block.

Design System Structure

For reference, here’s what the HelloLeo Design System looks like. Raw tokens are defined three times—:root (light), .dark (explicit dark), and the @media (prefers-color-scheme: dark) block (OS default)—and then mapped to Tailwind utilities in @theme inline. You and Leo edit the raw token (e.g. --primary), never the --color-* mapping, and never hardcode hex in components.

Design tokens (src/styles.css)

@import "tailwindcss";

:root {
  /* Colors (light) */
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* ... more colors ... */

  /* Effects */
  --radius: 0.625rem;
}

/* Explicit dark mode (the `dark` class) */
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --border: oklch(1 0 0 / 10%);
  /* ... mirror every color token ... */
}

/* OS default dark mode — keep identical to .dark */
@media (prefers-color-scheme: dark) {
  :root {
    --background: oklch(0.145 0 0);
    --foreground: oklch(0.985 0 0);
    --primary: oklch(0.922 0 0);
    /* ... mirror every color token ... */
  }
}

/* Map raw tokens to Tailwind utilities, and define fonts */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... more color mappings ... */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-display: "Space Grotesk", "Inter", sans-serif;
}

The body font token is --font-sans; the heading font token is --font-display (older projects use --font-heading). Both font tokens live in the @theme inline block, not in :root.

Font loading (index.html)

Fonts load via a Google Fonts <link> in the <head>. The scaffold ships preconnect tags plus a css2 stylesheet link for the default families, and the editor rewrites this link to match your selected fonts on save.

<head>
  <!-- ... -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
</head>

Workspace Themes

Workspace Themes are available on the Enterprise plan.

Workspace Themes let you define your brand once and apply it across all projects in your workspace. Every new project starts on-brand automatically—no manual setup needed.

How It Works

Open any project in your workspace
Go to Settings > Design
Configure your colors, typography, and effects
Click Save as Workspace Theme

New projects created in the workspace inherit the saved theme automatically.

Managing Workspace Themes

In your workspace settings under the Design tab, you can:

View saved themes - See all themes saved to the workspace
Set a default theme - Choose which theme applies to new projects
Edit a theme - Update an existing theme and push changes across projects

Workspace themes support both light and dark mode—configure both before saving.

Live Preview

See your design changes in real-time

Project Settings

Other project configuration options

Get Started

Features

Prompting Guide

Integrations

Examples & Use Cases

Troubleshooting

How It Works

Using the Design Editor

Accessing the Editor

Colors Tab

Typography Tab

Effects Tab

Saving Changes

Light & Dark Mode

Troubleshooting

”No Color Tokens Found” Message

“No Font Variables Found” Message

Colors/Fonts Not Applying

Fonts Not Loading

Shadows Not Working

Design System Structure

Design tokens (src/styles.css)

Font loading (index.html)

Workspace Themes

How It Works

Managing Workspace Themes

Live Preview

Project Settings

​How It Works

​Using the Design Editor

​Accessing the Editor

​Colors Tab

​Typography Tab

​Effects Tab

​Saving Changes

​Light & Dark Mode

​Troubleshooting

​”No Color Tokens Found” Message

​“No Font Variables Found” Message

​Colors/Fonts Not Applying

​Fonts Not Loading

​Shadows Not Working

​Design System Structure

​Design tokens (src/styles.css)

​Font loading (index.html)

​Workspace Themes

​How It Works

​Managing Workspace Themes

Live Preview

Project Settings

How It Works

Using the Design Editor

Accessing the Editor

Colors Tab

Typography Tab

Effects Tab

Saving Changes

Light & Dark Mode

Troubleshooting

”No Color Tokens Found” Message

“No Font Variables Found” Message

Colors/Fonts Not Applying

Fonts Not Loading

Shadows Not Working

Design System Structure

Design tokens (src/styles.css)

Font loading (index.html)

Workspace Themes

How It Works

Managing Workspace Themes