| Field | Value |
| --- | --- |
| Version | `3.1.0` |
| Packages | `asheeui` `3.1.0`, `@asheeui/core` `3.1.0`, `@asheeui/web` `2.9.0`, `@asheeui/native` `2.9.0`, `@asheeui/theme` `0.1.1`, `@asheeui/puck` `2.3.1`, `@asheeui/cli` `1.0.1` |
| Previous release | [3.0.0](/releases/3.0.0) |
| Breaking changes | **No.** Existing configurations and selections keep their behaviour. |

3.1 adds the missing half of theming: a product can now let a reader create a palette while the
application runs, without rebuilding the configuration or reaching into a renderer. The palette goes
through the same `extends` resolution, validation and painting as a configured one.

The release also adds the small primitive that makes a theme UI possible, and an optional package that
composes the editing experience.

## Runtime themes

Both providers accept a new controlled prop:

```tsx
<AsheeUIProvider config={config} themes={themes}>
  <App />
</AsheeUIProvider>
```

`themes` is an `ExternalColorConfig`, the same shape as `config.color`. It is merged over the configured
map before resolution, so:

- a runtime theme may extend `light`, `dark`, a configured theme or another runtime theme;
- removing a name removes it from `availableThemes`, the web stylesheet and the device's painter;
- removing a name that overrode a configured theme restores the configured definition;
- a selected theme that disappears falls back to the default and its stored selection is cleared.

`light`, `dark` and `system` are reserved. Retune the built-ins in `config.color`; runtime input is for
the themes the application adds. Names are lowercase slugs, colours are the portable hex/rgb set, and
`extends` must name a declared theme.

The [runtime themes guide](/guides/runtime-themes) covers persistence, the selection race on the web,
and the editor package.

## `ColorSwatch`

`ColorSwatch` is a labelled block of one colour, implemented on both renderers and added to the
umbrella (now **183 names**).

```tsx
import { ColorSwatch } from "asheeui";

<ColorSwatch color="#0ea5e9" label="Ocean primary" />;
```

It paints the colour as data (`style.backgroundColor`) and takes the shared `size` and `radius` names.
A labelled swatch is one image to assistive technology; without a label it is decoration and is hidden.
See [ColorSwatch](/components/data-display/color-swatch).

## `@asheeui/theme`

The optional editing layer is a separate package so an application that does not need a theme UI does
not carry one:

| Component | What it does |
| --- | --- |
| `ColorField` | Hex/rgb input, swatch, presets and validation |
| `ThemeSwitcher` | System, built-in and runtime themes, as a select or cards |
| `ThemeCard` | A palette preview with select/edit/delete actions |
| `ThemeEditor` | Name, slug, base, eight roles, contrast checks and save/apply/delete |
| `ThemeGallery` | Saved themes, a create action and optional starter presets |
| `ContrastBadge` | WCAG ratio and level for a pair of colours |

The package is controlled: the application keeps `themes`, persists them and passes them to the
provider. The editor never calls `setTheme` except through `onApply`.

`0.1.1` adds `THEME_PRESETS` (Ocean, Forest, Sunset, Mono) and the gallery's `presets` /
`onPresetSelect` props, and fixes a native-only defect where a theme card's base badge was rendered as
a text array inside a `View`.

## Reference application

The fitness tracker now persists definitions and selection on both shells: localStorage after hydration
on the web, AsyncStorage before the provider mounts on a device. Its Settings screen uses `ThemeSwitcher`,
`ThemeGallery` and `ThemeEditor` directly. The web implementation keeps a stored runtime selection until
its definition arrives, instead of letting the controller discard it on the first render.

## The release set

| Package | Version | What it contains |
| --- | --- | --- |
| `asheeui` | `3.1.0` | The portable surface, now 183 names |
| `@asheeui/core` | `3.1.0` | Colour parsing, WCAG contrast, runtime validation and the owner-scoped controller |
| `@asheeui/web` | `2.9.0` | `themes`, `ColorSwatch` and the runtime stylesheet path |
| `@asheeui/native` | `2.9.0` | `themes`, `ColorSwatch` and the shared channel parser |
| `@asheeui/theme` | `0.1.1` | The optional editing UI, including starter presets |
| `@asheeui/puck` | `2.3.1` | Unchanged |
| `@asheeui/cli` | `1.0.1` | Unchanged |

Install the editor separately:

```bash
pnpm add @asheeui/theme
```

`asheeui`, `@asheeui/core` and `react` are its peers.