Use and override components

Use a Web component for presentation you expect to reuse: a header, article card, editorial band, or responsive device frame. Keep page data and content objects outside the component so the component remains a presentation boundary.

Create a complete site component

Put a component under .web/components/<name>/:

.web/components/article-card/
├── manifest.json
├── render.js
└── style.css          # required by this beta.25 guide

The current source resolver requires manifest.json and render.js for a new component and can resolve a component without style.css. That is not the authoring rule for this documented target: the verified 2.0.0-beta.25 CLI requires style.css for a new standalone component. Include all three files in every beta.25 starter or site component; recheck this narrow rule when changing runtime version. If a component needs a browser-side script, its manifest must declare hasScript: true and the directory must provide script.js.

render.js exports render(ctx). The renderer context supplies props, slots, t(), locale, escapeHtml(), icon(), and pagination(). Treat that as trusted site code: it is not a sandbox for untrusted third-party plugins.

Know what overrides what

The current resolver assembles a component in this order:

A later same-named layer overrides an earlier one. For a component that already exists below it, a theme or site can override only one file, for example style.css, and inherit the rest. A completely new component name must provide the complete component definition; a lone stylesheet is not a new component.

Local .web/themes/ and a shared theme library are alternatives, not two theme sources that automatically stack. Do not assume a local theme plus a library theme will compose unless the exact target setup has been verified.

Keep page layouts simple

Use a component from a page layout with declared props and an explicit empty state. Avoid copying its HTML into several page layouts merely because the first use is small. Conversely, do not turn one-off page structure into a global component without a second real use; that creates an opaque abstraction with no reuse benefit.

After changing a component, run the local validation chain and inspect every consuming page in both its wide and narrow layout. A watcher may invalidate local page cache during development, but automatic hot refresh is not an unconditional product guarantee; reload and recheck when a result looks stale.

See Themes and tokens for visual-system configuration and Component resolution for the boundary between runtime/theme components and site-owned components.