design-integration

设计系统集成

概述

检测项目的设计系统，全面采用它，并且只通过获准的渠道进行扩展。绝不抵触、绝不忽视、绝不重建已有功能。

核心原则： 如果项目有设计系统，你创建的每个组件都必须使用该系统的基础组件、设计令牌和模式。如果没有系统，则应先建立一个，再编写组件。

没有例外。没有变通方案。没有捷径。

首要指令

NEVER REBUILD WHAT THE DESIGN SYSTEM ALREADY PROVIDES

如果系统提供了 <Dialog> 组件，就使用它。不要自行编造一个。不要将它包在带有覆盖样式的容器中。使用它的变体 API，并且只通过其文档说明的扩展点进行扩展。

适用场景

以下情况必须使用：

• 进入任何现有的、带有用户界面的代码库
• 为成熟的应用引入新的 UI 元素
• 扩展项目的组件库
• 初始化将包含 UI 层的新项目

以下情况尤其适用：

• 引入 @shadcn/ui、@mui/material、antd、@chakra-ui 或同类依赖
• 存在包含基础组件的 components/ui 目录
• 存在 tailwind.config、theme.ts 或设计令牌文件等配置文件
• 需要为没有现成系统的项目添加 UI

入门流程

BEFORE authoring any UI component:

1. DETECT: What design system governs this project? (see Detection below)
2. STUDY: Read the system's component API for the element you are building
3. ASSESS: Does the system already provide this component?
   - Yes -> Consume it directly. Do NOT recreate it.
   - Partially -> Compose from existing primitives
   - No -> Build it adhering to the system's conventions
4. VALIDATE: Does your component feel native to the system?

Omit any step = fighting the system

检测步骤

digraph detect_system {
    rankdir=TB;
    start [label="New project or\nnew component", shape=doublecircle];
    check_deps [label="Inspect package.json\nfor UI frameworks", shape=box];
    known [label="Recognized design\nsystem present?", shape=diamond];
    check_code [label="Search source tree\nfor UI import patterns", shape=box];
    has_custom [label="Internal component\nlibrary found?", shape=diamond];
    check_tokens [label="Look for\ndesign token definitions", shape=box];
    has_tokens [label="Token file\ndetected?", shape=diamond];
    adopt_known [label="ADOPT\nUse the recognized system", shape=box, style=filled, fillcolor="#ccffcc"];
    adopt_internal [label="ADOPT\nFollow internal library conventions", shape=box, style=filled, fillcolor="#ccffcc"];
    bootstrap [label="BOOTSTRAP\nInitialize a design system", shape=box, style=filled, fillcolor="#ccccff"];
    extend_tokens [label="BUILD\non existing token foundation", shape=box, style=filled, fillcolor="#ccffcc"];

    start -> check_deps;
    check_deps -> known;
    known -> adopt_known [label="yes"];
    known -> check_code [label="no"];
    check_code -> has_custom;
    has_custom -> adopt_internal [label="yes\n(components/ui\nor equivalent)"];
    has_custom -> check_tokens [label="no"];
    check_tokens -> has_tokens;
    has_tokens -> extend_tokens [label="yes"];
    has_tokens -> bootstrap [label="no"];
}

阶段 1：检查依赖

