# HTML Rendering

This is a format-rendering reference — it describes how to render any
artifact in HTML, independent of which skill is producing it.

It is paired with a section contract (`plan-sections.md`,
`brainstorm-sections.md`, etc.) that describes *what* the artifact contains.
This reference describes *how* HTML specifically presents it. The same
content rendered by different skills shares the same HTML principles.

The HTML artifact is the *only* artifact the skill produces for that run —
output mode is exclusive (markdown OR HTML, never both). Downstream
consumers that read HTML today (`ce-work`, human readers) do so directly;
the agent-consumability rules below make that work. `ce-doc-review` is
*not* currently an HTML consumer — its mutation mechanics are markdown-only,
so the ce-plan handoff gates the 5.3.8 doc-review pass to `OUTPUT_FORMAT=md`
runs and skips it for HTML.

## Hard invariants

These hold regardless of which skill produced the artifact.

- **Single self-contained HTML5 file.** No companion `.css`, `.js`, or
  `.svg` files. CSS lives in `<style>`. SVG lives inline. Images are
  base64 data URIs or inline SVG. The one permitted exception is a
  `<link rel="stylesheet">` to a CDN webfont CSS endpoint (Google Fonts,
  Bunny Fonts, etc.), paired with an offline-readable fallback font stack
  so the doc remains readable if the CDN is unreachable.
- **All metadata appears as visible text — single source of truth.**
  The artifact's metadata (title, type, date, etc. — exact
  fields per-skill, defined in the section contract) renders as visible
  HTML elements that downstream agents and humans read. No hidden
  machine-readable copy in any form: no `<script type="application/json">`
  frontmatter block, no `data-*` attribute mirror, and no
  `<meta name="created">` / `<meta name="origin">`
  in `<head>` duplicating the same values that appear in the visible
  header. One representation for each value — drift across two copies is
  the failure this rule prevents.

  The text-and-attribute redundancy in `<time datetime="2026-05-12">2026-05-12</time>`
  is acceptable because the attribute is a parser hint, not a hidden copy.
- **Stable IDs as anchor IDs AND visible text.** Every ID-bearing item
  (R-IDs, U-IDs, A-IDs, F-IDs, AE-IDs, KTDs) gets `id="r1"` on its
  element AND appears as visible text inside the element (e.g., the
  text "R1." inside the table cell or heading). Downstream agents find
  the ID in source the same way they find it in markdown.
- **Source / composition signal.** A visible footer at the bottom of
  the doc names the composition timestamp and the source identifier
  (the user prompt context, the upstream brainstorm doc when one
  exists, or just the composing skill name when there's no external
  source). Example shape:
  `<footer class="composition-signal">Composed 2026-05-17T14:23Z by ce-plan from <code>docs/brainstorms/...-requirements.md</code></footer>`.
  Under exclusive output mode this signal is the artifact's own
  provenance — there's no markdown sibling to reference. Omitting it
  leaves readers unable to tell how stale the rendering is.
- **ASCII identifiers.** Class names, element IDs, data attribute names
  are ASCII-only.
- **Unified plan navigation.** Unified plan artifacts include a visible
  navigation region near the top of the document. It links to stable section
  anchors for `goal-capsule`,
  `product-contract`, `planning-contract`, `implementation-units`,
  `verification-contract`, `definition-of-done`, and `appendix` when those
  sections exist. Requirements-only artifacts omit links to absent
  implementation sections.
- **Visible readiness metadata.** If the artifact has `artifact_contract`,
  `artifact_readiness`, `product_contract_source`, or `execution`, render
  those values in the visible header metadata. Do not hide a duplicate copy in
  JSON, `data-*`, or `<meta>` tags.

## Precedence stack for style preferences

Honor user style preferences in this order (highest to lowest):

