Tokens make a visual decision reusable without forcing every page to carry its own color, type, and spacing rules. In a new site, put the common visual vocabulary in .web/tokens.json before inventing page-specific CSS exceptions.
Declare light and dark token values
tokens.json is independent of site.yaml. Its top-level properties become the light/default CSS custom-property layer; its dark object supplies the dark-mode overrides. The runtime also provides default --ds-* design tokens and AUP palette/tone defaults. A site can override those values deliberately.
Keep a token semantic rather than local to a page. For example, name a token for a surface, reading width, or accent role, not for “the blue on the third card.” The second name makes a future redesign unnecessarily expensive.
What theme: does and does not do
The .web/site.yaml theme: block can opt into the shared theme library and declare AUP CSS tone/palette values. It does not currently select a component overlay directory from .web/themes/<name>/. Do not write a tone name expecting it to replace a header or card component.
If a local .web/themes/ tree is present, it is a distinct source with its own precedence behavior. In particular, local-theme token/SEO behavior and shared-library fallback do not have the same cascade. Until a concrete target setup has been tested, avoid mixing both systems in one new site.
Review a visual-system change
- Change the smallest set of semantic token values.
- Build and open a representative content page plus the home page in light and dark presentation.
- Check text contrast, focus visibility, images, and narrow-width wrapping manually.
- If a page needs a structural change, make it in a component; do not encode layout behavior into a color token.
The current token reader filters some obvious style/script injection patterns. That is not a guarantee that arbitrary untrusted CSS is safe to accept. Treat the token file as trusted site configuration.
See Theme and token reference for compatibility notes and Use and override components for component-layer overrides.