Icon
传达操作、状态或对象含义。中文惯用名：图标。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.icon |
| 名称 | Icon |
| 二级分类 | 通用（general） |
| 用途 | 传达操作、状态或对象含义 |
| 描述 | 中文惯用名：图标。 |
预览
静态结构：渲染为单个 <svg data-slot="icon">（lucide-react，shrink-0 + aria-hidden，纯装饰不进入无障碍树）；name 经 normalizeIconName 归一（kebab-case / camelCase / PascalCase 均接受）后查 ICONS 白名单，未命中渲染 help-circle 占位并标 data-unknown（不抛错）；size 档位 sm=16 / default=20 / lg=24，数字按 px；color 缺省 currentColor 跟随文本色；className / style 合并到图标根节点。
DSL 结构
{
"type": "Icon",
"props": {
"name": "download",
"size": 28,
"color": "#1677ff"
}
}何时用
何时使用
- 为操作、状态或对象补充视觉标识：按钮内的动作图标、列表行的类型图标、空态与提示的语义图标。
- 紧凑空间中替代文字标签：工具栏、表头筛选、卡片角落入口。
- 需要跟随上下文的跟随式图标：不传 color 时继承 currentColor，自动适配所在容器（含 danger 等有色按钮）。
何时不用
- 图标本身就是可点击入口：使用 Button（icon 通道）或 Link，Icon 只表达含义、不承载点击与焦点。
- 需要图形化表达（插图、缩略图、封面）：使用 Image 等展示组件。
- 含义无法从上下文推断且无处放文案：先补 Tooltip 或可见文本，而不是让用户猜图形。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（default） | 20px 线性图标 | 正文、列表行内与文本并列的图标 |
| sm 小号 | 16px | 按钮内、菜单项、表格密集区域 |
| lg 大号 | 24px | 空态、卡片头部、强调入口 |
| 数字尺寸 | size 传数字按 px 精确控制（如 28） | 自定义插图式图标、视觉稿逐像素对齐 |
| 自定义颜色 | color 覆盖为固定色值 | 品牌色图标、与文本色不同的强调图标 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 图标名：kebab-case（如 arrow-right）或 PascalCase（如 ArrowRight），取自 ICONS 白名单；未命中渲染 help-circle 占位并标 data-unknown |
size | `'sm' | 'default' | 'lg' |
color | string | — | 颜色（CSS 颜色值）；缺省 currentColor 跟随文本色 |
strokeWidth | number | — | 描边宽度（lucide 缺省 2） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 图标只做语义补充：关键含义必须能从相邻文本或 Tooltip 得知，不依赖用户猜测图形。
- 纯图标入口必须提供可访问名称（Tooltip 文案或 aria-label），且点击命中区不小于 32px。
- 同一区域图标取同一档尺寸（常用 sm / default），不混用三档造成基线错位。
- 颜色跟随语义：状态色交给 Text / Tag / Status 的语义容器，除品牌表达外不给 Icon 硬编码颜色。
- 新增图标先在 ICONS 白名单登记（一行导入 + 一行映射），未登记的名字会静默落为占位图标。
正例
- ✓ 列表行：Icon name="file-text" 表示文档类型，与标题文本同色。
- ✓ 危险操作按钮：Button 的 icon="trash" + danger，图标自动跟随按钮文字色。
反例
- ✕ 直接给 Icon 绑 onClick 当按钮用（应使用 Button 的 icon 通道）。
- ✕ 依赖未登记的图标名（渲染为占位问号图标，用户误读为帮助入口）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。