依赖	系统	实施方式
@radix-ui/*、class-variance-authority	shadcn/ui	遵循 shadcn 的文件和变体约定
@mui/material、@emotion/react	Material UI	遵循 Material Design 规范
antd	Ant Design	遵循 Ant 组件模式
@chakra-ui/react	Chakra UI	遵循 Chakra 主题配置和样式属性
@headlessui/react	Headless UI	配合 Tailwind 设置样式
@mantine/core	Mantine	遵循 Mantine 钩子和组件模式
primereact、primevue	PrimeReact/PrimeVue	遵循 Prime 主题和模板系统

阶段 2：扫描内部组件

查找：

• components/ui/ 目录（典型的 shadcn/ui 布局）
• components/common/ 或 components/shared/
• 来自组件目录的 Barrel 重新导出
• Storybook 故事（.stories.tsx）

阶段 3：定位设计令牌

搜索：

• tailwind.config.js/ts（Tailwind CSS 主题自定义配置）
• theme.ts 或 theme.js（自定义主题对象）
• 在 :root 或 [data-theme] 上定义的 CSS 自定义属性
• tokens/ 或 design-tokens/ 目录
• styles/variables.css 或 styles/tokens.css

采用：在现有系统中工作

通用原则

1. 按原样使用组件 API。 不要添加带有内联覆盖样式的包装元素。
2. 使用系统的变体机制。 如果系统提供 variant="danger"，就使用它，而不是手动覆盖颜色。
3. 使用系统的尺寸属性。 如果系统接受 size="sm"，就不要用自定义 CSS 覆盖。
4. 通过系统指定的扩展点进行扩展。 不要通过 CSS 优先级争夺来扩展。
5. 遵循系统的目录约定。 如果基础组件位于 components/ui/，新增组件也应放在那里。

shadcn/ui

基于 Radix UI + Tailwind CSS 构建、可复制并自定义的组件。

约定：

• 基础组件位于 components/ui/（基础构件）
• 应用组件位于 components/（由基础组件组合而成）
• 使用 cn() 辅助函数合并类字符串
• 使用 class-variance-authority 中的 cva() 定义变体
• 所有样式均通过 Tailwind 工具类设置

添加缺失的组件：

npx shadcn@latest add [component-name]

组合自定义组件：

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Badge } from "@/components/ui/badge"

export function ProjectCard({ project }) {
  return (
    <Card>
      <CardHeader><CardTitle>{project.title}</CardTitle></CardHeader>
      <CardContent>
        <Badge variant={project.live ? "default" : "secondary"}>
          {project.live ? "Live" : "Draft"}
        </Badge>
      </CardContent>
    </Card>
  )
}

禁止事项：

• 使用原始 CSS 文件覆盖 shadcn 样式
• 重建 shadcn 已提供的组件
• 在 shadcn 组件旁使用非 Tailwind 样式
• 条件组合类名时忽略 cn() 辅助函数

Material UI

约定：

• 在 theme.ts 中通过 createTheme() 定义主题
• 从 @mui/material 导入组件
• 通过 sx 属性或 styled() API 设置样式
• 通过 theme.components 设置全局覆盖

扩展主题：

const theme = createTheme({
  palette: { primary: { main: '#0d9488' } },
  components: {
    MuiButton: {
      defaultProps: { disableElevation: true },
      styleOverrides: { root: { textTransform: 'none', borderRadius: 8 } },
    },
  },
});

Ant Design

约定：

• 从 antd 导入组件
• 通过 ConfigProvider 和 token 系统设置主题
• 通过 theme.token 设置全局 token，通过 theme.components 设置单个组件的 token

禁止： 直接覆盖 .ant-* CSS 类，或与竞争的组件库混用 Ant。

Tailwind CSS（独立使用，不搭配组件库）

当项目使用 Tailwind，但没有配套的组件框架时：

1. 检查 tailwind.config 中的自定义主题扩展
2. 仅使用这些值——不要使用任意值
3. 复用代码库中现有的类模式

扩展：为现有系统添加内容

当系统缺少你需要的组件时：

构建前检查清单

1. 搜索系统文档——它可能以其他名称存在
2. 判断能否通过现有基础组件组合实现
3. 查找社区插件或扩展

在系统内构建新组件

遵循系统的规范：

1. 命名——遵循系统的命名模式（PascalCase 组件、kebab-case 文件等）
2. API——遵循系统的属性约定（variant + size、cva、sx 等）
3. 样式——使用相同的样式机制（Tailwind + cn()、sx 属性、token 引用）
4. TOKEN——引用系统 token 值，切勿使用原始字面值
5. 无障碍——复现系统的无障碍模式（ARIA 属性、键盘导航、焦点管理）

启动：不存在系统时

项目规模	建议
原型 / MVP	Tailwind CSS + shadcn/ui
小型团队，品牌特色鲜明	Tailwind CSS + 无头基础组件（Radix/Headless UI）
企业 / 大型组织	Material UI 或 Ant Design（功能齐全、约束性强）
以设计为中心 / 代理机构项目	Tailwind CSS + 定制组件库

最低限度的启动步骤

1. 安装 CSS 框架（大多数情况下推荐 Tailwind）
2. 定义设计 token（利用 godmode:ux-patterns design-tokens.md 中的模板）
3. 创建基础组件（至少包括 Button、Input、Card、Badge）
4. 配置主题（CSS 自定义属性或 Tailwind 配置）

快速启动（Tailwind + shadcn/ui）

npx tailwindcss init -p
npx shadcn@latest init
npx shadcn@latest add button input card badge dialog toast

随后，使用项目专属的 token 值自定义 tailwind.config.ts。

在现有代码库中发现 Token

加入缺少已记录 token 的项目时：

Token 类别	查找位置
颜色	CSS 变量、Tailwind 配置、主题文件、最常用的 hex/rgb 值
字体排印	字体导入、CSS 字体声明、Tailwind 配置中的字体部分
间距	各样式表中最常见的 padding/margin/gap 值
边框圆角	组件样式中最常见的 border-radius 值
阴影	最常见的 box-shadow 声明

发现流程：

1. 在所有样式文件中搜索 CSS 自定义属性（--）
2. 检查 tailwind.config 中的 theme.extend 自定义项
3. 检查是否导出了 theme.ts 或 theme.js
4. 如果没有找到任何内容，检查使用频率最高的 5-10 个组件，找出反复出现的值并将其记录为 token

认知陷阱

自我辩解	事实
“系统没有这个组件”	用基础元素组合，或按照既定规范扩展。不要绕过系统。
“直接写原始 CSS 比学习 API 更快”	今天更快，之后却会一直不一致。投入时间学习系统。
“我之后会把它接入系统”	之后永远不会到来。脱离系统的组件会影响它接触到的一切。
“系统的 API 限制太多”	API 的设计目的就是防止不一致。遵循它，或以正确方式扩展。
“结合两个系统能兼得两者之长”	结合两个系统只会兼得两者之短：样式冲突、包体积翻倍。
“这是一次性组件，不重要”	一次性组件会不断增加。正确构建，否则就会成为技术债务。
“我只覆盖这个属性就好”	一次覆盖会变成二十次。使用系统的主题机制。

防护规则 -- HALT

• 使用 !important 覆盖系统样式
• 在一个项目中混用两种不同的组件框架
• 重建系统已经提供的组件
• 忽略系统的主题或令牌方案
• 系统已有组件时仍使用原始 HTML 元素
• 在 components/ui/ 旁创建 components/custom/
• 在 Tailwind 项目中添加独立 CSS 文件
• 系统提供调色板时仍硬编码十六进制颜色
• 已有 UI 库时再安装第二个

此列表中的每一项都意味着：HALT。使用现有系统。

集成

前置知识：

• godmode:ux-patterns -- 提供设计参考；本技能负责针对特定系统的实现

互补技能：

• godmode:ui-engineering -- 在设计系统内运作的实现模式
• godmode:project-bootstrap -- 在项目设置期间初始化设计系统