21st-design-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

21st Design Sync — publish your project's design as a theme

21st Design Sync — 将你的项目设计发布为主题

Take the design a project already ships (its light + dark CSS variables) and publish it to the public 21st.dev theme library so anyone can preview, bookmark, and apply it. Under the hood this is one CLI call:

21st publish-theme <file.css> --name "…"

提取项目已有的设计（其亮色+暗色CSS变量），并将其发布到公共21st.dev主题库，以便任何人都可以预览、收藏和应用。底层实现仅需一条CLI命令：

21st publish-theme <file.css> --name "…"

。

Pre-flight (always)

前置检查（必做）

Auth needs a real API key.
```
publish-theme
```
is a management endpoint: it accepts a
```
21st_sk_…
```
key only, not a
```
21st login
```
session token. Get one at https://21st.dev/mcp (or https://21st.dev/settings/api-keys) and pass it via
```
--api-key 21st_sk_…
```
or the
```
TWENTYFIRST_TOKEN
```
/
```
API_KEY_21ST
```
env var. If the user has no key, point them there — don't try to mint one.
The CLI is the unified
```
@21st-dev/cli
```
(bin
```
21st
```
). Use
```
npx @21st-dev/cli
```
if it isn't installed.
Publishing is public and outward-facing. A published theme is immediately
```
is_public
```
in the community library (there is no unlisted/private option for themes). Confirm with the user before publishing.

