> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloleo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Design System
> Customize your project's visual theme with the visual editor
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
1. Open your project in HelloLeo
2. Click **Settings** in the top navigation bar
3. 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 `` 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 `` 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 in
its .
```
### Colors/Fonts Not Applying
If changes don't appear in the preview:
1. **Check the CSS structure** - The design system needs the raw `oklch` color tokens in `:root`, `.dark`, and the `@media (prefers-color-scheme: dark)` block
2. **Verify the `@theme inline` mapping** - Tokens must be mapped to utilities via `--color-*: var(--*)`
3. **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:
1. **Google Fonts ``** - `index.html` `` must contain a Google Fonts ``; the editor rewrites that existing link on save but never creates one, so older projects may need it added once
2. **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
in its (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:
1. **CSS variables** - Project needs `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`
2. **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)
```css theme={null}
@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 `` in the ``. 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.
```html theme={null}
```
## 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
1. Open any project in your workspace
2. Go to **Settings > Design**
3. Configure your colors, typography, and effects
4. 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.
See your design changes in real-time
Other project configuration options
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
1. Open any project in your workspace
2. Go to **Settings > Design**
3. Configure your colors, typography, and effects
4. 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.