1. **In-session conversation** — explicit direction the user gave this run.
2. **Preferred stylesheet reference** named in loaded agent-instruction
   context (typically `AGENTS.md` / `CLAUDE.md`, but scan loaded context;
   don't enumerate locations). The reference may be a file path
   (`docs/style.css`), a URL, a named library ("Tailwind"), or a style
   brand ("Stripe docs"). Agent-instruction files carry deliberate
   agent-aware preferences, so this tier sits above DESIGN.md.
3. **DESIGN.md** discovered on the filesystem (see "DESIGN.md discovery"
   below).
4. **Fallback default** — the opinionated palette / typography choices the
   agent makes when no preference exists.

### Active-recall at compose time

Before writing the CSS, scan loaded context for any stylesheet reference
the user has indicated for documents like this. If found and inlinable
(short local file, fetchable URL within budget), inline it into `<style>`.
If found but not inlinable (large framework, paywalled stylesheet, named
system without a fetchable source), compose CSS in its spirit — typography,
color, density cues drawn from the named system. Only fall back to the
default style when no preference signal exists.

The single-file invariant is preserved either way. External
`<link rel="stylesheet">` is permitted only for CDN webfont CSS (with the
offline fallback font stack); never link to an external stylesheet
carrying layout, color, or typography rules the doc cannot read offline.

### DESIGN.md discovery

When tier 3 of the precedence stack applies, look for a DESIGN.md file in
these locations, first match wins:

1. Worktree root (resolve via `git rev-parse --show-toplevel`).
2. `docs/DESIGN.md`.
3. `.compound-engineering/DESIGN.md`.

Read once at compose time. Absent → fall through to the fallback default.

Worktree-root only — do not fall through to a main checkout. Users
working from a worktree who want HTML defaults can add DESIGN.md to the
worktree.

**DESIGN.md is a partial override, not all-or-nothing.** Real DESIGN.md
files vary widely: some are token tables, some are CSS variables, some are
prose; most are authored for a *product or marketing surface*, not a
long-form doc. The governing split: **take the brand's scale-independent
identity literally, own the scale-dependent layout values yourself, and
skip decoration.**

- **Take literally (scale-independent identity):** the color palette
  (under the contrast rule), font *weight* and *style*, OpenType features,
  and radius *character* (sharp vs rounded). These carry the brand and are
  safe at any size.
- **Own it yourself (scale-dependent layout):** the **type size scale**
  and **spacing magnitudes**. DESIGN.md values are almost always
  product/marketing-scaled (display headings at 48-80px, airy ~96px
  section gaps); read them only as *hierarchy*, then set doc-appropriate
  values (body ~14-16px, headings ~1.2-1.6× body, comfortable paragraph
  spacing).
- **Skip decoration:** decorative or atmospheric brand voltage with no
  content to attach to in a doc — gradient orbs, full-bleed hero
  photography, motion. Take the palette and feel; do not reproduce the
  decoration.

Specific cases:

- **Fonts: load only open webfonts; never attempt a proprietary brand
  face.** A self-contained doc can only load an open webfont (Google Fonts
  or an open CDN) via the permitted webfont `<link>` plus an offline
  fallback stack. **Assume a bespoke brand face is proprietary and do not
  attempt to load it** — Airbnb Cereal, Coinbase Display/Sans, BMW Type,
  Waldenburg, Circular and the like will not render in a single file;
  trying just produces a broken fallback. Use the DESIGN.md's own fallback
  chain, or a family-matched system stack (serif↔serif, sans↔sans,
  mono↔mono). Load a named face *only* when it is a known open webfont
  (Inter, Geist, Cal Sans, Roboto…); when unsure whether a face is open,
  do not try. Honor the DESIGN.md's declared roles (`body` / `display` /
  `mono`) and never promote a display/decorative face into a body or
  small-text role. Net: reproduce the brand's serif-vs-sans structure and
  weight voice, not necessarily its exact faces.
- **Typography-scale mismatch.** DESIGN.md typography tokens are usually
  sized for product UI — marketing pages, app screens, hero sections —
  with display headings at 48-80px. A long-form doc needs body at ~14-16px
  and headings at ~1.2-1.6× body. When the size scale looks
  product-scaled (the common case), use the **family**, **weight**, and
  **OpenType feature** assignments (these carry the design language) and
  pick the agent's own size scale for the doc surface. Apply DESIGN.md
  sizes literally only when they are clearly doc-scaled — body 14-16px,
  headings under ~32px.
- **Scope mismatch (product UI vs doc surface).** A DESIGN.md aimed at
  product marketing or app UI may name button states, input borders, or
  hero backgrounds tied to *that* surface, not a generic doc. The page
  surface is the case to judge: a **reading canvas** — white, off-white,
  or a legible dark — transfers **literally** and should be the doc
  background; a bright product/marketing-hero surface
  (`--surface: #c0f0fb`) does not — extract the principle (the design
  language uses a tinted surface) rather than the literal value when the
  token is product-UI-scoped.
