.web/site.yaml 是当前 Web Device 的站点级配置入口。它把过去分散在许多 .web/ 小文件中的标量设置集中起来，但不把每一种文件都塞进 YAML：tokens、redirects 和 logo 仍有各自适合的独立形态。
一个保守的起点是：
locale: en
locales:
- en
- zh
seo:
title: Example site
description: A small site built with Web Device.只写你确实需要、并已在目标 ARC 版本验证的键。配置文件允许作者注释，但未知键目前会被 reader 忽略；这避免一处新键让站点不能读取，也意味着拼写错误不会自动变成你期望的功能。
配置的职责边界
| 需要配置什么 | 位置 |
|---|---|
| 默认 locale、locale 列表、render mode、颜色方案、评论开关、detail sections | .web/site.yaml 顶层键 |
| 站点 SEO 与模板级值 | site.yaml 的 seo:、template: 块 |
| 共享 theme library opt-in 与 AUP CSS 的 tone、palette | site.yaml 的 theme: 块 |
| 设计 tokens | .web/tokens.json，或兼容的 .web/tokens/ 目录 |
| 重定向规则 | .web/redirects |
| 站点 logo 资产 | .web/template/logo.svg |
site.yaml 与旧的分散文件布局可在兼容窗口同时读取。对相同配置值，YAML 表达会覆盖对应的扁平文件值。新站点应优先使用 site.yaml，但不要在没有跑过目标消费者的情况下批量删除历史文件。
theme: 块当前不会选择 .web/themes/<name>/ 下的 component overlay 目录。当前 runtime 中，active overlay 不是普通 site.yaml 的作者配置开关；不要把 tone 或 palette 名称当成 component-theme 的目录名。
不要把页面设置上提为站点设置
全站 title、默认 locale 或 theme 选择属于 .web/。某一页的 SEO title/description 属于 pages/<name>/seo/；一篇内容的标题、摘要、日期和标签属于其 content/<type>/<slug>/ 对象。把它们都塞进 site.yaml 会让页面复用、locale 覆盖和内容索引失去边界。
修改后怎样验收
- 先写最小
site.yaml，保留现有 tokens、redirects 和 logo 文件。 - 运行
arc dsl validate .与arc blocklet check .，再构建站点。 - 在每个声明的 locale 中核对首页 title/description、链接和主题表现。
- 若从扁平文件迁移，逐项比较构建输出，不要只比 YAML 是否能解析。
继续阅读路由、导航与语言了解 locale；阅读主题与 tokens了解视觉配置的下一层。