Problem
The current color token architecture mixes internal palette values with public-facing semantic tokens, making it unclear which tokens are meant for internal theming and which should be consumed by host apps.
Proposal
Establish a clear two-layer token structure:
-
Internal palette files — define raw color values per theme:
_colors-light.scss — light theme palette_colors-dark.scss — dark theme palette
-
Public token file — _colors.scss exposes named semantic tokens that reference the internal palette. These are the only tokens consumer apps should use.
Why
- Prevents host apps from depending on internal color values that may change between themes
- Makes it obvious which tokens are part of the public API
- Simplifies adding new themes in the future (just add a new palette file)
- Reduces confusion during code review and onboarding
Out of scope
This issue is about restructuring and documenting the token layers — not changing any visual output. All resolved color values should remain the same.
Problem
The current color token architecture mixes internal palette values with public-facing semantic tokens, making it unclear which tokens are meant for internal theming and which should be consumed by host apps.
Proposal
Establish a clear two-layer token structure:
Internal palette files — define raw color values per theme:
_colors-light.scss— light theme palette_colors-dark.scss— dark theme palettePublic token file —
_colors.scssexposes named semantic tokens that reference the internal palette. These are the only tokens consumer apps should use.Why
Out of scope
This issue is about restructuring and documenting the token layers — not changing any visual output. All resolved color values should remain the same.