mcpField
2
21st-design-sync

21st-design-sync

github.com/21st-dev设计与 UI311.8k 次安装7 周前更新
代码仓库

关于 21st-design-sync

用于将项目的浅色和深色 CSS 设计令牌发布到 21st.dev 公共主题库的技能，涵盖令牌准备、命名、身份验证、发布及后续编辑。

主要功能

  1. 01查找浅色和深色 CSS 令牌
  2. 02准备可发布的主题文件
  3. 03设置主题名称和可选标签
  4. 04使用 21st CLI 发布
  5. 05说明编辑与替换方式

适用场景

  1. 01公开分享项目配色主题
  2. 02补齐缺失的深色模式令牌
  3. 03更新已发布主题的信息

MCP 相关

该技能提及通过 21st MCP 获取 API 密钥；实际发布使用 21st CLI。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/21st-dev/skill --skill 21st-design-sync

安装后在 Claude Code 中输入/21st-design-sync确认已加载。

详细介绍

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

提取项目现有的设计（浅色和深色 CSS 变量），并将其发布到 公开 的 21st.dev 主题库，让任何人都可以预览、收藏和应用。底层只需调用一次 CLI： 21st publish-theme <file.css> --name "…"。

发布前检查（始终执行）

  1. 身份验证需要真实的 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 环境变量传入。如果用户没有密钥，请引导他们前往该页面获取，不要尝试生成密钥。
  2. CLI 统一使用 @21st-dev/cli（可执行文件为 21st）。如果尚未安装，请使用 npx @21st-dev/cli。
  3. 发布是公开且面向外部的。 主题发布后会立即在社区主题库中设为 is_public（主题没有未列出或私有选项）。发布前请先向用户确认。

步骤 1 — 查找项目的设计令牌

定位定义 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 映射。

步骤 2 — 组装有效的主题 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%;
  /* …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 执行更新或插入）。运行两次会在主题库中创建两个主题。
  • 若要修改现有主题的名称 / 标签 / 可见性，请直接编辑： 21st edit <theme-id> --type theme [--name "…"] [--tags a,b]。
  • 若要修改颜色，请发布新文件并移除旧主题： 21st delete <theme-id> --type theme --yes（软取消发布，可恢复）。

不适用场景

  • 将组件库同步到 Claude Design 项目 → 请使用内置的 /design-sync 技能；它会同步到其他位置。
  • 发布组件（而非配色主题） → 请使用 21st-registry。

评论

支持 Markdown