SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsagent-html

agent-html

Frontend & websites

View repository

Updated 10-15 23:24

About this skill

Agent HTML Design System and Componentization Specification

This specification guides AI Agents on how to generatehigh information density, industrial-grade texture, zero external dependencies, double-click to open instantlysingle-file HTML.

Zero, Value Judgment Rules: When to use HTML, and when to resolutely not use it (Judgment Rules)

Golden Rule：Markdown is the Source of Truth, HTML is the Human Review Surface.

Not all outputs need to be made into HTML. Before starting, the AI Agent must first make a value judgment:

1. Scenarios that prioritize HTML (having any of the following characteristics):

  • Spatial and multi-dimensional (Spatial): widescreen data dashboard, left-right two-column log reviewer, metric statistics grid, dense status kanban;
  • Parallel and comparative (Parallel / A-B): baseline vs challenger, version diff, model evaluation, solution trade-off matrix;
  • Interactive and instant filtering (Interactive / Filterable): containing dozens of records requiring millisecond-level search, multi-tab switching, accordion collapse and expand;
  • For formal human decision-making/archiving (Human Review Surface): formal architecture review, interview hiring report, technical retrospective white paper, release notes.

2. Scenarios where HTML must resolutely not be used (just stay in terminal Markdown):

  • Linear single-line content: ordinary Q&A, short explanations, single code snippet explanations (< 200 characters);
  • Pure terminal commands/scripts: shell commands that users need to immediately copy and execute in the terminal;
  • Information without spatial structure: running-account text with no tables, no comparisons, no dimensions; forcibly outputting HTML will interrupt the user's terminal flow and waste tokens.

3. After deciding to use HTML, then decide the granularity (Output Granularity)

This isthe second question, and it is equally important as the first question. Misjudging the granularity will give the user something far beyond or far below expectations:

Granularity Deliverable When to use
Fragment Single component card / one chart / one table Single-point conclusion, single comparison, user just wants a quick look
Evidence page One page: KPI overview + charts + key detail table 2–3 independent conclusions, need to present evidence but do not need a complete narrative
Full-page template One of the seven general templates (see the "General Layout Templates" section) Complete narrative delivery: report, retrospective, review, white paper

The default tier is "evidence page", not "full-page template". When the user says "analyze this dataset" or "help me build this dashboard" butdoes notsay "report / white paper / annual report / retrospective / review":

  • an evidence page must be delivered first(KPI + the strongest one or two charts + key details), and in the reply use one sentence to hint "if you need the full report, it can be expanded further";
  • must notupgrade itself to a full-page master template just because "the data is rich," "there are many conclusions," or "the user mentioned analysis";
  • Conversely, when the user explicitly asks for a "report / whitepaper," you must not deliver only a single chart.

When unsure,choose the finer granularity: give one more card, and the user will say "expand further" on their own; give one more six-chapter report, and the user will only feel overwhelmed.

I. Anti-Patterns to Avoid Checklist (Anti-Patterns to Avoid)

When generating HTML, the following common AI anti-patterns are strictly prohibited. They are divided into two groups:Engineering and delivery layer(1–10, most can be scripts/validate.mjs machine-determined) andData and semantic layer(11–17, most can only be reviewed by human eyes).

1. Engineering and delivery layer (1–10)

  1. Markdown in an HTML Trenchcoat (Markdown in an HTML Trenchcoat): merely using <p> and <h1> to wrap several large blocks of run-on text, with no use at all of cards, grids, status badges, or Callouts.
  2. Smuggling in external CDNs / remote fonts: introducing Tailwind CDN, Google Fonts, or CDN scripts. In offline environments or intranet server rooms, this directly fails to a blank screen.
  3. Dead-end UI / No Copy-back (Dead-end UI / No Copy-back): the user filters, checks boxes, or manually reviews on the page, but the page has no "copy results" or "export Markdown" button, so the operation cannot be brought back to the terminal for the Agent.
  4. Fixed-height Truncation (Fixed-height Truncation): setting height: 400px; overflow: hidden;, which causes content to be cut off directly under different systems or font sizes.
  5. Pretending to support dark mode: some elements hard-code #ffffff or #000000, causing text or background to blend together and become invisible in dark mode.
  6. Lack of mobile/small-screen responsiveness: no <meta name="viewport"> added or lack of @media breakpoints, causing horizontal scrollbars to explode in split-screen small windows.
  7. Lack of Empty State handling (Empty State): tables or lists are blank white when a search yields no results, with no "no matching records" prompt provided.
  8. Missing print styles (@media print): report-type pages have not been optimized with @media print styles, so buttons fly around when the user needs to export a PDF.
  9. Charts introducing heavy third-party libraries: introducing Chart.js/ECharts just to draw a simple line chart (with the risk of a blank screen when offline); you must stick to pure native vector SVG.
  10. Loss of key metadata and data precision: over-beautifying the layout while losing key error codes, timestamps, original IDs, or Traces, thereby losing engineering verification value.

