logo-with-variants

带变体的 Logo 创建器

遵循 Elements 代码库中既定的模式，创建支持变体的 Logo 组件。

何时使用此技能

• 用户提供了多个 Logo SVG 文件（图标、字标或 Logo 变体）
• 用户提到“变体”“浅色／深色模式”，或引用 Clerk 风格的 Logo
• 用户想要为集合添加一个包含多个变体的新 Logo
• 用户在 public/test/ 中有 SVG 文件，或提供了 Logo 文件路径

流程

1. 分析提供的 SVG

• 确定变体类型（图标、Logo、字标）
• 检测浅色／深色模式版本（文件名以 -dark.svg 或 -light.svg 结尾）
• 从每个 SVG 中提取 viewBox、颜色和尺寸
• 记录提供的品牌指南

2. 创建组件文件

位置：src/components/ui/logos/{name}.tsx

Props 接口：

{
  className?: string;
  variant?: "icon" | "logo" | "wordmark";
  mode?: "dark" | "light";
}

结构：

• 根据 variant prop 使用条件渲染
• 使用 COLORS 对象模式配置浅色／深色模式的颜色
• 默认使用 variant="wordmark"（主 Logo）
• 支持主题感知的 mode prop
• 添加适当的 TypeScript 类型

参考实现：查看 src/components/ui/logos/clerk.tsx，遵循其中的确切模式。

3. 将 SVG 转换为 JSX

对于每个 SVG 文件：

• 读取 SVG 文件内容
• 将 SVG 属性转换为 JSX（例如，fill-rule → fillRule、stroke-width → strokeWidth）
• 将硬编码颜色替换为 COLORS 对象中的变量
• 保留 viewBox 和尺寸
• 添加 title 标签以实现无障碍访问

4. 创建注册表结构

位置：registry/default/blocks/logos/{name}-logo/

要创建的文件：

1. registry-item.json：

{
  "name": "{name}-logo",
  "type": "registry:block",
  "title": "{DisplayName} Logo",
  "description": "{Brand description}",
  "categories": ["logos"],
  "meta": {
    "hasVariants": true,
    "variants": [
      "icon-dark",
      "icon-light",
      "logo-dark",
      "logo-light",
      "wordmark-dark",
      "wordmark-light"
    ],
    "variantTypes": {
      "base": ["icon", "logo", "wordmark"],
      "modes": ["dark", "light"]
    }
  },
  "files": [
    {
      "path": "components/logos/{name}.tsx",
      "type": "registry:component"
    }
  ],
  "docs": "{Brand} logo with 3 base variants (icon, logo, wordmark) and 2 modes (dark, light) = 6 total combinations. Theme-aware: automatically adapts colors when you switch themes."
}

重要：variants 数组必须以 {base}-{mode} 格式明确列出所有组合（例如，“icon-dark”“logo-light”）。这样 UI 中才会正确显示变体数量徽章（例如，“6”）。不要只列出基础名称，例如 ["icon", "logo", "wordmark"]。

2. 将组件复制到：components/logos/{name}.tsx

5. 更新 registry/index.ts

关键步骤：registry/index.ts 文件是构建流程的事实来源。你必须在此文件中添加或更新 Logo 条目，使用与 registry-item.json 完全相同的元数据结构。

位置：registry/index.ts

找到注册表条目数组，并添加包含完整 meta 字段的 Logo 条目：

{
  $schema: "https://ui.shadcn.com/schema/registry-item.json",
  name: "{name}-logo",
  type: "registry:block",
  title: "{DisplayName} Logo",
  description: "{Brand description}",
  registryDependencies: [],
  dependencies: [],
  categories: ["logos"],
  meta: {
    hasVariants: true,
    variants: [
      "icon-dark",
      "icon-light",
      "logo-dark",
      "logo-light",
      "wordmark-dark",
      "wordmark-light",
    ],
    variantTypes: {
      base: ["icon", "logo", "wordmark"],
      modes: ["dark", "light"],
    },
  },
  files: [
    {
      path: "registry/default/blocks/logos/{name}-logo/components/logos/{name}.tsx",
      type: "registry:component",
    },
  ],
  docs: "{Brand} logo with 3 base variants (icon, logo, wordmark) and 2 modes (dark, light) = 6 total combinations. Theme-aware: automatically adapts colors when you switch themes.",
}

如果要更新现有 Logo：在 registry/index.ts 中搜索 Logo 名称，并用包含 meta 字段的新元数据替换整个条目。

6. 更新 Logo 集合

添加到 registry/default/blocks/logos/logos/registry-item.json：

• 将新 Logo 添加到列表
• 确保其属于正确的类别（tech-giants、ai-services 等）

7. 构建注册表

运行：

bun run build:registry

这会生成公开注册表文件。

组件模板模式

interface LogoProps {
  className?: string;
  variant?: "icon" | "logo" | "wordmark";
  mode?: "dark" | "light";
}

const COLORS = {
  dark: "#HEX_VALUE",
  light: "#HEX_VALUE",
};

export function BrandLogo({
  className,
  variant = "wordmark",
  mode = "dark",
}: LogoProps) {
  const color = COLORS[mode];

  if (variant === "icon") {
    return (
      <svg className={className} viewBox="...">
        {/* Icon SVG content */}
      </svg>
    );
  }

  if (variant === "logo") {
    return (
      <svg className={className} viewBox="...">
        {/* Logo SVG content */}
      </svg>
    );
  }

  // Default: wordmark
  return (
    <svg className={className} viewBox="...">
      {/* Wordmark SVG content */}
    </svg>
  );
}

预期结果

完成后：

1. 可在 @/components/ui/logos/{name} 使用该组件
2. Logo 会显示在 Logos 页面上，并带有变体徽章
3. 上下文菜单会显示“查看 X 个变体”选项
4. 变体对话框会显示所有组合（变体 × 模式）
5. 每个变体的复制／下载功能都能正常使用
6. 可通过 npx shadcn@latest add @elements/{name}-logo 安装

品牌指南集成

如果提供了品牌指南：

• 使用指定的准确品牌颜色
• 遵循命名约定（例如，Linear 使用“Linear”，而非“linear”）
• 遵循层级关系（字标为主，紧凑布局使用 Logo 图形，社交媒体使用图标）
• 在组件注释中加入使用说明

参考文件

• 模板：src/components/ui/logos/clerk.tsx
• 注册表示例：registry/default/blocks/logos/clerk-logo/
• 变体对话框：src/app/docs/logos/logo-variants-dialog.tsx
• Logo 集合：registry/default/blocks/logos/logos/registry-item.json

应避免的常见问题

• 别忘了将组件复制到 src/ 和 registry/ 目录中
• 确保在注册表元数据中设置 hasVariants: true
• 不要对颜色进行硬编码——使用 COLORS 对象以支持主题
• 修改后记得运行 build:registry
• 提交前测试所有变体组合