图标配置（Icon Registry）

@plaud/design 不内置任何图标实现，只定义一份「图标契约」（IconRegistry）。组件内部用到的全部图标，都由使用方在应用入口处注入，design 不做任何兜底—— 未注入或缺失某个图标时，相关组件会在渲染时抛错。

这样设计的好处：

图标实现与组件库解耦，业务方可以接入任意图标库（自绘 SVG、lucide-react 等）
全局一处配置，整站统一替换
TypeScript + 运行时双重校验，缺图标在编译期 / 开发期即暴露

快速开始

在应用根部用 DesignProvider（或轻量的 IconRegistryProvider）注入一份覆盖全部 key 的 registry：

import { DesignProvider } from '@plaud/design'
import type { IconRegistry } from '@plaud/design'

const icons = {
  search: MySearchIcon,
  calendar: MyCalendarIcon,
  // …覆盖 IconRegistry 的全部 key
} satisfies IconRegistry

export const App = () => (
  <DesignProvider icons={icons}>
    <YourApp />
  </DesignProvider>
)

satisfies IconRegistry 会在编译期校验：少一个 key、或某个图标组件的 props 类型不符（例如 sort 必须接收 sortDirection），都会直接报错。

两种 Provider

Provider	能力	适用场景
`DesignProvider`	主题 + Overlay 宿主 + 图标注入（`icons` 必填）	业务应用入口，一站式
`IconRegistryProvider`	仅图标注入（`icons` 必填），不管理主题	主题由外部托管的场景（如本文档站的 Docusaurus）

图标契约（IconKey）

IconRegistry 的全部 key 可通过运行时常量 ICON_KEYS 获取：

import { ICON_KEYS } from '@plaud/design'

console.log(ICON_KEYS) // ['infoCircle', 'checkmarkCircle', ...]

其中绝大多数图标的类型是 ComponentType<IconProps>（IconProps 等价于原生 <svg> 的 props）； sort 比较特殊，额外接收 sortDirection，类型为 ComponentType<SortIconProps>。

接入自己的图标库

只要满足契约即可替换为任意来源，例如使用 lucide-react：

import { Search, Calendar, ChevronDown } from 'lucide-react'
import type { IconRegistry } from '@plaud/design'

const icons = {
  search: Search,
  calendar: Calendar,
  chevronDown: ChevronDown,
  // …其余 key
} satisfies IconRegistry

参考实现

本文档站使用一套来自 Figma Design System 的默认实现（packages/design-site/src/icons/plaud-icon-registry.tsx），并在 src/theme/Root.tsx 中通过 IconRegistryProvider 注入，使下方所有组件示例都能正常渲染图标：

src/theme/Root.tsx
import { IconRegistryProvider } from '@plaud/design'

import { plaudIconRegistry } from '../icons/plaud-icon-registry'

const Root = ({ children }) => (
  <IconRegistryProvider icons={plaudIconRegistry}>{children}</IconRegistryProvider>
)

业务方可以直接复制这份 plaudIconRegistry 作为起点，再按需替换其中的图标。

校验行为

编译期：DesignProvider / IconRegistryProvider 的 icons 为必填，satisfies IconRegistry 保证全量覆盖
开发期：Provider 挂载时若发现缺失的 key，会在 console.error 中列出
运行期：组件渲染到某个未提供的图标时抛错，提示缺失的 key

快速开始​

两种 Provider​

图标契约（IconKey）​

接入自己的图标库​

参考实现​