- **Partial coverage.** When DESIGN.md defines some categories but not
  others (colors but no spacing scale, typography but no elevation), use
  it for what it covers and the fallback default for the rest. Do not
  require DESIGN.md to be complete before honoring it.

## Format principles

These shape what "good" HTML looks like; the agent applies them per
artifact based on content.

### Readable measure, not full bleed

Long-form text is unreadable at full viewport width — past ~80 characters
per line the eye loses the return sweep and scanning slows. As a
fallback-default (precedence tier 4, overridden by in-session direction or
DESIGN.md), center the document in a content container and hold prose to a
comfortable measure.

- **Page container.** A centered column with a max-width in the ~820-960px
  band (`margin-inline: auto`) keeps the doc off the far edges of wide
  monitors while leaving room for the format's richer shapes.
- **Prose measure.** Hold running paragraphs to roughly 65-80 characters
  (`max-width: ~70ch` on text blocks). The named test: read a paragraph at
  full window width on a wide display — if the return sweep to the next
  line is effortful, the measure is too wide.
- **Let wide content break out.** Tables, diagrams, and side-by-side
  columns may use the full container width (or wider) when the content
  needs it — the measure constraint is for prose, not for everything.

Express the constraint in `ch`/`rem` rather than a single hardcoded pixel
value so it survives font-size and DESIGN.md overrides. DESIGN.md or an
in-session instruction overrides these values; this is the fallback when no
layout preference exists.

### Markdown source is content, not design

When markdown (or markdown-shaped chat context) is part of the input, use
it for semantic content — what the doc is about, what sections exist,
what facts each section establishes. Do NOT treat its bullet-vs-table
presentation choices as authoritative; re-choose the rendering per
content shape in HTML's richer affordance space. If the markdown rendered
13 requirements as a bulleted list, that does NOT mean HTML must render
them as a list — ask whether 13 items sharing `ID + body` shape deserve
a table.

### Prose is authoritative

When a visualization disagrees with the surrounding prose, the prose
governs. If they diverge, the visualization is wrong.

### Hyperlink the reference index

When the doc has a Sources & References (or equivalent reference-index)
section, hyperlink each entry to its canonical destination so readers
can open it directly. A long bare-text list of paths and ticket IDs is
the format's biggest unforced UX miss — the reader has to copy-paste
every entry into a browser or IDE.

Resolve the repo's GitHub URL once at compose time:

```bash
git remote get-url origin
```

Apply linking to three reference shapes:

- **Repo-relative code/doc paths** (`services/foo.ts`,
  `docs/solutions/bar.md`) → `<repo-url>/blob/main/<path>`.
- **Named GitHub PRs/issues** (`PR #636`, `issue #1048`) →
  `<repo-url>/pull/636` or `<repo-url>/issues/1048`.
- **Named external trackers** (Linear `ESP-1705`, Jira `PROJ-123`) →
  link only when the workspace URL is established in loaded context
  (e.g., a `linear.app/<workspace>/...` URL appeared earlier in the
  session or in `AGENTS.md`); otherwise leave as text.

**Do not invent URLs.** If `origin` isn't a GitHub URL (GitLab,
Bitbucket, internal host) and the equivalent main-tree URL pattern
isn't obvious, leave entries as `<code>` text. If the external
tracker workspace isn't established, leave as text. A broken or
guessed link is worse than no link.

**Scope: reference index only, not inline prose.** Inline `<code>`
mentions of paths or PRs inside paragraph prose stay as code or text.
Linking every mention would clutter; readers expect clickable jumps
where the doc presents itself as a reference index.

### Stable section anchors for unified plans

When rendering a unified plan, every major logical section gets a stable
anchor ID and visible heading text:

| Logical section | Required id |
|---|---|
| Goal Capsule | `goal-capsule` |
| Product Contract | `product-contract` |
| Product Requirements | `product-requirements` |
| Planning Contract | `planning-contract` |
| Implementation Units | `implementation-units` |
| Verification Contract | `verification-contract` |
| Definition of Done | `definition-of-done` |
| Appendix | `appendix` |

Long HTML plans are agent-consumed as source text as often as they are read in
a browser. Keep the heading text visible and adjacent to the `id`; do not rely
on a nav link alone to carry the section name.

### Text contrast is local

Every text-on-background pairing must hold up on its own. A color that
works for prose on the page background does not automatically work for
a small label inside a tinted container. The most common violation:
applying a generic "muted" text variable (calibrated for prose-on-bg) to
secondary text inside an accent-soft / warn-soft / info-soft container.

