SVG 图标管理规范

任务目标

本 Skill 用于：统一 React TypeScript 项目中 SVG 图标的存储、封装和使用方式
能力包含：SVG 转换为 React 组件、图标迁移流程、使用规范说明
触发条件：用户需要"统一管理 SVG 图标"、"重构图标代码"、"创建图标规范"、"迁移内联 SVG"

前置准备

依赖说明：无外部依赖，使用 React + TypeScript 内置能力
目录结构准备：确保项目中存在 components/ 目录，创建 components/icons/ 子目录
```
mkdir -p src/components/icons
```

最佳实践示例：参考 best-practice-examples/ 目录下的实际项目示例

best-practice-examples/assets/ - 业务组件示例
best-practice-examples/components/icons/ - 图标组件示例

快速开始（给智能体的执行指令）

当用户要求"将内联 SVG 抽离"或"统一管理图标"时，智能体应按以下步骤执行：

步骤 1：扫描并识别图标

1. 使用 glob_file 或 grep_file 搜索项目中所有的 .tsx/.jsx 文件
2. 在这些文件中搜索包含 <svg> 标签的代码
3. 记录所有找到的内联 SVG 位置（文件路径、行号）
4. 读取这些文件，提取完整的 SVG 代码

步骤 2：创建图标组件

1. 对于每个提取的 SVG：
   - 确定图标功能，生成合适的组件名（PascalCase）
   - 在 src/components/icons/ 目录创建对应的 .tsx 文件
   - 按照 icon-component-template.md 的模板编写组件代码
   - 确保包含 TypeScript 类型定义

步骤 3：更新业务组件

1. 对于每个包含内联 SVG 的文件：
   - 添加 import 语句导入新创建的图标组件
   - 删除原有的 <svg> 标签
   - 替换为 <IconName /> 组件调用
   - 迁移原始的属性（width、height、fill 等）

步骤 4：验证完成

1. 确认所有内联 SVG 都已替换为组件
2. 确认所有图标组件都保存在 src/components/icons/ 目录
3. 确认所有组件文件名和命名符合规范
4. 确认 TypeScript 编译无错误

操作步骤

1. 创建图标目录结构

在项目根目录执行以下操作：

创建 components/icons/ 目录（如果不存在）
该目录将存放所有图标组件

2. 提取并封装 SVG 为 React 组件

2.1 识别并读取需要迁移的图标

执行步骤：

使用文件搜索工具查找项目中所有 .tsx 和 .jsx 文件
在这些文件中搜索内联的 <svg> 标签
记录所有包含内联 SVG 的文件路径和行号
读取这些文件，提取完整的 SVG 代码
识别每个 SVG 的用途（按钮图标、导航图标等）

关键检查点：

已定位所有内联 SVG 的位置
已记录每个 SVG 的上下文用途
已提取完整的 SVG 代码（包括 viewBox、path 等）

2.2 转换 SVG 为 React 组件

执行步骤： 对于每个提取的 SVG，执行以下操作：

读取并解析 SVG 代码：获取完整的 <svg> 标签及其内容
转换文件名：将原始文件名或功能描述转换为 PascalCase 格式
创建组件文件：在 src/components/icons/ 目录下创建 .tsx 文件
编写组件代码：参考 references/icon-component-template.md，按照模板编写组件
保存文件：将创建的组件保存到 src/components/icons/ 目录

示例操作：

输入：从 Button.tsx 提取的箭头 SVG
  ↓
步骤 1：读取 SVG 代码 <svg viewBox="0 0 24 24"><path d="..." /></svg>
  ↓
步骤 2：转换文件名 ArrowRight
  ↓
步骤 3：创建 src/components/icons/ArrowRight.tsx
  ↓
步骤 4：参考模板编写组件代码
  ↓
步骤 5：保存文件

完整模板和示例： 详见 references/icon-component-template.md

3. 更新业务组件

3.1 替换内联 SVG

执行步骤： 对于每个包含内联 SVG 的业务组件：

定位内联 SVG 代码：找到组件中的 <svg> 标签
记录原始属性：记下原有的 width、height、fill、className 等属性值
添加导入语句：在文件顶部添加 import IconName from '@/components/icons/IconName'
替换 SVG 标签：删除 <svg> 标签及其内容，替换为 <IconName />
迁移属性：将原始属性作为 props 传递给新组件（如 <IconName width={24} height={24} />）
验证功能：确认替换后组件功能和样式保持一致

3.2 使用封装的 Icon 组件

从 components/icons 导入图标组件
按需传递 props（size、color 等）
支持通过 className 自定义样式

详细使用示例见 references/best-practice-examples.md

4. 图标迁移检查清单

完整的迁移检查清单详见 references/migration-checklist.md，包含：

迁移前环境检查
逐步迁移操作指南
迁移后功能验证
常见问题解决方案

5. 代码审查与规范检查

在完成迁移后，检查以下规范：

禁止场景：

❌ 禁止在业务组件内直接写 SVG 代码
❌ 禁止在 icons 目录外存放独立的 SVG 组件文件
❌ 禁止在非 components/icons 目录下创建图标组件

规范要求：

✅ 所有 SVG 图标必须封装为 React 组件
✅ 组件必须保存在 components/icons/ 目录下
✅ 必须从 components/icons 导入使用
✅ 组件必须包含 TypeScript 类型定义
✅ 支持通过 props 配置常用属性

详细的规范要求详见各参考文档。

资源索引

最佳实践示例：见 best-practice-examples/（实际项目示例，包含 components 和 assets）
- best-practice-examples/components/icons/ - 图标组件示例
- best-practice-examples/assets/ - 业务组件示例
组件模板：见 references/icon-component-template.md（标准 React 图标组件模板、属性配置、常见变体）
迁移清单：见 references/migration-checklist.md（完整迁移检查项、问题解决方案）
最佳实践文档：见 references/best-practice-examples.md（基于实际项目的最佳实践和使用说明）

注意事项

仅在需要创建新的图标组件或迁移现有图标时读取参考文档
智能体已具备理解和转换 SVG 代码的能力，无需自动化脚本
转换时保留 SVG 的 viewBox 和 path 数据，确保图标形状不变
默认 fill="currentColor" 以支持通过 CSS 控制颜色
使用 TypeScript 确保类型安全，避免运行时错误
best-practice-examples/ 目录包含实际项目示例，可供参考

使用示例

场景 1：迁移现有内联 SVG

需求： 将 Button 组件中的内联箭头图标提取为独立组件

执行方式： 智能体手动执行

读取 Button 组件中的 SVG 代码
参考 references/icon-component-template.md 创建 ArrowRight.tsx
参考 best-practice-examples/components/icons/ 中的示例
替换 Button 组件中的内联 SVG
测试验证显示效果

场景 2：创建新图标规范

需求： 新项目需要建立图标管理规范

执行方式： 智能体自然语言指导

创建 components/icons/ 目录
参考 references/icon-component-template.md 创建图标组件
参考 best-practice-examples/components/icons/ 中的桶导出方式
在项目中推行统一的图标使用方式

场景 3：批量迁移图标

需求： 项目中有多个内联 SVG 需要统一迁移

执行方式： 智能体逐个处理

扫描识别所有内联 SVG 位置
按照 references/migration-checklist.md 逐个迁移
替换所有业务组件中的内联 SVG
执行完整回归测试

svg-icon-best-practice