4.3 KiB
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:
@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:
// apps/web-ui/src/theme.config.ts
import type { ThemeId } from 'web-components'
export const ACTIVE_THEME: ThemeId = 'freshyo'
// apps/admin-web/src/theme.config.ts
import type { ThemeId } from 'web-components'
export const ACTIVE_THEME: ThemeId = 'freshyo'
The root renders it directly:
<html lang="en" data-theme={ACTIVE_THEME}>
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
- Add a
[data-theme="<id>"]block topackages/web-components/theme.cssoverriding the roles you want (--theme-brand-*,--theme-flash-*,--theme-accent-*, neutrals, semantic surface/text). - Add
{ id: '<id>', label: '...' }toTHEMESinpackages/web-components/src/theme/themes.ts. - Change
ACTIVE_THEMEin 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:
@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:
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:
import { colors, withAlpha } from 'web-components'
<Icon color={colors.brand600} />
<div style={{ backgroundColor: withAlpha(colors.brand600, 8) }} />
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 typecheckin both appsnpm run buildin both apps- Change a token in
theme.cssand confirm both apps update without any app CSS edits. - Change
ACTIVE_THEMEand confirm the server-rendered<html data-theme>uses the new value on first paint.