# Shared web theme system Both `apps/web-ui` and `apps/admin-web` get every color from one place, and each app selects its theme in one place: ``` apps/web-ui/src/theme.config.ts # ACTIVE_THEME for web-ui apps/admin-web/src/theme.config.ts # ACTIVE_THEME for admin-web packages/web-components/theme.css # Tailwind tokens + theme values packages/web-components/src/theme/colors.ts # JS color map packages/web-components/src/theme/themes.ts # registered theme IDs ``` The app stylesheets only import the shared CSS and keep layout/base rules: ```css @import "tailwindcss"; @import "web-components/theme.css"; @source "../../../packages/web-components/src"; ``` Do **not** add `@theme` blocks or literal colors to either app stylesheet. ## The theme control Each app owns exactly one constant: ```ts // apps/web-ui/src/theme.config.ts import type { ThemeId } from 'web-components' export const ACTIVE_THEME: ThemeId = 'freshyo' ``` ```ts // apps/admin-web/src/theme.config.ts import type { ThemeId } from 'web-components' export const ACTIVE_THEME: ThemeId = 'freshyo' ``` The root renders it directly: ```tsx ``` Change the constant before deploying. There is no query parameter or localStorage override. ## Current themes Three themes are registered: | ID | Label | Character | | --- | --- | --- | | `freshyo` | Freshyo Blue | The default cool blue. Untouched `:root` palette. | | `jolly` | Jolly Mango | Warm cream paper, burnt-tangerine brand, watermelon flash, mint accent, lagoon-blue info. | | `blush` | Blush Petal | Blush-rose neutrals, rose-quartz brand, raspberry flash, lilac accent, periwinkle-blue info. | Each theme provides neutral/status palettes plus `brand`, `flash`, `accent`, `android`, and `whatsapp`, along with semantic surface/text tokens (`background`, `foreground`, `surface`, `border`, `input`, `muted`, `ring`, `primary`, `success`, `warning`, `danger`, `info`). `android`/`whatsapp` and the status palettes are inherited from the default theme; `jolly` and `blush` re-tint the neutrals, `blue`, `brand`, `flash`, `accent` and the semantic surface roles. ## Adding a theme later 1. Add a `[data-theme=""]` block to `packages/web-components/theme.css` overriding the roles you want (`--theme-brand-*`, `--theme-flash-*`, `--theme-accent-*`, neutrals, semantic surface/text). 2. Add `{ id: '', label: '...' }` to `THEMES` in `packages/web-components/src/theme/themes.ts`. 3. Change `ACTIVE_THEME` in the relevant app (`web-ui`, `admin-web`, or both). TypeScript rejects an `ACTIVE_THEME` value that is not registered in `THEMES`. ## How tokens work `theme.css` defines themeable palettes as CSS variables: ```css @theme static { --color-brand-500: var(--theme-brand-500); --color-gray-500: var(--theme-gray-500); } :root { --theme-brand-500: #2E90FA; --theme-gray-500: oklch(55.1% 0.027 264.364); } ``` Tailwind utilities such as `bg-brand-500`, `text-gray-500`, `border-red-500` compile to `var(--color-*)`, so changing theme variables changes every utility without rebuilding the app. `@theme static` is intentional: it keeps every palette/token in the compiled CSS even when only referenced from TypeScript (`style={{ color: ... }}`). ## Using colors in TypeScript Theme keys are role-based, never hue-based. There is no `blue1`, `pink1`, `gray600`, etc.: a theme may render `brand` as blue, yellow, or anything else. `colorsType` is the union of all available color roles: ```ts import type { colorsType } from 'web-components' const iconColor: colorsType = 'brand600' ``` Each key in `colors.ts` carries a comment showing where that role is used in `web-ui` / `admin-web`. Prefer Tailwind classes. When a JS/icon value is required, use the shared map: ```tsx import { colors, withAlpha } from 'web-components'
``` `withAlpha()` uses `color-mix`, so it works with CSS-variable-backed colors. Do not concatenate a hex alpha suffix onto a color string. ## Verification - `npm run typecheck` in both apps - `npm run build` in both apps - Change a token in `theme.css` and confirm both apps update without any app CSS edits. - Change `ACTIVE_THEME` and confirm the server-rendered `` uses the new value on first paint.