知识深度解析
企业级
组件库设计
为什么需要企业级组件库？
四层架构模型
一个优秀的组件库应该像洋葱一样分层——每一层只依赖下层，绝不反向引用。 点击每一层查看详细说明。
Design Tokens
Layer 0 · Foundation
示例内容
colorsspacingtypographyshadowsradiibreakpointsz-index
关键原则
- 1所有设计决策抽象为 CSS 变量或 JS 常量
- 2支持 Light / Dark / Brand 多主题
- 3变量命名遵循语义化（如 --color-primary 而非 --blue-500）
- 4由设计师和工程师共同维护，版本化管理
↓ 被 Primitives 层依赖
四大设计原则
Design Tokens 体系
Design Tokens 是组件库的"设计基因"——它将颜色、间距、字号等设计决策 抽象为可编程的变量，实现"一处修改，全局生效"。
组件实验室
亲身体验一个 Button 组件的设计空间。调整 Variant、Size、状态，观察 API 设计如何覆盖所有场景。
配置面板
<Button
variant="primary"
size="md"
/>DesktopTabletMobile
Primary
Default
Primary
Hover
Primary
Active
Primary
Focus
Primary
Variant × Size 矩阵
| sm | md | lg | |
|---|---|---|---|
| Primary | Primary | Primary | Primary |
| Secondary | Secondary | Secondary | Secondary |
| Outline | Outline | Outline | Outline |
| Ghost | Ghost | Ghost | Ghost |
主题系统
优秀的组件库应该支持多主题切换。所有视觉属性通过 CSS 变量控制，组件代码完全不需要修改。
Dashboard Card
Analytics overview
Revenue
Users
Conversion
Primary Action
Secondary
Same component · Different CSS variables
构建最佳实践
API 设计速查表
✅ 推荐做法
- 用 variant 而非大量 boolean props 控制样式
- 默认导出 + 命名导出并存，支持 Tree Shaking
- 用 asChild 模式支持自定义渲染元素
- 所有交互组件支持键盘操作和 ARIA 属性
- 用 displayName 方便调试，forwardRef 透传 ref
- 提供 compound components 模式（如 Select.Option）
✕❌ 避免的做法
- Props 数量超过 15 个（考虑拆分或用 composition）
- 在组件内部硬编码颜色、字号等视觉属性
- 直接操作 DOM（除 Portal、Focus Trap 等特殊场景）
- 忽略 SSR 兼容性（避免 useEffect 中的 layout 计算）
- 不提供 TypeScript 类型定义或文档注释
- 破坏性变更不走 semver major 版本号
技术栈选型
| 维度 | Radix + Tailwind | shadcn/ui | Headless UI |
|---|---|---|---|
| 无样式层 | ★★★★★ | ★★★★★ | ★★★★☆ |
| 可定制性 | ★★★★★ | ★★★★☆ | ★★★★★ |
| 无障碍性 | ★★★★★ | ★★★★★ | ★★★★☆ |
| 学习成本 | ★★★☆☆ | ★★★★★ | ★★★☆☆ |
| 生态丰富度 | ★★★★★ | ★★★★☆ | ★★★☆☆ |
| 企业级适用 | ★★★★★ | ★★★★☆ | ★★★★☆ |
核心洞察
好的组件库是「设计系统」的代码化身
它不仅仅是 UI 组件的集合，而是团队协作的契约、产品一致性的保障、 设计师与工程师之间的桥梁。从 Design Tokens 到自动化发布， 每一个环节都需要精心设计。
Design Tokens分层架构API 设计主题系统自动化发布