theming

1---2name: theming3description:4  Use when an app uses @pierre/theming to list, resolve, select, switch,5  persist, or apply themes, including color modes, theme controllers, React6  state, UI colors, and bundled Pierre or Shiki collections.7---8 9# `@pierre/theming`10 11Use `@pierre/theming` to manage runtime themes. The package separates theme12metadata, theme resolution, selected state, and UI color mapping.13 14## Install15 16```bash17pnpm add @pierre/theming18```19 20Install optional peer dependencies only for the selected entry. The React entry21needs `react`. The themes entry needs `@pierre/theme`, `@shikijs/themes`, and22`shiki`.23 24## Select an API reference25 26| Need                                                           | Reference                                    |27| -------------------------------------------------------------- | -------------------------------------------- |28| Create a collection, catalog, descriptor, or bundled theme set | [Collections API](references/collections.md) |29| Register, load, seed, or cache theme objects                   | [Resolver API](references/resolver.md)       |30| Track the color mode and selected light and dark themes        | [Controller API](references/controller.md)   |31| Normalize workbench colors or derive colors                    | [Colors API](references/colors.md)           |32| Read controller state in React                                 | [React API](references/react.md)             |33 34## Select a controller recipe35 36| Situation                                                                    | Recipe                                                                |37| ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |38| One app or page shares one color mode and one light/dark selection           | [Use one controller](references/recipe-one-controller.md)             |39| Independent areas need separate selections or separate controller lifecycles | [Use multiple controllers](references/recipe-multiple-controllers.md) |40 41Use one controller by default. Use multiple controllers only when the theme42state must differ between areas.43 44## Select a framework recipe45 46| Host                                    | Recipe                                                 |47| --------------------------------------- | ------------------------------------------------------ |48| Vanilla JavaScript or another framework | [Use vanilla JavaScript](references/recipe-vanilla.md) |49| React                                   | [Use React](references/recipe-react.md)                |50