React Starter Kit 图标规范实战指南data-icon 属性、图标尺寸控制与组件化传递【免费下载链接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.项目地址: https://gitcode.com/gh_mirrors/rea/react-starter-kit导读本指南以 shadcn 技能库中的图标规则文档.agents/skills/shadcn/rules/icons.md为核心骨架结合本仓库react-starter-kit的packages/ui、apps/app的实际组件与路由源码系统讲解在 shadcn/ui 项目中正确使用图标的三条硬性规则始终使用项目配置的iconLibrary导入图标、在Button等组件内通过data-icon属性定位图标而不再手写尺寸类、以及以组件对象而非字符串键传递图标。读完本文你将能在 shadcn 组件中写出既符合设计系统规范、又具备类型安全与可维护性的图标代码。一、先从配置说起iconLibrary 决定图标导入路径在 shadcn/ui 体系中图标并非组件自带的固定资源而是由项目在components.json中声明的iconLibrary字段决定的。规则文档的第一条规则即明确始终使用项目配置的iconLibrary进行导入。检查项目上下文中的iconLibrary字段lucide→lucide-reacttabler→tabler/icons-react以此类推。永远不要默认假定是lucide-react。在本仓库中packages/ui/components.json的第 19 行声明了iconLibrary: lucideapps/app/components.json同样如此。因此本项目的正确导入方式为import { CheckIcon, SearchIcon, ArrowRightIcon } from lucide-react;为什么不能写死lucide-react因为 shadcn 的 preset 与社区 registry 允许项目自由切换图标库。一旦项目将iconLibrary切换为tabler或hugeicons写死的lucide-react导入将全部失效且图标命名如CheckvsCheckIcon也会随之变化。仓库的技能文档 .agents/skills/shadcn/SKILL.md 的“Key Fields”一节明确说明iconLibrary决定图标导入方式并强调“永远不要假设是lucide-react”。这也是在接入第三方 registry 组件后需要校验并替换图标导入的根本原因。二、规则一Button 内的图标使用data-icon属性问题传统做法为什么不对在 shadcn 组件内部图标不再需要手动添加间距与尺寸类。规则文档给出的反例{/* Incorrect */} Button SearchIcon classNamemr-2 size-4 / Search /Buttonmr-2手动制造图标与文本的间距size-4手动锁定图标尺寸。这两者都属于“把组件内部样式细节泄漏到调用方”的做法会导致图标尺寸与按钮变体default/sm/lg/icon不匹配间距在不同主题、不同按钮变体下无法统一调整视觉不一致维护成本高。正确写法data-icon定位图标位置规则文档给出的正例{/* Correct: 前缀图标 */} Button SearchIcon>[_svg]:pointer-events-none [_svg]:size-4 [_svg]:shrink-0这表示Button内部通过 CSS 选择器[_svg]自动对所有SVG 图标统一应用size-4即width: 1rem; height: 1rem与shrink-0防止 flex 压缩并禁用其指针事件。这就是“组件通过 CSS 管理图标尺寸”的实现证据——图标的大小由组件决定与调用方传入的 className 无关。因此即使你在Button内省略size-4图标也会被组件内部的[_svg]:size-4规则自动缩放到标准尺寸。而data-icon属性的作用则是让组件 CSS 能够区分图标在按钮中的位置前缀或后缀从而精确控制其与文本之间的间距如gap-2由Button的inline-flex items-center justify-center gap-2统一提供无需手动mr-2。三、规则二组件内部禁止为图标添加尺寸类适用范围规则文档明确指出禁止在Button、DropdownMenuItem、Alert、Sidebar*等 shadcn 组件内部为图标添加size-4、w-4 h-4等尺寸类。除非用户明确要求自定义图标尺寸。反例与正例{/* Incorrect */} Button SearchIcon classNamesize-4>{/* Incorrect */} const iconMap { check: CheckIcon, alert: AlertIcon, }; function StatusBadge({ icon }: { icon: string }) { const Icon iconMap[icon]; return Icon /; } StatusBadge iconcheck /;这种写法存在明显缺陷无类型安全icon是任意字符串拼写错误如chekc不会在编译期暴露运行时风险字符串键在映射表中不存在时返回undefined渲染直接崩溃维护成本高每新增一个图标都要同步维护映射表不利于 Tree Shaking整个映射表被引用编译器难以准确移除未使用的图标。正例直接传递组件对象// 从项目配置的 iconLibrary 导入如 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明确约束参数必须是 React 组件编译期即可捕获错误传参零映射开销调用方直接传入组件引用无需任何查找表Tree Shaking 友好只导入实际使用的图标打包体积更小命名解构{ icon: Icon }将 prop 重命名为局部变量Icon以便在 JSX 中作为组件使用JSX 要求组件名大写开头。仓库中的实际应用这一模式在本仓库中已有真实落地。看 apps/app/components/layout/sidebar-nav.tsx 的实现import type { LucideIcon } from lucide-react; interface SidebarNavItem { icon: LucideIcon; label: string; to: keyof FileRoutesByTo; } export function SidebarNav({ items }: SidebarNavProps) { return ( nav classNameflex-1 p-4 space-y-1 {items.map((item) ( Link key{item.to} to{item.to} className... item.icon classNameh-4 w-4 / span{item.label}/span /Link ))} /nav ); }这里icon字段的类型是LucideIconlucide-react 导出的图标组件类型item.icon /直接渲染传入的组件对象——正是“以组件对象传递图标”的工程化实践。调用方只需SidebarNav items{[{ icon: Settings, label: Settings, to: /settings }]} /与之类似apps/app/components/user-menu.tsx 中LogOut、RefreshCw、User均从lucide-react直接导入并以组件形式使用而 apps/app/components/auth/auth-form.tsx 中的Mail、ArrowLeft也是如此。这些页面级代码共同印证了规则三在真实项目中的落地形态。五、三条规则的内在逻辑让组件成为图标样式的唯一来源将三条规则放在一起看它们其实指向同一个设计原则规则解决的问题核心机制使用iconLibrary导入图标来源不确定components.json的iconLibrary字段data-icon属性图标在按钮中的位置前缀/后缀data-iconinline-start/inline-end禁止尺寸类图标尺寸与间距统一组件内 CSS[_svg]:size-4、gap-2组件对象传递类型安全与 Tree Shakingicon: React.ComponentType/LucideIcon其核心思想是图标是组件的“零件”组件的 CSS 负责其外观调用方只负责“放什么图标”和“放哪里”。这一约定保证了整个设计系统在不同页面、不同变体间保持视觉一致同时将图标的导入来源、尺寸、间距、类型约束集中管理。在实际编码中你可以通过npx shadcnlatest info --json获取当前项目的iconLibrary配置通过npx shadcnlatest docs component获取组件的 API 文档与示例参见 .agents/skills/shadcn/cli.md再结合本文的三条规则检查自己写的图标代码是否合规。六、快速自查清单在提交图标相关代码前请对照以下清单检查依据 .agents/skills/shadcn/rules/icons.md导入来源正确图标是否从项目iconLibrary对应的包导入本仓库为lucide-react而非写死其他图标库Button 内使用data-iconButton内的图标是否使用了data-iconinline-start或data-iconinline-end且未添加className组件内无尺寸类Button、DropdownMenuItem、Alert、Sidebar*等组件内部的图标是否没有任何size-*、w-* h-*、mr-*类组件对象传递自定义组件接收图标时是否使用icon{SomeIcon}类型为React.ComponentType或LucideIcon而非字符串键查找表页面级场景例外非 shadcn 组件内使用图标时尺寸与间距是否仍由你自己负责此时size-*类可用对照这三条规则与本仓库的 packages/ui 组件实现、apps/app 页面代码你就能写出与设计系统完全一致、类型安全且易于维护的 shadcn 图标代码。【免费下载链接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.项目地址: https://gitcode.com/gh_mirrors/rea/react-starter-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考