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.
• For WeChat mini programs, TDesign mini program, uni-app, .wxss, app.json, or theme.json, read references/miniprogram.md.
• For HarmonyOS ArkTS, Flutter, native app resources, or app-wide theme abstractions, read 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.