token 让一个视觉决定可复用，而不用让每个页面各自携带颜色、字体和间距规则。新站点先在 .web/tokens.json 放入共同的视觉词汇，再考虑页面特有的 CSS 例外。
声明浅色和深色 token 值
tokens.json 独立于 site.yaml。顶层属性形成浅色/默认 CSS custom property 层；dark 对象提供深色模式覆盖。runtime 也提供默认 --ds-* design token 与 AUP palette/tone 默认值；site 可以有意识地覆盖它们。
token 应表达语义，而不是绑定某一页。例如用它表达 surface、阅读宽度或 accent role，而不是“第三张卡片的蓝色”；后者会让未来改版变得不必要地昂贵。
theme: 做什么、又不做什么
.web/site.yaml 的 theme: 块可以 opt into 共享 theme library，并声明 AUP CSS 的 tone/palette。它当前不会从 .web/themes/<name>/ 选择 component overlay 目录；不要写一个 tone 名称就期待它替换 header 或 card component。
存在本地 .web/themes/ tree 时，它是有独立优先级行为的另一来源。特别是本地 theme 的 token/SEO 与共享 library fallback 的 cascade 不相同。没有在具体目标环境测试前，新站点不要把两套系统混用。
审阅一次视觉系统改动
- 先修改最小集合的语义 token 值。
- build 后，在浅色与深色呈现中打开首页和一张代表性内容页。
- 手动检查文本对比度、focus 可见性、图片和窄宽度换行。
- 若页面需要结构变化，应放进 component，不要把 layout 行为编码成颜色 token。
当前 token reader 会过滤一小部分明显的 style/script injection 模式，但这不代表任意不可信 CSS 都安全。应把 token 文件当作受信任的 site 配置。
兼容性说明见 主题与 token 参考；component 层覆盖见 使用与覆盖组件。