# Theme Tokenization

> Implement or refactor light/dark theme support and design-token based styling across web apps, WeChat/uni-app mini programs, HarmonyOS ArkTS, Flutter, and other apps. Use when the user asks for 样式 token 化, 设计 token, 统一字体/颜色/间距/圆角/阴影, 支持明暗主题, dark mode, light mode, color mode, CSS variables, Tailwind/Ant Design/TDesign theme mapping, theme.json/app.wxss, ArkTS resources, ThemeData, or migration of hard-coded styles to shared tokens.

- Skill: `herongdev/theme-tokenization` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add herongdev/theme-tokenization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/herongdev/theme-tokenization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: herongdev (https://skillmd.com/u/herongdev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/herongdev/theme-tokenization

---


# Theme Tokenization

## Purpose

Turn scattered styling into a platform-appropriate token system with reliable light/dark support. Prefer semantic tokens that describe intent (`surface`, `text-muted`, `primary-soft`) over raw palette names, then wire every UI layer to consume those tokens.

## Routing

- For React, Next.js, Nuxt, Vue, Vite, Tailwind, Ant Design, plain CSS, or CSS variables, read [references/web.md](references/web.md).
- For WeChat mini programs, TDesign mini program, uni-app, `.wxss`, `app.json`, or `theme.json`, read [references/miniprogram.md](references/miniprogram.md).
- For HarmonyOS ArkTS, Flutter, native app resources, or app-wide theme abstractions, read [references/app.md](references/app.md).
- For multi-platform repos, read every relevant reference and keep token names semantically aligned across platforms even when units and implementation files differ.

## Workflow

1. Discover the existing styling system before editing.
   Search for `theme`, `dark`, `light`, `token`, `tokens`, `colors`, `spacing`, `font`, `radius`, `--*`, `var(`, `ThemeData`, `$r('app.color`, `theme.json`, `app.wxss`, `tailwind`, `ConfigProvider`, `TDesign`, and component-library theme files. Identify current prefixes and naming before adding new ones.

2. Define the token contract.
   Use a compact semantic set: brand/primary, primary-soft, page/background, surface, surface-muted/elevated, text, text-secondary, text-muted/placeholder/disabled, text-inverse, border, success, warning, danger/error, info, overlay, shadow, spacing scale, radius scale, font family, font size, line height, and font weight.

3. Choose one source of truth per platform.
   Web can use CSS variables plus a TS/JS token object when component libraries need runtime values. Mini programs use global `.wxss` variables plus `theme.json` for shell values. HarmonyOS uses `resources/base` and `resources/dark` with matching resource names. Flutter uses `ThemeData`, `ColorScheme`, and `ThemeExtension` or `AppTokens`.

   For large multi-platform design systems, consider an existing token build pipeline or a Style Dictionary-style generator that emits CSS, JS, Android/iOS, Flutter, and other artifacts. Do not introduce a generator for a small app unless the repo already has one or the user asks for cross-platform token generation.

4. Wire theme selection.
   Support system preference by default. Add manual switching only when the product already has or clearly needs a toggle. Keep browser `color-scheme`, meta/theme-color, mini program navigation text, and app status/navigation bars in sync with the current theme.

5. Migrate usage.
   Replace hard-coded colors, fonts, spacing, radii, shadows, and component-library defaults with token references. Leave truly content-specific media colors alone, but move reusable overlays, scrims, badge tones, and chart/status colors into tokens.

6. Verify both themes.
   Run available typecheck/build/lint. Grep for remaining hard-coded styles. Open or screenshot light and dark screens when a frontend is involved. Check nav/status bars, tab bars, modals, empty/loading/error states, icons, borders, shadows, and disabled states.

## Rules

- Preserve the repo's established prefix and style. If the repo already uses `--ms-*`, `--app-*`, `$r('app.color.*')`, or `AppTheme`, extend that vocabulary instead of inventing a parallel system.
- Prefer semantic token usage in components. Raw palette steps are allowed inside token files, not in page/component code.
- Keep light and dark token names identical. Only values should differ.
- Avoid one-off dark-mode patches. If a page needs dark support, first ensure its foundations are tokenized.
- Map third-party component libraries to app tokens rather than styling each instance.
- Use platform units naturally: `px/rem` or CSS variables on web, `rpx` in mini programs, `vp/fp` resources in ArkTS, logical pixels and text styles in Flutter.
- Keep accessibility in view: text and icon colors must maintain contrast on both light and dark surfaces.

## Completion Checklist

- Token source files exist for color, type, spacing, radius, and core shadows.
- Light/dark values are present for semantic color tokens.
- Global app shell consumes theme tokens: body/page, navigation, tab bar, modals/drawers, component library theme, status/navigation bar where applicable.
- Components use token references, not scattered hex/RGBA values.
- Build/typecheck/lint or platform preview has been run when available.
- Residual hard-coded style values are either removed or intentionally documented in the final response.