21st-design-sync

用途

21st Design Sync 用于把一个项目当前已经采用的设计方案——即它的 shadcn / Tailwind CSS 变量和颜色令牌——发布到 21st.dev 公共主题库，成为一个可分享的主题。任何人都可以预览、收藏并应用这个主题。该技能本质上是一次 CLI 调用：21st publish-theme <file.css> --name "…"。

前置检查

发布主题是管理端点操作，需要真实的 API key。它只接受 21st_sk_… 形式的 key，不接受 21st 的登录会话令牌。key 可在 https://21st.dev/mcp 或 https://21st.dev/settings/api-keys 获取，并通过 --api-key 21st_sk_… 参数或 TWENTYFIRST_TOKEN / API_KEY_21ST 环境变量传入。如果用户没有 key，应指引其前往上述地址获取，而不是尝试自行生成。

CLI 为统一的 @21st-dev/cli（可执行文件名为 21st）。若尚未安装，可使用 npx @21st-dev/cli。

发布是对外公开的行为。主题一旦发布，在社区库中立即为 is_public 状态（主题没有 unlisted / private 选项）。因此发布前应先与用户确认。

第一步：定位项目设计令牌

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

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

目标是找到包含 CSS 自定义属性的 :root { … } 块（--background、--foreground、--card、--primary、--secondary、--muted、--accent、--destructive、--border、--input、--ring，以及 --chart-* / --sidebar-* 令牌、--radius）和与之对应的 .dark { … } 块。值可能是 hsl(...)、oklch(...)、hex 或原始通道值，应保持项目原样，不做改动。

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

第二步：组装有效的主题 CSS 文件

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

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

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

令牌名称应保持 shadcn 标准，这样主题预览卡片才能正确显示，其他人应用时也能正常生效。

最小结构示例：

: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%;
  /* …项目其余的深色令牌… */
}

第三步：命名与标签

名称（必填，不超过 50 个字符）：从项目推断，例如取自 package.json 的产品 / 品牌名、仓库名或站点标题。如果有歧义，应询问用户。

标签（可选）：几个符合用户浏览主题习惯的描述词，例如 dark、minimal、neutral、vibrant、saas，以逗号分隔传入。

第四步：发布

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

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

更新与重新发布

每次执行 publish-theme 都会创建一个新主题（不像组件那样支持按 slug 覆盖更新）。运行两次就会在主题库中出现两个主题。

若要修改已有主题的名称 / 标签 / 可见性，就地编辑：21st edit <theme-id> --type theme [--name "…"] [--tags a,b]。

若要修改颜色，需发布一个新文件并删除旧主题：21st delete <theme-id> --type theme --yes（软取消发布，可逆）。

不适用的情况

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