Back to Details

svg-icon-best-practice

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SVG 图标管理规范

SVG Icon Management Specification

任务目标

Task Objectives

  • 本 Skill 用于：统一 React TypeScript 项目中 SVG 图标的存储、封装和使用方式
  • 能力包含：SVG 转换为 React 组件、图标迁移流程、使用规范说明
  • 触发条件：用户需要"统一管理 SVG 图标"、"重构图标代码"、"创建图标规范"、"迁移内联 SVG"
  • This Skill is used to: unify the storage, encapsulation and usage of SVG icons in React TypeScript projects
  • Capabilities include: converting SVG to React components, icon migration process, and usage specification instructions
  • Trigger conditions: users need to "unify SVG icon management", "refactor icon code", "create icon specifications", "migrate inline SVG"

前置准备

Preparations

  • 依赖说明：无外部依赖，使用 React + TypeScript 内置能力
  • 目录结构准备：确保项目中存在 
    components/
    目录，创建 
    components/icons/
    子目录
    bash
    mkdir -p src/components/icons
最佳实践示例：参考 best-practice-examples/ 目录下的实际项目示例
  • best-practice-examples/assets/
    - 业务组件示例
  • best-practice-examples/components/icons/
    - 图标组件示例
  • Dependency Notes: No external dependencies, uses built-in capabilities of React + TypeScript
  • Directory Structure Preparation: Ensure the 
    components/
    directory exists in the project, create the 
    components/icons/
    subdirectory
    bash
    mkdir -p src/components/icons
Best Practice Examples: Refer to the actual project examples in the best-practice-examples/ directory
  • best-practice-examples/assets/
    - Business component examples
  • best-practice-examples/components/icons/
    - Icon component examples

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

Quick Start (Execution Instructions for Agents)

当用户要求"将内联 SVG 抽离"或"统一管理图标"时，智能体应按以下步骤执行：
When users request "extract inline SVG" or "unify icon management", agents should follow these steps:

步骤 1：扫描并识别图标

Step 1: Scan and Identify Icons

1. 使用 glob_file 或 grep_file 搜索项目中所有的 .tsx/.jsx 文件
2. 在这些文件中搜索包含 <svg> 标签的代码
3. 记录所有找到的内联 SVG 位置（文件路径、行号）
4. 读取这些文件，提取完整的 SVG 代码
1. Use glob_file or grep_file to search all .tsx/.jsx files in the project
2. Search for code containing <svg> tags in these files
3. Record the locations (file paths, line numbers) of all found inline SVGs
4. Read these files and extract the complete SVG code

步骤 2：创建图标组件

Step 2: Create Icon Components

1. 对于每个提取的 SVG：
   - 确定图标功能，生成合适的组件名（PascalCase）
   - 在 src/components/icons/ 目录创建对应的 .tsx 文件
   - 按照 icon-component-template.md 的模板编写组件代码
   - 确保包含 TypeScript 类型定义
1. For each extracted SVG:
   - Determine the icon's function and generate an appropriate PascalCase component name
   - Create a corresponding .tsx file in the src/components/icons/ directory
   - Write component code following the template in icon-component-template.md
   - Ensure TypeScript type definitions are included

步骤 3：更新业务组件

Step 3: Update Business Components

1. 对于每个包含内联 SVG 的文件：
   - 添加 import 语句导入新创建的图标组件
   - 删除原有的 <svg> 标签
   - 替换为 <IconName /> 组件调用
   - 迁移原始的属性（width、height、fill 等）
1. For each file containing inline SVG:
   - Add an import statement to import the newly created icon component
   - Delete the original <svg> tag
   - Replace it with the <IconName /> component call
   - Migrate original attributes (width, height, fill, etc.)

步骤 4：验证完成

Step 4: Verify Completion

1. 确认所有内联 SVG 都已替换为组件
2. 确认所有图标组件都保存在 src/components/icons/ 目录
3. 确认所有组件文件名和命名符合规范
4. 确认 TypeScript 编译无错误
1. Confirm all inline SVGs have been replaced with components
2. Confirm all icon components are stored in the src/components/icons/ directory
3. Confirm all component filenames and naming comply with specifications
4. Confirm TypeScript compilation has no errors

操作步骤

Operation Steps

1. 创建图标目录结构

1. Create Icon Directory Structure

在项目根目录执行以下操作：
  • 创建 
    components/icons/
    目录（如果不存在）
  • 该目录将存放所有图标组件
Execute the following operations in the project root directory:
  • Create the 
    components/icons/
    directory (if it does not exist)
  • This directory will store all icon components

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

2. Extract and Encapsulate SVG as React Components

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

2.1 Identify and Read Icons to Migrate

执行步骤：
  1. 使用文件搜索工具查找项目中所有 
    .tsx
    和 
    .jsx
    文件
  2. 在这些文件中搜索内联的 
    <svg>
    标签
  3. 记录所有包含内联 SVG 的文件路径和行号
  4. 读取这些文件，提取完整的 SVG 代码
  5. 识别每个 SVG 的用途（按钮图标、导航图标等）
