Zero-dependency, single-file HTML design system & agent skill for LLMs.
Inspired by shadcn/ui. 100% offline. 0 npm packages. 0 external CDNs.
Optimized for Claude Code, Pi, Codex, and Cursor.
Installation · The Problem · What You Get · The 7 Archetypes · Component Library · Prompt Triggers · Star History · Support
👉 Click the preview above or visit agent-html-bice.vercel.app to test the live interactive component gallery & archetype previews.
🎬 30-second promo (plays inline, muted) · 1080p MP4 with soundtrack
Install directly into your coding agent (Claude Code, Cursor, Pi, Codex, Copilot, etc.) with zero manual cloning:
# Install to current project workspace
npx skills add QingYunA/agent-html
# Or install globally across all 70+ agents on your machine
npx skills add QingYunA/agent-html -gNo build step or Node.js server required. Explore the component gallery (or test online directly at agent-html-bice.vercel.app):
# Open the interactive component gallery in your browser
npx agent-html open
# Extract any raw archetype directly to a file
npx agent-html snippet button
npx agent-html template dashboard > api-dashboard.html
npx agent-html template kanban > my-kanban.htmlManual Git Symlink Setup (Alternative)
git clone https://github.com/QingYunA/agent-html.git ~/Code/agent-html
# Link into universal agents directory
ln -sf ~/Code/agent-html/skills/agent-html ~/.agents/skills/agent-html
# If using Claude Code or Pi:
ln -sf ../../.agents/skills/agent-html ~/.claude/skills/agent-html
ln -sf ../../../.agents/skills/agent-html ~/.pi/agent/skills/agent-htmlWhen asking LLMs (Claude Code, Pi, Codex, ChatGPT) to generate an HTML dashboard or report, the output usually falls into one of two traps:
- The CDN trap: The model injects
<script src="https://cdn.tailwindcss.com"></script>and external Google Fonts. It looks acceptable at first glance, but breaks completely in air-gapped corporate intranets, takes 2 seconds to parse, causes flash-of-unstyled-content (FOUC), and rots over time when CDN endpoints change. - The visual slop trap: If you forbid CDNs, the model hallucinates raw inline CSS with garish colors, harsh pure-black borders, random 30px paddings, broken alignment, and zero dark mode support.
agent-html fixes this by packaging a tight ~75-line native CSS token sheet and 7 battle-tested layout archetypes. Double-click any generated file in Finder, and it renders instantly with enterprise-grade polish.
- Zero dependencies: No
node_modules, no npm build step, no CDN links. Every file runs offline and standalone. - Zinc-neutral design tokens: A pure CSS variable port of shadcn/ui. 1px borders, subtle radii, clean typography, and high information density.
- 7 structural layout archetypes: Scaffolds for Reports, Dashboards, Workbenches, Side-by-Side Comparisons, Timelines, Kanban Boards, and diff-based Code Reviews ready to copy.
- Native light & dark modes: Seamless switching with CSS variables and a 5-line vanilla JS toggle.
- Closed-loop feedback: Built-in "Copy as Markdown" and "Copy Review Decisions" affordances so static HTML files never become dead ends.
- Deterministic verification linter: Includes
scripts/validate.mjsso agents self-test tag symmetry, zero-CDN compliance, and viewport setup before presenting files to humans. - 32 curated vector SVGs: Lucide-style inline vector icons with
stroke="currentColor"that adapt to font colors without font files. - Zero-CDN Pure SVG charts: Area trends, columns, donuts, dual lines, ranking bars, gauges, stacked columns, and 7×24 heatmaps, plus one shared hover tooltip.
- Tabs & form controls: Accessible tabs, labelled inputs, selects, checkboxes, switches, and segmented radios that copy their values back to the agent.
- Judgment-first evals: 12 eval cases, including ones where the right answer is not to make HTML.
Rather than rigid business screens, agent-html provides 7 fundamental layout scaffolds with clear <!-- [Slot: ...] --> injection points:
| Archetype | Template Path | Best For | Key Capabilities |
|---|---|---|---|
| 01. Report | templates/en/report.html |
Technical reviews, RFCs, audits | TOC ScrollSpy, KPI score overview, details accordion, print CSS |
| 02. Dashboard | templates/en/dashboard.html |
Metrics monitoring, billing | 4 KPI cards, native SVG area & bar charts, filterable table |
| 03. Inspector | templates/en/inspector.html |
Trace inspection, prompt debugging | 100vh split screen, item filtering, JSON payload viewer, review actions |
| 04. Compare | templates/en/compare.html |
Model A/B testing, prompt diffs | Dual baseline vs challenger cards, delta comparison matrix |
| 05. Timeline | templates/en/timeline.html |
Incident postmortems, changelogs | Single-track vertical timeline, status dots, diagnostic logs |
| 06. Kanban | templates/en/kanban.html |
Bug triage, backlog grooming | 4-column drag & drop, status badges, agent feedback loop |
| 07. Review | templates/en/review.html |
PR & patch code review | Paste raw git diff, line-anchored findings with severity, per-file verdicts, copy review back to agent |
📸 Click to view full-resolution static screenshots for all 7 archetypes
Beyond full-page archetypes, agent-html packages production-grade atomic primitives and zero-CDN pure SVG charts. 100% offline, zero npm, zero external CDN, and instant dark mode support:
Semantic variants aligned with shadcn/ui standards, complete with :hover, :active, and :disabled micro-interactions:
| Variant | Class | Semantic Role | Common Use Case |
|---|---|---|---|
| Primary | .btn.btn-primary |
Solid high-contrast block | Submit, approve, primary CTAs |
| Secondary | .btn.btn-secondary |
Neutral subtle background | Cancel, back to list, secondary filters |
| Outline | .btn.btn-outline |
1px border stroke | Export report, copy Markdown, view details |
| Ghost | .btn.btn-ghost |
Transparent, hover-only fill | Table row actions, breadcrumbs, link buttons |
| Destructive | .btn.btn-destructive |
Semantic warning red | Block release, drop database, abort workflow |
| With Icon | .btn with inline <svg> |
Icon + text pair | Download PDF, refresh status, search |
| Icon Button | .btn.btn-icon |
32x32px square | Theme toggle, settings, collapse trigger |
<!-- Ready-to-copy button snippets -->
<button class="btn btn-primary">Approve Release</button>
<button class="btn btn-secondary">Previous Step</button>
<button class="btn btn-outline btn-sm">
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
<span>Export PDF</span>
</button>
<button class="btn btn-destructive btn-sm">Block Deployment</button>
Zero external JS chart libraries required. Uses standard inline SVG for crisp, Retina-sharp rendering that never breaks:
| Chart Type | Native Mechanism | Key Advantage | Typical Use Cases |
|---|---|---|---|
| 📈 Area Trend | Bezier curves with linearGradient |
Zero load time, smooth gradient | 24h throughput (TPS), latency trends |
| 📊 Column Histogram | Rounded rect with data value labels |
High contrast, intuitive comparison | P95/P99 latency distribution, error codes |
| 🍩 Multi-Segment Donut | circle with stroke-dasharray offsets |
Pure CSS variable math, zero JS | Node health ratio, resource allocations |
| 📉 Dual-Line Ingress/Egress | Solid line vs dashed comparator line | Dual-metric temporal correlation | Inbound vs outbound traffic, baseline vs test |
| 📑 Horizontal Ranking Bar | Pill progress bars with semantic colors | Maximum space efficiency | Slow query ranking, TTFT by model |
| ⏱️ Semi-Circle Gauge | Semi-circle stroke arc with gradient | Immediate threshold alert | Memory watermark, API rate-limit quota |
| 🧱 Stacked Column | Stacked rect segments from a zero baseline |
Total and composition in one glance | Errors by category per week, cost by service |
| 🟪 Heatmap (7×24) | Grid of rect with a single-hue ordinal scale |
Spots patterns across two dimensions | Builds by weekday × hour, errors by service × code |
Where is the SVG chart code?
The full, canonical code for all eight chart forms (and the shared data-tip hover tooltip) lives in one place — skills/agent-html/references/components.md, section 6.
It is deliberately not duplicated here. Two hand-copied versions of the same snippet always drift apart, and a stale copy in a README is worse than no copy: an agent that copies it produces a broken chart. (We learned this the hard way — see skills/agent-html/references/failures.md F-014.)
Each chart there ships with the four-part contract: a conclusion-style title, a subtitle stating the unit contract (1 rim dot = 300 TPS), the body, and an uppercase encoding caption. The contract itself is specified in SKILL.md.
Designed with stroke="currentColor" to automatically inherit font size and color in light and dark modes:
| Category | Curated Icons | Engineering Context |
|---|---|---|
| System & Shell | Search · Terminal · Settings · Activity |
Global search, CLI output, settings, healthcheck |
| DevOps & Git | Branch · Commit · PR · Bug |
Code reviews, trace audits, changelog releases |
| Status & Verdicts | Check · Alert · Shield · Lock |
Pass badges, critical blockers, security audits |
| Actions & Data | Copy · Download · Calendar · Filter · Refresh |
Copy back to Agent, PDF export, date ranges |
| Infrastructure | Server · Database · CPU · External |
Host metrics, slow queries, cluster CPU, RFC docs |
| Review & Docs | Plus · Minus · File · Folder · Eye · Comment · Flag · Clock |
Diff stats, file trees, review threads, due dates |
<!-- Automatic theme & color inheritance -->
<span style="display: inline-flex; align-items: center; gap: 6px; color: var(--ok);">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>
<span>All test suites passing</span>
</span>Once installed, prompts like:
- "Generate a standalone HTML dashboard for our cluster metrics with a trend chart"
- "Create an executive evaluation report for candidate John Doe as a single file"
- "Build a side-by-side prompt comparison matrix in HTML"
- "Don't write a wall of markdown, give me a clean single-file visual report for this PR review"
will automatically trigger the agent-html skill and produce clean, zero-dependency, self-contained files.
All atomic HTML slots (buttons, badges, callouts, KPI stat cards), tabs, form controls, 32 currentColor vector SVGs, zero-CDN pure SVG charts, and vanilla interaction scripts are documented in skills/agent-html/references/components.md and live-previewed in index.html.
Join the discussion and share your feedback on LINUX DO.
If you find agent-html helpful, consider buying me a coffee to support continued maintenance and development!
MIT © 2026 QingYunA