icon-design

图标设计

使用 SVG 和 CSS 创建一致、易于访问且美观的图标系统。

前置条件

• 阅读 .agents/design-context.md（参见 design-context）：Brand Marks 中的“Icon Style”字段（例如“描边、2px 笔画、圆角端点”）决定你绘制的每个图标的填充、描边宽度和端点／连接样式。使用共享颜色令牌中的语义颜色（--success-*、--error-* 等）。
• 如果项目已经使用图标库（Lucide、Heroicons、Phosphor、Material Symbols），请沿用其网格和描边样式，不要混用其他风格；优先使用库中的图标，而不是绘制新图标。

---

步骤 1：SVG 图标基础

基础模板

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"
  width="24" height="24" fill="none" stroke="currentColor"
  stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  
</svg>

关键属性

属性	值	原因
fill	none	默认使用线框图标
stroke	currentColor	从 CSS 继承文本颜色
stroke-width	2	所有图标保持一致
stroke-linecap	round	友好、现代的观感
stroke-linejoin	round	与端点样式匹配，保持一致
viewBox	0 0 24 24	标准 24px 网格

---

步骤 2：图标网格系统

网格尺寸

网格	用途	描边宽度
24x24	默认 UI 图标	2px（较轻的图标组使用 1.5px）
20x20	紧凑型 UI、表单字段	1.5px
16x16	行内文本、徽章	1.5px（或填充式）
32x32	功能图标、导航	2-2.5px
48x48	插图图标、主视觉	3px

尽可能在各自的网格上绘制每种尺寸，并使用整数像素坐标。通过 CSS 将 24px 图标缩小至 16px 时，描边也会随之缩小（2px 会变成 1.33px，显得模糊）；因此应绘制 16px 变体，或在路径上使用 vector-effect="non-scaling-stroke"。

基准线形状（24x24，Material 风格）

• 有效区域：20x20（每侧留出 2px 内边距）；内边距仅用于视觉补偿
• 圆形：直径 20x20
• 正方形：18x18（同样大小的圆形看起来比正方形小，因此正方形绘制得更小）
• 竖向矩形：16w x 20h；横向矩形：20w x 16h

CSS 尺寸

.icon { width: 1.5rem; height: 1.5rem; flex-shrink: 0; display: inline-block; vertical-align: middle; }
.icon-sm { width: 1rem; height: 1rem; }
.icon-md { width: 1.25rem; height: 1.25rem; }
.icon-lg { width: 2rem; height: 2rem; }
.icon-xl { width: 3rem; height: 3rem; }

---

步骤 3：视觉对齐修正

形状	修正
三角形／播放图标	向右移动约 1px（视觉重心）
圆形	比正方形大约 10%（基准线尺寸为 20，而正方形为 18）
高瘦形状	垂直居中，可能需要轻微调整 Y 偏移
尖顶形状	让尖端稍微超出网格边界

整个图标组的描边宽度必须保持一致——通过调整尺寸和位置进行视觉补偿，不要改变描边宽度。描边粗细不均是图标组不一致最明显的表现。

---

步骤 4：图标样式

线框（基于描边）

用途最广。适用于各种尺寸，缩放效果好，视觉重量轻。使用 fill="none" stroke="currentColor"。

填充（实心）

视觉重量更大。适用于激活／选中状态或较小尺寸。使用 fill="currentColor"。

双调（双色）

主描边搭配低不透明度的次要填充区域。无需增加复杂度即可增添层次感。

.icon-duotone { --icon-primary: currentColor; --icon-secondary: currentColor; }
.icon-duotone .icon-bg { fill: var(--icon-secondary); opacity: 0.15; }
.icon-duotone .icon-fg { stroke: var(--icon-primary); fill: none; }

圆角与锐角

圆角（stroke-linecap: round）给人友好、现代的感觉。锐角（stroke-linecap: square/butt）给人精确、技术感强的感觉。选择一种并应用于整个图标组。切勿混用。

第 5 步：语义化图标选择

操作	图标	备注
关闭	X	始终位于容器右上角
返回	左箭头	或左尖括号
菜单	3 条水平线	汉堡菜单
搜索	放大镜	通常用于搜索输入框
设置	齿轮	或用于筛选设置的滑块
用户	人形剪影	圆形 + 头部形状
通知	铃铛	可带圆点徽标
删除	垃圾桶	配合确认操作使用
编辑	铅笔	或方框铅笔
添加	加号	FAB 中使用圆形背景
分享	从方框向上的箭头	或分叉箭头
下载	指向横线的向下箭头	与向下尖括号区分
勾选/完成	勾号	已确认状态使用圆形背景
信息	圆圈中的 i	蓝色语义色
警告	带 ! 的三角形	黄色/琥珀色语义色
错误	带 X 的圆圈	红色语义色

---

第 6 步：自定义 SVG 图标技巧

路径数据命令

• M：移动到，L：画线到，H/V：水平/垂直线
• C：三次贝塞尔曲线，A：弧线，Z：闭合路径
• 相对坐标通常使用小写字母，代码往往更短

