Back to Details

run-ui-registry-variations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

run-ui-registry-variations

run-ui-registry-variations

Manual workflow for UI work that must start from approved component registries instead of hand-rolled interface code. The skill hard-gates registry access, then builds three real variations for the user to compare.
用于 UI 工作的手动工作流，必须从已批准的组件注册表启动，而非手写界面代码。该技能会严格管控注册表访问权限，随后构建三个真实变体供用户对比。

When to use

适用场景

  • /run-ui-registry-variations <UI request>
  • The user explicitly says 
    run-ui-registry-variations
    .
  • The user asks for three UI options using shadcnblocks, Aceternity, or the Darkmatter shadcn registry.
  • The user wants a one-off UI, new no-design-system project surface, or 
    darkmatter.io
    surface and wants registry-backed options.
  • /run-ui-registry-variations <UI 请求>
  • 用户明确提及 
    run-ui-registry-variations
  • 用户要求使用 shadcnblocks、Aceternity 或 Darkmatter shadcn 注册表生成三个 UI 方案
  • 用户需要独立 UI 界面、无设计系统的新项目界面，或 
    darkmatter.io
    界面，且需要基于注册表的方案

When NOT to use

不适用场景

  • The user only asks which registry to use. Answer directly or use 
    ui-ux-pro-max
    .
  • The project is a flagship app with its own design system and the user did not explicitly invoke this skill.
  • The task is backend, infra, copywriting, or non-visual.
  • The user asks for one final implementation only and does not want alternatives.
  • 用户仅询问该使用哪个注册表。直接回答或使用 
    ui-ux-pro-max
  • 项目是拥有自有设计系统的旗舰应用，且用户未明确调用本技能
  • 任务属于后端、基础设施、文案撰写或非可视化类型
  • 用户仅需要最终实现方案，不需要备选版本

Contract

执行约定

  1. Use only these component sources for visual structure: 
    shadcnblocks
    , 
    Aceternity
    , or 
    https://shadcn.darkmatter.io
    .
  2. Validate registry access before using a source. 
    shadcnblocks
    and 
    Aceternity
    require API-key/token validation; 
    shadcn.darkmatter.io
    requires a live fetch check.
  3. Build exactly three variations. Do not stop at descriptions or moodboards.
  4. Present all three variations to the user before replacing the default UI path.
  5. Preserve secrets. Never print API keys, decrypted registry config, private URLs containing tokens, or generated plaintext credential files.
  6. Do not use unapproved component sources as filler. If a source fails validation, use another validated allowed source or stop.
  1. 视觉结构仅可使用以下组件源：
    shadcnblocks
    、
    Aceternity
    或 
    https://shadcn.darkmatter.io
  2. 使用组件源前必须验证注册表访问权限。
    shadcnblocks
    和 
    Aceternity
    需要验证 API 密钥/令牌；
    shadcn.darkmatter.io
    需要进行实时获取校验
  3. 必须构建恰好三个变体，不得仅停留在描述或情绪板阶段
  4. 在替换默认 UI 路径前，必须向用户展示全部三个变体
  5. 妥善保管机密信息。严禁打印 API 密钥、解密后的注册表配置、包含令牌的私有 URL 或生成的明文凭证文件
  6. 不得使用未批准的组件源作为填充内容。若某个源验证失败，使用其他已验证的允许源，或停止执行

Workflow

工作流程

1. Scope the target

1. 确定目标范围

Identify the target route, component, page, or prototype surface. If the app has an existing design system, read it first and keep the variations compatible with it.
For no-design-system Darkmatter work, 
darkmatter.io
, and one-off UIs, default the baseline visual language to 
https://shadcn.darkmatter.io
.
明确目标路由、组件、页面或原型界面。如果应用已有设计系统，需先读取该设计系统，确保变体与其兼容。
对于无设计系统的 Darkmatter 项目、
darkmatter.io
及独立 UI 界面，默认以 
https://shadcn.darkmatter.io
作为基础视觉规范。

2. Discover registry configuration

