HTML Visualizer

Generate content-layer artifacts: standalone HTML files that feel like Claude-generated artifacts in usefulness, routing, interaction, and polish. Do not draw Claude's host chrome unless the user explicitly asks for a Claude UI mockup.

The output must be:
- independently understandable outside chat
- useful in the first viewport
- matched to the content type, not forced into one diagram style
- responsive, dark-mode aware, and visually restrained
- honest about AI, storage, publishing, and external services
- easy for a later agent to modify through stable structure and metadata
- verified with the bundled scripts whenever possible

Mandatory Reading

For every artifact-like task, read these first:

1. references/artifact-product-protocol.md
2. references/content-visualization-routing.md
3. references/visualization-routing-examples.md
4. references/artifact-kind-patterns.md
5. references/artifact-visual-effects.md
6. references/artifact-output-contract.md
7. references/typography-and-color.md
8. references/claude-official-alignment.md
9. references/claude-field-observations.md

Then read only the specific reference files needed for the selected kind, subject, or rendering technique.

For skill maintenance or “not Claude-like enough” feedback, also read:
- references/artifact-forward-test.md
- references/artifact-failure-remediation.md
- references/strategy-confidence-audit.md
- references/claude-field-research-protocol.md
- references/TESTING.md
- references/claude-official-alignment.md
- references/claude-field-observations.md

Core Workflow

Before writing HTML, form a routing brief. You do not need to show it unless useful, but the file must reflect it.

artifact_needed: yes/no, and why
artifact_kind: html-app / ai-app / visual-explainer / interactive-simulation / data-viz / courseware / ui-prototype / document / code-file / diagram-text
content_archetype: process / dynamic-flow / mechanism / state-machine / data-table / trend / comparison / composition / hierarchy / relationship / timeline / spatial / text-evidence / formula-parameter / ui-workflow / tool / ai-tool / lesson / document / code-system
experience_model: product-prototype / work-tool / ai-assistant / learning-game-lesson / data-analysis / mechanism-explainer / shareable-document
primary_user_value: what the user gets immediately in the first viewport
canvas_structure: single-visual / split-inspector / dashboard / workbench / courseware / document / prototype-stage / app-shell
interaction_intensity: static / guided / animated / manipulative / generative
visual_style_profile: default Claude-like neutral / user preference as accent / provided brand system, plus boundaries
primary_reference_files: exact references to follow
must_have_actions: copy / export / reset / history / download / pause / none
verification_focus: formulas, data, states, motion, accessibility, or viewport concerns to prove
rejected_alternatives: at least one tempting but wrong approach

Execution order:

1. Run the artifact decision gate before creating files.
2. If artifact_needed:no, stop artifact generation: the deliverable is a direct answer in chat or a small code block; create no HTML file, HTML wrapper, artifact-meta, dashboard, fake canvas, or placeholder file.
3. If the user asked for current data, real images, file generation, code execution, web research, or connector/private data and the required source/tool/authorization is missing, route to the matching boundary reference instead of inventing an artifact.
4. If artifact_needed:yes, pick artifact_kind, content_archetype, and experience_model before choosing SVG/Canvas/Chart.js.
5. Match the closest example in references/visualization-routing-examples.md.
6. Read the kind recipe in references/artifact-kind-patterns.md.
7. Read visual, output, and typography references.
8. Read only the domain-specific references needed by the selected route.
9. Draft the page blueprint: first viewport, primary surface, support surface, states, actions, metadata.
10. Generate the HTML.
11. Run validation commands and fix failures before delivery.

Routing Rules

Use the user's real intent, not keywords alone:

Experience Model Standards

• product-prototype: realistic task UI with at least two meaningful states such as empty, loading, error, success, selected.
• work-tool: usable controls, output, reset/clear, and copy/export/history when useful.
• work-tool for algorithmic art: use a real Canvas/SVG composition with algorithmic art,
  visible seed control, parameter controls, regenerate, reset, and export PNG.
  Include an image generation boundary: this is deterministic local rendering unless a
  real image pipeline is invoked. Avoid static poster only, browser-side image API keys,
  and unseeded random output.
