skills/development-workflows/html-artifact/SKILL.md
Create self-contained HTML artifacts, single-file by default and split into offline per-page bundles when oversized, for complex, visual, comparison-heavy, reviewable, or shareable work outputs. Use this skill when the user asks for an HTML artifact, browser-viewable report, implementation plan, PR/code review report, architecture explainer, design comparison, research briefing, incident report, status dashboard, temporary structured-data editor, mini deck, or design-system specimen. Prefer this skill for long Markdown-like outputs that benefit from navigation, cards, diagrams, filters, copy/export buttons, or annotated diffs. Do not use it for short answers, simple commands, commit messages, tiny patch summaries, or production UI implementation unless the user explicitly asks for a review artifact.
npx skillsauth add bahayonghang/my-claude-code-settings html-artifactInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Create a browser-viewable HTML artifact when complex work needs a richer review surface than a wall of Markdown. Default to one self-contained file; use a split bundle when the planned content is too large for a reviewable single page.
Use HTML artifacts for complex, visual, comparison-heavy, reviewable, or shareable outputs. Keep ordinary Markdown for short answers, simple commands, commit messages, tiny summaries, and routine implementation reports unless the user explicitly asks for an artifact.
Every artifact must be:
.html or .htm file unless the pre-build size gate says to split. When split, create docs/artifacts/<slug>/index.html plus self-contained part pages such as part-01-overview.html.fetch, XHR, beacons, WebSockets, or automatic network requests.<!doctype html>, <html>, <head>, <meta charset="utf-8">, <meta name="viewport">, <title>, <main id="main">, and one clear <h1>.prefers-reduced-motion support.When the artifact is report-like, decision-making, comparison-heavy, deck-like, likely to be screenshotted/shared, or intended for senior review, make the design pass explicit before writing HTML. Use the $frontend-design method as an upstream thinking step, then translate it into offline artifact constraints.
Make these four decisions:
editorial, dashboard, dossier, deck, or workbench.spacious presentation, medium-density report, or high-density cockpit.table-first, card-first, inline-SVG-first, HTML-lane-first, swimlane-first, or chart-first. Pick chart-first when the artifact's core argument is trend, distribution, or proportion; pick swimlane-first when responsibility / handoff between roles is the key story.Translate frontend-design principles into this skill's hard constraints:
auto-fit grids when the item count is known. Explicitly compose 5 cards as 3+2 and 7 cards as 4+3 at desktop widths.repeat(auto-fit, ...) and producing orphan rows such as 4+1.Load references/template-selection.md when choosing a template. Use the first matching primary goal, then combine secondary sections if needed.
When the user asks to deeply analyze a codebase architecture, call mechanism, enum/selection strategy, module boundaries, redundancy, trainer/worker dispatch, or model-trainer organization, default to an Architecture Atlas + Review Workbench + Strategy Blueprint report rather than a generic polished page. Treat this as an evidence-driven architecture audit artifact, not production UI and not a code-editing skill.
Use this fixed report contract unless the user gives a narrower structure:
Enum recommendations must include a table with these columns: current entrypoint, recommended enum type, recommended member names, naming basis, caller impact, and documentation update point. Keep long code identifiers in HTML tables/lists; use short SVG labels only.
| User goal | Start with | | -------------------------------------------------------- | ------------------------ | | Implementation plan, PRD, roadmap, migration plan | Strategy Blueprint | | Code review, PR explainer, diff audit | Review Workbench | | Architecture, data flow, interface boundary | Architecture Atlas | | Option comparison, buy/build, design choice | Decision Matrix Studio | | Research report, learning brief, source-backed synthesis | Evidence Dossier | | Weekly/project status, release readiness, QA report | Status Brief | | Incident report, RCA, postmortem | Incident Timeline | | JSON/YAML/prompt/config editing or local triage tool | Interactive Editor | | Meeting readout, mini deck, slide-like walkthrough | Narrative Deck | | Design tokens, component states, visual audit | Component Specimen Sheet |
references/templates/ plus references/accessibility-and-security.md when relevant. Load references/diagram-cookbook.md for roadmaps, flows, dependency lanes, or architecture diagrams. Load references/size-and-splitting.md when the size gate is near or above the split threshold.docs/artifacts/<slug>.html for single-page artifacts. For split bundles, prefer docs/artifacts/<slug>/index.html plus part-NN-topic.html pages.assets/starter-template.html as the copyable baseline, not as a remote dependency.python skills/development-workflows/html-artifact/scripts/check_html_artifact.py <artifact.html>
references/design-review-checklist.md.Before writing HTML, make a short size plan. Do not wait for the validator's post-build large-file warning to discover that the artifact should have been split.
estimated_total_bytes using the method in references/size-and-splitting.md.<900 KB: single page by default.900 KB–1.2 MB: single page is allowed, but compress content first by summarizing repeated rows, moving raw evidence into collapsible summaries, and shortening excerpts.1.2 MB–1.5 MB: prefer a split bundle unless the artifact has one tightly coupled reading flow.>1.5 MB: split bundle is required unless the user explicitly asks for one file.Size plan: estimated_total_bytes=1.34 MB from 9 sections, 4 tables (~180 rows), 3 SVG diagrams, and 40 short evidence excerpts. Decision: split bundle with index + 3 parts.
For split bundles, keep each page offline self-contained. Do not create a site that depends on shared CSS, shared JS, JSON files, images, or fetch.
The starter template includes reusable primitives. Prefer these over ad-hoc CSS for common artifact problems:
hero--compact.hero--split for left conclusion plus right thesis board/meta cluster; hero--compact when no right-side material exists; hero--deck for executive readouts.grid-2, grid-3, grid-4, grid-5-balanced (3+2 desktop), and grid-7-balanced (4+3 desktop). All grid children should tolerate long mixed-language text.table--matrix, table--evidence, and table--decision; use is-recommended, key-row, verdict-column, or evidence-column to make conclusions scannable.figure.diagram-frame with inline SVG, timeline/phase lanes, or structured HTML diagrams; always include figcaption and a text equivalent list or table.architecture-map, boundary-band, evidence-rail, edge-legend, and risk-heat for codebase audit pages that need C4-lite boundaries, traceable evidence, call edges, and risk density.Mermaid can be an input sketch, but static SVG or clear HTML must be the final artifact output.
Preferred order:
Do not leave raw Mermaid syntax as the main visual expression. Even when the user provides Mermaid, convert the idea into static SVG or a readable HTML diagram with text equivalents.
Inline SVG labels must stay crisp and short:
<text> only for short node/edge labels. Put long code identifiers, file paths, mixed Chinese/English explanations, and nuanced prose in the adjacent ordered list, table, or card text equivalent.stroke, stroke-width, paint-order: stroke, text-shadow, filter, or drop-shadow; these commonly blur screenshots and exported images..svg-label or .diagram-frame text with fill-only text, moderate font size, and moderate weight. Emphasize the surrounding node shape, border, fill, or nearby HTML annotation instead of outlining the letters.<tspan> and keep each line scannable. If it needs more than two short lines, use an HTML lane/card instead of SVG text.For generated artifacts, run python skills/development-workflows/html-artifact/scripts/check_html_artifact.py <artifact.html>.
For changes to this skill, run node --test skills/development-workflows/html-artifact/tests/check-html-artifact.test.mjs, then project gates.
Keep this entrypoint small. Load detailed references only as needed:
references/template-selection.md — template selection and combination rules.references/size-and-splitting.md — pre-build byte estimation, split thresholds, naming, navigation, and compression strategies.references/accessibility-and-security.md — offline, accessibility, privacy, and validation rules, including the color / mode / theme layering.references/design-review-checklist.md — manual visual QA covering the six dimensions (composition, tables, diagrams/SVG, charts, interactive controls, modes/offline).references/tables-cookbook.md — eight table recipes plus responsive strategy and non-decorative emphasis. Load when an artifact has decision matrices, evidence tables, risks, trends, heatmaps, or summaries.references/charts-cookbook.md — eight inline-SVG/CSS-only chart recipes plus a decision tree. Load when a metric, distribution, or trend needs visualization beyond a number with a status pill.references/svg-cookbook.md — icons, decorative motifs, and spot illustrations using currentColor and tokens.references/diagram-cookbook.md — inline SVG and HTML diagram recipes (phase roadmap, decision flow, swimlane, state machine, tree, before/after, gantt, dependency, evidence-to-claim) and shape/connector conventions.references/interaction-cookbook.md — ten native-first interaction recipes (filter chip, search, sortable table, tabs, disclosure, dialog, scroll-spy, theme toggle, copy with feedback, keyboard shortcuts) with progressive-enhancement baselines.references/templates/strategy-blueprint.md — implementation plans and PRDs.references/templates/review-workbench.md — code review and PR reports.references/templates/architecture-atlas.md — architecture and data-flow explainers.references/templates/decision-matrix-studio.md — option comparison and ADR-style decisions.references/templates/evidence-dossier.md — research and source-backed reports.references/templates/status-brief.md — project/release/QA status dashboards.references/templates/incident-timeline.md — incident reviews and postmortems.references/templates/interactive-editor.md — local structured-data editors.references/templates/narrative-deck.md — browser mini decks.references/templates/component-specimen-sheet.md — design-system and component review sheets.development
Implement safe, behavior-preserving code refactors after inspecting the existing project. Use when the user asks to refactor code, split large files or modules, extract functions or methods, reduce duplicated logic, rename confusing classes/functions/variables, improve code comments, remove unused or dead code, or says 重构代码, 拆分模块, 提取方法, 减少重复代码, 优化命名, 优化注释, 删除未调用代码. For broad refactor requests, plan safe slices and wait for approval; for narrow scoped requests, directly implement the smallest verifiable slice.
development
Use only when the user explicitly asks for swarm, subagents, parallel agents, dynamic workflow, multi-agent orchestration, 多智能体编排, or when the task truly needs coordinated research plus implementation plus review plus verification packets. Do not use for ordinary code review, planning-only work, single-line bugfixes, routine audits, or migrations unless orchestration is requested or at least two independent workflow dimensions are present.
development
Run a code quality review focused on maintainability, structure, abstraction quality, file growth, branching complexity, boundary cleanliness, and refactoring opportunities. Use when the user asks for code quality review, code review, maintainability review, architecture quality review, PR code quality feedback, 代码质量审查, 代码质量 review, 可维护性审查, 架构质量审查, or review comments about code structure. Do not use for pure security review, formatting-only review, performance profiling, or implementation tasks unless the user also asks for a code quality review.
development
Plan-first brainstorming workflow that turns an idea into an approved Markdown implementation plan by default. Use when the user wants to brainstorm, design, scope, or plan a feature/spec before implementation. Spark explores project context, asks only blocking questions, writes the plan under the project root's .plannings/YYYY-MM-DD-feature-slug.md path, self-reviews it, and waits for user approval. Create an HTML or visual plan/spec only when the user explicitly asks for HTML, browser-viewable, or visual output; save the paired .html beside the Markdown plan.