visual-explainer

Visual Explainer

Produce editable source and verified, self-contained HTML. The default explainer theme uses the Hairline preset across posters, diagrams, slides, and videos. An explicit brand or requested look takes precedence. Prefer prose when a visual would add no understanding.

Remove any element whose absence changes neither meaning nor operation. Do not add kickers, decorative numbering, badges, metric tiles, or tiny uppercase labels to create hierarchy. Use composition, spacing, readable typography, and direct language.

Use the installed CLI

Require Node 22.12 or newer. Set SKILL_DIR internally to the absolute directory containing this file. Use node "$SKILL_DIR/scripts/artifacture.mjs" for init, add, list, export, video, engine, and verify. The CLI handles runtime setup, required npm packages, and workspace stylesheet imports. The user only installs the skill and asks for an artifact; do not ask them to configure paths, caches, or a second checkout.

When authoring imports or following a reference that uses npm --prefix REPO, obtain the ready runtime with REPO=$(node "$SKILL_DIR/scripts/artifacture.mjs" path). Pass absolute source and output paths. Private brands and copied consumer edits remain user-owned. See installation.md only for development overrides or troubleshooting.

Author, export, verify

1. Select one route below and read its card. Read additional references only when the selected route calls for them.
2. For a standalone chart, author a LieflatChart JSON envelope; for a data story, compose its figures in MDX. Archify uses typed JSON. Otherwise author .mdx by default, or .tsx for local state, generated/custom SVG, or video. Import shared components from REPO/visual-explainer-mdx/components.tsx.
3. Export chart JSON with node "$SKILL_DIR/scripts/artifacture.mjs" chart <abs-source.json> --out <abs-output.html>. Archify uses its validated delivery command. For MDX/TSX, use node "$SKILL_DIR/scripts/artifacture.mjs" export <abs-source> --out <abs-output>; for static HTML, use export-static. Fix export failures in the source.
4. Read verification.md, execute its routed checks, open the artifact, and report the source, HTML, report JSON, and any incomplete verification.

Completion requires editable source, a successful export, and evidence for every required verification pass. Apply feedback to the source and re-export.

Choose a route

Request	Read first	Read only when needed
React workspace, reusable components, or seekable scene motion	react-workspaces.md	Discover actual APIs with the component CLI; copy local leaf modules instead of importing the full renderer into an app.
chart or quantitative data	charts.md	Select unit, record, time, or relationship encodings; use basic comparisons when the evidence is sparse.
diagram or architecture	web-diagram.md	The card routes custom geometry and specialized diagrams.
implementation plan	visual-plan.md	—
comparison or data table	comparison-table.md	—
slides or presentation	slide-deck.md	For bespoke fixed-stage presentation chrome, read deck-navigation-shell.md, then slide-patterns.md.
interactive Hairline figure	vendored Hairline skill	Use its unchanged kernel, bench, build, and validation workflow.
motion video	generate-video.md	Use the Hairline motion baseline; read video-collections.md for shared episodes and instructional modes. Use render-video.md for an existing deck.
native mathematics or physical motion	native-engines.md	Manim Community or Psychopomp renders source into reusable clips and selected stills.
ASCII, texture treatments, or 3D model media	media-effects.md	Copy controlled effects and preserve media decoding ownership.
reference image to low-detail procedural 3D	procedural-models.md	Use the installed img2threejs skill and reuse its reviewed factory across outputs.
code walkthrough	code-walkthrough.md	—
explain a diff	explain-diff.md	—
project recap	project-recap.md	—

For point-and-click annotation, read annotate.md. If the request lacks a material choice that cannot be inferred, read clarify.md. For a component API not shown by the selected card, read mdx-components.md. For poster, video, brand-heavy, or bespoke HTML work, read legacy-html.md and only the branch it selects.

Authoring rules

• Keep MDX/TSX, chart JSON, or Archify JSON as the source of truth; generated HTML is disposable output.
• Prefer shared components, semantic content, and tokens over hand-authored coordinates or page CSS.
• For illustrations, read default-explainer-theme.md. Reuse shared geometry across formats; isolate strict Hairline pointer figures from seekable video scenes.
• For reusable React work, keep the scene → composition → slide → video boundary. Sample explicit time, author narrow layouts separately, and call disposeGraphicVideo when a registered host leaves.
• Use LieflatChart for editorial data stories and DataChart for quick bar, line, or dot comparisons. Marks must encode evidence; never invent records or quantities to fill a pattern.
• When adjusting type, read typography.md. Compose readable text blocks through measure, grouping, weight, and spacing.
• Use DiagramCanvas for compact supported layouts; use Archify for complex typed system maps. The diagram card routes both. Keep labels readable at initial scale: at least 14px in figures and 16px in body copy. Resize or split content before shrinking it.
• Discover dag for compact multi-parent dependencies, keyboard focus and lineage tracing. Its labeled scene and authored reveal reuse the existing graphics, slides and video pipeline; the interactive list remains a page control.
• Treat facts, labels, and visual encodings as claims. Keep them traceable to the user brief or inspected sources; mark uncertainty instead of inventing rationale.
• Preserve accessibility, responsive containment, and reduced-motion behavior. Optional metadata requires factual state, sequence, provenance, ownership, or navigation.

Use delegated-skills.md only when its delegated visual/prose checks are available. Use model-routing.md only when dispatching visual-review passes. The main thread orchestrates those passes and consumes their evidence; a visual-capable reviewer judges screenshots.