dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-brainstorm/references/html-rendering.md

@@ -0,0 +1,638 @@
+# 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-doc-review`, `ce-work`, human readers) do
+so directly; the agent-consumability rules below make that work. `ce-doc-review`
+also applies fixes in the artifact's native format while preserving its
+existing structure.
+
+## 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 artifact metadata.** If the artifact has `artifact_contract`,
+  `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`,
+  `<root>/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.
+
+Optional sections with a contract-defined semantic role put that role on their
+wrapping `<section>` with `data-ce-section`. For example, the broader-work
+relationship section uses `data-ce-section="work-relationships"`. The role is
+stable even when the visible heading changes; it supplements, rather than
+replaces, readable heading text and any useful anchor.
+
+### 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 must hold — 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
+  applies when there is content 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. A
+  `session-settled:` annotation renders as visible text in the card —
+  never an attribute or hidden markup — stem preserved verbatim so
+  grep works on the HTML artifact.
+- **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
+ID-bearing 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 `<root>/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-doc-review`, `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.
+
+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 section heading itself, the one downstream agents
+  grep for, 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 ID-bearing 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.