使用基本图形构建

<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
     stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
  <polyline points="3 11 12 3 21 11"/>
  <path d="M5 10v9a1 1 0 0 0 1 1h4v-6h4v6h4a1 1 0 0 0 1-1v-9"/>
</svg>

---

第 7 步：图标与文本对齐

/* Inline alignment */
.icon-text { display: inline-flex; align-items: center; gap: 0.5rem; }
.icon-text .icon { width: 1.25em; height: 1.25em; flex-shrink: 0; }

/* Button with icon */
.btn-icon { display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.625rem 1.25rem; }
.btn-icon .icon { width: 1.25em; height: 1.25em; margin-left: -0.125em; }

/* Icon-only button */
.btn-icon-only { display: inline-grid; place-items: center; width: 2.75rem; height: 2.75rem; padding: 0; border-radius: 0.5rem; } /* 44px target */

---

第 8 步：动画图标

悬停旋转

.icon-interactive { transition: transform 0.2s ease; }
.icon-interactive:hover { transform: rotate(90deg); }

加载旋转指示器

.icon-spinner { animation: spin 1s linear infinite; }
@keyframes spin { to { transform: rotate(360deg); } }

勾号绘制动画

pathLength="1" 会规范化路径长度，因此无需测量：

<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
  <path class="draw" pathLength="1" d="M5 12.5l4.5 4.5L19 7.5"/>
</svg>

.draw { stroke-dasharray: 1; stroke-dashoffset: 1; animation: draw 0.4s var(--ease-out, ease-out) forwards; }
@keyframes draw { to { stroke-dashoffset: 0; } }
@media (prefers-reduced-motion: reduce) { .draw { animation: none; stroke-dashoffset: 0; } }

悬停旋转也采用相同的封装方式。减少动态效果时，旋转指示器仍可继续旋转（它传达的是状态，而非装饰），但应降低速度或改为脉冲式透明度变化。

---

第 9 步：图标无障碍访问

规则

1. 装饰性图标（位于文本标签旁）：aria-hidden="true" focusable="false"
2. 有意义的图标（独立使用）：在按钮上提供 aria-label（并在其中的 SVG 上设置 aria-hidden="true"），或在 SVG 中使用带有 role="img" aria-labelledby 的 <title>
3. 关键操作绝不能只依赖图标——始终提供文本替代
4. 图标按钮：24x24px 是 WCAG 2.2 AA 的最小点击目标（SC 2.5.8）；建议使用 44x44px（Apple HIG、WCAG AAA 2.5.5）或 48x48dp（Material）
5. 传达含义的图标与背景之间需要达到 3:1 的对比度（SC 1.4.11）

.icon-button { min-width: 44px; min-height: 44px; display: inline-grid; place-items: center; }

---

第 10 步：常见 UI 图标模式

徽标指示器

.icon-with-badge { position: relative; display: inline-block; }
.icon-badge {
  position: absolute; top: -4px; right: -4px;
  width: 10px; height: 10px; background: var(--error-500);
  border-radius: 50%; border: 2px solid var(--bg-primary, white);
}

状态指示器

.status-icon { position: relative; }
.status-icon::after {
  content: ''; position: absolute; bottom: 0; right: 0;
  width: 8px; height: 8px; border-radius: 50%; border: 2px solid var(--bg-primary, white);
}
.status-icon--online::after  { background: var(--success-500); }
.status-icon--offline::after { background: var(--gray-400); }
.status-icon--busy::after    { background: var(--error-500); }

状态圆点仅依靠颜色传达信息——应搭配文本标签或 aria-label（“Online”），并使用 var(--bg-primary) 而不是 white 作为圆环颜色，以确保其在深色模式下正常显示。

---

验证整套图标

在一个临时 HTML 页面上，以 16、20、24 和 32px 的尺寸，将每个图标分别渲染在浅色和深色背景上，并放在文本标签旁边，然后截图（npx playwright screenshot --full-page "file://$PWD/icons.html" icons.png）。使用 Read 查看图片（16px 图标也要查看 4 倍放大的副本），并检查：所有图标的视觉重量是否一致、描边宽度是否相同、是否有图形被 viewBox 边缘裁切、形状是否与基准线对齐，以及在 16px 下是否清晰易辨。

快速参考

1. 使用统一的 viewBox（默认 24x24），并设置 2px 的有效区域内边距。
2. 选择一种风格（轮廓、填充、双色调），并应用于整套图标。
3. 使用 stroke="currentColor"，让图标继承文本颜色。
4. 保持 stroke-width 一致（24x24 时为 2px）。
5. 对三角形和圆形进行视觉校正。
6. 与文本内联时，使用 em 单位设置图标大小。
7. 装饰性图标始终添加 aria-hidden="true"。
8. 仅含图标的按钮始终添加 aria-label。
9. 触控目标建议为 44x44px（24x24px 是 WCAG 2.2 AA 的最低要求）。
10. 使用 stroke-dasharray + stroke-dashoffset 实现绘制动画。