2. Data and semantic layer (11–17)

This group is **"drawing the chart wrong" rather than "writing the page badly". They will not make the page error out, will not cause a blank screen, and validators cannot detect them, but they will make readersdraw wrong conclusions**—more dangerous than technical bugs, because they cannot be seen.

  1. Area/radius encoding not square-rooted: when using radius or dot size to represent values, you must Math.sqrt(v). Directly using the value as the radius makesthe area grow quadratically—a 2x difference is drawn as 4x, systematically exaggerating the gap.
  2. Truncated axis on bar charts: the contract of a bar islength ∝ value, and truncating the Y axis is breaking that contract. For extreme-value scenarios there are only three correct approaches: ① let the extreme value shoot through the roof (most honest) ② main chart + magnifier inset ③ tear the bar, not the axis (explicitly state it doesn't fit).
  3. Passing off aggregated numbers as raw records: spreading "37%" into 37 dots is acceptable, butyou must state it in the subtitle or footnote 1 点 = 1 个百分点; you may not fabricate nonexistent individual records just to fill out the density.
  4. Rounding without owning up: when percentages after rounding sum to less than 100 (e.g., 49+27+14+5+3 = 98), state in the footnote "the other 2% was eaten by rounding."Do not pad it to 100 with fake data.
  5. Color with no data meaning: it is forbidden to "grab five colors and sprinkle them evenly across all elements." Color must connect to a real dimension—ordinal ramps for values, categorical colors for categories, accent colors only for the single protagonist—and the footnote must clearly state what it encodes. After removing color, the structure of the chart should still be readable.
  6. Nondeterministic demo data: for demo/placeholder data, Math.random()is forbidden; deterministic pseudorandomness must be used.Refreshing twice must look identical, otherwise screenshots, screen recordings, and regression comparisons all become invalid.
  7. Adding interaction to elements with no real records: adding hover / click to purely decorative elements is deception. Before adding interaction, first ask "is there a real record behind this element?"—for the complete decision process, see thethree questions。

📕 Failure memories: thecauses, real cases, and review methodsof the above anti-patterns are in references/failures.md(12 entries). Before writing a new component, take a quick look—the spec tells you what to do, and the failure memories tell you what not to repeat. At the end of that document there is an index table that honestly marks which lessons have become machine constraints and which can still only rely on humans.

II. Why Design It This Way? (Design Principles & The "Why")

  1. Why insist on a pure single file with zero external dependencies (Zero-Dependency Standalone)?

    • Many visualization reports and use-case review tools are often opened in intranet server rooms, isolated environments without public internet access (Air-gapped), or local offline archives.
    • Introducing Tailwind CDN (cdn.tailwindcss.com) or third-party font libraries can cause a white screen (FOUC) on weak networks, failure when a CDN node goes offline, or blocking by corporate CSP policies. Therefore, refined CSS variables and minimal micro-scripts must be embedded directly.

  2. Why strictly adopt shadcn/ui's Zinc/Slate neutral color system?

    • When left to their own devices, large models easily produce "AI aesthetic drift"—random large corner radii, large areas of harsh gradients, and excessive meaningless whitespace.
    • The core of shadcn is:cool gray neutral base, precise 1px fine light borders, high information density, semantic status dots (Green/Amber/Red). This typography can make any data report look like a professional enterprise-grade product carefully tuned over several days by a senior front-end engineer.

  3. Why must dark mode (Light / Dark Theme) be natively built in?

    • Engineers and operations staff work extensively in dark IDE/terminal environments. With native mapping via CSS variables, just 5 lines of vanilla JS enable smooth switching, with zero build cost yet a greatly improved experience.

III. Seven Universal Layout Masters and Progressive Disclosure

Do not hand-write a complete page from scratch. After receiving a requirement, first choose from the following 7universal layout mastersthe skeleton that is closest. A bilingual Chinese-English master system is supported, aligned with the user's input language:

  • English scenarios: refer to assets/templates/en/<name>.html
  • Chinese scenarios: refer to assets/templates/zh/<name>.html

🗂 The assets in this repository are divided into three layers; don't mix them up:

Layer Location What it is How to use it
Skeleton (master) `assets/templates/zh en/*.html` The authoritative source for full-page layouts
Parts (component dictionary) references/components.md The authoritative source for fragments such as buttons/cards/charts Take individual fragments as needed
Finished documents (cases) examples/(repository only) Finished products that have gone through the full process with real data and passed all gates If you're unsure what the deliverable should look like, look here first

What is delivered to the user is always a single-file finished product, assembled from masters or components. Each asset has only one authoritative source. The same piece of code is not allowed to be stored in two places—two hand-copied duplicates will inevitably drift (see references/failures.md F-014). When duplication is found, keep one place and change the other to a pointer. examples/README.md It records item by item which easily forgotten rules that case demonstrated, including onethat gates cannot detect and only the human eye canchart scale error (F-015).

📌 All relative paths in this file are relative to the root directory of this Skill(i.e., the directory where SKILL.md is located), not relative to your current working directory. After installing to ~/.agents/skills/agent-html ,scripts/validate.mjs refers to ~/.agents/skills/agent-html/scripts/validate.mjs。

Layout mode Reader time Information density Core interaction Chinese master path English master path Applicable requirements and core structure
Report(Document / Report) 30s+ Medium Floating table of contents ScrollSpy, collapsible accordion assets/templates/zh/report.html assets/templates/en/report.html Technology selection, architecture review, incident retrospective, interview report, requirements description, release notes. Structure: adaptive widescreen container (default 1200px ~ 1280px, supports adaptive widescreen expansion up to 96%, avoiding tables being squeezed on wide screens), floating table of contents (Sticky TOC with ScrollSpy), core conclusion Callout, KPI overview bar, multi-section <details> collapsible accordion, one-click copy as Markdown export.
Dashboard data panel(Dashboard & Data Grid) <10s High Real-time dual filtering, copy table assets/templates/zh/dashboard.html assets/templates/en/dashboard.html Resource monitoring, usage dashboard, attendance/comp time management, order/task flow management. Structure: wide-screen grid, top action bar, 4-column adaptive KPI stat cards, native SVG trend chart and bar chart, real-time dual-filter table, one-click copy table (MD).
Inspector review workbench(Master-Detail Workbench) Read item by item High Master-Detail linkage, manual adjudication assets/templates/zh/inspector.html assets/templates/en/inspector.html Log/Trace review, Prompt debugger, JSONL editor, configuration management. Structure: viewport-filled (100vh), left-side filtered item list, right-side dynamically linked rendering of selected item details, manual review adjudication bar (Pass/Fix/Reject), copy review conclusion and send back to Agent.
Compare(Side-by-Side Comparison) ~30s Medium Side-by-side comparison, Delta determination assets/templates/zh/compare.html assets/templates/en/compare.html Model A/B testing, before-and-after Prompt revision comparison, architecture version diff, product package/feature matrix. Structure: side-by-side two-column cards (baseline vs challenger), core adjudication Callout, quantitative difference comparison table (Delta win/loss determination labels), one-click export Markdown.
Timeline(Timeline & Postmortem) 30s+ Medium Collapsible diagnostic logs assets/templates/zh/timeline.html assets/templates/en/timeline.html Release roadmap, changelog, incident postmortem. Structure: single-track vertical timeline on the left, status node dots, precise timestamps and operator Tag, expandable diagnostic logs, one-click copy timeline as Markdown.
Kanban board(Triage & Agile Kanban) <10s Medium Native HTML5 drag-and-drop sorting assets/templates/zh/kanban.html assets/templates/en/kanban.html Defect classification and organization, requirement prioritization, task status flow. Structure: 4-column agile kanban (Backlog, In Progress, Blocked, Done), pure native HTML5 drag-and-drop sorting (zero dependencies), one-click copy sorting results back to Agent for closed loop.
Review code review(Diff Review) Read item by item High Line-level findings, per-file adjudication assets/templates/zh/review.html assets/templates/en/review.html PR / branch code review, patch review, before-and-after refactoring difference explanation. Structure: paste as-is git diff to <script type="text/plain" id="diffSource"> to automatically parse as a unified diff; findings are anchored by "new version line number" and presented as inline comments (blocker / major / minor / nit + suggested changes); each file is segmented with a single-choice adjudication (pass / comment / request changes); file tree filtering + empty state; Tabs switch between diff and findings list; one-click copy review conclusion back to Agent.

Choose based on "reader time" and "information density", not by industry vocabulary. In the master template names, "report", "kanban", and "postmortem" describelayout personality, not usage scenario restrictions — "timeline" can carry personal life data, and "compare" can carry the trade-offs between two options. Selection depends on: how many seconds the reader is willing to spend, how dense the content is, and whether specific interactions are needed.

⚠️ Chinese and English masters must be structurally isomorphic. zh and en are two language versions of the same skeleton, not two templates maintained in parallel; changing one must synchronize the other.scripts/validate.mjs 's [ZH_EN_PARITY] will judge " <nav> / <aside> / <details>that exists in Chinese but not in English" as blocking.

💡 Component dictionary reference: The complete code for all button variants, pill badges, 32 vector icons, native pure SVG charts, Tabs, form controls, and interaction scripts is all in references/components.md。It is the single source of truth for component code— this file no longer repeats any component code.

IV. Micro-CSS Core Base

When generating HTML, be sure to put the following approximately 75 lines of CSS base into <head><style> It is the cornerstone of consistent texture across all components:

:root {
  --bg: #fafafa;
  --card: #ffffff;
  --card-fg: #09090b;
  --popover: #ffffff;
  --popover-fg: #09090b;
  --primary: #18181b;
  --primary-fg: #fafafa;
  --primary-hover: #27272a;
  --secondary: #f4f4f5;
  --secondary-fg: #18181b;
  --secondary-hover: #e4e4e7;
  --accent: #f4f4f5;
  --accent-fg: #18181b;
  --destructive: #dc2626;
  --destructive-fg: #fafafa;
  --muted: #f4f4f5;
  --muted-fg: #71717a;
  --border: #e4e4e7;
  --input: #e4e4e7;
  --ring: #18181b;
  --radius: 8px;
  --radius-sm: 6px;
  --radius-lg: 12px;
  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
  --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);

  --ok: #16a34a;   --ok-bg: #f0fdf4;   --ok-border: #bbf7d0;
  --warn: #d97706; --warn-bg: #fffbeb; --warn-border: #fde68a;
  --err: #dc2626;  --err-bg: #fef2f2;  --err-border: #fecaca;
  --info: #2563eb; --info-bg: #eff6ff; --info-border: #bfdbfe;

  /* 图表专用色（Tremor 风格）。语义固定，不可当作装饰色随机分配：
     每个色相各承担一种数据含义，见「轻量原生图表规范」一节。 */
  --chart-indigo: #6366f1;   /* 主指标时序走势 */
  --chart-emerald: #10b981;  /* 正常 / 健康 / 增长 / 放行 */
  --chart-amber: #f59e0b;    /* 警戒 / 抖动 / 温和上升 */
  --chart-rose: #f43f5e;     /* 异常瓶颈 / 错误峰值 / 降级 */
  --chart-violet: #8b5cf6;   /* P95 / P99 峰值高亮 */
  --chart-cyan: #06b6d4;     /* 辅助对比时序 / 出向流量 */
  --chart-slate: #64748b;    /* 低优对比柱 / 中性刻度 */
}