• ai-assistant: input, mode strip, structured result, loading/error/empty, copy/history, and an honest baked / host-live / external-backend boundary.
• learning-game-lesson: core relation first, then stepper, quiz, score, feedback, reveal, or simulation.
• data-analysis: KPI, main chart, insight cards, visible source table / 源数据表 heading or caption, units, and correct chart type.
• data-analysis for mixed-scale trend data: include a visible chart choice note, explicit mixed-scale handling, trend annotation, source table, and copy summary; use dual-axis, normalized small multiples, or another justified comparison view, with no pie chart for trend data and no single-axis flattening.
• work-tool for provided weather snapshots: build a weather snapshot planner only when the user asks to save/reuse/plan from provided data. Keep weather data display boundary, source-backed snapshot, retrieved at, source/time, snapshot/live boundary, no fake Google Maps, no fake weather, activity planner, chart/table, and copy/export/reset visible.
• mechanism-explainer: main diagram, inspector/evidence, state or flow where relevant.
• mechanism-explainer for an inline visual converted to a durable artifact: show a preview diagram
  tied to diagram source, keep source-to-preview mapping, expose copy diagram source,
  state the download SVG/HTML boundary and save as artifact boundary, and include
  no fake Claude host save as a boundary when host persistence is unavailable.
• shareable-document: executive summary, outline or sections, copy actions, evidence tables when useful.

Output Contract

Every full artifact must include:

• <main data-artifact-root>
• a first-viewport <section data-primary-surface> containing the actual work
• <section data-support-surface> when controls, evidence, history, or tables exist
• <section data-error-boundary> for JS-heavy artifacts
• <script type="application/json" id="artifact-meta"> with fields from references/artifact-output-contract.md, including experience_model

Keep editable material in DATA / CONFIG objects where possible. Use stable ids/classes and clear render/update/reset functions so later edits are local.

Visual Standards

Follow references/typography-and-color.md and references/artifact-visual-effects.md.
Use references/claude-official-alignment.md to calibrate Claude-like behavior:
route the artifact by content type, keep the work product in the first viewport,
use warm neutral surfaces and sparse semantic accents, and never copy Claude host
chrome unless the user explicitly asks for a Claude UI mockup.

