Site-wide configuration

.web/site.yaml is the current Web Device entry point for site-level configuration. It gathers scalar settings that were previously scattered across many .web/ files, but it does not force every kind of file into YAML: tokens, redirects, and the logo retain their own suitable forms.

A conservative starting point is:

locale: en
locales:
  - en
  - zh

seo:
  title: Example site
  description: A small site built with Web Device.

Write only keys you need and have verified against the target ARC version. The config document allows author comments, but the reader currently ignores unknown keys. That prevents a new key from making a site unreadable, and it also means a spelling mistake does not automatically become the behavior you intended.

Configuration responsibilities

What you configure	Location
Default locale, locale set, render mode, color scheme, comment switches, and detail sections	Top-level keys in `.web/site.yaml`
Site SEO and template-level values	The `seo:` and `template:` blocks in `site.yaml`
Shared-theme-library opt-in and AUP CSS tone/palette	The `theme:` block in `site.yaml`
Design tokens	`.web/tokens.json`, or the compatible `.web/tokens/` directory
Redirect rules	`.web/redirects`
Site logo asset	`.web/template/logo.svg`

site.yaml and the older split-file layout can be read during the compatibility window. For the same configuration value, the YAML expression overrides the corresponding flat-file value. Prefer site.yaml for a new site, but do not bulk-delete historical files until the target consumer has been run.

The theme: block does not currently select a component-overlay directory below .web/themes/<name>/. In the current runtime, an active overlay is not a normal site.yaml authoring switch. Do not treat a tone or palette name as a component-theme directory name.

Do not lift page settings into site settings

A site title, default locale, or theme selection belongs in .web/. A page's SEO title/description belongs in pages/<name>/seo/; an item's title, summary, date, and tags belong to its content/<type>/<slug>/ object. Putting all of them into site.yaml erases the boundaries needed for page reuse, locale overrides, and content indexing.

Accept a configuration change

Start with a minimal site.yaml, keeping existing token, redirect, and logo files.
Run arc dsl validate . and arc blocklet check ., then build the site.
In every declared locale, inspect the home-page title/description, links, and theme presentation.
When migrating from flat files, compare the rendered build item by item; do not only confirm that YAML parses.

Read Routes, navigation, and locales for locale behavior, and Themes and tokens for the next visual layer.