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

# Themes

Extensions can contribute custom themes **data-driven** (JSON in manifest) or **code-driven** (renderer bundle). Data-driven themes work for all installed extensions; code-driven themes require trust.

## Data-Driven Themes (Manifest)

Declared in `manifest.json` → `contributes.themes[]`. Registered at boot via `bootstrapExtensions.ts`.

```json
{
  "contributes": {
    "themes": [
      {
        "id": "sakura-dark",
        "name": "Sakura Dark",
        "colors": {
          "--primary": "340 82% 65%",
          "--primary-foreground": "340 5% 95%",
          "--secondary": "320 70% 55%",
          "--accent": "350 90% 70%",
          "--background": "340 15% 5%",
          "--foreground": "340 5% 95%",
          "--card": "340 12% 8%",
          "--card-foreground": "340 5% 95%",
          "--muted": "340 10% 15%",
          "--muted-foreground": "340 5% 65%",
          "--border": "340 10% 20%",
          "--ring": "340 82% 65%"
        },
        "info": {
          "label": "Sakura",
          "description": "Cherry blossom dark theme",
          "accent": "350 90% 70%",
          "gradient": "from-pink-500 via-rose-500 to-fuchsia-600",
          "icon": "🌸",
          "category": "dark"
        }
      }
    ]
  }
}
```

### Color Format

**HSL strings** (without `hsl()` wrapper): `"340 82% 65%"`

Keys map to CSS custom properties. The `--` prefix is optional (stripped at apply time):

| Key                 | CSS Variable           | Description                   |
| ------------------- | ---------------------- | ----------------------------- |
| `primary`           | `--primary`            | Main brand color              |
| `primaryForeground` | `--primary-foreground` | Text on primary               |
| `secondary`         | `--secondary`          | Complementary                 |
| `accent`            | `--accent`             | High-impact highlights        |
| `background`        | `--background`         | Page background               |
| `foreground`        | `--foreground`         | Primary text                  |
| `card`              | `--card`               | Panel/surface background      |
| `cardForeground`    | `--card-foreground`    | Text on card                  |
| `muted`             | `--muted`              | Inactive/secondary background |
| `mutedForeground`   | `--muted-foreground`   | Muted text                    |
| `border`            | `--border`             | Border color                  |
| `ring`              | `--ring`               | Focus ring                    |

### Registration

```ts
// bootstrapExtensions.ts
function registerContributedTheme(extensionId: string, theme: ContributedTheme) {
  const registered: RegisteredTheme = {
    id: `${extensionId}:${theme.id}`,        // Namespaced
    name: theme.name || theme.id,
    colors: theme.colors,                    // Written as CSS custom properties
    info: theme.info,
    extensionId,
  };
  extensionRegistry.registerTheme(registered);
}
```

### Theme Switcher

Themes appear in Settings → Appearance → Themes. User selection persists in `settings.theme`.

## Code-Driven Themes (Renderer)

For dynamic themes (time-based, reactive, animated), contribute via renderer bundle:

```ts
// renderer.js
export async function activate(ctx) {
  ctx.registry.registerTheme({
    id: `${ctx.extensionId}:dynamic-sakura`,
    name: 'Dynamic Sakura',
    colors: computeColorsBasedOnTime(), // Can be updated reactively
    info: { label: 'Sakura', category: 'dark' },
    extensionId: ctx.extensionId,
  });

  // Optional: reactive updates
  setInterval(() => {
    ctx.registry.registerTheme({
      id: `${ctx.extensionId}:dynamic-sakura`,
      name: 'Dynamic Sakura',
      colors: computeColorsBasedOnTime(),
      extensionId: ctx.extensionId,
    });
  }, 60000);
}
```

{% hint style="warning" %}
**Trust-gated:** Only loads for trusted extensions.
{% endhint %}

## Theme Application

When user selects a theme:

{% stepper %}
{% step %}

## Apply CSS custom properties

CSS custom properties are applied to `:root` (or `[data-theme="..."]`).
{% endstep %}

{% step %}

## Respect Tailwind dark mode

Tailwind `dark:` variant respects `--background`/`--foreground`.
{% endstep %}

{% step %}

## Apply glassmorphism styles

Glassmorphism panels use `--card` + `--glass-border` + `backdrop-blur`.
{% endstep %}

{% step %}

## Apply glow styles

Glows use `--glow-primary` (defaults to `--primary`).
{% endstep %}
{% endstepper %}

```css
/* Global application */
:root {
  --primary: 340 82% 65%;
  --background: 340 15% 5%;
  /* ... */
}

[data-theme="tatakai.extension.mycustom:sakura-dark"] {
  --primary: 340 82% 65%;
  --background: 340 15% 5%;
  /* ... */
}
```

## Testing Checklist

* [ ] All 12 core color tokens provided
* [ ] HSL format (space-separated, no `hsl()`)
* [ ] `info.category` set to `"dark"` or `"light"`
* [ ] Theme appears in switcher with correct label
* [ ] Switching applies instantly (no reload)
* [ ] Glass panels, glows, borders use theme colors
* [ ] Code-driven theme updates reactively
* [ ] Namespaced ID prevents collisions

## Related

* [Extension Overview](/extensions/extension-overview.md)
* [Manifest Reference](/extensions/extension-manifest.md)
* [Design system](/technical-reference/design-system.md)
* [Analytics Capability](/extensions/extension-capabilities/analytics-capability.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tatakai.me/extensions/extension-capabilities/themes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.