# @mwillbanks/tuil-theme

Source: /tuil/docs/reference/packages/theme
Locale: en

Theme tokens, variants, utilities, capabilities, and registries for tuil.



## Overview [#overview]

Theme tokens, variants, utilities, capabilities, and registries for tuil.

`@mwillbanks/tuil-theme` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-theme
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-theme
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-theme
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-theme
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Themes normalize token sets, component defaults, slots, variants, terminal capabilities, and spacing. Registries resolve named themes while `ThemeController` provides live observable switching.

<Mermaid
  chart="flowchart LR
  S0[&#x22;define&#x22;]
  S1[&#x22;normalize&#x22;]
  S2[&#x22;register&#x22;]
  S3[&#x22;resolve&#x22;]
  S4[&#x22;switch&#x22;]
  S5[&#x22;unsubscribe&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4
  S4 --> S5"
/>

## API [#api]

| API                                                                                              | Signature                             | Description                                 |
| ------------------------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------- |
| [`ColorScheme`](/tuil/docs/reference/packages/theme/api/color-scheme)                                 | `type ColorScheme`                    | Public type ColorScheme.                    |
| [`compileUtilities`](/tuil/docs/reference/packages/theme/api/compile-utilities)                       | `function compileUtilities`           | Public function compileUtilities.           |
| [`ComponentTheme`](/tuil/docs/reference/packages/theme/api/component-theme)                           | `interface ComponentTheme`            | Public interface ComponentTheme.            |
| [`createDefaultThemeRegistry`](/tuil/docs/reference/packages/theme/api/create-default-theme-registry) | `function createDefaultThemeRegistry` | Public function createDefaultThemeRegistry. |
| [`createTheme`](/tuil/docs/reference/packages/theme/api/create-theme)                                 | `function createTheme`                | Public function createTheme.                |
| [`defaultLightTheme`](/tuil/docs/reference/packages/theme/api/default-light-theme)                    | `constant defaultLightTheme`          | Public constant defaultLightTheme.          |
| [`defaultTheme`](/tuil/docs/reference/packages/theme/api/default-theme)                               | `constant defaultTheme`               | Public constant defaultTheme.               |
| [`normalizeTheme`](/tuil/docs/reference/packages/theme/api/normalize-theme)                           | `function normalizeTheme`             | Public function normalizeTheme.             |
| [`resolveComponentProps`](/tuil/docs/reference/packages/theme/api/resolve-component-props)            | `function resolveComponentProps`      | Public function resolveComponentProps.      |
| [`resolveSlotProps`](/tuil/docs/reference/packages/theme/api/resolve-slot-props)                      | `function resolveSlotProps`           | Public function resolveSlotProps.           |
| [`SemanticColor`](/tuil/docs/reference/packages/theme/api/semantic-color)                             | `interface SemanticColor`             | Public interface SemanticColor.             |
| [`SlotComponents`](/tuil/docs/reference/packages/theme/api/slot-components)                           | `type SlotComponents`                 | Public type SlotComponents.                 |
| [`SlotMap`](/tuil/docs/reference/packages/theme/api/slot-map)                                         | `type SlotMap`                        | Public type SlotMap.                        |
| [`SlotPropFactory`](/tuil/docs/reference/packages/theme/api/slot-prop-factory)                        | `type SlotPropFactory`                | Public type SlotPropFactory.                |
| [`SlotProps`](/tuil/docs/reference/packages/theme/api/slot-props)                                     | `type SlotProps`                      | Public type SlotProps.                      |
| [`SlottedComponentProps`](/tuil/docs/reference/packages/theme/api/slotted-component-props)            | `interface SlottedComponentProps`     | Public interface SlottedComponentProps.     |
| [`SpacingToken`](/tuil/docs/reference/packages/theme/api/spacing-token)                               | `type SpacingToken`                   | Public type SpacingToken.                   |
| [`TerminalStyleProps`](/tuil/docs/reference/packages/theme/api/terminal-style-props)                  | `type TerminalStyleProps`             | Public type TerminalStyleProps.             |
| [`Theme`](/tuil/docs/reference/packages/theme/api/theme)                                              | `interface Theme`                     | Public interface Theme.                     |
| [`ThemeController`](/tuil/docs/reference/packages/theme/api/theme-controller)                         | `class ThemeController`               | Public class ThemeController.               |
| [`ThemeFactory`](/tuil/docs/reference/packages/theme/api/theme-factory)                               | `type ThemeFactory`                   | Public type ThemeFactory.                   |
| [`ThemeInput`](/tuil/docs/reference/packages/theme/api/theme-input)                                   | `type ThemeInput`                     | Public type ThemeInput.                     |
| [`ThemeProvider`](/tuil/docs/reference/packages/theme/api/theme-provider)                             | `function ThemeProvider`              | Public function ThemeProvider.              |
| [`ThemeRegistry`](/tuil/docs/reference/packages/theme/api/theme-registry)                             | `class ThemeRegistry`                 | Public class ThemeRegistry.                 |
| [`ThemeRegistryEntry`](/tuil/docs/reference/packages/theme/api/theme-registry-entry)                  | `interface ThemeRegistryEntry`        | Public interface ThemeRegistryEntry.        |
| [`useTheme`](/tuil/docs/reference/packages/theme/api/use-theme)                                       | `function useTheme`                   | Public function useTheme.                   |

## Events and lifecycle [#events-and-lifecycle]

Theme changes use `ThemeController.subscribe()` so React consumers remain consistent with `useSyncExternalStore`.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { createDefaultThemeRegistry } from "@mwillbanks/tuil-theme";

const themes = createDefaultThemeRegistry();
app.themeController.set(themes.resolve("default-light"));
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)