HTML Report

Interactivity (When It Helps)

The served document runs JavaScript, so a report can be interactive — and should be when interactivity genuinely helps the reader explore the data, not as decoration. All of it runs client-side over the embedded DATA snapshot; there is no server and no live refresh (that's interactive-dashboard).

Reach for interactivity when it earns its place:

• Sortable / filterable tables — let the reader sort a holdings table by weight or P&L, or filter to a sector. Pays off most on tables past ~15 rows.
• Tabbed or accordion sections — segment a long report (Summary / Financials / Valuation / Risks) so the reader isn't scrolling past everything.
• Interactive charts — Chart.js/ECharts hover tooltips, series toggles (click a legend entry to hide a line), range zoom on a long price history.
• Collapsible detail / "show more" — keep the default view tight; let the curious expand methodology, footnotes, or a raw-numbers table.
• In-page search / highlight — for a long screen or a wide comparison.

Rules:

• Wire events with addEventListener, not inline onclick= / on*= attributes. It is the robust pattern across every surface and keeps logic out of the markup.
• Client-side only. Operate on the embedded DATA; never fetch() a data API (the CDN allowlist blocks it). If the data must be live or is too big to embed, that's a dashboard, not a report.
• Default state must be meaningful. The report has to read correctly before any click — a reader (or a PDF export) that never interacts must still see the substance. Never hide the headline finding behind a tab.
• Degrade for print. Interactive controls (tab bars, filter inputs, sort buttons, "show more" toggles) are chrome — give them .no-print, and make collapsed content render expanded when printing so the PDF is complete. The @media print block below already hides button / .no-print.
• Keep it self-contained and lean. Vanilla JS over the embedded data; no framework, no build step. A little event delegation goes a long way.

Match the effort to the data: a one-number recap needs no interactivity; a 40-holding portfolio or a multi-section deep-dive benefits a lot.

Print / PDF

PDF export = the browser's print-to-PDF. Include an @media print block — without it, PDFs come out degraded. It should:

@media print {
  /* hide interactive chrome — buttons, toolbars, nav, anything not part of the document */
  .no-print, button, nav, .toolbar { display: none !important; }

  /* keep logical blocks from splitting across pages */
  section, figure, table, .card, .kpi { break-inside: avoid; page-break-inside: avoid; }
  h1, h2, h3 { break-after: avoid; }

  /* sane page setup */
  @page { margin: 18mm 16mm; }
  body { background: #fff; color: #000; }

  /* never let entrance animations leave content invisible in the PDF */
  *, *::before, *::after { animation: none !important; transition: none !important; opacity: 1 !important; }

  /* collapse side-by-side layouts — paper is ~816px wide; squeezed columns
     overlap charts and crush prose */
  .row, .grid, .columns { display: block !important; }
  .row > *, .grid > *, .columns > * { width: 100% !important; max-width: 100% !important; }
}

If any element starts at opacity: 0 for an entrance animation, the opacity: 1 !important rule above is what stops the PDF from exporting blank — keep it. Test the print path before declaring done.

Multi-column layouts print badly. Print width is ~816 CSS px — a flex/grid row pairing a chart card with a text column does not fit and will overlap or crush. Either keep the document single-column throughout (safest for a report), or include print rules like the collapse block above for every side-by-side container you create. Chart wrappers keep their fixed height either way.

Landscape documents must declare it. If the content is genuinely wide (a comparison matrix, a wide timeline, a dashboard-style sheet), declare the orientation in the print block — PDF export honors it and lays the page out at landscape width (~1056 CSS px), so charts and columns size for the real paper:

@page { size: letter landscape; margin: 14mm 16mm; }

Named sizes (a4, legal, ...) with optional landscape work too. Without a declaration, export is portrait Letter — don't design landscape-wide content and skip the declaration.

Print typography. Screen sizing usually reads too large on paper. Inside @media print, set print-affecting sizes in pt and tighten slightly:

@media print {
  body { font-size: 10.5pt; line-height: 1.45; }
  h1 { font-size: 17pt; }  h2 { font-size: 13pt; }  h3 { font-size: 11pt; }
  .card, section { padding: 10pt 12pt; }
}

Aim for 10–11pt body text — the register of a printed research note. Keep table cell padding compact (4pt 8pt) so wide tables fit. Page margins come from @page { margin: ... }, not body padding.

Authoring Workflow

1. Fetch and validate data first (check for empty/None); sample or aggregate to a sensible size.
2. Read .agents/skills/ui-design/SKILL.md and commit to a typographic pairing + color direction.
3. Build the full document — inline CSS/JS, embed DATA, draw charts from it; add the @media print block.
4. Write to <task_name>/report.html (UTF-8). Image-heavy → reference the charts already in <task_name>/charts/*.png relatively as charts/*.png.
5. Open it and print-preview, then cite the report to the user as a clickable link.

Use the Quality Checklist below to verify before delivering.

Quality Checklist

• Full <!DOCTYPE html> document; CSS and JS inline; only allowlisted CDNs referenced
• Data embedded via <script>const DATA = {json.dumps(..., ensure_ascii=False)}</script>; large datasets sampled/aggregated
• Multi-file (if used): all asset paths relative, all assets under the report's task directory
• Every color in var(--color-role, #literalFallback) form — no bare var(), no unvariabled hardcodes
• Charts: wrapper-div heights, maintainAspectRatio: false, getComputedStyle + literal fallback for canvas colors
• @media print block present: hides chrome, break-inside: avoid, sane @page margins, animations/opacity neutralized
• Interactivity (if any): events via addEventListener (no inline on*=), runs on embedded DATA (no live fetch), default state is meaningful, controls .no-print and collapsed content expands when printing
• User's stated preferences (this chat / long-term memory / saved prefs) honored wherever they differ from this skill's defaults
• Design follows .agents/skills/ui-design/SKILL.md (typography, single accent, profit/loss color discipline, no AI slop)
• Written to <task_name>/; numbers correctly formatted; opened and print-previewed; cited to the user as a link