# HTML Widget
> 生成可交互的 HTML 可视化组件 — 算法动画、数据图表、概念演示、交互式教程等。当用户需要交互式演示、动画解释、数据探索、UI 原型等场景时触发，直接输出 html 代码块，前端会在安全沙箱中渲染为可交互组件。
- Skill: `pm-shawn/html-widget` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pm-shawn/html-widget`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pm-shawn/html-widget/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: pm-shawn (https://skillmd.com/u/pm-shawn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pm-shawn/html-widget
---
你现在帮用户生成 **可交互的 HTML 组件**。直接在回复中输出 ` ```html ` 代码块，前端会在安全沙箱 iframe 中自动渲染为可交互组件。
**重要规则**：
- **不要调用 generate_image 工具**，HTML 代码块就是最终输出
- **不要调用文件写入工具**（write_file 等）把 HTML 保存到本地——这是对话内的临时可视化，不是文件交付物
- **不要用 Artifacts 模式**——直接输出代码块即可
- **不要调用 report_plan / todo_write**——直接输出代码块，不需要规划步骤
## 何时用可视化 vs 写文件
| 用户意图 | 做法 |
|---------|------|
| "看看"、"分析一下"、"展示"、"解释"、"演示" | → 输出 ` ```html ` 代码块（可视化） |
| "导出"、"保存"、"生成报表"、"做个文件"、"发给领导" | → 调用 write_file（文件交付） |
| "分析数据，然后做个报表" | → 先可视化展示关键发现，再写文件 |
## 输出格式
输出 ` ```html ` 代码块，内容为 HTML 片段（**不含** ``、``、``、`` 标签，这些由渲染器自动包裹）。
**必须按此顺序**：`
```
## 尺寸规范
根据内容复杂度选择合适的尺寸：
| 类型 | 高度 | 适用场景 |
|------|------|---------|
| 紧凑型 | ≤150px | 单个指标卡片、迷你图、简单计数器 |
| 标准型 | 150-400px | 单个图表、数据表格、简单交互 |
| 完整型 | 400-700px | 仪表盘、多图表组合、复杂交互 |
- 宽度：始终自适应 100%
- body 已预设 16px 内边距
## 设计规范
> **核心审美原则**：克制、留白、精致。宁可简洁到"少了点什么"，也不要堆砌到"多了点什么"。每个像素都要有存在的理由。
### 配色体系
**必须使用浅色/白色背景**。禁止深色/黑色背景。
**基础色（CSS 变量，已预注入）**：
| 变量 | 用途 | 值 |
|------|------|-----|
| `--abu-primary` | 主色/强调色 | #d97757（暖橙） |
| `--abu-text` | 正文文字 | #29261b（深棕） |
| `--abu-text-muted` | 次要文字/辅助信息 | #888579（暖灰） |
| `--abu-bg` | 页面背景 | #ffffff |
| `--abu-bg-secondary` | 卡片/区块背景 | #f5f3ee（米白） |
| `--abu-border` | 边框/分割线 | #e5e2db（浅驼） |
**数据色板**（图表数据系列，按优先级排列）：
| 序号 | 色值 | 名称 | 适用 |
|------|------|------|------|
| 1 | `#4F46E5` | 靛蓝 | 默认首选、主数据系列 |
| 2 | `#0891B2` | 青色 | 对比系列 |
| 3 | `#10B981` | 翠绿 | 正向指标（增长/完成） |
| 4 | `#F59E0B` | 琥珀 | 警告/中性指标 |
| 5 | `#EF4444` | 赤红 | 负向指标（下降/错误） |
| 6 | `#7C3AED` | 紫色 | 补充系列 |
| 7 | `#EC4899` | 玫红 | 补充系列 |
**语义色**：
- 成功/增长：`#10B981`，搭配浅底 `#ecfdf5`
- 危险/下降：`#EF4444`，搭配浅底 `#fef2f2`
- 警告：`#F59E0B`，搭配浅底 `#fffbeb`
- 信息：`#4F46E5`，搭配浅底 `#eef2ff`
**配色原则**：
- 白色基底 + 单一强调色。一个组件最多 1 种强调色 + 数据色板
- 大面积只用白/米白/浅灰，色彩只用于数据点、状态标识、CTA 按钮
- 图表背景透明，不要给 chart container 加背景色
- 相邻数据系列色相间距 > 60°，确保色盲友好
### 间距系统（4px 网格）
所有间距使用 4 的倍数：
| token | 值 | 用途 |
|-------|-----|------|
| `--s-1` | 4px | 图标与文字间距、紧凑元素内边距 |
| `--s-2` | 8px | 相关元素间距、小卡片内边距 |
| `--s-3` | 12px | 组内元素间距、按钮组 gap |
| `--s-4` | 16px | 段落间距、卡片内边距（默认） |
| `--s-5` | 20px | 区块间距 |
| `--s-6` | 24px | 大卡片内边距、区块间隔 |
| `--s-8` | 32px | 主要分区间隔 |
用法示例：`padding: 16px`、`gap: 12px`、`margin-bottom: 24px`。不要出现 5px、7px、15px 这种非 4 倍数值。
### 圆角
| 场景 | 值 |
|------|-----|
| 小元素（标签、徽章） | `4px` |
| 按钮、输入框 | `6px` |
| 卡片、面板 | `10px` |
| 大容器、模态框 | `12px` |
统一使用 `border-radius`，不要混用不同的圆角值。一个组件内圆角值最多 2 种。
### 字体与排版
- **字体栈**：`system-ui, -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif`
- **字重**：仅 `400`（正文）和 `600`（标题/强调），禁用 300/500/700/800
- **等宽数字**：数值型内容加 `font-variant-numeric: tabular-nums` 确保对齐
| 层级 | 字号 | 字重 | 行高 | 用途 |
|------|------|------|------|------|
| 大标题 | 24px | 600 | 1.3 | 仪表盘主标题 |
| 标题 | 18px | 600 | 1.4 | 区块标题、图表标题 |
| 小标题 | 15px | 600 | 1.5 | 卡片标题 |
| 正文 | 14px | 400 | 1.6 | 默认正文 |
| 辅助 | 12px | 400 | 1.5 | 标签、图例、脚注、数据来源 |
| 超大数字 | 28-36px | 600 | 1.2 | KPI 核心数值 |
**中文排版规则**：
- 中英文/中文与数字之间加半角空格：`GDP 总量 101.4 万亿`
- 数字千分位：`¥1,234,567`
- 日期格式：`2024 年 3 月` 或 `2024-03-15`
- 百分比：正数加 `+` 号 → `+12.3%`
- 标点用中文全角：`，` `。` `、` `（` `）`
### 组件模式
#### 卡片（Card）
```css
.card {
background: var(--abu-bg-secondary);
border-radius: 10px;
padding: 16px;
}
.card-title {
font-size: 12px;
font-weight: 400;
color: var(--abu-text-muted);
text-transform: uppercase;
letter-spacing: 0.5px;
margin-bottom: 8px;
}
```
- 卡片之间 gap `12px`
- 卡片内不要再嵌套卡片（最多一层）
- 卡片标题用辅助字号（12px）+ muted 色，不要用大标题
#### KPI 指标卡
```css
.kpi-value {
font-size: 28px;
font-weight: 600;
color: var(--abu-text);
font-variant-numeric: tabular-nums;
line-height: 1.2;
}
.kpi-trend {
display: inline-flex;
align-items: center;
gap: 4px;
font-size: 12px;
font-weight: 600;
margin-top: 4px;
padding: 2px 6px;
border-radius: 4px;
}
.kpi-trend.up { color: #10B981; background: #ecfdf5; }
.kpi-trend.down { color: #EF4444; background: #fef2f2; }
```
- 趋势指示用 `↑` `↓` 字符 + 语义色背景标签，而不是纯文字
- 数值居左对齐，不要居中
#### 数据表格（Table）
```css
.data-table {
width: 100%;
border-collapse: separate;
border-spacing: 0;
font-size: 13px;
}
.data-table th {
text-align: left;
font-weight: 600;
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.5px;
color: var(--abu-text-muted);
padding: 8px 12px;
border-bottom: 2px solid var(--abu-border);
}
.data-table td {
padding: 10px 12px;
border-bottom: 1px solid var(--abu-border);
color: var(--abu-text);
}
.data-table tr:last-child td { border-bottom: none; }
.data-table tr:hover td { background: var(--abu-bg-secondary); }
```
- 表头用小字 + 大写 + muted 色，营造层次感
- 数字列右对齐 + `tabular-nums`
- 不要给表格加外边框，只用行分割线
#### 标签页（Tabs）
```css
.tabs {
display: flex;
gap: 0;
border-bottom: 1px solid var(--abu-border);
margin-bottom: 16px;
}
.tab {
padding: 8px 16px;
font-size: 13px;
color: var(--abu-text-muted);
border: none;
background: none;
cursor: pointer;
border-bottom: 2px solid transparent;
margin-bottom: -1px;
transition: color 0.15s, border-color 0.15s;
}
.tab:hover { color: var(--abu-text); }
.tab.active {
color: var(--abu-primary);
border-bottom-color: var(--abu-primary);
font-weight: 600;
}
```
#### 徽章/标签（Badge）
```css
.badge {
display: inline-flex;
align-items: center;
padding: 2px 8px;
font-size: 11px;
font-weight: 600;
border-radius: 4px;
letter-spacing: 0.3px;
}
.badge-success { color: #10B981; background: #ecfdf5; }
.badge-danger { color: #EF4444; background: #fef2f2; }
.badge-warning { color: #D97706; background: #fffbeb; }
.badge-info { color: #4F46E5; background: #eef2ff; }
```
#### 进度条（Progress Bar）
```css
.progress-track {
height: 6px;
background: var(--abu-border);
border-radius: 3px;
overflow: hidden;
}
.progress-fill {
height: 100%;
border-radius: 3px;
background: var(--abu-primary);
transition: width 0.4s ease;
}
```
#### 分割线
```css
.divider {
height: 1px;
background: var(--abu-border);
margin: 16px 0;
}
```
### 按钮
基础按钮样式已预设在渲染器中，直接用 `