[data-theme="dark"] {
  --bg: #09090b;
  --card: #121215;
  --card-fg: #fafafa;
  --popover: #121215;
  --popover-fg: #fafafa;
  --primary: #fafafa;
  --primary-fg: #18181b;
  --primary-hover: #e4e4e7;
  --secondary: #27272a;
  --secondary-fg: #fafafa;
  --secondary-hover: #3f3f46;
  --accent: #27272a;
  --accent-fg: #fafafa;
  --destructive: #ef4444;
  --destructive-fg: #fafafa;
  --muted: #18181b;
  --muted-fg: #a1a1aa;
  --border: #27272a;
  --input: #27272a;
  --ring: #d4d4d8;
  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.5);
  --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.5);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.5);
  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.5);

  --ok: #4ade80;   --ok-bg: #052e1680;   --ok-border: #166534;
  --warn: #fbbf24; --warn-bg: #451a0380; --warn-border: #854d0e;
  --err: #f87171;  --err-bg: #450a0a80;  --err-border: #991b1b;
  --info: #60a5fa; --info-bg: #17255480; --info-border: #1e40af;

  --chart-indigo: #818cf8;
  --chart-emerald: #34d399;
  --chart-amber: #fbbf24;
  --chart-rose: #fb7185;
  --chart-violet: #a78bfa;
  --chart-cyan: #22d3ee;
  --chart-slate: #94a3b8;
}

