> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/the-building-blocks/themes.md).

# Themes

A Buzzy theme is the app-wide design system used by generated screens, manually edited screens, and widgets.

Themes are more than a color picker. A theme includes visual identity, brand settings, dark or light mode, design guidelines, and UI tokens that screen builders use when laying out forms, lists, dashboards, buttons, navigation, and custom surfaces.

## What a Theme Controls

| Theme area          | What it affects                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------- |
| Visual identity     | Overall style, design inspiration, tone of voice, and imagery direction.                      |
| Brand               | App icon and cover-image direction.                                                           |
| Mode                | Light or dark mode behavior.                                                                  |
| Colors              | Brand, semantic, text, background, surface, link, success, warning, danger, and info colors.  |
| Typography          | Font families, base size, line height, headings, labels, and reading rhythm.                  |
| Radius              | Corner treatment for buttons, cards, fields, modals, and panels.                              |
| Borders and shadows | How screens communicate depth, grouping, and separation.                                      |
| Design guidelines   | A markdown design-direction artifact that future screen builders and AI agents should follow. |

```mermaid
flowchart TD
    T["Theme"] --> V["Visual Identity<br/>style, voice, imagery"]
    T --> C["Tokens<br/>colors, type, radius, borders, shadows"]
    T --> D["Design Guidelines<br/>screen-building rules"]
    T --> S["Screens<br/>lists, forms, dashboards, navigation"]
    T --> W["Widgets<br/>native and custom surfaces"]
```

## How Themes Fit into the Build Flow

Themes are generated after the brief, flows, and data model are understood, and before detailed screen generation.

That order matters:

* The brief explains the product posture and audience.
* Flows explain the kind of experience users need.
* The data model explains the density and type of information screens must handle.
* The theme defines the visual language before screens are built.
* The blueprint and screens then use the theme when choosing layout density, surface treatment, and hierarchy.

In Builder MCP workflows, the accepted theme becomes part of the downstream source of truth. If the app changes audience or brand direction, update the theme before doing heavy screen refinement.

## Default Themes and Customization

Buzzy includes default theme bases such as neutral, slate, stone, zen, fashion, and air-style directions. A generated app can start from the most appropriate default and then customize:

* primary and accent colors
* background and surface colors
* font families and text hierarchy
* corner radius
* border and shadow strategy
* dark mode
* imagery direction
* design-guideline markdown

Theme changes apply globally, so they are usually more efficient than editing every screen one by one.

## Themes and Widgets

Widgets should feel like part of the app.

Native widgets can inherit the app theme directly. Code widgets should also respect the app's theme classes and tokens where possible, especially for colors, typography, spacing, border radius, and background treatment.

Use a Buzzy Function for secrets or server-side provider calls. Do not hardcode API keys or privileged logic inside theme-aware widget code.

## Good Theme Hygiene

* Use the theme for app-wide visual decisions.
* Keep one coherent radius, border, and shadow language.
* Make primary actions visually obvious.
* Match interface density to the app type: operational tools should be scannable; discovery apps can be more image-led.
* Keep design-guideline markdown aligned with the actual theme values.
* Review desktop and mobile screens after changing the theme.
* Check widgets after changing theme mode, surface colors, or typography.

## Related Pages

* [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint.md)
* [Toolkits, Cookbooks & Widgets](/the-building-blocks/toolkits-and-cookbooks.md)
* [Code widget](/the-building-blocks/code-widget-custom-code.md)
* [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp.md)
* [Working with themes](/getting-started-with-buzzy/new-buzzy-ai-v3/7.-working-with-themes.md)