shadcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Install, customize, and compose shadcn/ui components with design-system awareness. shadcn is a code distribution system — components are source files you own, not packages.

在具备设计系统认知的前提下，安装、自定义并组合shadcn/ui组件。 shadcn是一个代码分发系统——组件是你拥有的源文件，而非依赖包。

Workflow

工作流程

Every shadcn interaction follows four steps: Orient, Install, Refine, Verify.

所有shadcn操作都遵循四个步骤：状态确认、安装、优化、验证。

1. Orient

1. 状态确认

Read project state before any CLI operation. Run

npx shadcn@latest info

to get framework, installed components, aliases, icon library, and base library. Read

components.json

directly for theme config. Never guess configuration.

在执行任何CLI操作前先查看项目状态。运行

npx shadcn@latest info

获取框架、已安装组件、别名、图标库和基础库信息。直接查看

components.json

获取主题配置。切勿猜测配置。

2. Install

2. 安装

Add components via CLI, never by copying from docs manually.

bash

npx shadcn@latest add button card dialog    # Multiple at once
npx shadcn@latest add @namespace/component  # From custom registry
npx shadcn@latest add --dry-run button      # Preview before writing

Before re-adding an existing component, run

npx shadcn@latest diff <name>

to see upstream changes. Commit local customizations first —

add

overwrites files.

通过CLI添加组件，切勿手动从文档复制代码。

bash

npx shadcn@latest add button card dialog    # 批量添加多个组件
npx shadcn@latest add @namespace/component  # 从自定义注册表添加
npx shadcn@latest add --dry-run button      # 预览操作效果再执行

重新添加现有组件前，运行

npx shadcn@latest diff <name>

查看上游变更。先提交本地自定义修改——

add

命令会覆盖文件。

3. Refine

3. 优化

This is where craft lives. After every

add

, audit the component against the project's design system:

Typography: Does it use the project's font variables and scale? Replace any hardcoded font sizes.
Color tokens: Does it reference the project's CSS custom properties? Convert any raw color values to semantic tokens.
Spacing rhythm: Does it follow the project's spacing scale? Harmonize padding and margins.
Border radius: Does it use
```
--radius
```
from the theme? Shadcn sets this globally.
Animation: Does it use
```
tw-animate-css
```
classes, not
```
tailwindcss-animate
```
?
Composition: Create wrapper components that compose shadcn primitives. Edit base components only for structural changes.

When

minoan-frontend-design

is active, translate its creative direction into shadcn theme variables and component customizations.

这是定制化的核心环节。每次执行

add

后，对照项目的设计系统检查组件：

排版：是否使用了项目的字体变量和字号体系？替换所有硬编码的字号。
颜色令牌：是否引用了项目的CSS自定义属性？将所有原始颜色值转换为语义化令牌。
间距规范：是否遵循项目的间距比例？统一内边距和外边距。
圆角设置：是否使用了主题中的
```
--radius
```
变量？Shadcn会全局设置该变量。
动画效果：是否使用
```
tw-animate-css
```
类，而非
```
tailwindcss-animate
```
？
组件组合：创建封装shadcn基础组件的包装器组件。仅在需要结构变更时编辑基础组件。

当

minoan-frontend-design

生效时，将其创意指导转化为shadcn主题变量和组件自定义设置。

4. Verify

4. 验证

Build the project to catch type errors. Visually inspect the component in context. Check dark mode. Check mobile.

构建项目以捕获类型错误。在实际场景中直观检查组件。检查暗黑模式适配。检查移动端显示效果。

Tailwind v4 Contract

Tailwind v4 约定

shadcn v4 uses OKLCH color space with

@theme inline

— not HSL, not

tailwind.config.ts

css

:root {
  --primary: oklch(0.205 0.03 264.05);
  --primary-foreground: oklch(0.985 0 0);
}
@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

Leave

tailwind.config

blank in

components.json

for v4 projects. Use

data-slot

attributes for targeted styling. Use

React.ComponentProps<>

—

forwardRef

is removed.

shadcn v4使用OKLCH颜色空间和

@theme inline

——而非HSL或

tailwind.config.ts

。

css

:root {
  --primary: oklch(0.205 0.03 264.05);
  --primary-foreground: oklch(0.985 0 0);
}
@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

v4项目中请将

components.json

里的

tailwind.config

留空。使用

data-slot

属性进行目标样式设置。使用

React.ComponentProps<>

——已移除

forwardRef

。

Theming

主题设置

Colors follow

background

foreground

pairs. The background suffix is omitted for the primary role:

--primary

(background),

--primary-foreground

(text on that background).

Extend with custom semantic tokens by adding both the CSS variable and the

@theme inline

mapping:

css

:root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.14 0.04 84); }
@theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }

Use

cn()

(clsx + tailwind-merge) for all class name composition.

颜色遵循「背景色 + 前景色」的配对原则。主色（primary）省略背景色后缀：

--primary

（背景色）、

--primary-foreground

（该背景上的文本色）。

通过添加CSS变量和

@theme inline

映射来扩展自定义语义化令牌：

css

:root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.14 0.04 84); }
@theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }

所有类名组合请使用

cn()

（clsx + tailwind-merge）。

References

参考文档

Consult

references/

on demand:

```
cli-v4-reference.md
```
— Full command reference, flags, monorepo patterns. Read for any CLI operation.
```
components-json-schema.md
```
— Configuration schema with all fields. Read when initializing or reconfiguring.
```
theming-oklch.md
```
— OKLCH color system, CSS variable conventions, dark mode, custom colors. Read when theming.
```
registry-authoring.md
```
— Custom registry creation, namespacing, auth, item types. Read when building registries.
```
tailwind-v4-migration.md
```
— Breaking changes, upgrade path, tw-animate-css, data-slot. Read when migrating or troubleshooting.
```
component-inventory.md
```
— 59 components by category. Read when choosing what to install.
```
customization-patterns.md
```
— Wrapper composition, data-slot styling, diff tracking. Read when customizing components.

按需查阅

references/

目录下的文件：

```
cli-v4-reference.md
```
— 完整的命令参考、参数说明、monorepo模式指南。执行任何CLI操作前请阅读。
```
components-json-schema.md
```
— 包含所有字段的配置Schema。初始化或重新配置项目时请阅读。
```
theming-oklch.md
```
— OKLCH颜色系统、CSS变量规范、暗黑模式、自定义颜色设置。进行主题设置时请阅读。
```
registry-authoring.md
```
— 自定义注册表创建、命名空间、权限验证、项目类型说明。构建注册表时请阅读。
```
tailwind-v4-migration.md
```
— 破坏性变更、升级路径、tw-animate-css、data-slot用法。迁移或排查问题时请阅读。
```
component-inventory.md
```
— 按分类划分的59个组件列表。选择要安装的组件时请阅读。
```
customization-patterns.md
```
— 包装器组合、data-slot样式、差异跟踪方法。自定义组件时请阅读。