# Theme builder

> Build, verify, and export a browser theme against Chrome's own color math on themes.extension.dev.

Canonical: https://docs.extension.dev/themes
This page as Markdown: https://docs.extension.dev/themes.md
Section: Themes
Siblings: [The editor](https://docs.extension.dev/themes/editor.md) · [Colors](https://docs.extension.dev/themes/colors.md) · [Presets and palettes](https://docs.extension.dev/themes/presets.md) · [Images and tints](https://docs.extension.dev/themes/images.md) · [Import a theme](https://docs.extension.dev/themes/import.md) · [Export and install](https://docs.extension.dev/themes/export.md) · [Firefox preview](https://docs.extension.dev/themes/firefox-preview.md) · [Publish and hand off](https://docs.extension.dev/themes/publish.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# Theme builder

[themes.extension.dev](https://themes.extension.dev) resolves a theme the way
Chrome resolves it and paints the result as you edit. Reach for it when you
want a browser theme without hand-writing a manifest, because a theme ships no
code and no runtime throws when a color sits in the wrong slot.

## Quick start

```text
1. Open themes.extension.dev and pick a preset.
2. Change the frame color and watch the preview repaint.
3. Click Export ZIP.
```

The ZIP is a store-ready Chrome package. What the builder paints is what
Chrome paints.


## How it works

**What you set.** The builder covers the color sections, the tints, the
wallpaper, the presets and a palette generator, listed under Reference. It
warns on accessibility problems as you choose, low contrast between tab text
and frame being the usual one. It also imports an existing theme, so a theme
built elsewhere can be corrected here.

**Exporting.** Five exports are listed under Reference. **Install this
theme** writes files; it does not install. The last step stays yours: open
`chrome://extensions`, turn on Developer mode, click Load unpacked, and
choose the folder. The button appears only in a browser that can write a
folder from a page, which today means Chromium. Elsewhere it is not shown,
and **Export ZIP** is the path.

**Firefox.** The Firefox package carries only the keys Gecko renders, and the
page lists what it dropped. The editor's preview is Chrome; the
[Firefox preview](/themes/firefox-preview) runs a real Firefox in the page
and repaints as you edit.

**Publishing.** **Publish** uploads the theme to your account, then opens an
[/import](/guides/import) URL where you name the repository and choose public
or private. Nothing is created until you confirm there. The upload needs you
signed in, so publishing signed out asks you to sign in first. The upload
carries about 6 MB of images and refuses a theme above that.

From the created project the theme submits to stores like any extension, and
that submission is a separate step you start yourself. See
[Publishing](/publish/overview).

**Verifying one.** The [MCP server](/tools/mcp) ships `extension_theme_verify`,
which checks a theme manifest against the colors Chrome actually paints. The
tool is in the server's `extras` group, which is off unless named: start the
server with `extras` in `--features`, as in `--features=local,platform,extras`. A
regression shows up as a diff rather than as two screenshots someone compares
by eye.

## Reference

| Part | What you set |
| --- | --- |
| Color sections | Frame, toolbar, tabs, and the new tab page |
| Tints | HSL adjustments applied to the buttons, the frame, the inactive frame, and background tabs |
| Wallpaper | Upload the frame and new tab artwork |
| Presets | Complete themes to start from |
| Palette generator | A full palette derived from a seed color |

| Export | What you get |
| --- | --- |
| Install this theme | The unpacked theme folder written to a folder you choose |
| Export ZIP | A store-ready Chrome package |
| Export Firefox ZIP | A separate package, because Firefox themes use a different manifest shape |
| Export manifest.json | The manifest as a file |
| Copy manifest JSON | The same manifest on your clipboard |

| Limit | Value |
| --- | --- |
| Theme name | Required |
| Version | 1 to 4 numbers, each between 0 and 65535 |
| Publish upload | About 6 MB of images |

## When it fails

- **There is no Install button.** The browser cannot write a folder from a
  page. Firefox and Safari do not, so take the ZIP and unzip it yourself.
- **The Chrome ZIP does not load in Firefox.** The manifest shapes differ.
  Export the Firefox ZIP separately, never reuse the Chrome one.
- **The Firefox theme looks nothing like the editor.** The editor's preview
  is Chrome, and the Firefox package drops the keys Gecko cannot render. Open
  the [Firefox preview](/themes/firefox-preview) to see Gecko paint it.
- **The installed theme does not match the builder.** Run
  [`extension_theme_verify`](/tools/mcp/theme-verify) against the manifest,
  on a server started with `extras` in `--features`.
  It renders the manifest through the same resolver and reports what differs;
  the real-pixel check is left for you to confirm in Chrome.
- **Export is blocked.** The theme has no name, or the version is not 1 to 4
  numbers between 0 and 65535. Chrome refuses those manifests, so the builder
  refuses them first.
- **Publish asks for a sign-in.** Building and exporting work signed out. The
  theme is uploaded to your own account, so publishing needs a session before
  anything is uploaded.
- **Publish says the theme is too large.** The upload carries about 6 MB of
  images. Shrink the new tab background or the frame image.
- **The builder flags a contrast warning.** Fix it before shipping. That pair
  of colors is what every tab title renders in.

## Next

- [Import](/guides/import) for what the publish link hands off to
- [Publishing](/publish/overview) for the store submission
- [extension.dev MCP](/tools/mcp) for `extension_theme_verify`, listed with the `extras` group