认证需要有效的API密钥。
```
publish-theme
```
是管理端点：它仅接受
```
21st_sk_…
```
格式的密钥，不支持
```
21st login
```
会话令牌。可前往**https://21st.dev/mcp**（或**https://21st.dev/settings/api-keys**）获取密钥，并通过`--api-key 21st_sk_…
```
参数或
```
TWENTYFIRST_TOKEN
```
/
```
API_KEY_21ST`环境变量传入。如果用户没有密钥，引导他们前往上述地址获取，不要尝试生成密钥。
CLI工具是统一的
```
@21st-dev/cli
```
（二进制命令为
```
21st
```
）。如果未安装，可使用
```
npx @21st-dev/cli
```
。
发布操作是公开对外的。已发布的主题会立即在社区库中设为
```
is_public
```
状态（主题没有未列出/私有选项）。发布前请与用户确认。

Step 1 — Find the project's design tokens

步骤1 — 找到项目的设计标记

Locate the file that defines the shadcn/Tailwind theme variables. Check, in order:

```
app/globals.css
```
,
```
src/app/globals.css
```

src/index.css

styles/globals.css

app/styles/globals.css

You're looking for a

:root { … }

block of CSS custom properties (

--background

--foreground

--card

--primary

--secondary

--muted

--accent

--destructive

--border

--input

--ring

, the

--chart-*

--sidebar-*

tokens,

--radius

) and a matching

.dark { … }

block. Values may be

hsl(...)

oklch(...)

, hex, or raw channels — keep them exactly as the project wrote them.

Tailwind v4 projects usually keep the same

:root

.dark

blocks plus an

@theme inline

mapping; you only need the

:root

and

.dark

token values, not the

@theme

mapping.

定位定义shadcn/Tailwind主题变量的文件，按以下顺序查找：

```
app/globals.css
```
、
```
src/app/globals.css
```

src/index.css

、

styles/globals.css

、

app/styles/globals.css

你需要找的是包含CSS自定义属性（

--background

、

--foreground

、

--card

、

--primary

、

--secondary

、

--muted

、

--accent

、

--destructive

、

--border

、

--input

、

--ring

、

--chart-*

--sidebar-*

标记、

--radius

）的

:root { … }

代码块，以及对应的

.dark { … }

代码块。值可以是

hsl(...)

、

oklch(...)

、十六进制或原始通道值——完全保留项目中的原始写法即可。

Tailwind v4项目通常保留相同的

:root

.dark

代码块，外加

@theme inline

映射；你只需要

:root

和

.dark

中的标记值，不需要

@theme

映射。

Step 2 — Assemble a valid theme CSS file

步骤2 — 生成有效的主题CSS文件

The publish endpoint parses

--name: value;

pairs out of a

:root { … }

block and a

.dark { … }

block, and requires both to be non-empty. So the file you publish must contain both.

Copy the project's
```
:root
```
and
```
.dark
```
blocks into a standalone file (e.g.
```
project-theme.css
```
). Nothing else is required.
If the project has only a light
:root
and no
.dark
(or an empty one), generate a dark variant before publishing — don't ship a theme with an empty dark mode. Reuse the
```
add-dark-mode
```
/
```
oklch-skill
```
approach: invert lightness while preserving hue/chroma so the dark set stays on-brand. Keep the same token names.
Keep the token names shadcn-standard so the theme previews correctly on the card and applies cleanly for others.

Minimal shape:

css

:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 4%;
  --primary: 240 6% 10%;
  /* …the rest of the project's light tokens… */
  --radius: 0.5rem;
}
.dark {
  --background: 240 10% 4%;
  --foreground: 0 0% 98%;
  --primary: 0 0% 98%;
  /* …the rest of the project's dark tokens… */
}

发布端点会从

:root { … }

和

.dark { … }

代码块中解析

--name: value;

对，并且要求两个代码块都非空。因此，你要发布的文件必须同时包含这两个代码块。

将项目的
```
:root
```
和
```
.dark
```
代码块复制到一个独立文件中（例如
```
project-theme.css
```
）。不需要其他内容。
如果项目只有亮色
:root
代码块，没有
.dark
代码块（或为空），请在发布前生成暗色变体——不要发布暗色模式为空的主题。使用
```
add-dark-mode
```
/
```
oklch-skill
```
方法：反转亮度同时保留色调/色度，使暗色集保持品牌风格。保留相同的标记名称。
保持标记名称符合shadcn标准，以便主题在卡片上正确预览，并能被其他人顺利应用。

最小结构示例：

css

:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 4%;
  --primary: 240 6% 10%;
  /* …项目其余的亮色标记… */
  --radius: 0.5rem;
}
.dark {
  --background: 240 10% 4%;
  --foreground: 0 0% 98%;
  --primary: 0 0% 98%;
  /* …项目其余的暗色标记… */
}

Step 3 — Name & tag it

步骤3 — 命名与添加标签

Name (required, ≤ 50 chars): infer from the project — the product/brand name from
```
package.json
```
, the repo, or the site title. Ask the user if it's ambiguous.
Tags (optional): a few descriptors that match how people browse themes, e.g.
```
dark
```
,
```
minimal
```
,
```
neutral
```
,
```
vibrant
```
,
```
saas
```
. Pass comma-separated.

名称（必填，≤50字符）：从项目中推断——可以是
```
package.json
```
中的产品/品牌名称、仓库名称或网站标题。如果不确定，请询问用户。
标签（可选）：几个符合主题浏览习惯的描述符，例如
```
dark
```
、
```
minimal
```
、
```
neutral
```
、
```
vibrant
```
、
```
saas
```
。使用逗号分隔。

Step 4 — Publish

步骤4 — 发布

bash

21st publish-theme ./project-theme.css \
  --name "Acme" \
  --tags dark,minimal \
  --api-key 21st_sk_…            # or set TWENTYFIRST_TOKEN

The command prints the live theme URL (

https://21st.dev/community/themes/<slug>

). Share it with the user.

bash

21st publish-theme ./project-theme.css \
  --name "Acme" \
  --tags dark,minimal \
  --api-key 21st_sk_…            # 或设置TWENTYFIRST_TOKEN环境变量

命令会输出主题的在线URL（

https://21st.dev/community/themes/<slug>

）。将该URL分享给用户。

Updating vs re-publishing

更新与重新发布的区别

Each
publish-theme
creates a NEW theme (there's no upsert-by-slug like components have). Running it twice = two themes in the library.
To change name/tags/visibility on an existing theme, edit it in place:
```
21st edit <theme-id> --type theme [--name "…"] [--tags a,b]
```
.
To change the colors, publish a fresh file and remove the old one:
```
21st delete <theme-id> --type theme --yes
```
(soft-unpublish, reversible).

每次执行
publish-theme
都会创建一个新主题（不像组件那样支持按slug更新）。执行两次会在库中生成两个主题。
要修改现有主题的名称/标签/可见性，直接在线编辑：
```
21st edit <theme-id> --type theme [--name "…"] [--tags a,b]
```
。
要修改颜色，请发布新文件并删除旧主题：
```
21st delete <theme-id> --type theme --yes
```
（软删除，可恢复）。

When NOT to use this

不适用场景

Syncing a component library to a Claude Design project → that's the built-in
```
/design-sync
```
skill, a different destination.
Publishing a component (not a color theme) → use
```
21st-registry
```
.

将组件库同步到Claude Design项目→使用内置的
```
/design-sync
```
功能，这是不同的目标场景。
发布组件（而非颜色主题）→使用
```
21st-registry
```
。