Test by reading each filled shape's labels at the rendered scale. If the
subtitle or secondary text feels washed-out against the fill, the choice
is wrong for that local context — pick a color from the same family as
the fill (accent-text for accent-soft, etc.) or drop the muting entirely
and rely on font-size and weight for hierarchy.

### Body bold not colored by default

Reserve accent text color for status chips, ID chips, links, and section
borders. Do NOT color `<strong>` in body content by default. Bold weight
already carries emphasis; applying accent color to every `<strong>` in a
long list overwhelms the eye, especially in dark mode. CSS should leave
`strong` at `color: inherit` unless a specific surface (status pill, ID
chip) is being styled.

### Chips and pills: uniform shape, no one-sided accent

Status chips, ID chips, and metric pills in the same row share one shape
— same border-radius, border weight, and fill treatment. Differentiate
categories only by the chip's overall fill/text color (applied to the
whole pill, like a soft-tint badge), never by an accent on one edge. A
colored stripe or arc on a single side of a pill reads as broken and
asymmetric — as if a border half-failed to render — so avoid it. The same
holds for any element, not just chips: differentiate by a full tint, not
a colored stripe on one edge. If an ID chip should stand out from metric
chips, vary its fill/text color uniformly, not its edge treatment, and
keep every chip in the row a visual set.

### No JS framework runtimes

A small inline `<script>` for active-section TOC tracking or anchor-
permalink behavior is acceptable. React, Vue, Svelte, or any framework
runtime is not. The single-file invariant doesn't permit framework
bundles, and the artifact's longevity doesn't warrant a build dependency.

## Section anatomy

How section types commonly render in HTML. These are patterns, not
contracts — the agent picks shapes that fit the content.

- **Summary / Problem Frame** — semantic `<section>` with prose
  paragraphs. Optionally precede with an eyebrow label (small-caps tag
  above the title) for editorial polish.
- **Requirements** — `<table>` is the default at 5+ uniform items;
  bullets at smaller counts. Concern-grouping takes precedence over the
  flat-table default: when requirements span distinct concerns, group them
  under bold inline headers (or per-group sections) first, then apply the
  5+ table default *within* each group rather than flattening the whole
  section into one table. Each row has the R-ID as visible text in
  its own column. Consider adding a "covered by" column for reverse
  traceability when ID-anchored items have downstream references in
  the same doc.
- **Implementation Units** — repeating `<article>` cards with a stable
  ID chip (visible "U1" text), a metadata strip (`<dl>` with field
  labels and values for Goal, Files, Dependencies), and secondary
  content (Approach, Test Scenarios, Verification, Patterns to Follow)
  inside `<details>` collapsibles, **default-closed**. At 3+ units the
  default-closed rule is load-bearing — rendering all units fully
  expanded turns the doc into one continuous scroll where the reader
  can't see the unit list at a glance. The metadata strip is the
  primary always-visible surface; subsection labels (`<summary>`) are
  clickable affordances for readers to expand on demand. A single unit
  with no secondary content can skip `<details>` entirely; the rule
  fires when content exists to hide. The `<dl>` strip is for *descriptive*
  fields (Goal, Files, Dependencies). A *directive* field — `Execution
  note` is the canonical case, carrying a procedural instruction the
  implementer must act on (e.g. "start with a failing integration test") —
  does not belong in the strip, where it renders as a passive pair styled
  like a date and gets skimmed past. Render it as an advisory callout (see
  Tinted callout cards) so its visual weight matches its actionability. The
  test: descriptive value -> metadata pair; something the reader must act
  on -> callout.
- **Key Technical Decisions** — repeating cards with the decision ID,
  bold decision title (often with inline code for technical
  identifiers), and prose rationale. Flat cards (not collapsibles) —
  these are reference material readers scan, not drill into.
