Token Designer

The Token Designer is a visual editor for your site's design tokens. It generates a Tailwind v4 theme.css file that defines colors, typography, spacing, border radius, and shadows for your Astro site. Every change updates a live preview so you can see exactly how your site will look.

Opening the Token Designer

Click the Palette icon in the header toolbar to open the Token Designer modal.

Layout

The Token Designer uses a two-panel layout:

Quick-jump buttons at the top let you scroll directly to Colors, Typography, or Spacing.

AI Theme Generation

At the top of the editor panel, a prompt box lets you describe the theme you want. Type a description like "Modern SaaS theme with teal and coral accents" and click Generate. The AI produces a full color palette (light and dark), and recommends a font pairing.

AI generation uses your configured API key (Anthropic, OpenAI, or Google -- checked in that order). If no key is available, it falls back to keyword-based generation.

Preset Themes

Below the AI box, a grid of 18 preset themes gives you a one-click starting point.

Dark Presets

Light Presets

Ocean Blue, Forest, Sunset, Purple Haze, Rose Gold, Coral Reef, Mint Fresh, Lavender, Amber Glow, Steel, Cherry, Electric.

Click any preset to apply its colors immediately. Dark presets also set appropriate surface and content colors and disable the dark mode variant since the theme is already dark. Light presets reset surface and content colors to default light values.

Colors

Expand the Colors section (palette icon) to edit every color token in your theme. There are 20 tokens organized into groups.

Color Groups

Click any color swatch to open a color picker. Each token shows its corresponding Tailwind utility classes (e.g., bg-primary, text-primary).

Light and Dark Mode

A toggle at the top of the Colors section lets you switch between editing Light and Dark color sets. Each mode has its own full set of color tokens.

Dark Mode Strategy

Choose how dark mode is activated:

Typography

Expand the Typography section (type icon) to configure fonts for your site.

Font Selection

Each dropdown lists available fonts. Fonts you have installed via the Font Manager appear at the top of the dropdown under an "Installed Fonts" heading. Below that, a set of default options is always available: Inter, Space Grotesk, Plus Jakarta Sans, DM Sans, Outfit, Sora, Manrope, JetBrains Mono, and Fira Code.

Installing Fonts First

To install and activate a custom font:

1. Open the Font Manager -- click the T icon in the toolbar
2. Browse or search for a font
3. Select weights and click Add to Project
4. Close the Font Manager
5. Open the Token Designer -- your installed font now appears at the top of the dropdowns

See the Font Manager documentation for full details on browsing, previewing, and installing fonts.

Custom Fonts Toggle

By default, all text uses the Body Font. Enable Use different fonts for headings and code to unlock the Heading Font and Code Font dropdowns. This lets you create typographic contrast -- for example, a display font for headings paired with a clean sans-serif for body text.

Font Size Scale

The Typography section also shows a read-only preview of the font size scale:

These are Tailwind defaults. Use standard Tailwind classes like text-sm, text-lg, text-2xl in your components.

Font Preview

The live preview on the right panel loads your selected fonts from Google Fonts CDN so you can see accurate rendering as you experiment.

Spacing and Border Radius

Expand the Spacing & Radius section (box icon) to view the spacing and border radius scales.

Spacing Scale

Visual bars show the relative sizes. Spacing tokens use --space-* to avoid conflicts with Tailwind's built-in --spacing-* variables.

Border Radius

Visual squares demonstrate each radius value.

Note: Spacing and radius are Tailwind defaults shown for reference. Use standard Tailwind utilities like p-4, gap-6, rounded-lg directly in your code.

Saved Themes and Import/Export

Expand the Saved Themes & Import/Export section to manage your theme presets.

Saving a Theme

1. Click Save Current Theme
2. Enter a name
3. The theme is saved to your browser's local storage

Saved themes store all color tokens (both light and dark). Load or delete saved themes from the list.

Exporting Colors

Click Export Colors to copy your color tokens as JSON to the clipboard. The format includes both light and dark color sets.

Importing a Theme

