CodaPet 设计系统
由Shadcn UI,Radix UI,Tailwind CSS和TypeScript所建的综合性React组件库.
特征
- ++ 50+ 可访问的UI 组件
- 由 Radix UI 原始人创建
- 尾风 CSS 样式
- 机动第一反应设计
- QQ 类型脚本支持
- 最佳业绩
- QQ 暗模式支持
- * 遵守《世界妇女宪章》
安装
国家防范机制一揽子计划
npm install @codapet/design-system
同伴依赖关系
库需要React和React DOM作为对等依赖. 确保安装它们 :
npm install react react-dom
CI/建构器的说明( 如 Vercel, GitHub Actions ) : 由于此软件包在 npm 上是公开的, 因此没有额外的认证或 .npmrc 需要时间。 只要运行正常的安装命令.
说明:库支持回放18.0.0及以上. 对于最佳相容性,请使用回放18.2.0或更后.
快速启动: Next.js 15 + Tailwind v4
遵循这些步骤,将设计系统整合到全新的Next.jsapp中.
- 创建 Next.js app( 建议的 TypeScript) :
npx create-next-app@latest my-app
cd my-app
- 添加 Tailwind v4 PostCSS 插件( Tailwind v4 需要) :
npm install -D @tailwindcss/postcss
创建 postcss.config.mjs (如果你没有的话):
/** @type {import('postcss-load-config').Config} */
const config = {
plugins: {
'@tailwindcss/postcss': {},
},
}
export default config
- 安装设计系统 :
npm install @codapet/design-system
- 为 Tailwind v4 扫描配置全局CSS并导入设计系统样式.
编辑 app/globals.css数字 :
@import "tailwindcss";
/* Tell Tailwind where to scan for class usage */
@source "../**/*.{js,ts,jsx,tsx,mdx}";
@source "../../node_modules/@codapet/design-system/dist/**/*.{js,mjs,ts,tsx}";
/* Import the design system tokens and base styles (after Tailwind) */
@import "@codapet/design-system/styles";
- 确保您的 Next.js 根布局包含全局 :
// app/layout.tsx
import type { Metadata } from 'next'
import './globals.css'
export const metadata: Metadata = { title: 'My App' }
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
- 使用组件 :
// app/page.tsx
import { Button, Card, CardContent, CardHeader, CardTitle } from '@codapet/design-system'
export default function Page() {
return (
<main className="p-8">
<Card>
<CardHeader>
<CardTitle>Hello</CardTitle>
</CardHeader>
<CardContent>
<Button>Works!</Button>
</CardContent>
</Card>
</main>
)
}
- 运行应用程序 :
npm run dev
尾风 v3( 遗留)
如果您在 Tailwind v3 上, 请使用基于配置的内容扫描 @source (见下文Styling).
使用量
基本设置
import { Button, Card, Input } from '@codapet/design-system'
function App() {
return (
<div>
<Card>
<Input placeholder="Enter your name" />
<Button>Click me</Button>
</Card>
</div>
)
}
可用组件
库中输出所有 UI 组件 components/ui 目录 :
import {
Accordion,
Alert,
AlertDialog,
AspectRatio,
Avatar,
Badge,
Breadcrumb,
Button,
Calendar,
Card,
Carousel,
Chart,
Checkbox,
Collapsible,
Command,
ContextMenu,
Dialog,
Drawer,
DropdownMenu,
Form,
HoverCard,
Input,
InputOTP,
Label,
Menubar,
NavigationMenu,
Pagination,
Popover,
Progress,
RadioGroup,
Resizable,
ScrollArea,
Select,
Separator,
Sheet,
Sidebar,
Skeleton,
Slider,
Sonner,
Switch,
Table,
Tabs,
Textarea,
Toggle,
ToggleGroup,
Tooltip,
} from '@codapet/design-system'
公用事业
import { cn } from '@codapet/design-system'
// Utility function for merging class names
const className = cn('base-class', 'conditional-class')
钩子
import { useIsMobile } from '@codapet/design-system'
function MyComponent() {
const isMobile = useIsMobile()
// ...
}
发展
先决条件
- 节点.js 18+
- npm 或纱线
设置
- 清除仓库
- 安装依赖性 :
npm install
发展指挥部
npm run dev- 启动开发服务器npm run build:lib- 建造图书馆以供分发npm run build:all- 建立库和演示应用程序npm run lint- 运行ESLintnpm run test:lib- 测试图书馆的建筑npm run check:deps- 检查依赖树npm run clean:deps- 清洁和重新安装依赖性
分发大楼
要将库构建为 npm 软件包 :
npm run build:lib
这将生成:
dist/index.mjs- ES模块捆绑dist/index.d.mts- 类型脚本声明
出版
发布器在semver标签上通过GitHub Actions实现自动化.
设置一次( npm 信任的出版) :
- 打开 npmjs.com (英语) → 设置 → 受托出版 → GitHub 动作
- 仓库 :
codapet/codapet-design-system - 工作流程文件名 :
release.yml(必须准确匹配,包括扩展) - 允许的行动 : npm 发布
- 可选限制以符号为基础的出版 设置 – 出版访问 在验证 OIDC 工程后
释放步骤 :
# update version in package.json
git commit -am "chore(release): v1.2.3"
git tag v1.2.3
git push --follow-tags
工作流程构建、测试和运行 npm publish --access public。 。 。 .
样式
设计系统使用Tailwind CSS来进行造型. 请将 Tailwind CSS 包含在您的项目中, 并配置 Tailwind 扫描此软件包, 从而生成其内部使用的公用设备 .
尾风 v4( 建议)
- 在您的全球CSS( 例如 ) 中.
app/globals.css,添加@source包含设计系统,并在 Tailwind 后导入样式表:
@import "tailwindcss";
/* Tell Tailwind to scan the design system in node_modules */
@source "../**/*.{js,ts,jsx,tsx,mdx}";
@source "../../node_modules/@codapet/design-system/dist/**/*.{js,mjs,ts,tsx}";
/* Import the design system CSS tokens and base layers */
@import "@codapet/design-system/styles";
- 确保您的布局导入您的全局( 下一步 ) :
// app/layout.tsx
import "./globals.css";
尾风 v3
如果您还在 Tailwind v3 上, 请使用内容 globs 代替 @source数字 :
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
'./app/**/*.{js,ts,jsx,tsx}',
'./components/**/*.{js,ts,jsx,tsx}',
'./node_modules/@codapet/design-system/dist/**/*.{js,mjs,ts,tsx}',
],
theme: { extend: {} },
plugins: [],
}
解决问题
- 部件未样式:
- 保证您
globals.css包含@source说明设计系统在node_modules(Tailwind必须看到班级使用才能输出公用事业). - 更改后重新启动 dev 服务器
@source或有尾风相接. - 校验
@import "@codapet/design-system/styles";接下来@import "tailwindcss";。 。 。 . - 如果您使用 Tailwind v3 , 请配置
content如上所显示.
- 保证您
- PostCSS 无法解析导入 :
- 保证
@tailwindcss/postcss安装并显示于postcss.config.*。 。 。 . - 如果您看到错误解决
tw-animate-css在应用程序中安装:npm i -D tw-animate-css。 。 。 .
- 保证
- 还卡住? 清除缓存并重建 :
rm -rf .next接下来npm run dev。 。 。 .
扶养管理
关于如何组织和管理依附关系的详细资料,参见: 汇款。 。 。 .
关键点 :
- 同伴依赖关系: react and react DOM (由消费应用程序提供)
- 依赖关系:UI图书馆和公用事业(与图书馆捆绑在一起)
- 差异依赖: 建设工具和发展公用事业(不包括在一揽子中)
使用 AI 编码代理
这个包裹载着一个 AGENTS.md ——AI代理的指南(Claude Code, Cursor, Codex等),解释库与sock shadcn/ui的区别(按钮默认,自定义组件,品牌标志,常见的快取). 它与 npm tarball 一起发布, 所以一旦你安装了包, 文件在 node_modules/@codapet/design-system/AGENTS.md。 。 。 .
为了让克洛德代码自动拉入 消费者回购的每个会话, 在你的回购中加一行 CLAUDE.md (或 AGENTS.md:
@./node_modules/@codapet/design-system/AGENTS.md
这个 @path 语法将文件的内容融入代理商的上下文. 因为它在会话开始时就解决了,所以指南总是匹配版本的 @codapet/design-system 您已经安装了 —— 调试解析器, 获取更新的向导, 没有复制- 粘贴 .
对于其他代理工具(Cursor, Codex等),文件仍然可以在同一个路径上被读取;参考您工具的docs,用于如何在额外的上下文文件中指向它.
捐款
- 叉子存储器
- 创建特性分支
- 做你的改变
- 在适用的情况下添加测试
- 提交拉动请求
许可证
麻省理工学院许可证 - 详情见LICENSE文件.