shadcn/ui 图标规范解析：iconLibrary 配置、data-icon 属性与图标组件化传参

在 shadcn/ui（本仓库 ui/ui）中，图标看似是小事，却是组件一致性的关键：图标库由项目配置决定、尺寸由组件样式接管、图标以组件对象而非字符串传递。本文基于仓库中的图标规则文件 skills/shadcn/rules/icons.md 展开，逐条讲解三条强制规则的来龙去脉，并结合 CLI 源码（icons/libraries.ts、preset.ts、migrate-icons.ts）与组件实现（button.tsx）说明规则背后的机制，读完你可以掌握：如何正确识别并使用当前项目的图标库、为什么按钮内图标要用 data-icon 属性、以及为什么"字符串键查图标"是反模式。

规则一：永远使用项目配置的 iconLibrary，绝不默认假设 lucide-react

规则文件的第一条要求：始终从项目上下文的 iconLibrary 字段确认图标库来源，lucide 对应 lucide-react、tabler 对应 @tabler/icons-react，以此类推——绝不能默认假设是 lucide-react。

这条规则对应的是每个 shadcn/ui 项目根目录的 components.json。本仓库 v4 应用自身的配置就是范例，见 apps/v4/components.json：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/registry/new-york-v4/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

也就是说：同一个项目换一张 components.json，图标导入来源就应该跟着变。CLI 侧对"合法图标库"有一套权威映射表，定义在 packages/shadcn/src/icons/libraries.ts 中，当前支持 5 个图标库，每个条目包含 npm 包名、导入语句模板、用法示例和导出名：

iconLibrary 值	包名	导入方式	用法
lucide	lucide-react	import { ICON } from 'lucide-react'	<ICON />
tabler	@tabler/icons-react	import { ICON } from '@tabler/icons-react'	<ICON />
hugeicons	@hugeicons/react、@hugeicons/core-free-icons	双包导入	<HugeiconsIcon icon={ICON} strokeWidth={2} />
phosphor	@phosphor-icons/react	import { ICON } from '@phosphor-icons/react'	<ICON strokeWidth={2} />
remixicon	@remixicon/react	import { ICON } from '@remixicon/react'	<ICON />

从这份映射可以推断出两个实操要点：

1. 不同图标库的组件形态不同。比如 hugeicons 不是直接渲染 <Icon />，而是 <HugeiconsIcon icon={ICON} strokeWidth={2} /> 这种"外壳 + 图标数据"的形式，写代码前必须按映射表确认，而不是照搬 lucide 的写法。
2. iconLibrary 字段贯穿 CLI 全流程：
   • init 时可选，缺省回退为 lucide（packages/shadcn/src/commands/init.ts 中 let iconLibrary = defaultConfig.iconLibrary ?? "lucide"）；
   • 预设（preset）代码里编码了图标库选择，iconLibrary 占 6 个 bit（packages/shadcn/src/preset/preset.ts），不同预设各有默认值，例如 nova 预设默认 lucide、另有预设默认 hugeicons 或 phosphor（见 packages/shadcn/src/preset/defaults.ts）；
   • npx shadcn@latest info 会输出并展示 iconLibrary（packages/shadcn/src/commands/info.ts）；
   • 若 components.json 中写了一个不支持的库，CLI 会报出错误码 14（INVALID_CONFIG_ICON_LIBRARY，见 packages/shadcn/src/utils/errors.ts）。

因此给 Agent 或人类开发者写图标代码前，标准动作是：读 components.json → 取 iconLibrary → 按映射表确定包名与导入形式。跳过这一步直接 import { Search } from "lucide-react"，在 tabler 或 phosphor 项目里就是错的。

规则二：Button 中的图标使用 data-icon 属性

规则第二条：给按钮内的图标加 data-icon="inline-start"（前缀图标）或 data-icon="inline-end"（后缀图标），图标上不加任何尺寸类。

错误写法：

<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>

为什么这样设计？从组件源码看，shadcn/ui 的 Button 已经把"图标与文字的排布"内置到样式层。以 base 版按钮为例（apps/v4/registry/bases/base/ui/button.tsx），基类中内置了 [&_svg]:pointer-events-none [&_svg]:shrink-0，即所有子 svg 自动禁止事件、禁止收缩；尺寸与间距则由 cn-button 一族工具类（如 cn-button-size-default、cn-button-variant-default）按当前 size 变体统一控制，并依据 data-icon 属性决定是否压缩图标旁内边距。也就是说：

• data-icon 是语义声明：告诉样式系统"我是前缀/后缀图标"，从而应用正确的间距规则（例如 inline-end 时不需要右外边距）；
• 手动写 mr-2 size-4 会与组件内建尺寸逻辑打架：按钮 size 变化（sm/lg/icon）时图标大小不会跟随，前缀/后缀间距也与样式系统脱钩。

