freshyo/docs/theme-system.md
2026-10-28 00:11:50 +05:30

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.