Key defaults:
- first viewport shows the artifact's useful product, not a feature explanation
- mobile first viewport: data-primary-surface must start early enough to be
prominent in the first viewport; keep compact capability/status strips,
horizontally
scrollable, or move details to data-support-surface instead of stacking
long explanation chips above the workbench
- for data-viz / dashboard, KPI strip alone is never enough for data-primary-surface; the primary surface must include the main chart/table/work area
- every HTML artifact declares and uses these baseline semantic CSS tokens in light and dark mode: --ink, --muted, --paper, --soft, --line; aliases may exist, but these exact names are required for validators and later edits
- neutral base, 1 primary semantic color, 1 secondary semantic color; state colors only for state
- user style preferences such as "pink", "dark", "hand-drawn", or "Claude-like" must become a bounded style profile: keep the neutral base, use the requested style as an accent or documented brand system, and do not claim persistent Claude account memory
- when a visual preference affects an artifact, include style-preference-boundary and bounded style profile in artifact metadata/capabilities, and make style_profile explicitly name neutral base, the user accent such as pink accent, and semantic state colors
- if the user asks to remember a future visual style but also says not to generate a webpage/artifact, answer in chat as no-artifact; explicitly say the preference is bounded to the current context/project and use the phrase "not saved to the Claude account / 不是 Claude 账号级记忆"; do not claim global persistent memory unless project/global rules are actually edited
- do not create or modify AGENTS.md, memory, project rules, or global rules for a style preference unless the user explicitly asks to persist the preference there
- no decorative orbs, bokeh, glassmorphism, blurred backgrounds, or generic radial gradients
- do not use linear-gradient, box-shadow, backdrop-filter, or blurred decoration for normal content artifacts; use borders, spacing, tone contrast, and data-driven color instead
- cards are for repeated items, modals, and framed tools; avoid cards inside cards
- controls must look and behave like real controls
- primary surface and page background must have clear visual separation; a
workbench/editor stage should not rely on the same background color as the
page, because surfaceSeparated browser checks treat that as a weak canvas
- editor-canvas artifacts must expose data-toolbar, data-editor-canvas,
data-object-list, and data-inspector; metadata capabilities must include
editor-canvas and selection-state; inspector input[type="color"],
select, and property controls need at least min-height: 30px
- interactive SVG/chart marks must have a real hit target at least 30px by 30px; do not put role="button" or tabindex directly on thin SVG paths, arcs, ticks, or tiny dots unless a transparent hit target or external button/legend row carries the interaction
- hidden input[type="radio"] / input[type="checkbox"] controls inside a visible label or pill must either cover that visible label with inset:0, width:100%, height:100%, min-width: 30px, and min-height: 30px, or the visible input/label itself must be at least 30px by 30px
- source tables must have a visible source table / 源数据表 heading or caption; they must not widen the page: wrap wide tables in a max-width: 100% container with overflow-x: auto, and make row-select/action controls display: inline-flex with min-width: 30px and min-height: 30px
- every full HTML artifact must include an explicit overflow-x:hidden guard on html,body
- animation must explain change; long or continuous motion needs pause/reset and reduced-motion support
- mobile must not crop text, controls, or the primary surface

AI, Storage, Publish

Claude's host may provide AI, storage, publish, sharing, embed, and MCP. Local HTML does not.

Official host details that affect routing:
- roughly 15 lines is only a soft artifact threshold; independent canvas value
matters more than line count
- editing a prior user message creates a conversation fork; local version
controls are not Claude chat lineage
- Cowork live artifacts are host-local, currently private/non-shareable
workspaces with host version history
- AI-powered artifacts do not require user API keys in Claude, but usage counts
against the user's plan; current input is text-oriented and arbitrary external
APIs still require a connector or backend
- connector/local-file approval is per user and limited to the explicitly
approved scope

Use:
- ai_mode: none when no AI behavior exists
- ai_mode: baked for precomputed examples or rule-based local behavior
- ai_mode: host-live only when a host explicitly injects an AI adapter
- ai_mode: external-backend only after a real backend/API/key plan exists

Never hard-code vendor API endpoints, ask for browser-side API keys, or claim local HTML has Claude account capabilities.

Domain References

Read only what matches the route:

Courseware Rules

For lesson or problem-solving tasks:

1. Build a lesson blueprint before HTML.
2. Identify subject, lesson type, input source, and core claims.
3. For STEM problems, solve and verify reasoning before adding animation.
   Computational STEM pages must define a source_of_truth: problem_spec,
   computed_values, answer_bindings, and visual/model data all come from
   the same source, not duplicated by hand in separate formula, chart, Canvas,
   or 3D blocks. For science/engineering workbenches, also expose a deterministic
   calculation kernel or formula model, units, model_points, live readout bindings,
   and checks covering answer card == final step, visual readout == computed_values,
   and model_points come from problem_spec. For exact/symbolic domains, follow
   references/validation/computational-stem-kernel.md: use a deterministic
   calculation kernel when it reduces correctness risk, but do not add a large
   external dependency unless it is licensed, available, and worth the V1 cost.
4. Treat computational STEM as an explicit capability cluster: solid geometry,
   analytic geometry, physics workbenches, chemistry workbenches, biology variable-control labs,
   and intake/spec-review workbenches all follow the same product pattern.
   Normalize text / image / random inputs into one problem_spec, review a recognized spec before
   solving image-derived problems unless visible assumptions are explicitly allowed, and run
   clean-answer resampling before rendering random practice. Borrow EduLab's structured spec/kernel/
   render/check pattern where useful, but keep the current html-visualizer neutral base,
   restrained semantic accents, and output contract.
