Start by changing the visual system that has the smallest, clearest contract: .web/tokens.json. Do not begin by assuming that theme.tone selects a component overlay.
A narrow visual change
- Choose one semantic goal: reading surface, accent role, or content width.
- Change the corresponding top-level token value in
.web/tokens.json. - Add a
darkoverride only when the dark presentation actually differs. - Build, then inspect a home page and a content/detail page in both light and dark presentation.
- Check text contrast, focus visibility, images, and narrow-width wrapping before expanding the token set.
This produces a site-owned visual layer that components can reuse without a new component-selection mechanism.
Do not guess at theme overlays
In the current runtime, site.yaml theme: values opt into a shared theme library and set AUP CSS tone/palette; they do not choose .web/themes/<name>/ as an active component overlay. Local theme trees and library fallback have different precedence. If a design requires a local overlay, first make a small target-version fixture and verify the exact resolver path before treating it as a reusable theme recipe.
The token reader is not a security boundary for untrusted CSS. Keep the file under the same trusted review discipline as component code.