137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# 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
|
|
<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
|
|
|
|
1. Add a `[data-theme="<id>"]` 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: '<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'
|
|
|
|
<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 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 `<html data-theme>` uses
|
|
the new value on first paint.
|