---
name: site-docs-authoring
description: >-
  Review or author pages under site/pages/{architecture,getting-started,
  guides,patterns,reference}/, the docs site (count the pages on disk; it
  grows). Use when asked to add
  or edit a getting-started/architecture/guides/patterns/reference page,
  review a site docs page for consistency, fix a callout that reads as plain
  text, or explain why an inline-code chip or a demo gallery looks broken.
  NOT for a component's own .examples.html demo (primitive-authoring) or any
  pure-primitive-composition training-harvest page (governed by
  composition-and-examples.md's no-style-block rule; owner: a2ui-maintenance).
disable-model-invocation: false
user-invocable: true
---

# site-docs-authoring

> **Claude-only seat.** This skill dispatches a Claude Code subagent (the Agent tool), under Codex, run the equivalent work inline instead (gh#1888).

Every page under `site/pages/{architecture,getting-started,guides,patterns,
reference}/` shares one skeleton: `<header><h1>` + a deck `<p>`, then numbered
`<section data-section data-property="...">` blocks, each opening
`<h2 variant="section">` with an optional `<p data-note>` subtitle. Two
archetypes ride it, narrative/explainer (architecture, getting-started,
guides: prose + `<code-ui>` + tables, no live demos) and reference/gallery
(patterns, reference: the same skeleton plus `<preview-ui>` demo rows and a
near-universal closing "Guidance for agents" callout).

Full decomposition, the convention rules, and the training-harvest-surface
boundary this skill does NOT cover: read
[`../../../../../.claude/docs/conventions/site-pages-authoring.md`](../../../../../.claude/docs/conventions/site-pages-authoring.md)
in full before authoring or reviewing: it is the source of record; this
skill routes to it and enforces it, it does not restate it.

## Task shape → action

| Task shape | Do |
| --- | --- |
| New page in an owned category | Read the convention doc's template section; copy the shared skeleton from a sibling page in the same category (narrative archetype vs. reference/gallery archetype). |
| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>`, the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text, never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either, wrong shape, the convention doc's rule 2 carries the working treatment (eyebrow `<tag-ui>` title-row, TKT-0011). |
| Tamed admin-shell demo | Add `class="demo-frame"` to the shell instance + a page-local `<style>` block setting only `--demo-frame-height` (and any genuinely page-specific extra). That's `site/site.css`'s `.demo-frame` utility already covering `position`/`border`/`overflow`/`.demo-body` padding. |
| A surface needs to read as "its own distinct object" against the page background (a chip, a pill) | Reuse `--a-canvas-well-strong` (`packages/web-components/styles/colors/semantics/core.css`), verified ≥3:1 (WCAG 2.2 SC 1.4.11) in both schemes. `--a-canvas-well` alone is for a subtly-sunken panel; for a NEW candidate token, text/link AA pairs are gated by `npm run verify:contrast`, a non-text 3:1 (SC 1.4.11) check has no mechanical runner today, so prove that ratio by hand and cite it in the PR. |
| "Is this page consistent?" / review request | Check the page against the convention doc's numbered rules by name (the doc's own headings are the roster: it has grown past four); a finding names the specific rule violated, not just "this looks off." |
| Anything touching a real UI primitive not already listed above | Audit `packages/web-components/components/` before inventing markup (this repo's standing rule), a fake `data-*`/`class` convention with no CSS is exactly the defect class this skill exists to prevent. |

## Verify after any change

- `npm run check:links`, intra-repo links across the touched pages.
  (Before ADR-0072 Decision 2 / gh#2410 retired site-a2ui, a markup change
  also needed `node scripts/build/site-a2ui.mjs --page <route>` to
  regenerate a compiled A2UI artifact. The docs site now renders each
  route's fragment directly, no compile step, no artifact to regenerate.)
- `npm run verify:contrast` for any new or changed token used for text or
  link contrast (that gate covers text/link AA pairs only, a non-text 3:1
  claim needs a hand-proved, cited ratio; no mechanical runner exists).
- `npm run check:lightningcss-build` after any CSS change (`site/site.css`
  or a component's own `.css`).
- **Visually verify any `alert-ui`/rich-slotted-content change in a
  browser**, a wrong container tag (`<span>` instead of `<div>`) still
  silently reorders mixed inline content on render even without a compile
  step; this is not optional for this one content shape.

A check that cannot run (missing script, no network for a build step) is a
named blocker in the report, flag it and stop; never mark the page done on
an assumed pass.

The fresh-context critic for an authored page is the `demo-audit-agent`
agent (its dogfood visual probe covers rendered site surfaces), the author
never certifies their own page's rendered result; the mechanical checks
above plus that read-only pass together are the review.

Done when the touched page(s) pass the checks above and, for a reviewed
page, every finding cites the specific rule in `site-pages-authoring.md` it
violates.