🎨 ZenUI

一个规范驱动的 React 组件库，展示现代前端系统设计能力。

为什么是 ZenUI？

这不是又一个"快速搭建"的组件库教程项目。ZenUI 展示的是如何系统性地设计、开发、测试和交付一个生产级组件库。

| 常见组件库开发模式 | ZenUI 模式 | | --- | --- | | 业务驱动，被动生长 | 规范驱动，主动设计 | | 文档滞后于代码 | 文档同步，Storybook 即文档 | | 测试覆盖不均 | 分层策略，核心路径 + 无障碍 | | 样式硬编码或 CSS-in-JS 混用 | Design Tokens + CSS Variables，主题原生切换 | | 代码即交付物 | 流程即交付物，可复制的生产模式 |

快速开始

# 安装
npm install @deda/zenui react react-dom

# 引入组件和样式
import { ThemeProvider, Button } from '@deda/zenui';
import '@deda/zenui/style.css';

# 使用
<ThemeProvider>
  <Button variant="primary">Hello ZenUI</Button>
</ThemeProvider>

组件清单

基础组件

• Button — 5 种变体、3 种尺寸、加载/禁用状态、图标集成
• Icon — 10+ 常用图标，SVG + currentColor，支持 Tree Shaking
• Input — 3 种变体、前缀/后缀、Addon、完整的表单校验集成

复合组件

• Modal — Portal 渲染、焦点陷阱、键盘导航、滚动锁定
• Form — 泛型类型推导、声明式校验、受控/非受控双模式

扩展组件

• DatePicker — 日历面板、键盘导航、禁用日期、Portal 弹出

架构亮点

1. Design Tokens 三层架构

原始令牌 (primitives)  →  语义令牌 (semantic)  →  CSS Variables  →  组件消费
     具体色值             设计含义赋值           主题差异化       var(--zen-colors-primary)

2. 五大架构暗坑规避

| 暗坑 | 解决方案 | | --- | --- | | 样式隔离 | CSS Modules + 哈希类名 | | 循环依赖 | 严格的分层依赖：Icon → Button → Input → 复合组件 | | A11y 无障碍 | 每个组件内置 ARIA 属性、键盘导航、焦点管理 | | 类型安全 | 泛型推导、Omit 排除冲突属性、strict 模式禁止 any | | 测试策略 | 纯函数单元测试 + 组件交互测试 + jest-axe 无障碍检查 |

3. 主题系统

基于 CSS Variables 的零重渲染主题切换，data-theme 属性控制，支持亮色/暗色一键切换，Storybook 工具栏直接演示。

工程化体系

脚本一览

| 命令 | 用途 | | --- | --- | | pnpm dev | 启动开发服务器 | | pnpm build | 构建 ESM + CJS + 类型声明 | | pnpm test | 运行测试 | | pnpm test:coverage | 生成覆盖率报告 | | pnpm lint | ESLint 检查并自动修复 | | pnpm format | Prettier 格式化代码 | | pnpm typecheck | TypeScript 类型检查 | | pnpm check:all | 一键运行所有检查 | | pnpm storybook | 启动 Storybook 文档站 | | pnpm build-storybook | 构建静态文档站 |

CI/CD

每次 push 自动运行：类型检查 → 代码规范检查 → 单元测试 → 构建验证。

Git 提交规范

基于 约定式提交，Husky + Commitlint 强制检查。

本地开发

# 克隆项目
git clone https://github.com/your-username/zenui.git
cd zenui

# 安装依赖
pnpm install

# 启动开发服务器（实时预览组件）
pnpm dev

# 启动 Storybook（组件文档）
pnpm storybook

# 运行所有检查
pnpm check:all

项目统计

| 指标 | 数值 | | --- | --- | | 组件数量 | 7 个（基础 ×3 + 复合 ×2 + 扩展 ×1） | | 自定义 Hooks | 4 个（useForm、useFocusTrap、useLockScroll、useDatePicker） | | TypeScript 严格模式 | ✅ 零 any | | 测试用例 | 核心逻辑全覆盖 | | 无障碍 | WAI-ARIA 合规 | | 构建产物 | ESM + CJS + 类型声明 |

许可证

MIT © lzldemo