---
name: report-with-html
description: >-
Produces the reader-facing HTML artifact — report, dashboard, architecture view, data browser, or
review workbench — evidence-backed, browser-verified. Use when the deliverable IS a visual HTML
report, or the user asks for an HTML/web presentation. Load data-visualization-discipline for
chart judgment. Not for chat status or Markdown prose unless asked to become a report; not for
PowerPoint (deck-creator Route C).
---
# report-with-html
Create a reader-facing HTML artifact whose information architecture follows the
reader's question—not the author's implementation checklist.
## Trigger boundary
Use this skill when the requested artifact is itself a visual HTML report or
interactive information tool. Typical outputs include:
- a system, architecture, journey, causal, decision, comparison, or gap view;
- a client-facing data report or one-pager;
- a data/archive browser or review workbench;
- an explicitly requested HTML/web presentation.
Do not trigger it for a normal status reply, generic review, code diff, issue list,
or Markdown document. Those tasks may be reported in chat unless the user explicitly
asks to turn the result into a visual HTML artifact.
For restoring or hosting an existing HTML page without changing its content,
take [Existing HTML restoration](references/local-http-preview.md#existing-html-restoration)
and stop after its delivery checks. This transport-only route does not enter the
new-report design, masked-render or reader-review workflow below. If the request
also changes the report's conclusions, layout or interactions, use the applicable
authoring/maintenance workflow for those changes.
For a local report that needs HTTP preview, use
`references/local-http-preview.md` and its bundled `scripts/preview_report.py`.
Serve only the reviewed explicit file
snapshot; verify its HTTP readiness and rendered content/action in the permitted
browser.
The default delivery is the verified HTML opened in a browser. A PNG is a QA artifact
and is delivered only when the user asks for an image. If the user needs editable
PowerPoint, finish and verify the HTML first, then use `deck-creator` (Route C).
## SSOT map
**Visualization judgment lives in another skill — load it before designing any chart or
geometry.** `data-visualization-discipline:data-visualization-discipline` owns which form
fits the content, which chart type and summary statistic to use, whether segments may be
aggregated, how many categorical colors are allowed, cross-view color identity, table
discipline, the antipattern list, and the pre-delivery self-check gate. This skill does not
restate those rules; a second copy would drift. This skill owns the report page itself:
register calibration, the component shelf, the approved corpus, page order, the decision-card
contract, interaction contracts, and browser verification.
- Reader-facing principles, content boundary, decision-card contract, accessibility:
`references/design-principles.md`
- **Layout density (铺满画布 / 消灭空洞), page order as narrative rhythm, the HTML table
micro-spec, and form → component implementation:** `references/visualization-patterns.md`.
**Not conditional on having already chosen a form** — most of it applies to every page
regardless of what you draw.
- Approved corpus and register calibration:
`references/approved-examples.md`
- Reusable interactions and their keyboard contracts:
`references/interaction-components.md`
- Parameter exploration, selected-record follow-up and recoverable workbench state:
`references/interactive-analysis.md`. Load before authoring those interactions;
keep static reports on the ordinary path.
- Numbered hover/focus source previews and original-content adapters:
`references/citation-source-preview.md` (candidate/pilot; load when citations use previews).
- Photos, screenshots and explanatory diagrams: `references/visual-evidence.md`.
Load before authoring when objects, physical choices, visual defects or relationships
need to be seen; do not wait until images have already been selected.
- Long-lived/generated-page maintenance:
`references/long-lived-report-maintenance.md`
- Version-comparison reading order, paired evidence and full-text inspection:
`references/version-comparison-reading.md`. Load when the page explains what
changed between editions; keep source interpretation separate from presentation.
- Fresh-context review payload:
`references/independent-review-prompt.md`
- Warm-paper starter implementation:
`assets/report-template.html`
**Read these before authoring** — the principles, the patterns file, the closest
approved example, and `data-visualization-discipline`. The rest are activated by what the
artifact actually contains.
Do not let "read only what's activated" decide the required sources above. That filter operates over needs
you already know you have, so it is structurally unable to surface *a step you don't know
exists* — and it hands the skip a legitimate-sounding rationale, which is worse than forgetting.
These are the sources that tell you which steps exist.
## Product contract
### Reader and evidence first
Write down the audience, the decision or understanding the page must enable, and the
authoritative sources before choosing components. Retrieve current facts during this
session. Every number needs a unit, date/window, and traceable source; unknown values
stay unknown.
Screen copy may contain a factual takeaway when the same page visibly supports it
with data, mechanism, or primary evidence. Remove unsupported value judgments,
slogans, maxims, superlatives, and unproven causal claims. A grep pattern such as
`不是.*是` only surfaces *candidates*; its presence alone is never a failure. Judge each
candidate with the test in `design-principles.md` §3 — delete the sentence, and ask
whether the reader loses a fact they could have checked on this page, or only an opinion.
The first stays, the second goes.
Use complete, audience-readable language. Internal codes, private shorthand, naked
algorithm scores, and unexplained abbreviations do not belong on the page.
### Let the question choose the skeleton
- “How does it work?” → journey, architecture, or mechanism.
- “What should we decide?” → options, trade-offs, decisive unknowns, recommendation.
- “Why did it happen?” → timestamped causal chain plus falsifying evidence.
- “Which is better?” → entities × criteria on a common baseline.
- “Let me inspect this collection.” → list/detail, search/filter, state, provenance,
deep links, and review-output return path.
Implementation state is a badge on that skeleton, not the skeleton itself. A missing
dependency, unverified result, or unknown must remain visible.
For technical selection or purchase comparisons, use the concrete-plan reading order
in `references/visualization-patterns.md` before arranging sections. Distinguish choosing
what to investigate next from authorizing a purchase or deployment.
### Geometry and real evidence
Use position and length for important quantitative comparisons. Color carries category
or state, not a second independent measure. A geometry needs an explicit encoding key
and a data-supported readout.
Do not redraw the same entity set in multiple decorative forms. Each section must
answer a different sub-question. For UI or visual-product review, real screenshots are
the primary evidence: crop the exact defect with enough surrounding context and keep
before/after crops identical.
Use an installed mature charting capability or the current project's declared chart
stack for statistical charts. If neither exists, research and select a maintained
library before implementing; do not hand-build a chart engine.
### Interaction and accessibility
For calculators or workbenches that continue from the reader's parameters or
selection, load `references/interactive-analysis.md` before implementing controls,
state recovery or the return to the conversation. Keep context preparation,
state saving and an explicit message send distinct; use a manual handoff in a
standalone browser.
**Evidence comes to the reader; the reader does not travel to the evidence.** When the
page cites a clause, a screenshot, or a source passage, embed it at the point of citation
— an in-place overlay or drawer that returns the reader to where they were. An anchor
that throws the reader elsewhere on the page and expects them to navigate back is
prohibited, not merely discouraged; `design-principles.md` §13 holds the rule and the
user's own words for it. Hash anchors remain correct for nav and for external deep links:
what is banned is being forced to leave mid-read.
Copy approved interactions from `assets/components/` instead of rebuilding them.
Behavior is part of the component contract; register-specific styling may change.
Copy each component through its complete contract:
1. Read the component file's own header contract — it states prerequisites the registry
table does not repeat (required CSS tokens, required DOM structure, which element
types it scans). `citation-drawer`, for instance, only linkifies inside ``
elements and needs a generator-produced `#s9`.
2. Make those prerequisites true in your page.
3. **Click the component's primary interaction in a real browser before delivery.** A
component can be present, id-unique, tag-balanced and completely inert — every static
check passes while the feature does nothing. Only the click distinguishes those two
worlds.
Every interaction must work without a pointer:
- use native buttons, links, and dialogs when available;
- provide a visible close control and Escape handling for modal surfaces;
- keep focus inside an open modal and restore it to the invoker on close;
- expose names, states, and relationships with semantic HTML and ARIA;
- preserve visible focus, logical tab order, and usable narrow-screen geometry.
## Workflow
1. **Define success.** Record audience, question, source set, required evidence,
delivery form, and what would make the artifact fail. The gate template (step 5) also
always carries a `读者已知清单` slot — fill it when the declared audience is narrower than
"any reader" (an internal, already-informed reader rather than a stranger): the specific
terms, scripts, or systems that audience is assumed to already know, in checkable
backtick-quoted form. When the audience genuinely is a stranger, write
`不适用: ` — the slot still has to be filled, just with that answer. Write this before
step 9's first review, not after one returns findings — see `references/audience-triage.md`
for why the ordering is load-bearing and how step 9 uses this list.
Resolve the actual reader and intended use from the original request, later corrections,
and the current project contract. Distinguish a publication-ready draft from an actual
external publication. Set evidence precision for that use: for private investigation,
retain traceable original identifiers, paths, and logs rather than silently substituting
a public, redacted edition. Follow the authorized project's existing delivery directory
or document library; a scratch directory is a working location. If no destination is
established, choose a reversible local default and state it. Ask only for missing inputs
that materially affect the result and cannot reasonably be defaulted. For an investigation,
record complete readability and proof of the core causal claim as separate acceptance
results. A readable report does not close the investigation while necessary, authorized
actions can still advance that claim; unavailable historical evidence remains unknown.
2. **Calibrate.** Read the mandatory sources — `design-principles.md`,
`references/visualization-patterns.md`, the closest entry in `approved-examples.md`, and
`data-visualization-discipline` — then any component reference the artifact activates.
Use the nearest approved register; do not copy a skin blindly.
3. **Plan visual evidence and 造量纲 — before a line of HTML.** First follow
`references/visual-evidence.md` for sections about concrete objects, physical choices,
visual defects or relationships. Put representative images at the relevant options
and explain connections with diagrams; identify unavailable evidence explicitly.
Record the selected visuals in the existing page intent, not a second inventory.
Section by section, name what in the content is
**ordered / has magnitude / has direction / has a counterpart**, and write that quantity
down. Each geometry then carries it in the markup:
```html
…
```
**No supported quantity or relationship means no invented geometry.** Keep that
content as prose; a verified photo or screenshot can still show the object or evidence.
Wrapping a sentence in a coloured box does not make it a diagram.
**A number and the coordinate that encodes it come out of the same script.** As soon as
any geometry is positioned by a computed value — a bar length, a tick at `left:30.80%`,
an axis label, a line's endpoints — write a small no-dependency script that prints *both*
the finding and the coordinates, paste from its output, and ship the script next to the
page. Computing the value in prose and then hand-writing the SVG attribute is a two-copy
fact with no `grep` that can catch the drift: it is how the same quantity ends up rounded
two different ways in two sections, and how an axis label lands at the position of a
smaller number — a lie factor authored by the very page arguing against lie factors.
Shipping the script also makes the drawing auditable: a reader re-runs it and diffs.
Step 5's gate asks for that script's path and stats the file, so this rule has a machine
consumer rather than being one more thing only you referee.
4. **Author.** If a calling Skill supplies a user-approved local report form that still
fits this report's output contract, use that form as the starting point. Otherwise
start from `assets/report-template.html` or an approved example. The calling Skill
owns template approval and storage; this Skill owns report generation and visual QA.
Keep customer facts and conclusions tied to current evidence, and do not copy the
caller's template into this Skill's update-owned `assets/`. Before updating an accepted
report's facts or content, follow the [incremental maintenance recipe](references/long-lived-report-maintenance.md#63-已验收报告的有界增量更新).
Use actual shelf components for new or changed interactions; retain the approved
embedded implementation during a data-only update. If the page embeds mutable source documents, follow the long-lived-report
reference and keep generated and authored regions separate.
5. **Run the delivery gate — it produces the artifacts the judgment steps otherwise skip.**
```bash
uv run /scripts/delivery_gate.py init page.html [--height 9600]
# → renders page.png AND page--masked.png (all text transparent — the squint test,
# headless; see the script header for the technique's provenance)
# → scans for ≥120 CSS px whitespace voids (visualization-patterns.md 版面填充纪律)
# → writes page.html.gate.md: the delivery gates + the stage-1 questions
# (`STAGE1` in delivery_gate.py owns the exact list), every slot empty
# Read the masked PNG segment by segment, fill every slot, then:
uv run /scripts/delivery_gate.py check page.html # exit 1 until it passes
```
`check` fails on: a missing or stale masked render (so 遮字自测 cannot be claimed without
the evidence), a percentage-driven visual with no `data-geometry`/`data-derived-from` (so
造量纲 cannot be skipped — pure-layout boxes opt out **visibly** with `data-layout`), any
unfilled slot, and a gate file older than the page (so "filled the checklist, then kept
editing" cannot pass). It asserts these steps **happened**; it says nothing about whether
the conclusions are right — that is still steps 9 and 10.
6. **Render a fresh artifact.** Step 5 already produced `page.png` at the height you passed
it; re-render here only when you changed the page since, and **pass the same height** —
`render_report.sh` overwrites in place, so a shorter H silently replaces a good render with
a truncated one.
```bash
/scripts/render_report.sh page.html page.png 1300 2400 # H is an example, not a default
```
`` is this skill's own directory — its absolute path is given to you when
the skill loads. Bare relative paths like `report-with-html/scripts/…` only resolve
from one particular parent directory and fail with exit 127 anywhere else.
The renderer fails without a new valid PNG and never treats an existing output as
success. Set `CHROME_BIN` to an explicit managed Chrome/Chromium executable in CI
or a shared-browser environment; an invalid override is a hard failure.
Then split it and read every segment — a tall PNG exceeds what one Read can resolve:
```bash
uv run /scripts/crop_segments.py page.png --segments 5
```
**That step is also where truncation is caught.** Chrome screenshots exactly the
`--window-size` you passed and never grows to fit, while the renderer's PNG check only
proves the bytes are a valid image — so a page taller than your H loses its tail
silently, and §6 of `design-principles.md` puts the strongest conclusion last. The
splitter warns when content runs to the final canvas row, which means the canvas cut
through the page rather than the page ending inside it. It is checked here rather than
in the renderer because the only non-mutating way to measure page height is a second
`--dump-dom` call, and that hangs on some pages — a gate that can never measure is a
gate that always skips.
**That warning has one false positive, and its obvious remedy does not terminate under
it — so read the warning's own two branches before you re-render.** If the page sizes
anything in `vh` (a scrolling panel at `max-height:78vh` is the common case), headless
`1vh` is `H/100`, so raising H grows that element too and content stays pinned to the
canvas bottom at *every* H. Discriminate once by rendering at a clearly different H and
comparing the reported content bottom: unchanged means it was real truncation and is now
fixed; still ≈ the new canvas height means it is the `vh` loop. Do not keep doubling H —
an operator who sees the same warning at 3000 and at 40000 learns to ignore it, and a
gate trained into noise no longer catches the real truncation it exists for.
Also test the narrow-screen layout with real device emulation and measure overflow.
Device emulation is not optional phrasing: headless Chrome clamps `--window-size` to a
~500 CSS px minimum width (measured 2026-09-17: asking 390 yields `innerWidth=500`;
`--force-device-scale-factor` does not shrink the CSS viewport either). For 390-class
phone widths use Playwright/CDP `Emulation.setDeviceMetricsOverride` (or Ego) — never
report a `--window-size=390` run as a phone-width test.
Measuring painted bar spans for the proportion gate: anchor on the *container* (find the
track box first, then measure dark pixels inside it), never cluster content pixels
globally — edge antialiasing creates phantom clusters and a long bar hides its own track
row (two real failures from 2026-09-17).
7. **Exercise the journey.** In a real browser, follow the reader's route—not merely
a click list. Test understanding order, the obvious next action, keyboard access,
modal focus, deep links, filters, and error/empty states. Use
`frontend-visual-qa` for micro, macro, and intent review. Every shelf component you
embedded gets its primary inte