@pipi-kit/ui

> 基于 React、shadcn、@radix-ui、lucide-react、Tailwind v4 开发的主题化 UI 组件库

💡 特别说明

适配 nextify-coo 项目:
- 统一从主入口导入: import { Button, Input } from '@pipi-kit/ui'
- 使用主项目的 CSS 变量和样式定义(globals.css)
- 零配置迁移,只需替换导入路径

🎯 核心理念

组件库不"定义美",只"定义能力"

@pipi-kit/ui 是一个基于 Tailwind CSS v4 和 CSS 变量的组件库,它提供:
- ✅ 组件结构
- ✅ 交互行为
- ✅ 可访问性 (A11y)
- ✅ 通过 globals.css 中的 CSS 变量实现主题化

所有的样式、主题、设计 Token 都通过 globals.css 中的 CSS 变量 和 Tailwind 工具类 定义。

📦 安装

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





🎯 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` 支持
3. 添加完整的 TypeScript 类型
4. 保持可访问性 (A11y) 标准
5. 不要包含任何硬编码样式

---

记住: 组件库不"定义美",只"定义能力";美,永远交给项目。