Skip to content

[feat] synthpanel report --format html — single-file HTML rendering for stakeholders #331

@openclaw-dv

Description

@openclaw-dv

Why

Researchers run a panel and get JSON. Their stakeholders (PMs, execs, designers) are not the consumers of JSON. The current paths to a stakeholder-readable artifact are:

  • Open the JSON, copy interesting bits into Slides
  • Run `synthpanel report` and screenshot the terminal output
  • Open the JSON in a viewer and screenshot

All friction. The `sp-viz-layer` spec (`specs/sp-viz-layer/questions.md`) frames this exactly: "non-terminal humans aren't the primary consumers of those files."

Sketch

```bash
synthpanel report run-2026-04-30T14-22 --format html --output panel-report.html
```

Single-file HTML (inline CSS, inline data, no external deps so it survives email + Slack uploads):

  • Header: panel metadata (date, N personas, models used, total cost)
  • Per-question section: the question, response distribution chart (Likert bars, multiple-choice donut, free-text theme cloud)
  • Synthesis block: themes / agreements / disagreements / surprises / recommendation
  • Per-persona detail (collapsed by default, expandable)
  • Cost rollup table

Why this is medium-difficulty

  • Need to pick a charting approach. Options: inline SVG (zero dep), `Chart.js` via CDN (rejected — not single-file), `uPlot`/`apexcharts` inlined (works but adds page weight), pure HTML/CSS bars (limited but always ships)
  • Color theming: should match `site/` styling if the marketing site has tokens; otherwise pick a defensible default
  • Accessibility: chart contrast, alt text for visual elements, keyboard navigation in the per-persona expandables

Investigate

  • `specs/sp-viz-layer/research/` — the research polecats may have already mapped existing-tool comparables (Great Expectations, Prefect, MLflow, evidently-ai)
  • `src/synth_panel/cli/output.py` — `OutputFormat` enum
  • `src/synth_panel/persistence.py` — how saved runs are loaded
  • `site/` — existing styling tokens that could be reused

Acceptance

  • Single .html file, opens correctly in Chrome/Firefox/Safari without internet
  • No external CDN dependencies
  • Renders charts for likert / multiple-choice / free-text
  • Synthesis section is the visual focal point (per the sp-viz-layer framing)
  • Test: golden-file comparison against a fixed input run

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions