Artifacture

Verified visual explainers for coding agents. Artifacture turns MDX/React sources into self-contained HTML artifacts: architecture diagrams, code walkthroughs, literate diff explainers, comparison tables, and slide decks. Verification is a routed family of skills: Artifacture runs deterministic mechanics and artifact-specific checks, Impeccable owns general visual craft, and Unslop owns prose. Visual judgment is dispatched to the smallest model and batch size that clears the relevant eval suite; the main agent orchestrates and summarizes instead of spending a frontier-model turn inspecting every screenshot.

Artifacture began as a fork of nicobailon/visual-explainer and preserves its spirit; see Credits below.

Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan. Instead of ASCII art and box-drawing tables, it authors MDX/React source, generates a self-contained HTML artifact, and opens it in your browser.

> draw a diagram of our authentication flow
> /visual-explainer:diff-review
> /visual-explainer:plan-review ~/docs/refactor-plan.md
> generate this in Blueprint style

Long-form explainer generated via /generate-video --style=long-form. Local render — no cloud, no API keys.

Mono-Industrial — the default aesthetic. Space Grotesk display, Space Mono labels, optional Geist Pixel Square for one moment of surprise per page. Grayscale canvas, status colors only on values.

The same MDX source under the Terminal preset — one of six locked aesthetics. Swap the preset, keep the content: the design system changes, the source never does.

Examples

Real output, deployed. Every link is an unedited artifact from the pipeline: one self-contained HTML file, view-source friendly. The full set lives at claytonkim.com/artifacture-examples.

Architecture diagram · computed layout, linearizes on mobile	Literate diff + quiz · background, walkthrough, comprehension check
Diff / terminal / JSON blocks · build-time Shiki, ANSI, collapsible trees	Slide deck · scroll-snap, keyboard nav, PDF export
Magazine · horizontal full-bleed spreads	Poster · fixed canvas, PNG export
Six presets · one source, six locked aesthetics	Explainer page · the default scrollable format

Video formats (9:16 reel, 16:9 long-form) render to MP4 through Hyperframes; sample clips are in docs/features.md.

What it adds to upstream visual-explainer

• ve-verify (scripts/verify/): a 200+ check deterministic design-quality gate — static scans, real-browser measurement (390px overflow, WCAG contrast in both themes, Mermaid render), and routed specialist judgment. Exit codes and JSON reports make it usable as a CI gate. Seeded-violation fixtures prove deterministic checks fire; the visual-model policy separately selects the smallest model and screenshot batch size that clear precision, recall, silence, grounding, schema, latency, and cost gates.
• Tiered agent docs: SKILL.md is a ~2.5k-token bootstrap plus one ~300-token card per use case (cards/). A covered flow reads about 3,100 tokens instead of 62,000. Deep references load only on escalation.
• 17 shared components (visual-explainer-mdx/components.tsx): DiagramCanvas with computed layout and CSS-only mobile linearization, build-time Shiki CodeBlock, DiffBlock, TerminalBlock, JsonTree, an interactive Quiz, MermaidBlock with zoom/pan chrome, decks, posters, and more. Strict-export integrity checks catch bad edge ids and undefined components at build time.
• PresentationDeck (visual-explainer-mdx/presentation.tsx): a second deck engine for presented (not scrolled) decks — a fixed 1920×1080 stage scaled to fit any screen, collapsible slide rail, two-axis keyboard navigation (Left/Right for slides; Up/Down for ordered click-ins or custom states, falling through to the next slide when exhausted), and drill-down primitives (click-to-expand cards/sheets with a click-anywhere-to-close guard, ladder/fanout diagrams, metrics, steppers). Fully --ve-* token-driven so every preset skins it; its behavioral contract is pinned by a headless eval suite (npm run ve:eval-presentation). See docs/presentation-deck.md for when to use it vs SlideDeck.
• /explain-diff: a literate diff mode (background → intuition → walkthrough → quiz), adapted from Geoffrey Litt's prompt pattern.
• Two model eval harnesses: evals/model-matrix/ compares artifact generation, while evals/visual-model-policy/ qualifies visual-verification models and screenshot batch sizes. Generation quality and review quality are deliberately not treated as the same benchmark.
• One-command team sharing: share.sh deploys to Vercel (zero setup, public) or sharehtml on Cloudflare (stable update-in-place URLs, team SSO via Cloudflare Access, comments). See docs/TEAM-SHARING.md.
• External design systems + ve:learn: brand token sets are user-owned artifacts resolved from a registry outside the skill ($ARTIFACTURE_DESIGN_DIR → ~/.artifacture/design-systems/ → repo design-systems/) and inlined into exports by preset name. npm run ve:learn -- <code-file|url|image> --name <slug> drafts a system from a token source, a live page, or an image palette; deterministic heuristics are pinned by their own eval suite (evals/design-systems/). The repo ships the mechanism only — systems (typically private brand tokens) live in your own registry. See docs/design-systems.md.

Skill family

Artifacture is the artifact-mechanics and evidence-routing member of a skill family:

Skill	Owns
Artifacture	export, browser/state coverage, clipping, containment, layout candidates, diagrams, operating-model fidelity, and evidence routing
Impeccable	general visual craft, design specificity, typography, color, generic decoration, and visual AI tells
Unslop	prose cadence, voice, and AI-writing patterns

Artifacture does not copy the other skills' judgment prompts. Legacy high-precision craft/prose detectors remain temporarily as candidate extractors: they can route evidence, but they cannot fail Artifacture. If a companion skill is missing, its pass is reported as skipped. Artifacture-owned visual judgment uses the smallest eval-qualified model and screenshot batch size; a frontier/main agent is not the automatic fallback.

See installation and family setup and the visual-model policy harness.

Install

Any agent with skills support (Claude Code, Codex, Cursor, and others), via the skills CLI:

npx skills add theclaymethod/artifacture

Install the recommended companion skills:

npx impeccable skills install
npx skills add theclaymethod/unslop

First generation clones the render pipeline to ~/.artifacture (one-time, Node >= 22); full-clone installs use the repo in place. The companion skills remain independently versioned and keep ownership of their prompts.

Claude Code, as a plugin:

git clone https://github.com/theclaymethod/artifacture.git
/plugin marketplace add ./artifacture

Manual, for any harness that reads file-based skills:

git clone --depth 1 https://github.com/theclaymethod/artifacture.git /tmp/artifacture
cp -r /tmp/artifacture/plugins/visual-explainer ~/.agents/skills/visual-explainer
rm -rf /tmp/artifacture

After installation, follow docs/installation.md to verify the render pipeline, detect missing companion skills, and install or generate a visual-model policy. Until a pass has an eval-qualified route, Artifacture reports no-eval-qualified-model rather than consuming the current large agent by default.

For the upstream project, see nicobailon/visual-explainer.

Commands

Command	What it does
/generate-web-diagram	Generate an HTML diagram for any topic (inline SVG by default, Mermaid fallback)
/generate-visual-plan	Generate a visual implementation plan for a feature or extension
/generate-slides	Generate a magazine-quality slide deck (vertical, or --magazine for horizontal editorial layout)
/generate-poster	Generate a single-canvas poster via poster-ai
/generate-video	Generate an explainer MP4 via Hyperframes (--style=long-form or --style=reel)
/render-video	Convert an existing HTML deck or magazine to an MP4
/diff-review	Visual diff review with architecture comparison and code review
/plan-review	Compare a plan against the codebase with risk assessment
/project-recap	Mental model snapshot for context-switching back to a project
/fact-check	Verify accuracy of a document against actual code
/share	Share an HTML page via sharehtml team access or Vercel fallback

The agent also kicks in automatically when it's about to dump a complex table in the terminal (4+ rows or 3+ columns) — it renders HTML instead.

For private team sharing setup, see docs/TEAM-SHARING.md.

Docs

• Features: the full capability reference, including all output modes, aesthetics, and how generation works.
• Installation and skill family: core setup, companion skills, failure behavior, and visual-model policy.
• Design systems: the external design-system registry format, resolution order, ve:learn token learning, and the agent-assisted refinement flow.
• PresentationDeck vs SlideDeck: which deck engine to reach for, the drill-down primitives, and the eval-pinned behavioral contract.
• Team sharing: one-command deploys to Vercel or a team-gated Cloudflare space.
• Skill docs: what an agent actually reads, plus the per-use-case cards.
• Verifier: the deterministic design-quality gate and its eval suite.
• Model-matrix harness: benchmark your own model or agent on the same briefs.
• Visual-model policy harness: select the smallest qualified model and safe screenshot batch size per routed pass.

Limitations

• Requires a browser to view HTML output
• Results vary by model capability
• Demo capture requires ffmpeg (always) plus either Playwright MCP or agent-browser (either one works)
• Video output (/generate-video, /render-video) requires Node ≥ 22 and FFmpeg; the skill runs hyperframes-doctor.sh at the start of any video command and aborts with install hints if prerequisites are missing

Credits

Artifacture is derived from nicobailon/visual-explainer (MIT) by Nico Bailon — the original skill concept, aesthetic system, and template library. Borrows ideas from Anthropic's frontend-design skill and interface-design.

The /explain-diff literate diff mode adapts Geoffrey Litt's explain-diff prompt. The Nothing aesthetic adapts dominikmartn/nothing-design-skill. Team sharing integrates jonesphillip/sharehtml as an optional backend. The component-contract and token-economics approach was informed by measuring modem-dev/sideshow's surface model. SVG text measurement guidance references chenglou/pretext.

Diagram rules and philosophy paraphrased (with attribution) from cathrynlavery/diagram-design (MIT, Cocoon AI).

Video output wraps HeyGen's Hyperframes (Apache 2.0) — local HTML → MP4 rendering via headless Chrome + GSAP + FFmpeg.

License

MIT