21st-design-sync

用途

21st Design Sync 用于把某个项目已经采用的配色设计（其 shadcn / Tailwind CSS 变量与颜色令牌）发布到 21st.dev 公共主题库，供他人预览、收藏和应用。它做的是「同步已有设计」，而不是重新设计。

底层调用一条 CLI 命令：

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

主要能力

在项目中定位定义 shadcn / Tailwind 主题变量的文件（如 app/globals.css、src/app/globals.css、src/index.css、styles/globals.css、app/styles/globals.css 等）。
读取其中的 :root { … } 与 .dark { … } 两个 CSS 自定义属性代码块，包括 --background、--foreground、--card、--primary、--secondary、--muted、--accent、--destructive、--border、--input、--ring、--chart-*、--sidebar-*、--radius 等令牌。
将这两个代码块整理粘贴为一个独立主题 CSS 文件（例如 project-theme.css）后发布。
支持为主题指定名称（必填，不超过 50 字符）和可选标签（如 dark、minimal、neutral、vibrant、saas，逗号分隔）。
发布后输出主题的在线 URL（形如 https://21st.dev/community/themes/<slug>）。

使用方式

前置检查

认证需要一个真实的 API 密钥。publish-theme 是管理端点，只接受 21st_sk_… 形式的密钥，不接受 21st 登录会话令牌。可在 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（主题没有 unlisted / private 选项）。发布前需与用户确认。

步骤 1：找到项目的设计令牌

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

app/globals.css、src/app/globals.css
src/index.css、styles/globals.css、app/styles/globals.css

需要的是一个 :root { … } 块（CSS 自定义属性）以及一个对应的 .dark { … } 块。取值可能是 hsl(...)、oklch(...)、hex 或原始通道值，应保持项目原本的写法不变。

Tailwind v4 项目通常保留同样的 :root / .dark 块，另加一个 @theme inline 映射；只需 :root 和 .dark 的令牌值，不需要 @theme 映射。

步骤 2：组装有效的主题 CSS 文件

发布端点会从 :root { … } 块和 .dark { … } 块中解析 --name: value; 键值对，并要求两者都非空。因此发布的文件必须同时包含这两个块。

把项目里的 :root 和 .dark 块复制进一个独立文件（如 project-theme.css），无需其他内容。

如果项目只有浅色的 :root、没有 .dark（或为空），应在发布前生成深色变体，不要发布一个空深色模式的主题。可复用 add-dark-mode / oklch-skill 的思路：反转明度同时保留色相与彩度，使深色集合保持品牌一致，并沿用相同的令牌名称。

保持令牌名称符合 shadcn 标准，以便主题在卡片上正确预览并被他人干净地应用。

最小结构示例：

: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… */
}

步骤 3：命名与打标签

名称（必填，≤50 字符）：从项目中推断，如 package.json、仓库或站点标题里的产品 / 品牌名；若不明确则询问用户。
标签（可选）：几个符合人们浏览主题习惯的描述词，例如 dark、minimal、neutral、vibrant、saas，以逗号分隔传入。

步骤 4：发布

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

命令会打印主题的在线 URL（https://21st.dev/community/themes/<slug>），将其分享给用户。

更新与重新发布的区别

每次 publish-theme 都会创建一个新主题（不像组件那样有按 slug 的 upsert）。运行两次等于库中多出两个主题。
若要修改已有主题的名称 / 标签 / 可见性，可原地编辑：21st edit <theme-id> --type theme [--name "…"] [--tags a,b]。
若要修改颜色，发布一个新文件并删除旧的：21st delete <theme-id> --type theme --yes（软下架，可逆）。

适用场景

把项目已采用、希望分享给社区的配色方案发布为公共主题。
需要在 21st.dev 社区主题库中预览、收藏或让他人应用该项目设计的场合。

不适用场景

将组件库同步到 Claude Design 项目：应使用内置的 /design-sync 技能，目标不同。
发布组件（而非颜色主题）：应使用 21st-registry。