2. 查找注册表配置

Check likely sources in this order:
  1. Project docs for registry setup.
  2. components.sops.json
    , 
    secrets/*.sops.json
    , or another encrypted project config.
  3. Plain 
    components.json
    , 
    .env.local
    , 
    .env
    , or package scripts.
If encrypted config exists, use 
sops-secret-access
. Decrypt only what is needed, prefer pipes or temp files, and do not print decrypted contents.
Common private token names to look for, but do not assume these are exhaustive:
  • SHADCNBLOCKS_API_KEY
    , 
    SHADCNBLOCKS_TOKEN
    , 
    SHADCNBLOCKS_REGISTRY_TOKEN
  • ACETERNITY_API_KEY
    , 
    ACETERNITY_TOKEN
    , 
    ACETERNITY_REGISTRY_TOKEN
按以下顺序检查可能的配置来源：
  1. 项目文档中的注册表设置说明
  2. components.sops.json
    、
    secrets/*.sops.json
    或其他加密的项目配置文件
  3. 明文形式的 
    components.json
    、
    .env.local
    、
    .env
    或 package 脚本
若存在加密配置，使用 
sops-secret-access
工具。仅解密所需内容，优先使用管道或临时文件，且不得打印解密后的内容。
常见的私有令牌名称如下，但不局限于这些：
  • SHADCNBLOCKS_API_KEY
    、
    SHADCNBLOCKS_TOKEN
    、
    SHADCNBLOCKS_REGISTRY_TOKEN
  • ACETERNITY_API_KEY
    、
    ACETERNITY_TOKEN
    、
    ACETERNITY_REGISTRY_TOKEN

3. Validate access

3. 验证访问权限

Always attempt private-provider preflight for both 
shadcnblocks
and 
Aceternity
, even if the likely fallback is 
shadcn.darkmatter.io
. If no key is available for a private provider, mark that provider blocked and do not use it.
For each intended source:
  • shadcnblocks
    : prove an API key/token is present and accepted by an authenticated registry request.
  • Aceternity
    : prove an API key/token is present and accepted by an authenticated registry request.
  • shadcn.darkmatter.io
    : prove the registry endpoint is reachable with 
    curl
    or the project's registry tooling.
Use 
bun scripts/validate-registry-access.ts
(this skill's copy) when the registry URL and env var name are known. If the project uses custom registry tooling, run the smallest read-only command that fetches a registry index or one known component.
If a private provider fails validation, do not use that provider in a variation. Continue with any validated allowed source; if no allowed source validates, stop and report the blocked provider checks.
始终对 
shadcnblocks
和 
Aceternity
执行私有提供商预检查，即使备选方案是 
shadcn.darkmatter.io
。如果某个私有提供商没有可用的密钥，标记该提供商为不可用，不得使用。
针对每个拟使用的源：
  • shadcnblocks
    ：证明存在 API 密钥/令牌，且通过身份验证的注册表请求可被接受
  • Aceternity
    ：证明存在 API 密钥/令牌，且通过身份验证的注册表请求可被接受
  • shadcn.darkmatter.io
    ：通过 
    curl
    或项目的注册表工具证明注册表端点可达
当已知注册表 URL 和环境变量名称时，使用 
bun scripts/validate-registry-access.ts
（本技能内置脚本）。如果项目使用自定义注册表工具，运行最小化的只读命令以获取注册表索引或某个已知组件。
若某个私有提供商验证失败，不得在变体中使用该提供商。继续使用所有已验证的允许源；如果没有任何允许源通过验证，停止执行并报告被阻止的提供商检查结果。

4. Select components

4. 选择组件

Each variation must cite the source registry and concrete components/blocks used. Prefer three distinct sources when all are available:
  1. Variation A: 
    shadcnblocks
  2. Variation B: 
    Aceternity
  3. Variation C: 
    shadcn.darkmatter.io
If only one or two sources validate, still build three variations, but all visual structure must come from the validated allowed source set.
每个变体必须注明所使用的源注册表及具体组件/组件块。当所有源均可用时，优先使用三个不同的源：
  1. 变体 A：
    shadcnblocks
  2. 变体 B：
    Aceternity
  3. 变体 C：
    shadcn.darkmatter.io
如果仅有一两个源验证通过，仍需构建三个变体，但所有视觉结构必须来自已验证的允许源集合。

5. Build three variations

5. 构建三个变体

Create real code artifacts, not only prose:
  • Use separate component files, clearly named exports, a preview route, tabs, Storybook stories, or another local pattern that lets the user compare all three.
  • Keep data contracts and business logic shared; vary layout, density, interaction treatment, and visual emphasis.
  • Do not wire one variation as the final default until the user chooses.
  • Avoid raw, custom-only Tailwind shells unless they wrap or compose registry components.
创建真实的代码产物，而非仅提供文字描述：
  • 使用独立的组件文件、命名清晰的导出、预览路由、标签页、Storybook 故事，或其他本地模式，方便用户对比全部三个变体
  • 共享数据契约与业务逻辑，仅调整布局、密度、交互处理方式和视觉侧重点
  • 在用户做出选择前，不得将任何变体设为最终默认版本
  • 避免使用纯自定义的 Tailwind 空壳，除非它们包装或组合了注册表组件

6. Verify and present

6. 验证与展示

Run the app's normal frontend checks for the touched surface. When a browser preview is possible, capture or inspect all three variations at desktop and mobile widths.
Present the result using 
reference/variation-template.md
. Include:
  • Validation status for 
    shadcnblocks
    , 
    Aceternity
    , and 
    shadcn.darkmatter.io
    .
  • Source registry and components used for each variation.
  • Local path/route for review.
  • Any blocked provider and the non-secret reason.
针对修改的界面运行应用常规的前端检查。当支持浏览器预览时，在桌面端和移动端宽度下截图或检查全部三个变体。
使用 
reference/variation-template.md
展示结果，包含以下内容：
  • shadcnblocks
    、
    Aceternity
    和 
    shadcn.darkmatter.io
    的验证状态
  • 每个变体所使用的源注册表和组件
  • 供评审的本地路径/路由
  • 任何被阻止的提供商及非涉密原因

Tools

工具

scripts/validate-registry-access.ts

scripts/validate-registry-access.ts

Validates that a registry endpoint is reachable, optionally using a token from an environment variable without printing the token.
bash
bun skills/run-ui-registry-variations/scripts/validate-registry-access.ts \
  shadcnblocks "$SHADCNBLOCKS_REGISTRY_URL" SHADCNBLOCKS_API_KEY

bun skills/run-ui-registry-variations/scripts/validate-registry-access.ts \
  aceternity "$ACETERNITY_REGISTRY_URL" ACETERNITY_API_KEY

bun skills/run-ui-registry-variations/scripts/validate-registry-access.ts \
  shadcn-darkmatter https://shadcn.darkmatter.io
Deps: Bun (
fetch
). If tokens live in SOPS, load them into the environment through the project-approved SOPS path first.
用于验证注册表端点是否可达，可选择从环境变量中读取令牌，且不会打印令牌。
bash
bun skills/run-ui-registry-variations/scripts/validate-registry-access.ts \
  shadcnblocks "$SHADCNBLOCKS_REGISTRY_URL" SHADCNBLOCKS_API_KEY

bun skills/run-ui-registry-variations/scripts/validate-registry-access.ts \
  aceternity "$ACETERNITY_REGISTRY_URL" ACETERNITY_API_KEY

bun skills/run-ui-registry-variations/scripts/validate-registry-access.ts \
  shadcn-darkmatter https://shadcn.darkmatter.io
依赖： Bun（
fetch
）。如果令牌存储在 SOPS 中，需先通过项目批准的 SOPS 路径将其加载到环境变量中。

Reference

参考资料

  • reference/variation-template.md
    — output format for presenting the three variations and provider validation evidence.
  • reference/variation-template.md
    —— 用于展示三个变体和提供商验证证据的输出格式。