关键检查点：
  • 已定位所有内联 SVG 的位置
  • 已记录每个 SVG 的上下文用途
  • 已提取完整的 SVG 代码（包括 viewBox、path 等）
Execution Steps:
  1. Use a file search tool to find all 
    .tsx
    and 
    .jsx
    files in the project
  2. Search for inline 
    <svg>
    tags in these files
  3. Record the file paths and line numbers of all files containing inline SVG
  4. Read these files and extract the complete SVG code
  5. Identify the purpose of each SVG (button icon, navigation icon, etc.)
Key Checkpoints:
  • Located all inline SVG positions
  • Recorded the contextual purpose of each SVG
  • Extracted complete SVG code (including viewBox, path, etc.)

2.2 转换 SVG 为 React 组件

2.2 Convert SVG to React Components

执行步骤： 对于每个提取的 SVG，执行以下操作：
  1. 读取并解析 SVG 代码：获取完整的 
    <svg>
    标签及其内容
  2. 转换文件名：将原始文件名或功能描述转换为 PascalCase 格式
  3. 创建组件文件：在 
    src/components/icons/
    目录下创建 
    .tsx
    文件
  4. 编写组件代码：参考 references/icon-component-template.md，按照模板编写组件
  5. 保存文件：将创建的组件保存到 
    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
Execution Steps: For each extracted SVG, perform the following operations:
  1. Read and Parse SVG Code: Obtain the complete 
    <svg>
    tag and its content
  2. Convert Filename: Convert the original filename or functional description to PascalCase format
  3. Create Component File: Create a 
    .tsx
    file in the 
    src/components/icons/
    directory
  4. Write Component Code: Refer to references/icon-component-template.md and write the component following the template
  5. Save File: Save the created component to the 
    src/components/icons/
    directory
Example Operation:
Input: Arrow SVG extracted from Button.tsx
  ↓
Step 1: Read SVG code <svg viewBox="0 0 24 24"><path d="..." /></svg>
  ↓
Step 2: Convert filename to ArrowRight
  ↓
Step 3: Create src/components/icons/ArrowRight.tsx
  ↓
Step 4: Write component code referring to the template
  ↓
Step 5: Save the file
Complete Template and Examples: See references/icon-component-template.md

3. 更新业务组件

3. Update Business Components

3.1 替换内联 SVG

3.1 Replace Inline SVG

执行步骤： 对于每个包含内联 SVG 的业务组件：
  1. 定位内联 SVG 代码：找到组件中的 
    <svg>
    标签
  2. 记录原始属性：记下原有的 width、height、fill、className 等属性值
  3. 添加导入语句：在文件顶部添加 
    import IconName from '@/components/icons/IconName'
  4. 替换 SVG 标签：删除 
    <svg>
    标签及其内容，替换为 
    <IconName />
  5. 迁移属性：将原始属性作为 props 传递给新组件（如 
    <IconName width={24} height={24} />
    ）
  6. 验证功能：确认替换后组件功能和样式保持一致
Execution Steps: For each business component containing inline SVG:
  1. Locate Inline SVG Code: Find the 
    <svg>
    tag in the component
  2. Record Original Attributes: Note the original values of attributes such as width, height, fill, className
  3. Add Import Statement: Add 
    import IconName from '@/components/icons/IconName'
    at the top of the file
  4. Replace SVG Tag: Delete the 
    <svg>
    tag and its content, replace it with 
    <IconName />
  5. Migrate Attributes: Pass the original attributes as props to the new component (e.g., 
    <IconName width={24} height={24} />
    )
  6. Verify Functionality: Confirm the component's functionality and style remain consistent after replacement

3.2 使用封装的 Icon 组件

3.2 Use Encapsulated Icon Components

  • 从 
    components/icons
    导入图标组件
  • 按需传递 props（size、color 等）
  • 支持通过 className 自定义样式
详细使用示例见 references/best-practice-examples.md
  • Import icon components from 
    components/icons
  • Pass props (size, color, etc.) as needed
  • Support custom styles via className
Detailed usage examples can be found in references/best-practice-examples.md

4. 图标迁移检查清单

4. Icon Migration Checklist

完整的迁移检查清单详见 references/migration-checklist.md，包含：
  • 迁移前环境检查
  • 逐步迁移操作指南
  • 迁移后功能验证
  • 常见问题解决方案
The complete migration checklist is available in references/migration-checklist.md, including:
  • Pre-migration environment checks
  • Step-by-step migration operation guide
  • Post-migration functionality verification
  • Common problem solutions

5. 代码审查与规范检查

5. Code Review and Specification Check

