基于 React、shadcn、@radix-ui、lucide-react、Tailwind v4 开发的 UI 组件库
npm install @pipi-kit/uiimport { Button, Input } from '@pipi-kit/ui'
bash
npm install @pipi-kit/ui
或
pnpm add @pipi-kit/ui
或
yarn add @pipi-kit/ui
`
$3
确保你的项目已安装以下依赖:
`bash
npm install react react-dom tailwindcss @radix-ui/react-slot
`
🚀 快速开始
$3
在你的 tailwind.config.ts 中添加组件库路径:
`typescript
import type { Config } from 'tailwindcss'
export default {
content: [
'./src/*/.{ts,tsx}',
// 重要: 必须扫描组件库的文件
'./node_modules/@pipi-kit/ui/*/.{js,mjs}',
],
// ... 其他配置
} satisfies Config
`
$3
在你的主 CSS 文件 (如 app.css 或 globals.css) 中定义 CSS 变量:
`css
@import "tailwindcss";
@layer base {
:root {
/ 主题色 /
--primary: #095EDC;
--shade-1: #FFFFFF;
--shade-5: #E2E2E2;
--shade-10: #121212;
/ 更多 CSS 变量... /
}
}
@theme {
/ Tailwind 颜色映射 /
--color-primary: var(--primary);
--color-shade-1: var(--shade-1);
--color-shade-5: var(--shade-5);
--color-shade-10: var(--shade-10);
}
`
完整的样式示例请参考 demo/globals.css
$3
`tsx
import { Button } from '@pipi-kit/ui'
function App() {
return (
)
}
`
📚 组件列表 (共 47 个)
$3
- Button - 按钮
- Input - 输入框
- Label - 标签
- Badge - 徽章
- Checkbox - 复选框
- Switch - 开关
- Slider - 滑块
- Progress - 进度条
- Textarea - 文本域
- RadioGroup - 单选按钮组
- Separator - 分隔线
- Skeleton - 骨架屏
- Avatar - 头像
- AspectRatio - 宽高比容器
- ScrollArea - 滚动区域
- VisuallyHidden - 视觉隐藏
$3
- Dialog - 对话框
- Select - 下拉选择器
- Popover - 气泡弹出框
- Tooltip - 工具提示
- HoverCard - 悬停卡片
- Sheet - 侧边抽屉
- Drawer - 底部抽屉
- AlertDialog - 警告对话框
- Toggle - 切换按钮
- ToggleGroup - 切换按钮组
- Collapsible - 折叠面板
- ContextMenu - 右键菜单
- DropdownMenu - 下拉菜单
$3
- Alert - 警告提示
- Toast - Toast 通知
- Toaster - Toast 容器
- Sonner - Sonner Toast
$3
- Card - 卡片
- Table - 表格
- Tabs - 标签页
- Accordion - 手风琴
$3
- Breadcrumb - 面包屑
- NavigationMenu - 导航菜单
- Menubar - 菜单栏
- Sidebar - 侧边栏
- Pagination - 分页
$3
- Command - 命令面板
- Calendar - 日历
- Carousel - 轮播图
- Form - 表单
- Resizable - 可调整大小的面板
🎨 设计原则
$3
组件库基于 globals.css 中的 CSS 变量实现主题化:
- ✅ 使用 CSS 变量定义颜色、间距、圆角等
- ✅ 使用 Tailwind 工具类组合样式
- ✅ 使用 CVA (Class Variance Authority) 管理样式变体
- ✅ 支持亮色/暗色主题切换
组件库不包含:
- ❌ 硬编码的颜色值如 bg-[#xxxxxx]
- ❌ BEM 类名如 ui-button__element
$3
- 单组件 = 单文件夹
- API 简洁、语义稳定
- 可复制、可发布
$3
- 复杂交互基于 Radix UI
- 无障碍访问 (A11y) 内置
- 保持原生 HTML 语义
🔧 组件 API
$3
`tsx
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'
size?: 'sm' | 'md' | 'lg' | 'icon'
asChild?: boolean
loading?: boolean
}
`
示例:
`tsx
// 基本用法
// 加载状态
// asChild 模式 (渲染为 Link)
`
$3
`tsx
interface InputProps {
prependIcon?: React.ReactNode
suffixIcon?: React.ReactNode
}
`
示例:
`tsx
import { Input } from '@pipi-kit/ui'
import { Search } from 'lucide-react'
// 带图标
prependIcon={ }
placeholder="搜索..."
/>
// 密码输入框 (自动显示/隐藏切换)
`
$3
`tsx
`
🎯 Variant 设计规范
$3
- 语义化变体: primary / secondary / destructive
- 通用尺寸: sm / md / lg / icon
- 通用样式: outline / ghost / link
$3
- 业务语义: submit / price / chrome
- 页面专属: header / sidebar
- 产品线: enterprise / pro
- 颜色名: blue / red / green
📖 完整示例
查看 demo 目录获取:
- globals.css - 完整的 CSS 变量定义和主题配置示例
🚀 发布到 npm
`bash
构建
npm run build
发布
npm publish --access public
`
📄 许可证
MIT
🤝 贡献
欢迎提交 Issue 和 Pull Request!
$3
1. 确保所有组件遵循"样式外置"原则
2. 使用 forwardRef 和 asChild` 支持