5 个关键问题 Q&A

Q1：Regen Icons 和普通 SVG 图标库最大差异是什么？ A：普通图标库 SVG 是源头；Regen 以 JSON 几何描述作为源码，SVG 属于编译产物，更适配 AI 生成图标。

Q2：新增图标为什么不能直接修改 SVG 文件？ A：SVG 是编译输出资产。修改 SVG 会被后续构建覆盖，必须编辑 generator/src 下的 .icon.json源文件。

Q3：硬约束和视觉建议分别承担什么作用？ A：硬约束由代码自动校验，不符合规则直接报错；视觉建议仅输出告警信息，图形美感最终靠人工复核。

Q4：Filled 填充图标是单独绘制的吗？ A：不是。复用同一套 JSON 源码，通过布尔运算自动生成，保证轮廓与填充图标几何完全对齐。

Q5：当前如何在项目中使用这套图标？ A：npm 包还未发布，可直接复制仓库 svg/outline 和 svg/filled 目录下的 SVG 文件使用。

一、Source-first：和传统图标库最大区别

传统图标库（Lucide、Tabler）：SVG 是源头，修改 SVG，再手动同步 React 组件、sprite 等产物；AI 很难读懂、保证风格统一。

Regen Icons：JSON 才是源码，SVG 是编译产物

• 源文件：generator/src/xxx.icon.json，用 12 种基础几何基元描述图形：line、polyline、rect、circle、arc、bend、quad、ellipse、dot、arrow、path、use
• 编译器：build-icons.mjs，把多基元合并成单条 SVG path，自动做风格润色
• 折线顶点自动加 2px 圆角
• 箭头按固定 6/8 规则生成箭头头部
• 同一套几何，自动派生 1.5 / 1.75 / 2 三档笔画宽度
• 一次构建，批量产出全部资产： outline/filled 独立 SVG、React 组件（icons.tsx）、sprite、icons.json 索引、预览画廊、视觉平衡报告

核心收益：一处修改，全部下游资产同步更新；JSON 对人和 AI 都可读，支持 diff 对比，这是 AI Agent 贡献图标最核心前提。

二、设计规范：硬约束（机器强制校验）+ 视觉建议（人工审查）分层

generator/docs/spec.md是整套系统的灵魂，把规则拆成两类，机器负责可量化规则，美感交给人眼。

✅ 编译器强制执行硬约束（校验不通过直接报错，CI 拦截）

1. 画布固定 24×24，安全区域 2–22，所有坐标必须落在整数 / 半格网格
2. 圆心、半径必须对齐半格；弧线角度为 45° 倍数；旋转只能 90° 倍数
3. 平行轴对齐笔画，中心间距≥3px（编译器自动两两比对所有线段）
4. 圆角上限：不超过短边 50%；禁止零长度线段、未知基元、文件名冲突等

💡 仅视觉建议（报告标记，不阻断构建）

• 墨量（笔画长度 × 宽度）、图形中心偏移、包围盒大小超标仅告警；部分图标天生墨量偏低（如 chevron），允许例外
• 视觉失衡的修复原则：调整图形重心，不能简单修改笔画宽度
• 审查基准：在 16px 尺寸下评估，不是放大到 96px；半个单位微调只是试验，不等于优化

设计哲学：机器解决所有可量化几何规则；曲线、视觉平衡、氛围感这类模糊判断交给人，避免 AI 以为 “CI 校验通过 = 图标合格”。

三、面向 AI Agent：三层指令文件 + 完整闭环工作流

项目内置三份 Agent 指令，支持 Claude / OpenAI Codex 接入，给 AI 一套完整可执行的新增图标流程：

1. AGENTS.md
   通用入口文档，读规范、查重、四步标准工作流
2. CLAUDE.md
   Claude Code 精简入口（10 行，指向 AGENTS.md）
3. .dev/SKILL.md
   完整 Agent 技能包，最详细操作规范

Agent 新增图标闭环流程

1. 编写 JSON 源文件，使用规定 12 种几何基元
2. pnpm check
   纯校验，不输出文件，校验硬约束
3. pnpm preview <图标名> <参考邻居图标> --matrix
   生成对比矩阵，覆盖多维度： 尺寸：16/20/24/32px × 三档笔画 × outline/filled 两种形态 × 深浅双主题
4. Agent 打开浏览器肉眼预览渲染结果（重点提醒：截图不算视觉审查）
5. pnpm test
   全量自动化测试
6. 提交 PR，CI 自动执行全部校验

AI 防呆规则

• ❌ 禁止直接复制其他图标库 SVG path，避免风格污染
• ✅ 区分两个标准：验证通过 = 几何合法；视觉审查 = 是否属于这套图标家族
• .dev/agents/openai.yaml
  预留 OpenAI Codex 接入配置

四、技术亮点：Outline / Filled 同源生成

填充版本不是单独绘制，复用同一套 JSON 几何源：

• 使用 paper.js 做布尔运算：轮廓闭合区域填充，开放线段转为胶囊形、圆弧转为环形扇区
• 生成 20% 透明度底色层，实现 tonal 色调填充效果 优势：轮廓与填充图标几何 100% 一致，不会出现两套图形视觉不匹配。

输出 SVG 特性：仅依赖currentColor，笔画宽度通过 CSS 变量--regen-icon-tone控制，原生支持深浅主题切换。

五、对比传统图标库的价值与边界

优势

1. AI 友好：结构化 JSON 源码，大模型更容易生成、修改、diff，摆脱 SVG path 字符串难控制的痛点
2. 一致性强：编译器锁死底层几何规则，AI 新增图标不会轻易跑偏风格
3. 多资产同步：维护成本低，一套源产出所有格式
4. 分层校验：把 “硬性工程规范” 和 “主观审美” 分开，适合 AI 辅助设计协作

局限

1. 只解决几何约束，最终审美仍然依赖人工复核，AI 不能独立完成最终验收
2. 自定义能力受限于 12 种基础基元，复杂图形表达能力弱于原生 SVG
3. 编译链路增加项目复杂度，小型图标库没必要引入这套系统

六、适用场景

• 需要批量由 AI Agent 持续扩充图标集的设计系统（B 端后台、管理平台）
• 团队想要标准化图标几何规则，统一多尺寸、轮廓 / 填充变体
• 希望把图标规范写成机器可执行代码，而不是纯文字设计文档