*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  background-color: var(--bg);
  color: var(--card-fg);
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

.card {
  background: var(--card);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  box-shadow: var(--shadow-sm);
  overflow: hidden;
}

.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 6px;
  font-size: 13px;
  font-weight: 500;
  height: 34px;
  padding: 0 12px;
  border-radius: var(--radius-sm);
  border: 1px solid var(--border);
  background: var(--card);
  color: var(--card-fg);
  cursor: pointer;
  text-decoration: none;
  transition: all 0.15s ease;
}
.btn:hover { background: var(--secondary); }
.btn-primary { background: var(--primary); color: var(--primary-fg); border-color: var(--primary); }
.btn-primary:hover { background: var(--primary-hover); opacity: 0.95; }
.btn-destructive { background: var(--err); color: #fff; border-color: var(--err); }
.btn-sm { height: 28px; padding: 0 8px; font-size: 12px; }

.badge {
  display: inline-flex;
  align-items: center;
  gap: 4px;
  font-size: 12px;
  font-weight: 500;
  height: 20px;
  padding: 0 7px;
  border-radius: 9999px;
  border: 1px solid var(--border);
  background: var(--secondary);
  color: var(--secondary-fg);
}
.badge-dot { width: 5px; height: 5px; border-radius: 9999px; background: currentColor; }
.badge-success { background: var(--ok-bg); color: var(--ok); border-color: var(--ok-border); }
.badge-warning { background: var(--warn-bg); color: var(--warn); border-color: var(--warn-border); }
.badge-danger  { background: var(--err-bg);  color: var(--err);  border-color: var(--err-border); }
.badge-info    { background: var(--info-bg); color: var(--info); border-color: var(--info-border); }

V. Component Index and Chart Contract (Components & Chart Contract)

There is only one source of truth for component code:references/components.md。Read the corresponding section on demand; do not write it by hand from memory. The table below tells you which section to find it in:

Need Go to components.md which section of
Buttons, status badges §1 Buttons · §2 Badges
KPI metric cards, mini trends §3 Metric Cards
Key conclusions / risk notice bars §4 Callout
Searchable table (including empty state) §5 Interactive Data Table
Trend / distribution / proportion / comparison / ranking / level / composition / cross-distribution §6 Charts A–H (area line, bar, donut, dual-line, ranking, gauge,stacked bar、heatmap）
Chart hover values §6-I Hover tooltip (one shared copy across the whole page, add to chart elements data-tip）
Icons §7 (32,stroke="currentColor" automatically adapts to dark mode)
Modals, collapse, tabs §8 Dialog / Details / Tabs
Requires manual input and bringing back to Agent §9 Form controls(input box, dropdown, checkbox, switch, segmented radio, validation error state)
Theme switching, table filtering, copy Markdown, verdict return, ScrollSpy, footer seal, drag-and-drop §10 Interaction Scripts

Lightweight Native Chart Specification (Zero-CDN Pure SVG Charts)

When generating data dashboards and reports,Strictly prohibited to introduce external CDN libraries such as Chart.js / ECharts / Recharts. Charts uniformly use pure native vector SVG implementation:

  • Zero network dependency: 100% instant open offline and in intranet server rooms, with absolutely no risk of CDN failure or blank screens;
  • Dark mode adaptive: directly use theme variables (including --chart-* chart semantic colors, definitions see “Micro-CSS Core Base”), no additional JS listener redraw needed;
  • Adaptive viewport: unified viewBox + style="width: 100%; height: auto;", perfect fidelity on Retina and print.

📖 The complete code for the eight forms is in references/components.md §6(area line / vertical bar / composite donut / dual-line time series / horizontal ranking / half-ring gauge / stacked bar / heatmap), hover tooltip see §6-I. The code is over there, the contract is here. Read this section before changing code.

Chart Four-Piece Set (all four are indispensable; violation means rework)

Every chart must have these four parts complete, in fixed order:

  1. Conclusion-style title — write judgments, not chart type names.峰值落在 16:00 的批处理窗口 is acceptable,24小时吞吐量趋势 is not.
  2. Subtitle writes the unit contract — use 1 X = 1 Y State clearly how many real quantities one visual unit equals, then use · Append a legend and time range.This is the core of data honesty, not decoration.：
    • 1 格 = 1 个百分点 · 空心 = 周末 · 近 30 天
    • 1 tick = 1 天 · 每 5 天一个刻度
    • When breaking down aggregate numbers, you must state the accounting basis (see Anti-pattern 13); if rounding makes the total less than 100, own it (see Anti-pattern 14).
  3. Chart body — honesty at the data layer. Density comes from units, not from embellishment.
  4. Bottom all-caps encoding note line —— font-size: 10px; letter-spacing: .08em; color: var(--muted-fg), explainingwhat the colors and scales are encoding：
    • 橙色 = 唯一主角（本轮最高耗时）
    • 灰阶 = 数值大小，越深越大

Light furniture (makes the chart not look shabby, but does not change the shadcn language)

A small chart with only data and one baseline is bound to look shabby. Add these four below —They carry no data; they only provide reading tracks：

Furniture Implementation
Emphasized baseline A 1px solid line at the bottom (var(--border)), distinct from the stroke-dasharray="3 3" reference dashed line above
Rim ticks Place a tick at every 5 or 10 units along the baseline so readers can estimate without having to read every number
Reference guides 2–3 horizontal dashed lines aligned with integer Y-axis values
Peak leader line Draw a 1px polyline from the peak bubble to the data point, so the bubble does not float in place

⚠️ Do not copy the furniture of editorial narrative style (the Lupi school): using hairline strokes to form areas, using crossbars to form bars, removing card borders and shadows — that is the signature of another design language, and importing it would damage both identities at once. The chart language of agent-html is shadcn enterprise dashboard: white card + 1px border + semantic status colors.Keep it.

VI. Interaction: Ask three questions first, then choose scripts (Interaction)

Do not assume by default that "adding interaction makes it more advanced." Adding behavior to elements with no content is deception; adding behavior to content that can be read at a glance is noise. Before adding any interaction, answer three questions in order:

  1. Is there a real record behind this element? No (pure texture decoration: dividers, decorative graphics, background accents) → Do not add interaction. Adding hover or click to an element with no content implies there is something to inspect.
  2. There is a record — can it be read without clicking? Yes (fewer than about 50 elements, with labels at both ends or at key points) → Static is enough, hover is just a nice-to-have, not a necessity.
  3. More than about 50 elements, or multiple path segments? → Mustprovide hover / pin; otherwise readers see only a cloud of atmosphere and cannot query item by item.

After the three questions are settled, decide which script below to use. Conversely:If the answers to the three questions point to "no interaction needed," do not force it just because "the template has this feature."

Script code is unified in references/components.md §10 (theme switching, table filtering, copy as Markdown, verdict return, ScrollSpy, footer seal, kanban drag-and-drop). Threedo not need to askbottom lines:

  • Place a theme toggle button in the top-right corner of every page, and in the <head> first set up data-theme, to prevent dark-mode users from seeing a light flash;
  • On any page with filtering, checkboxes, adjudication, or form input, youmusthave a "Copy Results" export (Anti-pattern 3);
  • Each deliverable has a Colophon footer stamp at the bottom (generation time, data sources, baseline version).

7. Delivery Self-Verification and Quality Gate (Self-Verification Gate)

Before delivery, do two things:If you can run the gate, run the gate; if you can't run the gate, go through the checklist manually item by item, and honestly state that "the gate was not run."

1 · First probe the environment (don't assume Node is available)

The gate script is written in Node.Many Agent runtime environments don't have Node at all, and may not have Chrome either—this is not an error, but you must probe first, then decide which path to take,never assume the artifact is fine just because you can't run it。

command -v node >/dev/null 2>&1 && echo "有 node" || echo "无 node"
Environment Which path to take
Has node Run the static gate (Section 2 below),must. This is the fastest and most certain layer
Has node and has Chrome/Chromium Then run the render smoke test (Section 3). Optional but strongly recommended
No node Skip the script, directly execute the Section 4manual self-check checklist, and in the delivery notes explicitly state "this environment has no Node, the gate was not run, and a manual checklist item-by-item review was performed"
Has node no Chrome Just skip the smoke test. Smoke test exit code 2 indicatesthe environment does not meet the conditions, not an artifact defect, do not judge the deliverable as unqualified based on this

Transparency over face-saving. An honest statement that "the gate was not run" is far more useful than a false claim of "verified and passed"—the latter would lead users to make decisions based on an unverified artifact.

2 · Static gate (must run when Node is available)

The path is relative tothis Skill root directory(not your working directory):

node <skill>/scripts/validate.mjs <generated_file.html>   # 校验单个产物
node <skill>/scripts/validate.mjs --all                    # 校验技能全部产物
node <skill>/scripts/validate.mjs --all --json             # 机器可读输出

This script has zero network, zero Token, pure Node built-in modules, with a total of 19 rules + 2 cross-file checks。

10 blocking-level rules(violations must be reworked):

  1. [ZERO_CDN] Whether it contains external script / link / @import CDN references and remote fonts;
  2. [THEME_TOKENS] Whether it declares a complete CSS variable foundation (--bg --card --primary --border) and supports dark mode;
  3. [VIEWPORT] Whether it has a responsive mobile small-screen viewport;
  4. [TAG_HYGIENE] Whether key tags such as svg / details / dialog / table / nav / aside are symmetrically closed;
  5. [DUP_ID] Within the same file, id whether it is unique (otherwise the element obtained by JS is uncertain);
  6. [SCRIPT_SYNTAX] Whether each inline <script> can compile—"No error reported" ≠ "it runs"；
  7. [DARK_MODE_LEAK] Whether any hardcoded #fff / #000 / white / black(fake dark mode) exists outside the token block;
  8. [WIDTH_HYGIENE] Whether tables include overflow-x Is the scroll container or main container hard-coded too narrow;
  9. [DOC_FENCES] Are the Markdown code fences in the specification document paired (an unclosed fence turns the entire following text into a code block, causing the Agent to misread the specification);
  10. [CSS_VAR_DEFINED] var(--x) Is a referenced variable defined in the same file. With a single file and zero dependencies, there is no external stylesheet to save it; andwithout a fallback, the var() failure is a total failure rather than degradation——stroke becomes none, and the graphic disappears entirely, rather than merely having the wrong color.

Common fix for item 8:.container use max-width: 1280pxfor the base width (or width: 100%; max-width: 1380px), and wrap the table in <div class="table-wrap" style="overflow-x: auto; width: 100%;">. It is strictly forbidden to hard-code the main container to a dead width of 800–860px.

9 reminder-level rules(manual review recommended):

  1. [NO_RANDOM] Does the demo/graphic data use Math.random()(must be deterministic);
  2. [CHART_TOKEN_ONLY] Is the SVG's fill / stroke hard-coded with color values (it should take CSS variables to follow the theme);
  3. [FIXED_HEIGHT] Is a fixed pixel height used together with overflow:hidden causing truncation;
  4. [PRINT_STYLE] Does the document-type master provide @media print；
  5. [EMPTY_STATE] If filtering/search is implemented, is an empty state also implemented;
  6. [AFFORDANCE] Is there a copy/export exit (to eliminate interaction dead ends);
  7. [COLOPHON] Does it include a footer provenance archive seal;
  8. [DOC_SECTIONS] Are section numbers duplicated or skipped;
  9. [MIN_FONT] Is the font size inside the SVG below 9px (if it does not fit, switch to hover display instead,do not shrink the font size to cram it in）。

2 cross-file checks：

  • [ZH_EN_PARITY]: Structural elements present in the zh master but missing in en (nav / aside / details / table / dialog / section) are judged as blocking; if the export button id for the same function differs between the Chinese and English versions, it is judged as a reminder.
  • [DOC_TOKEN_COVERAGE]: In the specification document, ```html if a code sample references a CSS variable outside the Micro-CSS base, it is judged as blocking.This guards against “following the documentation actually makes it worse”— the base and the sample are two hand-copied versions, and without this check they will drift apart (see references/failures.md F-014）。

3 · Render smoke test (blind spots static lint cannot cover; recommended to run when Chrome is available)

Static lint can prove "the code reports no errors,"but cannot prove "the page actually rendered". Run the render smoke test once more before delivery:

node <skill>/scripts/smoke.mjs            # 技能全部产物
node <skill>/scripts/smoke.mjs <file.html>  # 单个产物

It copies the artifact to a temporary directory (without modifying repository files), injects a probe script, then uses headless Chrome with --dump-dom to outputthe renderedDOM, and then asserts runtime facts:

  • Does any inline script haveruntimeerrors (valid syntax ≠ it actually runs; this is something static lint can never catch);
  • SVG Did it actually draw graphic primitives (rather than an "empty shell" where the container exists but the content is empty);
  • Click #themeToggle and check whether --bg actually changes before and after (fake dark mode);
  • Is there content truncated by overflow:hidden ;
  • Is there horizontal overflow at narrow viewports.

Requires Chrome/Chromium on the local machine (can be specified with CHROME_PATH , supports common macOS / Linux paths).When no browser is found, it exits with code 2 Skip, and state explicitly in the language that this is an environment issue, not a defect in the artifact. node <skill>/scripts/smoke.mjs --selftest will inject defects, proving that the probe itself can indeed fail.

4 · Exemption mechanism (whitelist before rules)

False positives will destroy trust in the gate, thereforethe container's token definition block (:root / [data-theme] / prefers-color-scheme) and @media print color literals inside the block are always legal, and require no exemption.

When an exemption is truly needed, on the matched line'sprevious linewrite:

/* @lint-allow: DARK_MODE_LEAK — 该按钮悬浮在恒为深色的代码块表面上，不随主题反转 */
.copy-btn:hover { background: #3f3f46; color: #fff; }
  • exemptionscope is only "the line containing the comment + the next line", and will not mask real violations elsewhere in the same file (this one was forced out by F-003: the initial implementation was file-level exemption, so allowing one place would incidentally mask other places);
  • a reason must be stated(≥4 characters); an exemption without a stated reason does not take effect (F-004);
  • Typical exemptable scenarios: buttons on code block/terminal surfaces that are always dark (F-005).Do not use it to mask real dark mode defects.

For why the whitelist comes before the rules and why an exemption applies only to one line, see references/failures.md F-002 / F-003 / F-004。

5 · Effectiveness of the gate itself (maintainer-oriented)

During repository development, use npm test(static lint + rule mutation testing) and npm run test:smoke(render smoke test).After changing rules, the mutation test must be rerun—a validator that "lets everything pass" is equivalent to no validator.

6 · Manual self-check list (when there is no Node, this is the only verification path）

The validator and smoke test together stillcannot test "whether the chart is drawn correctly". The following 6 items cannot be statically determined; all scripts green does not mean there is no problem—the Agent must self-check item by item against the data and semantic layers of the "anti-pattern avoidance list" before delivery：

  • the bar chart has no broken axis? (truncating the Y axis is a breach of contract; requires understanding Y-axis semantics)
  • area/radius encoding uses square root? (requires knowing whether a certain r is bound to a numeric value or to area)
  • color is connected to a real data dimension, and does the footnote clearly state what it is encoding? (semantic judgment)
  • the card title states the conclusion, not the chart type name? ("Revenue by plan" works, "bar chart" does not)
  • the chart type matches the data shape? (semantic judgment)
  • the demo data is deterministic? (refreshing twice must look the same)

The other two items, although statically detectable, are costly and easy to miss; confirm them once in passing before delivery:

  • language purity: the Chinese master and English master are not mixed; a single delivery uses only one language;
  • correct granularity: conforms to the determination in Article 3 of the "value assessment guidelines"—it neither turns "analyze this" into a full-page report, nor turns "I want a report" into a one-page chart.

This list is not supplementary explanation, but ratherthe boundary declaration of the gate, and alsothe only verification path when there is no Node. All green access controls likewise only prove that "there is nothing wrong engineering-wise," not that "there is nothing wrong in the diagram"—F-015 is an example with 18 rules, 14 artifact smoke tests, and 28 mutation test cases all green, yet the diagram was drawn incorrectly.