同样的组合方式还出现在其他场景，例如 SKILL.md 中关于按钮加载态的要求：Button 没有 isPending/isLoading 属性，正确做法是 Spinner + data-icon + disabled 组合（见 skills/shadcn/SKILL.md 的 Component Structure 一节）。这说明 data-icon 不是一次性技巧，而是 shadcn/ui 图标排布的统一约定。

规则三：组件内部的图标禁止手写尺寸类

规则第三条：在 Button、DropdownMenuItem、Alert、Sidebar* 等 shadcn 组件内部，不要给图标加 size-4、w-4 h-4 等尺寸类，因为组件通过 CSS 自行管理图标尺寸——除非用户明确要求自定义图标大小。

错误写法：

<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>

这条规则与规则二同源：shadcn/ui 的组件在样式层对"内部 svg"做了统一处理（Button 的 [&_svg]:shrink-0、DropdownMenuItem/Alert 等组件同样在 CSS 中定义图标尺寸），外部再叠一层 size-4 会造成两处真值并存——一旦主题或组件变体调整了默认图标尺寸，手写类名就成了顽固的例外点。从源码结构看，这类尺寸都收敛在各组件的 cn-* 工具类与 cva 变体里（button.tsx 的 buttonVariants 即为例证），所以"删掉手写尺寸类"几乎总是安全的默认选择；只有用户显式提出"这个图标要更大/更小"时才例外。

规则四：以组件对象传递图标，而不是字符串键

规则第四条：传图标时用组件对象，icon={CheckIcon}，而不是"字符串键 + 查表"。

错误写法：

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} />

背后的工程理由有三点：

1. 类型安全前移。icon: React.ComponentType 让调用方在传入 icon="check" 这种字符串拼错时立刻得到类型报错；字符串键方案里，键名错误只在运行时表现为 iconMap[icon] 取到 undefined 再渲染崩溃。
2. 消除隐式查表层。字符串键 + 映射表把"键到组件"的绑定藏在一个模块级对象里，换图标库（如 lucide → tabler）时除了改导入还要同步维护映射表；组件对象直传则只需改导入与 JSX，映射表整体消失。
3. 与规则一联动。正确写法中的注释特别强调"从项目配置的 iconLibrary 导入"——组件对象本身与具体图标库解耦（React.ComponentType 不关心它来自 lucide 还是 tabler），只有导入语句跟随 components.json 变化。

图标库切换：CLI 提供的迁移与校验能力

以上规则主要约束"日常写码"，而 shadcn/ui CLI 还为"整体换图标库"提供了工具链：

• 迁移命令：packages/shadcn/src/migrations/migrate-icons.ts 定义了 MIGRATION_ICON_LIBRARIES（源库→目标库的迁移路径），会交互式选择目标库、改写组件源码中的图标导入与用法，并同步更新 components.json 的 iconLibrary 字段（migrate-icons.ts 中的 updateConfigIconLibrary）。这解释了为什么 iconLibrary 必须是 components.json 的单一事实来源：迁移命令正是靠它知道"当前在哪个库"。
• 预设切换：通过 --preset 或 preset 编码可以整体切换设计系统，图标库选择被编码在 preset 的 6-bit 字段里（packages/shadcn/src/preset/preset.ts），apply 时会把 iconLibrary 同步回配置（packages/shadcn/src/commands/apply.ts）。
• 验证手段：npx shadcn@latest info 输出中的 iconLibrary 字段（info.ts）可用于确认当前项目实际生效的图标库；相关行为在 preset.test.ts 等测试中有覆盖（对所有 PRESET_ICON_LIBRARIES 逐一做 encode/decode 往返断言）。

小结：图标写码自检清单

结合 skills/shadcn/rules/icons.md 的四条规则与上面的源码依据，日常检查可收敛为一张清单：

1. 导入前：读项目 components.json 的 iconLibrary，按 libraries.ts 的映射确定包名与导入形式，不默认 lucide-react；
2. 按钮/组件内图标：加 data-icon="inline-start" 或 data-icon="inline-end"，不写 mr-*、size-*、w-4 h-4；
3. 所有 shadcn 组件内部：图标不手动定尺寸，除非用户显式要求自定义大小；
4. props 传递图标：类型写 React.ComponentType，直接传组件对象，删除"字符串键 + 图标映射表"的写法。

这四条规则的本质是一致的：把图标的来源（iconLibrary）、尺寸（组件 CSS）、身份（组件对象）分别收敛到各自单一的管理点，让图标代码在换库、换主题、换 size 变体时都不需要逐处手工修正。