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

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

  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:

@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 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.