在完成迁移后，检查以下规范：
禁止场景：
  • ❌ 禁止在业务组件内直接写 SVG 代码
  • ❌ 禁止在 icons 目录外存放独立的 SVG 组件文件
  • ❌ 禁止在非 components/icons 目录下创建图标组件
规范要求：
  • ✅ 所有 SVG 图标必须封装为 React 组件
  • ✅ 组件必须保存在 
    components/icons/
    目录下
  • ✅ 必须从 
    components/icons
    导入使用
  • ✅ 组件必须包含 TypeScript 类型定义
  • ✅ 支持通过 props 配置常用属性
详细的规范要求详见各参考文档。
After completing the migration, check the following specifications:
Prohibited Scenarios:
  • ❌ Directly writing SVG code in business components is prohibited
  • ❌ Storing independent SVG component files outside the icons directory is prohibited
  • ❌ Creating icon components outside the non components/icons directory is prohibited
Specification Requirements:
  • ✅ All SVG icons must be encapsulated as React components
  • ✅ Components must be stored in the 
    components/icons/
    directory
  • ✅ Must be imported and used from 
    components/icons
  • ✅ Components must include TypeScript type definitions
  • ✅ Support configuration of common attributes via props
Detailed specification requirements can be found in each reference document.

资源索引

Resource Index

  • 最佳实践示例：见 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（基于实际项目的最佳实践和使用说明）
  • Best Practice Examples: See best-practice-examples/ (actual project examples, including components and assets)
    • best-practice-examples/components/icons/ - Icon component examples
    • best-practice-examples/assets/ - Business component examples
  • Component Template: See references/icon-component-template.md (standard React icon component template, attribute configuration, common variants)
  • Migration Checklist: See references/migration-checklist.md (complete migration check items, problem solutions)
  • Best Practice Documentation: See references/best-practice-examples.md (best practices and usage instructions based on actual projects)

注意事项

Notes

  • 仅在需要创建新的图标组件或迁移现有图标时读取参考文档
  • 智能体已具备理解和转换 SVG 代码的能力，无需自动化脚本
  • 转换时保留 SVG 的 viewBox 和 path 数据，确保图标形状不变
  • 默认 fill="currentColor" 以支持通过 CSS 控制颜色
  • 使用 TypeScript 确保类型安全，避免运行时错误
  • best-practice-examples/ 目录包含实际项目示例，可供参考
  • Only read reference documents when creating new icon components or migrating existing icons
  • Agents already have the ability to understand and convert SVG code, no automation scripts required
  • Retain the viewBox and path data of SVG during conversion to ensure the icon shape remains unchanged
  • Default fill="currentColor" to support color control via CSS
  • Use TypeScript to ensure type safety and avoid runtime errors
  • The best-practice-examples/ directory contains actual project examples for reference

使用示例

Usage Examples

场景 1：迁移现有内联 SVG

Scenario 1: Migrate Existing Inline SVG

需求： 将 Button 组件中的内联箭头图标提取为独立组件
执行方式： 智能体手动执行
  1. 读取 Button 组件中的 SVG 代码
  2. 参考 references/icon-component-template.md 创建 ArrowRight.tsx
  3. 参考 best-practice-examples/components/icons/ 中的示例
  4. 替换 Button 组件中的内联 SVG
  5. 测试验证显示效果
Requirement: Extract the inline arrow icon in the Button component into an independent component
Execution Method: Manual execution by agent
  1. Read the SVG code in the Button component
  2. Refer to references/icon-component-template.md to create ArrowRight.tsx
  3. Refer to examples in best-practice-examples/components/icons/
  4. Replace the inline SVG in the Button component
  5. Test and verify the display effect

场景 2：创建新图标规范

Scenario 2: Create New Icon Specifications

需求： 新项目需要建立图标管理规范
执行方式： 智能体自然语言指导
  1. 创建 components/icons/ 目录
  2. 参考 references/icon-component-template.md 创建图标组件
  3. 参考 best-practice-examples/components/icons/ 中的桶导出方式
  4. 在项目中推行统一的图标使用方式
Requirement: A new project needs to establish icon management specifications
Execution Method: Natural language guidance by agent
  1. Create the components/icons/ directory
  2. Refer to references/icon-component-template.md to create icon components
  3. Refer to the barrel export method in best-practice-examples/components/icons/
  4. Promote a unified icon usage method in the project

场景 3：批量迁移图标

Scenario 3: Batch Migrate Icons

需求： 项目中有多个内联 SVG 需要统一迁移
执行方式： 智能体逐个处理
  1. 扫描识别所有内联 SVG 位置
  2. 按照 references/migration-checklist.md 逐个迁移
  3. 替换所有业务组件中的内联 SVG
  4. 执行完整回归测试
Requirement: Multiple inline SVGs in the project need to be migrated uniformly
Execution Method: Process one by one by agent
  1. Scan and identify all inline SVG positions
  2. Migrate one by one according to references/migration-checklist.md
  3. Replace all inline SVGs in business components
  4. Perform complete regression testing