在 open-slide 中正确使用 shadcn 图标：iconLibrary、data-icon 与组件式图标规范
在 open-slide 中正确使用 shadcn 图标：iconLibrary、data-icon 与组件式图标规范
本指南解析 open-slide 仓库内 .agents/skills/shadcn/rules/icons.md 中定义的 shadcn 图标使用规范，说明在基于 shadcn/ui 的 React 组件中如何正确导入图标、在 Button 等复合组件中摆放图标、避免尺寸类冲突，并以组件对象而非字符串键传递图标。读完你将掌握一套可直接落地到该仓库组件开发（以及任何 shadcn 项目）的图标实践。
一、总原则：始终使用项目配置的 iconLibrary
规范的第一条硬性要求是：永远从项目配置的 iconLibrary 字段所对应的图标库导入图标，而不是想当然地假设 lucide-react。
// 先确认项目的 iconLibrary 配置
// lucide → import ... from "lucide-react"
// tabler → import ... from "@tabler/icons-react"
在 open-slide 仓库中，packages/core/components.json 明确声明：
{
"style": "new-york",
"rsc": false,
"tsx": true,
"iconLibrary": "lucide"
}
因此本仓库内所有 shadcn 组件都应从 lucide-react 导入图标。这一点在源码中得到了验证：例如 packages/core/src/app/components/ui/select.tsx 顶部即 import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react"。
实践要点
- 开工前先读取项目根目录或组件目录下的
components.json，确认iconLibrary取值； - 若项目迁移图标库（如从 lucide 切到 tabler），全局搜索并批量替换导入来源，切勿局部混用两个库，否则会出现图标风格不一致甚至缺失的问题；
- 该字段决定导入语法，但
data-icon、组件式传参等使用规范与具体图标库无关，任何库都适用。
二、Button 中的图标使用 data-icon 属性
在 Button 这类复合组件中，图标的前置（prefix）与后置（suffix）位置通过 data-icon 属性表达，而不是靠 margin 工具类硬推间距。
错误的写法：
<Button>
<SearchIcon className="mr-2 size-4" />
Search
</Button>
正确的写法：
<Button>
<SearchIcon data-icon="inline-start"/>
Search
</Button>
<Button>
Next
<ArrowRightIcon data-icon="inline-end"/>
</Button>
data-icon="inline-start"：图标位于文本之前（前缀）；data-icon="inline-end"：图标位于文本之后（后缀，常用于「下一步」箭头）；- 图标上不要加任何尺寸类，间距与尺寸由组件自身的 CSS 统一处理。
open-slide 实际代码同样遵循这一约定，例如 packages/core/src/app/components/inspector/inspector-panel.tsx 中的 <PencilLine data-icon="inline-start" />。
三、组件内部禁止给图标加尺寸类
Button、DropdownMenuItem、Alert、Sidebar* 等 shadcn 组件已经通过 CSS 为内部 SVG 定义了尺寸，开发者不应再叠加 size-4、w-4 h-4 之类的 Tailwind 尺寸类。除非用户明确要求自定义图标大小，否则一律不加。
错误的写法：
<Button>
<SearchIcon className="size-4" data-icon="inline-start" />
Search
</Button>
<DropdownMenuItem>
<SettingsIcon className="mr-2 size-4" />
Settings
</DropdownMenuItem>
正确的写法：
<Button>
<SearchIcon data-icon="inline-start" />
Search
</Button>
<DropdownMenuItem>
<SettingsIcon />
Settings
</DropdownMenuItem>
以 open-slide 的 Button 实现为例，其变体样式通过 Tailwind 任意选择器统一约束内部 SVG：
"[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5",
[&_svg]:pointer-events-none：阻止 SVG 拦截点击事件；[&_svg]:shrink-0：防止 SVG 在 flex 布局中被压缩；[&_svg:not([class*='size-'])]:size-3.5：仅当 SVG 自身没有尺寸类时才套用默认size-3.5——这意味着如果你手动加了尺寸类，就会覆盖组件的统一视觉节奏，这正是规范禁止加尺寸类的原因所在。
因此，规范与源码互为印证：尺寸控制权属于组件层，图标自身只负责「存在」。
四、以组件对象传递图标，而非字符串键
当封装带图标的自定义组件（如徽章、状态标签、菜单项工厂）时，应把图标作为组件对象（React.ComponentType）传入，而不是用字符串去索引一个图标映射表。
错误的写法：
const iconMap = {
check: CheckIcon,
alert: AlertIcon,
}
function StatusBadge({ icon }: { icon: string }) {
const Icon = iconMap[icon]
return <Icon />
}
<StatusBadge icon="check" />
正确的写法：
// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).
import { CheckIcon } from "lucide-react"
function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
return <Icon />
}
<StatusBadge icon={CheckIcon} />
为什么要这样做
- 类型安全：
icon: React.ComponentType是强类型约束，拼错字符串键会在运行时才暴露，而传错组件对象会在编译期报错； - Tree Shaking 友好：直接引用具名导出，打包器可以精确剔除未使用图标，字符串映射表则可能整体拖入整包图标；
- 可组合性强：调用方可自由传入任意图标组件（甚至自定义 SVG 组件），无需预先在映射表登记；
- 符合 shadcn 生态惯例：shadcn 组件（如
Dialog、DropdownMenu）本身也以组件属性接收图标，保持一致的心智模型。
五、四条规范速查
| 场景 | 做法 | 反例 |
|---|---|---|
| 选择图标库 | 依据 components.json 的 iconLibrary 字段导入 |
默认假设 lucide-react |
| Button 内图标定位 | data-icon="inline-start" / data-icon="inline-end" |
className="mr-2 size-4" |
| 组件内图标尺寸 | 交给组件 CSS，不加尺寸类 | size-4、w-4 h-4 |
| 传参方式 | 传 React.ComponentType 组件对象 |
字符串键 + iconMap 查找 |
六、规范背后的工程意图
从 open-slide 的源码结构看，这套规范服务于「组件样式单一职责」的工程目标：图标库的选择权归项目配置（components.json），图标的外观尺寸归组件 CSS（如 Button 的 [&_svg...] 规则），开发者只负责表达「放哪、放什么」。当主题（themes）、设计预设或未来切换图标库时，只需改动配置与组件样式层，业务代码中的图标用法无需批量调整。
在 open-slide 的开发流程中，该规范同样作为 Agent 的编码约束存在：它位于 .agents/skills/shadcn/rules/ 目录，与 shadcn 技能规则配套，确保 AI 助手与人类开发者产出的 UI 代码遵循同一套图标约定，避免因习惯差异引入 mr-2 size-4 这类与组件样式冲突的 hack。相关可继续阅读的仓库文件：