Coolify shadcn 技能规则：图标（Icons）使用规范与 iconLibrary 机制详解

Coolify shadcn 技能规则图标Icons使用规范与 iconLibrary 机制详解【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 仓库中面向 AI Agent 的 shadcn/ui 开发技能.agents/skills/shadcn/将 UI 编码约定拆解为多份规则文件其中 rules/icons.md 专门规定了组件库中图标的三条核心纪律导入来源必须遵循项目配置而非主观假设、图标尺寸交给组件 CSS 处理、图标以组件对象而非字符串键传递。本文完整覆盖这三条规则的判定标准与正误代码对照并结合 SKILL.md 中iconLibrary字段的定义机制和仓库内的真实配置示例说明这套规范在 Coolify v5 前端中的落地背景帮助你写出与 shadcn 组件 CSS 约定完全对齐的图标代码。一、总则导入必须来自项目配置的 iconLibrary禁止假设 lucide-react规则文件的第一条硬性约定是Always use the projects configurediconLibraryfor imports.Check theiconLibraryfield from project context:lucide→lucide-react,tabler→tabler/icons-react, etc. Never assumelucide-react.含义是写任何图标代码之前必须先确认项目上下文中的iconLibrary字段再决定从哪个 npm 包导入图标组件绝不能默认lucide-react。字段值到导入包名存在固定映射关系文档明确给出两个例子lucide→ 从lucide-react导入tabler→ 从tabler/icons-react导入其余值按同样规则推导etc. 表示映射模式一致。1.1 iconLibrary 字段从何而来在 SKILL.md 的 Current Project Context 一节可以看到该字段由 CLI 命令注入npx shadcnlatest info --json其输出 JSON 中包含了项目配置与已安装组件列表SKILL.md 的 Key Fields 一节对iconLibrary的定义与规则文件逐字呼应iconLibrary→ determines icon imports. Uselucide-reactforlucide,tabler/icons-reactfortabler, etc. Never assumelucide-react.从源码结构看该技能的工作流Workflow 第 7 步进一步要求凡是npx shadcnlatest add从社区 registry 添加的组件若其图标导入与项目iconLibrary不一致例如 registry 项用了lucide-react而项目实际用hugeicons必须替换导入与图标名称。也就是说iconLibrary不仅约束自己写的代码也约束所有从外部注册表拉进来并需要审查的组件文件。1.2 Coolify v5 的真实示例iconLibrary 是 phosphor这条永不假设 lucide的规则在 Coolify 仓库里有一个现成的反面教材。v5 前端的 shadcn 配置存档 docs/v5/archive/components.json.txt 显示{ $schema: https://ui.shadcn.com/schema.json, style: base-lyra, iconLibrary: phosphor, tailwind: { css: resources/css/v5/app.css, baseColor: zinc, cssVariables: true }, aliases: { components: /components, ui: /components/ui } }该项目iconLibrary取值为phosphor而非lucide。如果开发者按惯性写出import { SearchIcon } from lucide-react就违反了图标来源与项目配置一致性的约定。这个存档也顺带印证了components.json是 CLI 的唯一配置来源——cli.md 开篇即声明 Configuration is read fromcomponents.json因此iconLibrary的实际取值始终以该文件或info --json的解析结果为准。二、规则一Button 内的图标使用>Button SearchIcon classNamemr-2 size-4 / Search /Button错误点有二一是用mr-2手工控制图标与文字间距二是用size-4手工控制图标尺寸——这两件事 shadcn 组件的 CSS 都已经处理好了。正确示例Button SearchIcon>// Icons in buttons:>Button SearchIcon classNamesize-4>Button SearchIcon>const iconMap { check: CheckIcon, alert: AlertIcon, } function StatusBadge({ icon }: { icon: string }) { const Icon iconMap[icon] return Icon / } StatusBadge iconcheck /正确做法// Import from the projects 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} /对照两段代码可以看到差异集中在类型声明正确写法将 props 类型声明为React.ComponentType调用处传的是组件引用{CheckIcon}而非字符串check。这样做的好处是可调用性、树摇和类型检查都在编译期成立字符串查表则引入了运行时映射层——图标不存在时静默得到undefined且查表本身必须与各 iconLibrary 包的具体图标名保持同步等于把规则第一条导入来源不固定的复杂度扩散到了每个查表模块。五、三条规则在技能体系中的位置与执行闭环从 SKILL.md 的 Critical Rules 一节可以看到icons.md 与 styling、forms、composition、base-vs-radix 五份规则文件共同构成始终强制执行的约束集合其中图标部分被摘要为三条Icons inButtonusedata-icon.data-iconinline-startordata-iconinline-endon the icon.No sizing classes on icons inside components.Components handle icon sizing via CSS. Nosize-4orw-4 h-4.Pass icons as objects, not string keys.icon{CheckIcon}, not a string lookup.每条都回链到 rules/icons.md 查看完整的 Incorrect/Correct 代码对。执行闭环则体现在 Workflow 第 7 步add任何 registry 组件后必须读回文件并校验其中明确包含将图标导入替换为项目iconLibrary对应的包并相应调整图标名这一动作最后再检查是否违反上述 Critical Rules。换言之图标规范不是写给人类自觉遵守的建议而是被写进了 Agent 每次添加组件后的强制审查清单。六、实操清单写图标代码前的三个检查项综合规则文件与 SKILL.md 的上下文机制在 Coolify v5 这类 shadcn 项目中编写或审查图标相关代码时可按以下清单自查查导入来源运行npx shadcnlatest info --json或查看项目components.json读取iconLibrary字段按映射关系选择导入包。Coolify v5 存档配置中该字段为phosphor此时lucide-react的导入即为违规查组件内尺寸类确认Button、DropdownMenuItem、Alert、Sidebar*等组件内部的图标没有size-*、w-* h-*类按钮内前缀/后缀图标改用data-iconinline-start/data-iconinline-end声明位置查传递方式组件 props 中接收图标时使用React.ComponentType类型的组件对象icon{CheckIcon}删除字符串键 iconMap的查表模式。以上规范均以仓库文件为事实依据规则本体见 icons.mdiconLibrary字段定义与强制审查流程见 SKILL.mdCLI 配置来源见 cli.mdCoolify v5 的 iconLibrary 取值实例见 components.json.txt。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考