# @codapet/design-system 中文文档

规范地址：https://npmcn.com/package/%40codapet/design-system/

版本：0\.9\.2
npm 元数据更新时间：2026-11-03T14:10:15.293Z
中文译文更新时间：2026-11-10T06:13:24.631Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40codapet/design-system
原文对照：https://npmcn.com/package/%40codapet/design-system/?lang=original
项目主页：https://github.com/codapet/codapet-design-system#readme
源码仓库：https://github.com/codapet/codapet-design-system

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：941 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：44 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2025-08-26T17:49:21.681Z
- 最新版本发布：2026-11-03T14:10:14.862Z
- 近 30 天下载量：4399（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：75（近 12 个月 54 个）

## 中文简介

由Shadcn UI,Radix UI,Tailwind CSS和TypeScript所建的综合性React组件库.

## 安装

```sh
npm install @codapet/design-system
```

也可以使用：`pnpm add @codapet/design-system`、`yarn add @codapet/design-system`、`bun add @codapet/design-system`

## README

# CodaPet 设计系统

由Shadcn UI,Radix UI,Tailwind CSS和TypeScript所建的综合性React组件库.

## 特征

-   ++ 50+ 可访问的UI 组件
-   由 Radix UI 原始人创建
-   尾风 CSS 样式
-   机动第一反应设计
-   QQ 类型脚本支持
-   最佳业绩
-   QQ 暗模式支持
-   \* 遵守《世界妇女宪章》

## 安装

### 国家防范机制一揽子计划

```bash
npm install @codapet/design-system
```

### 同伴依赖关系

库需要React和React DOM作为对等依赖. 确保安装它们 :

```bash
npm install react react-dom
```

CI/建构器的说明( 如 Vercel, GitHub Actions ) : 由于此软件包在 npm 上是公开的, 因此没有额外的认证或 `.npmrc` 需要时间。 只要运行正常的安装命令.

**说明**:库支持回放18.0.0及以上. 对于最佳相容性,请使用回放18.2.0或更后.

* * *

## 快速启动: Next.js 15 + Tailwind v4

遵循这些步骤,将设计系统整合到全新的Next.jsapp中.

1.  创建 Next.js app( 建议的 TypeScript) :

```bash
npx create-next-app@latest my-app
cd my-app
```

2.  添加 Tailwind v4 PostCSS 插件( Tailwind v4 需要) :

```bash
npm install -D @tailwindcss/postcss
```

创建 `postcss.config.mjs` (如果你没有的话):

```js
/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
export default config
```

3.  安装设计系统 :

```bash
npm install @codapet/design-system
```

4.  为 Tailwind v4 扫描配置全局CSS并导入设计系统样式.

编辑 `app/globals.css`数字 :

```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";
```

5.  确保您的 Next.js 根布局包含全局 :

```tsx
// 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>
  )
}
```

6.  使用组件 :

```tsx
// 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>
  )
}
```

7.  运行应用程序 :

```bash
npm run dev
```

### 尾风 v3( 遗留)

如果您在 Tailwind v3 上, 请使用基于配置的内容扫描 `@source` (见下文Styling).

* * *

## 使用量

### 基本设置

```tsx
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` 目录 :

```tsx
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'
```

### 公用事业

```tsx
import { cn } from '@codapet/design-system'

// Utility function for merging class names
const className = cn('base-class', 'conditional-class')
```

### 钩子

```tsx
import { useIsMobile } from '@codapet/design-system'

function MyComponent() {
  const isMobile = useIsMobile()
  // ...
}
```

## 发展

### 先决条件

-   节点.js 18+
-   npm 或纱线

### 设置

1.  清除仓库
2.  安装依赖性 :
    
    ```bash
    npm install
    ```
    

### 发展指挥部

-   `npm run dev` - 启动开发服务器
-   `npm run build:lib` - 建造图书馆以供分发
-   `npm run build:all` - 建立库和演示应用程序
-   `npm run lint` - 运行ESLint
-   `npm run test:lib` - 测试图书馆的建筑
-   `npm run check:deps` - 检查依赖树
-   `npm run clean:deps` - 清洁和重新安装依赖性

### 分发大楼

要将库构建为 npm 软件包 :

```bash
npm run build:lib
```

这将生成:

-   `dist/index.mjs` - ES模块捆绑
-   `dist/index.d.mts` - 类型脚本声明

### 出版

发布器在semver标签上通过GitHub Actions实现自动化.

设置一次( npm 信任的出版) :

-   打开 [npmjs.com (英语)](https://www.npmjs.com/package/@codapet/design-system) → **设置** → **受托出版** → **GitHub 动作**
-   仓库 : `codapet/codapet-design-system`
-   工作流程文件名 : `release.yml` (必须准确匹配,包括扩展)
-   允许的行动 : **npm 发布**
-   可选限制以符号为基础的出版 **设置 – 出版访问** 在验证 OIDC 工程后

释放步骤 :

```bash
# 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( 建议)

1.  在您的全球CSS( 例如 ) 中. `app/globals.css`,添加 `@source` 包含设计系统,并在 Tailwind 后导入样式表:

```css
@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";
```

2.  确保您的布局导入您的全局( 下一步 ) :

```tsx
// app/layout.tsx
import "./globals.css";
```

### 尾风 v3

如果您还在 Tailwind v3 上, 请使用内容 globs 代替 `@source`数字 :

```js
// 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`。 。 。 .

## 扶养管理

关于如何组织和管理依附关系的详细资料,参见: [汇款](https://npmcn.com/package/%40codapet/design-system/DEPENDENCIES.md)。 。 。 .

### 关键点 :

-   **同伴依赖关系**: react and react DOM (由消费应用程序提供)
-   **依赖关系**:UI图书馆和公用事业(与图书馆捆绑在一起)
-   **差异依赖**: 建设工具和发展公用事业(不包括在一揽子中)

## 使用 AI 编码代理

这个包裹载着一个 [`AGENTS.md`](https://npmcn.com/package/%40codapet/design-system/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,用于如何在额外的上下文文件中指向它.

## 捐款

1.  叉子存储器
2.  创建特性分支
3.  做你的改变
4.  在适用的情况下添加测试
5.  提交拉动请求

## 许可证

麻省理工学院许可证 - 详情见LICENSE文件.

## 常见问题

### @codapet/design-system 是什么？

由Shadcn UI,Radix UI,Tailwind CSS和TypeScript所建的综合性React组件库\.

### 如何安装 @codapet/design-system？

在项目目录运行 npm install @codapet/design-system，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @codapet/design-system 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @codapet/design-system 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @codapet/design-system 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @codapet/design-system 可以商用吗？

@codapet/design-system 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @codapet/design-system 的下载量有多少？

根据 npm 官方下载统计，@codapet/design-system 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,399 次，日均约 147 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @codapet/design-system 还在维护吗？

最新版本 0\.9\.2 发布于 2026/11/03（6 天前）；至今共发布 75 个版本，其中过去 12 个月发布了 54 个；首次发布于 2025/08/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。