Token file
.web/tokens.json is independent of .web/site.yaml.
| Shape | Role |
|---|---|
| Top-level CSS custom-property values | Light/default token layer |
dark object | Dark-mode override layer |
Runtime default --ds-* values | Baseline design system tokens a site may override |
Treat it as trusted configuration. The reader filters some obvious style/script-injection patterns but is not an untrusted-CSS sandbox.
Theme configuration
site.yaml can carry a theme: block for shared theme-library opt-in and AUP CSS tone/palette values. It does not currently make a .web/themes/<name>/ directory active as a component overlay. A named local theme tree and a shared-library fallback also have different precedence behavior; new sites should avoid mixing them before a concrete target setup is tested.
At a high level, a local .web/themes/ tree can affect token/SEO inheritance differently from a shared library fallback, while template structure remains site-layer-first. Do not rely on that subtle cascade for a first site; keep tokens in one explicit site-owned file and review the rendered result.
For the authoring guide, read Themes and tokens. If this reference does not settle a design question, verify the target setup before presenting a guessed theme contract.