- **Risks** — cards with a color-coded status eyebrow (e.g., "RISK ·
  MITIGATED" / "OPEN · DEFERRED FOLLOW-UP") and prose body. Communicate
  status through the eyebrow's color plus an optional subtle full-card
  tint — not a colored stripe on one edge (see "Chips and pills").
- **Scope Boundaries** — callout cards distinguished (in-scope vs deferred
  vs outside) by a colored eyebrow/label plus a subtle full-card tint when
  the distinction is meaningful — not a one-edge colored stripe.

The agent picks more elaborate or simpler shapes based on what each
specific artifact's content needs.

## Diagrams

When the section contract calls for a diagram (architecture, sequence,
flowchart, state machine, swim lane, data-flow, quantitative
comparison), HTML renders it as **inline SVG**. The agent picks the
shape that conveys the content fastest — there is no fixed catalog of
"approved" diagram types. If the content is quantitative comparison
across categories, a bar chart is the right shape; if it's component
relationships, a topology diagram; if it's process flow across
participants, a swim lane; etc.

**Conceptual diagrams are not wireframes.** The wireframe affordance below
is scoped to *UI-shaped requirements* and is excluded for non-visual
systems. That exclusion is about wireframes only —
a brainstorm about a data model, schema, agent workflow, or migration is
still free to use a conceptual diagram (a before/after field map, a
source-of-truth fan-out, a state diagram). Don't let the wireframe
exclusion suppress a conceptual diagram the content warrants.

**Diagrams complement prose; they never replace it.** A diagram is an
accelerant placed next to the prose it illustrates, not a substitute. The
IDed prose stays complete and standalone — a reader who ignores every
diagram still gets the full content in text, and a text-reading downstream
agent (which does not parse SVG geometry) is never left with a relationship
that exists only in the picture. This extends the prose-is-authoritative
rule above: prose governs not only on disagreement but on completeness, so
adding a diagram is not license to thin the prose it depicts.

### Layout legibility for hand-authored SVG

The agent designs SVG coordinates without rendering — layouts that look
fine in source can collide in practice. Before emitting, trace each
labeled arrow, each shape edge, and each text label:

- **No stroke — arrow *or* shape edge/border — passes through a text
  label.** If an arrow line/curve, or the border of a box, parallelogram,
  or other shape, crosses a label's bounding box, the text reads as
  struck-through and the stroke reads as terminating at the wrong element.
  Fix by re-routing the arrow, moving the label clear of every edge, or
  applying `paint-order: stroke fill` with a stroke color matching the
  diagram background to halo the label. The halo width is a judgment call:
  narrow enough not to bleed into glyph strokes (a halo whose width
  approaches the glyph's own stroke width muddies the text color), wide
  enough to mask the underlying stroke (at least its stroke width
  plus a hairline). Verify by inspecting rendered text at the target
  font size — if glyphs look thicker or more colored-toward-halo than
  the same text outside the diagram, the halo is too wide.
- **Labels inside skewed or rotated shapes sit in the shape's true
  interior, not its bounding box.** A parallelogram, isometric face, or
  rotated rect has an interior offset from its bounding box, so a
  box-aligned (e.g. left-aligned) label spills past the slanted edge.
  Inset the label to fall inside the actual shape — account for the
  skew/rotation offset at the label's vertical position — or place it
  outside the shape with a short leader. This is the usual failure in the
  **stacked-layers idiom** (offset parallelograms implying z-order), where
  per-layer labels left-aligned to the container both overflow the lower
  layers and get crossed by the neighbouring layer's edge. Prefer
  labelling each layer in its own un-overlapped region, or to the side of
  the stack.
- **Arrow labels sit adjacent to the arrow's midpoint** (typically
  within ~10-15px above or beside the line they describe). A label
  floating at the diagram's edge that readers have to trace back to an
  arrow is broken — readers will misread.
- **Avoid long curves that traverse the diagram** to connect a
  component on one side to one on the other. If A and D need a labeled
  connection across a multi-component layout, prefer reordering boxes
  so A and D are adjacent, numbered step badges next to each
  participant that the caption ties together, or a short
  labeled-channel notation — rather than one curve crossing multiple
  unrelated elements.
- **Differentiate diagram shapes by geometry first, by fill semantics
  second.** Geometry (diamond = decision, rect = step, oval =
  start/end, parallelogram = data) carries the role unambiguously.
  Fill semantics (accent-soft for highlighted path, warn-soft for
  fallthrough) carry meaning. Resist introducing additional neutral-tint
  tiers (a slightly-lighter grey to mark "decision shapes are different
  from boxes") — when geometry already differentiates, an additional
  luminance tier adds no information and creates fragility: small RGB
  deltas survive native browser rendering but can be flattened or
  inverted inconsistently by dark-mode extensions, accessibility
  plugins, or printing.

### Plan architecture diagrams are not directional sketches

Do not add hedging captions or section preambles to plan SVG diagrams —
phrases like "directional guidance for review, not implementation
specification" do not belong on plan diagrams or on unit-card
technical-design subsections. Plan diagrams render the same authoritative
content as the surrounding prose; the prose-is-authoritative rule
already governs disagreement. Hedging language is reserved for the
wireframe affordance below, which carries a *required* directional
caption because the wireframe is explicitly NOT a spec.

## Wireframe mockups (requirements docs only)

When a brainstorm requirement describes a user-facing visual surface (UI
feature, screen layout, screen flow, component placement), the HTML
rendering may include a wireframe mockup. The trigger is the
**requirement**, not the document: any requirement (or requirements group)
with a UI/layout shape can carry a wireframe, whether or not the brainstorm
as a whole is "a visual product" — a backend-heavy brainstorm with one
screen change still earns a wireframe for that requirement. It still applies
to brainstorm **requirements** output — the requirements-only unified plan
`ce-brainstorm` writes (now under `docs/plans/`), not an implementation-ready
plan (`ce-plan`'s enriched output) — and only to UI-shaped requirements — a
non-visual requirement (API design, data model, agent workflow,
infrastructure) takes a conceptual diagram instead, not a
wireframe.

When a wireframe is included:

- **Fidelity ceiling: wireframe, not mockup.** Gray boxes for layout
  regions, text labels for content placeholders, intentional placeholder
  copy (`[Product name]`, `[CTA label]`, `[user avatar]`). No
  pixel-perfect colors, no exact typography choices, no specific
  component-library references. The wireframe communicates spatial
  arrangement and structure, not visual style.
- **Static only.** Inline SVG or simple HTML/CSS for layout. No JS
  interaction, no working form fields, no state changes, no live data.
- **Anti-padding.** One wireframe per distinct visual concept.
- **Mandatory directional caption.** Every wireframe carries an explicit
  "directional, not the spec" note adjacent to it. Required wording (or
  close paraphrase): *"Directional only — illustrates the intended
  user-facing shape. Exact colors, spacing, copy, and component choices
  are placeholders for review, not requirements."*

Without this caption the wireframe risks being read as a binding visual
spec, which the affordance is explicitly designed to avoid.

## Affordance idioms

Common HTML affordances the agent can reach for when content benefits.
These are examples, not requirements — the agent picks what each
artifact's content warrants. Other affordances not listed here are
fine when the content suggests them.

- **Sticky TOC sidebar with active-section indicator** — available when
  the agent judges navigation will materially help and the
  implementation is reliable: two-column layout on desktop, collapsed
  to top-of-page on mobile, paired with a small inline
  `IntersectionObserver` script that toggles `.active` on the matching
  nav anchor. Trade-off: a broken sticky TOC (layout collisions,
  active-section state drift, dark-mode CSS issues) is worse than a
  static top-of-doc TOC. For most long docs, default-closed `<details>`
  on repeating cards (see Implementation Units anatomy) already cuts
  the visible scroll length enough that a static TOC works — reach for
  sticky only when collapsibles alone don't solve the navigation
  problem.
- **Within-section sub-nav** for sections containing 6+ repeating cards
  (Implementation Units, KTDs, Risks at large counts). A short list of
  card-anchor links (`<ul>` of `<a href="#u1">U1. ...</a>`) rendered at
  the top of the section gives readers a jump table — no JS needed.
  Lower-complexity alternative to the sticky TOC for the specific case
  of long card sections.
- **Eyebrow labels** (small-caps tag above section titles) for
  editorial polish, especially when section titles are narrative
  rather than literal.
- **Stats strip** at the top of the doc when the artifact has 3+
  quantifiable signals worth surfacing at a glance.
- **`<details>` + `<summary>`** for collapsible secondary content
  inside repeating cards. All collapsibles start closed — `open`
  attribute should not appear on any `<details>` inside repeating
  cards by default.
- **Side-by-side columns** for parallel content (Request / Response,
  Before / After, Two alternatives).
- **Tinted callout cards** for content that is "different in kind"
  (Deferred, Open Questions, advisory notes, unit-level execution notes)
  — a subtle full-card background tint plus a colored eyebrow/label
  communicates kind at a glance. Avoid a colored stripe on one edge; tint
  the whole card instead.

## Agent-consumability rules

Downstream agents that read HTML today (`ce-work`, a skill re-reading its
own prior artifact on a resume run, future consumers) reason over the HTML
as text — the way they reason over markdown, not via DOM extraction or a
script-style parse. `ce-doc-review` is not a current HTML consumer (see
opening note).

These rules are why such a consumer can locate one item (a single
requirement, unit, idea, or other ID-bearing entry) and reason over it from
source alone — its title, every labeled field, and any diagram's meaning —
with no hidden machine-readable copy to fall back on. The semantic structure
*is* the extraction contract: it is what makes the single-source-of-truth
invariant (no `data-*` or JSON metadata mirror) safe rather than lossy.
Weakening it — `<article>` item boundaries collapsed into `<div>` soup, a
field label demoted to an attribute, one item's content scattered across
distant parts of the doc — breaks that reasoning even when the rendered page
looks identical. Compose so semantic understanding is reachable in source:

- **Use semantic HTML over `<div>` soup.** `<article>` per unit card,
  `<dl>` for metadata pairs, `<table>` for tabular content, `<details>`
  / `<summary>` for collapsibles, `<section>` for top-level doc
  sections. Structure markers carry meaning to a text-reading agent.
- **Render field labels as visible text, not as attributes.** Emit
  `<dt>GOAL</dt><dd>...</dd>`, not `<dd data-field="goal">...</dd>`.
  The label is the semantic anchor.
- **Keep U-IDs, R-IDs, and similar as visible text** in headings and
  table cells, not only as `id=""` attributes. The agent finds "U1." in
  source the same way it finds "U1." in markdown.
- **Match section heading vocabulary to what the section contract
  defines.** When the section contract says "Implementation Units," the
  HTML heading is "Implementation Units" — not "How we'll build it,"
  even if the narrative version reads better. Section heading
  vocabulary is the contract downstream consumers grep for. (Editorial
  re-titles can appear as eyebrow labels, sub-headings, or visual
  framing — but the load-bearing section heading matches the contract
  name.)
- **All semantic content lives in actual HTML text.** No CSS `::before
  { content: "..." }` carrying meaning, no background images as
  content, no semantic info that only renders. Whatever the agent sees
  in source is what it knows.
- **Stable structure is the public API.** Element types, the ID and
  label scheme, and the field-label vocabulary do not break across
  versions. Visual styling can change freely.

## Post-compose audit

Before returning the artifact, scan it for common slips:

- **Single self-contained file.** No companion `.css` / `.js` / `.svg`.
- **No hidden machine-readable metadata copy.** No
  `<script type="application/json">` frontmatter block, no `data-*`
  attributes mirroring visible values, **no `<meta name="created">` /
  `<meta name="origin">` etc. in `<head>`
  duplicating the visible header**. Metadata lives in visible text;
  one source of truth per value.
- **All stable IDs** appear as both `id=""` and visible text.
- **Section heading vocabulary** matches the section contract names
  (downstream agents grep these).
- **Source / composition signal** is present as a visible footer at
  the bottom of the doc (composition timestamp + source identifier).
- **Repeating cards with 3+ instances put secondary content inside
  default-closed `<details>`.** Fully-expanded unit cards in a long
  Implementation Units section is a failure mode — the reader can't see
  the unit list at a glance. Verify by skimming the rendered units:
  each `<article>` should render as its ID + title + metadata strip
  with collapsibles below, not as one long block.
- **Within-section sub-nav** is present for sections with 6+ repeating
  cards.
- **Body `<strong>`** is not colored with accent palette.
- **No one-edge colored accent** (a colored stripe/arc on a single side)
  on chips, pills, or callout cards — differentiate by uniform fill +
  colored eyebrow/label instead. A one-sided stripe reads as
  broken/unintentional; chips in a row must be a uniform visual set.
- **`<details>`** inside repeating cards have no `open` attribute.
- **Diagram labels** are legible — no arrow paths crossing text,
  halo width appropriate for font size.
- **Diagrams complement prose, not replace it.** Every relationship a
  diagram conveys is also present in the surrounding IDed prose; no
  content lives only in an SVG.
- **No JS framework runtimes** included. Small inline `<script>` for
  active-section TOC tracking or anchor-permalink behavior is the only
  acceptable JS.
- **Each heading level** is visually distinct from others and from
  inline bold.
- **No template placeholders** (`{skill}`, `<value>`, `[plan title]`)
  leaked into output.
- **No process exhaust** callouts in the artifact.