5. For humanities/language tasks, use text evidence, annotation, structure, and answer framing instead of STEM-style flowcharts.
6. Include a main visual plus guided interaction: stepper, quiz, reveal, slider, sorting, or prediction.
7. Preserve answer checks, misconceptions, and verification logic.

Rendering Rules

• Standalone HTML may use normal CSS, but keep it inspectable and restrained.
• SVG viewBox default width is 860 for standalone outputs unless the specific reference says otherwise.
• Use CSS variables for colors and dark mode.
• SVG paths, arcs, and small glyphs are visuals first. If they are clickable, add an invisible rect/wide stroke hit target of at least 30px by 30px, or make the adjacent HTML legend/list row the accessible button.
• For Canvas/RAF simulations, use real elapsed time, fixed scale, locked parameters during playback, and pause/reset.
• For dynamic SVG flow, do not use animateMotion; use JS-controlled transforms and keep paths inspectable.
• For text/file-tree outputs, prefer copyable <pre> or tables over graphical boxes.

Verification

After generating or modifying an artifact, run the strongest relevant checks:

python scripts/lint_artifact.py <artifact.html>
python scripts/check_artifact_visual_quality.py <artifact.html>
node scripts/check_artifact_actions.js <artifact.html>
node scripts/check_artifact_ai_flow.js <artifact.html>  # for ai-app / ai-assistant
node scripts/check_artifact_interaction_flow.js <artifact.html>
node scripts/check_artifact_editor_canvas.js <artifact.html>  # for editor/authoring canvas
node scripts/check_artifact_surface_quality.js <artifact.html>
node scripts/check_artifact_layout_polish.js <artifact.html>
node scripts/check_artifact_viewport.js <artifact.html> --width 390 --height 844
node scripts/check_artifact_viewport.js <artifact.html> --width 1024 --height 760
python scripts/check_stem_source_of_truth.py <artifact.html>  # for STEM/math/physics/courseware

For skill-wide regression:

python validate_skill.py
python scripts/evaluate_forward_artifacts.py examples/forward-artifacts.sample.json
python scripts/evaluate_forward_artifacts.py examples/forward-artifacts.sample.json --score-draft
python scripts/check_routing_oracle.py examples/routing-oracle-cases.json --evidence examples/routing-oracle-evidence.json --summary
python scripts/check_coldstart_outputs.py examples/coldstart-eval-cases.json --init-manifest -
python scripts/check_forward_sample_quality.py examples/forward-artifacts.sample.json
node scripts/check_forward_sample_surface_quality.js examples/forward-artifacts.sample.json
node scripts/check_forward_sample_layout_polish.js examples/forward-artifacts.sample.json
node scripts/check_forward_sample_actions.js examples/forward-artifacts.sample.json
node scripts/check_forward_sample_ai_flows.js examples/forward-artifacts.sample.json
node scripts/check_forward_sample_interactions.js examples/forward-artifacts.sample.json
node scripts/check_forward_sample_editor_canvases.js examples/forward-artifacts.sample.json
node scripts/check_forward_sample_viewports.js examples/forward-artifacts.sample.json
python scripts/check_official_alignment_cases.py
python scripts/check_official_sample_coverage.py
python scripts/check_official_visual_diversity.py
node scripts/check_official_sample_artifacts.js
node scripts/check_official_sample_artifacts.js --viewports
node scripts/check_official_sample_viewports.js

If a check fails, fix the rule/source artifact first, then rerun the same check. Do not hand off a failing artifact as complete.

Delivery

Return the generated file path and a short verification summary. Mention unverified risks honestly. Do not claim Claude-host features unless the target host actually provides them.