# Style Studio

Use AI to generate custom themes and CSS for your chatbot interface.

---

Style Studio is a full-screen design environment inside the app builder where you can customize the look and feel of your chatbot's interface using AI or manual CSS. Describe what you want in plain English and the AI generates a complete theme -- colors, typography, bubble shapes, animations, and more.

## How It Works

Style Studio pairs a live chat preview with the Alchemist AI assistant. You describe the visual style you want, and the AI generates CSS that targets over 50 custom properties controlling every visual aspect of the chat interface.

```
You: "Make it look like a premium fintech app with dark mode, sharp corners, and a monospace font"
    |
AI generates CSS targeting:
  --chat-font-family, --chat-bubble-radius, --chat-user-bubble-bg,
  --chat-assistant-bubble-bg, --chat-input-bg, --chat-send-btn-bg, ...
    |
Live preview updates instantly
```

The AI sees a **sprite sheet** of all chat UI elements (welcome screen, user messages, assistant messages with markdown, tool cards, web sources, image generation, voice, error states, typing indicators, input area, and standalone tools) so it understands exactly what it is styling. This visual context means the AI can make informed decisions about color contrast, spacing, and typography across every element type.

## Getting Started


  **1.** 
    <strong>Open Style Studio</strong>

    Navigate to your app in the builder and click the **Style** tab.
  


  **2.** 
    <strong>Describe your style</strong>

    Open the Alchemist panel and describe the look you want. Be specific about colors, typography, mood, or reference a brand. Examples:

    - "Minimal and clean with lots of whitespace, soft grays, and Inter font"
    - "Bold and playful with rounded bubbles, bright gradients, and a comic book feel"
    - "Match our brand: navy blue (#1a237e), gold accents, serif headings"
  


  **3.** 
    <strong>Iterate</strong>

    The Alchemist supports multi-turn conversation. Ask for changes:

    - "Make the user bubbles more rounded"
    - "Switch to a darker background"
    - "Add a subtle glow to the send button"

    Each iteration builds on the previous CSS, so changes are cumulative.
  


  **4.** 
    <strong>Save</strong>

    Changes auto-save after 1.5 seconds of inactivity. The CSS, animation config, and welcome background preset are all persisted automatically.
  


## What You Can Customize

Style Studio controls the entire chat interface through CSS custom properties. Here are the major categories:

| Category | Properties | Examples |
|----------|-----------|----------|
| **Typography** | `--chat-font-family`, `--chat-font-size` | Google Fonts, system fonts, size scaling |
| **User bubbles** | `--chat-user-bubble-bg`, `--chat-user-bubble-color`, radius, padding, border, shadow | Gradients, solid colors, rounded or sharp corners |
| **Assistant bubbles** | `--chat-assistant-bubble-bg`, `--chat-assistant-bubble-color`, radius, padding, border, shadow | Independent styling from user bubbles |
| **Input area** | `--chat-input-bg`, `--chat-input-color`, `--chat-input-radius`, `--chat-input-area-bg` | Footer background, input field styling |
| **Send button** | `--chat-send-btn-bg`, `--chat-send-btn-color`, `--chat-send-btn-radius`, size, shadow | Circle, rounded square, custom colors |
| **Code blocks** | `--chat-code-bg`, `--chat-code-color`, syntax highlighting variables | Dark/light code themes, custom syntax colors |
| **Welcome screen** | Background preset selection | Retro grid, aurora, particles, gradient flow, mesh gradient |

## Animation Config

The AI can also recommend streaming text animation settings alongside the CSS. These control how new text appears during AI responses:

| Setting | Options | Description |
|---------|---------|-------------|
| **Type** | fade, blur, slideUp, slideDown | How tokens appear |
| **Duration** | 50-500ms | Speed of the animation |
| **Tokenize** | word, char | Animate by word or by character |

Animation settings appear as a metadata badge in the Style Studio when the AI recommends them. They are saved to your app's capabilities automatically.

## Welcome Background Presets

The AI can suggest a background animation for your chatbot's welcome screen. Available presets:

- **Retro Grid** -- Perspective grid lines that recede into the distance
- **Aurora** -- Soft, shifting aurora borealis gradients
- **Particles** -- Floating particle field
- **Gradient Flow** -- Smooth flowing color gradients
- **Mesh Gradient** -- Organic mesh gradient blobs

## CSS Security and Scoping

Custom CSS goes through two safety layers before it reaches the browser:

### Sanitization

All CSS is sanitized to remove potentially dangerous patterns:

- `@import` directives (prevents loading external stylesheets)
- `javascript:` URLs, `expression()`, and `behavior:` (legacy XSS vectors)
- Event handler attributes and script tags
- Non-image data URIs (data:image/* is allowed for backgrounds)
- External URLs not on the Google Fonts allowlist

### Scoping

Every CSS rule is automatically prefixed with `[data-app-id="<your-app-id>"]` so your custom styles only affect your chatbot. This means:

- Your CSS cannot leak into the host page when embedded as a widget
- Multiple chatbots on the same page cannot interfere with each other
- `@keyframes` and `@font-face` declarations are left global (they need to be)
- `@media` and `@supports` queries have their inner selectors scoped

> **Note:** You never need to write the scoping selector yourself. Write CSS as if your rules are already inside the chat container, and the scoper handles the rest.

## Layout Archetypes

The AI uses five layout archetypes when generating styles:

1. **Conversational** -- Traditional chat bubbles, rounded corners, alternating alignment
2. **Document-style** -- Full-width assistant messages, minimal borders, reading-focused
3. **Outlined/Card** -- Visible borders, card-like bubbles, structured feel
4. **Hybrid** -- Mix of conversational user bubbles with document-style assistant responses
5. **Symmetric** -- Both sides centered, uniform styling, minimal visual hierarchy

The AI chooses the archetype based on keywords in your description and can switch between them on request.

## Google Fonts

The AI has access to a curated list of Google Fonts and will include `@font-face` declarations in the generated CSS. Fonts are loaded from `fonts.googleapis.com` and `fonts.gstatic.com`, which are the only external domains allowed in custom CSS.

> **Warning:** The AI avoids using display or decorative fonts (like Playfair Display or DM Serif Display) as the primary chat font. These fonts are designed for headings, not long-form reading, and cause readability issues in chat interfaces.

## Tips for Better Results

1. **Be specific about mood**: "Professional and trustworthy" gives better results than "make it look good"
2. **Reference brands**: "Style it like Linear" or "Apple-inspired minimal" gives the AI strong direction
3. **Provide hex codes**: If you have brand colors, include them directly
4. **Iterate incrementally**: Start with a broad direction, then refine details
5. **Ask about dark mode**: The AI can generate styles that work well in both light and dark modes

## How It Integrates

Custom CSS from Style Studio is saved to your app's `customCss` field. When a consumer loads your chatbot:

1. The CSS is sanitized and scoped server-side
2. A `<style>` tag is injected with the scoped rules
3. Google Fonts are loaded via standard `@font-face` declarations
4. Animation config is applied to the streaming text renderer

This works everywhere your chatbot appears -- the standalone page, embedded widget, and custom domains.