Click Import Theme and paste either:

• CSS containing --color-* custom properties
• JSON from a previous export

The Token Designer parses the input and applies the colors.

Note: Saved themes are stored in your browser's local storage, not in the Codespace. They persist across sessions on the same browser but are not shared between devices.

Live Preview

The right panel shows a simulated browser frame with a full sample page. It includes:

• Navigation bar
• Hero section with badge
• Stats row
• User card
• Form fields
• Alert notification
• Tags
• Price card
• Footer

Every element uses your actual color tokens and font selections. The preview updates in real-time as you make changes -- no need to save or refresh.

Applying Your Theme

When you're satisfied with your design, click Apply Theme in the footer. This does two things:

1. Writes src/styles/theme.css -- Your design tokens are saved as Tailwind v4 @theme CSS variables
2. Updates font imports -- The correct @fontsource import statements are added to BaseLayout.astro, and any old font imports are removed

Generated CSS

The output is a Tailwind v4 theme file:

@theme {
    --color-primary: #6366f1;
    --color-primary-dark: #4f46e5;
    --color-primary-light: #818cf8;
    /* ... all color tokens ... */

    --font-sans: "Inter", system-ui, sans-serif;
    --font-heading: "Inter", system-ui, sans-serif;
    --font-mono: "JetBrains Mono", monospace;

    /* spacing, radius, shadows */
}

/* Dark mode (if enabled) */
.dark {
    --color-primary: #818cf8;
    /* ... dark color overrides ... */
}

This creates Tailwind utility classes like bg-primary, text-content, border-outline, font-heading that you can use throughout your Astro components.

Using Tokens in Components

<section class="bg-surface p-8">
    <h2 class="font-heading text-3xl text-content">Welcome</h2>
    <p class="font-sans text-content-light">Body text with lighter color.</p>
    <button class="bg-primary text-white rounded-lg px-4 py-2 cursor-pointer hover:bg-primary-dark">
        Get Started
    </button>
</section>

Footer Actions

The modal footer provides additional actions:

Workflow Summary

A typical workflow for setting up your site's design:

1. Install fonts -- Open the Font Manager, browse fonts, and install the ones you want
2. Open Token Designer -- Click the palette icon in the toolbar
3. Pick a starting point -- Use a preset theme, generate one with AI, or start from scratch
4. Customize colors -- Adjust primary, secondary, accent, surface, and content colors
5. Set up dark mode -- Choose a strategy and edit the dark color set
6. Configure typography -- Select your installed fonts for body, headings, and code
7. Preview -- Check the live preview to make sure everything looks right
8. Apply -- Click Apply Theme to write the CSS and font imports to your project

Existing Theme Detection

If your project already has a theme.css file, the Token Designer parses it on open. It extracts existing color variables, font selections, and dark mode configuration so you can continue editing where you left off.

Troubleshooting

Theme Not Applying

If your colors or fonts don't appear after clicking Apply Theme:

1. Check that src/styles/theme.css was created (look in the file tree)
2. Verify that theme.css is imported in your main layout
3. Save and wait for hot reload
4. Hard-refresh the preview if needed

Font Not Showing in Dropdown

If an installed font doesn't appear in the Typography dropdowns:

1. Make sure the font was installed via the Font Manager (not manually)
2. Check that the Codespace is running
3. Try closing and reopening the Token Designer

Dark Mode Not Working

1. Verify your dark mode strategy is set (class-based or media query)
2. For class-based: ensure your JavaScript toggles the .dark class on <html>
3. For media query: check your system's dark mode setting
4. Inspect the generated CSS to confirm the dark block exists

Colors Look Wrong in Preview

1. Make sure you're editing the correct mode (light vs dark)
2. Check for conflicting CSS in other stylesheets
3. Try resetting to defaults and reapplying

Next Steps

• Font Manager -- Install fonts before using them in Typography
• Component Library -- Sections that use your design tokens
• Visual Editor -- Edit elements with a visual interface
• AI Assistant -- Get help refining your design