ui-design-system

UI 设计系统

概述

使用以 Token 为先的架构，构建和维护可扩展的设计系统。本技能涵盖从原始设计 Token 到语义映射，再到主题化组件库的完整流程，并深入掌握 Tailwind CSS v4、CSS 自定义属性和响应式设计模式。

阶段 1：Token 基础

1. 审核现有设计资源（颜色、字体、间距、阴影）
2. 定义原始 Token（不带语义含义的原始值）
3. 创建语义 Token 层（将原始 Token 映射到意图）
4. 构建组件 Token 层（将语义映射到组件部件）

停止 — 在构建组件前，先向用户展示 Token 层级以供审核。

Token 层级决策表

层级	用途	命名约定	示例
原始	原始值，唯一事实来源	--color-blue-500、--space-4	oklch(0.55 0.18 250)
语义	映射到用途／意图	--action-primary、--text-secondary	var(--color-blue-600)
组件	限定到特定组件	--button-height-md、--card-radius	var(--space-4)

各层的创建时机

情况	所需层级
全新项目	全部三层（原始 + 语义 + 组件）
为现有项目添加深色模式	语义 + 组件（重新映射原始 Token）
更新品牌颜色	仅原始层（语义／组件自动更新）
添加新组件	仅组件层（引用现有语义 Token）
使用 @theme 的 Tailwind 项目	通过 @theme 定义原始 Token，通过 CSS 变量定义语义 Token

阶段 2：Token 实现

第 1 层：原始 Token

采用系统化命名的原始值。所有值的唯一事实来源。

/* Colors — using OKLCH for perceptual uniformity */
--color-blue-50: oklch(0.97 0.01 250);
--color-blue-100: oklch(0.93 0.03 250);
--color-blue-500: oklch(0.55 0.18 250);
--color-blue-900: oklch(0.25 0.10 250);

/* Spacing — 4px base unit */
--space-1: 0.25rem;   /* 4px */
--space-2: 0.5rem;    /* 8px */
--space-3: 0.75rem;   /* 12px */
--space-4: 1rem;      /* 16px */
--space-6: 1.5rem;    /* 24px */
--space-8: 2rem;      /* 32px */
--space-12: 3rem;     /* 48px */
--space-16: 4rem;     /* 64px */

/* Typography */
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'Geist Mono', monospace;
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;

/* Line Heights */
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;

/* Border Radius */
--radius-sm: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-full: 9999px;

/* Shadows */
--shadow-sm: 0 1px 2px 0 oklch(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px oklch(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px oklch(0 0 0 / 0.1);

第 2 层：语义 Token

将原始 Token 映射到用途。组件会引用这些 Token。

/* Surface */
--surface-primary: var(--color-white);
--surface-secondary: var(--color-gray-50);
--surface-elevated: var(--color-white);
--surface-overlay: oklch(0 0 0 / 0.5);

/* Text */
--text-primary: var(--color-gray-900);
--text-secondary: var(--color-gray-600);
--text-tertiary: var(--color-gray-400);
--text-inverse: var(--color-white);
--text-link: var(--color-blue-600);

/* Action */
--action-primary: var(--color-blue-600);
--action-primary-hover: var(--color-blue-700);
--action-secondary: var(--color-gray-100);
--action-danger: var(--color-red-600);

/* Border */
--border-default: var(--color-gray-200);
--border-strong: var(--color-gray-300);
--border-focus: var(--color-blue-500);

/* Status */
--status-success: var(--color-green-600);
--status-warning: var(--color-amber-500);
--status-error: var(--color-red-600);
--status-info: var(--color-blue-600);

第 3 层：组件 Token

限定到特定组件。

/* Button */
--button-height-sm: 2rem;
--button-height-md: 2.5rem;
--button-height-lg: 3rem;
--button-padding-x: var(--space-4);
--button-radius: var(--radius-md);
--button-font-weight: 500;

/* Input */
--input-height: 2.5rem;
--input-padding-x: var(--space-3);
--input-border: var(--border-default);
--input-border-focus: var(--border-focus);
--input-radius: var(--radius-md);

/* Card */
--card-padding: var(--space-6);
--card-radius: var(--radius-xl);
--card-shadow: var(--shadow-sm);
--card-border: var(--border-default);

阶段 3：组件架构

1. 识别原子组件（Button、Input、Badge、Avatar）
2. 定义分子组件（FormField、SearchBar、Card）
3. 构建有机体组件（Header、Sidebar、DataTable）
4. 建立组合模式（布局、页面模板）

停止 — 在构建变体前，先向用户展示组件清单以供审核。

组件复杂度决策表

级别	组件	组合方式
原子	Button、Input、Badge、Avatar、Icon	单个元素，无子元素
分子	FormField、SearchBar、Card、Tooltip	组合 2-3 个原子组件
有机体	Header、Sidebar、DataTable、Modal	多个分子组件
模板	DashboardLayout、AuthLayout	页面级组合

变体模式（使用 CVA 或 Tailwind Variants）

const buttonVariants = cva("inline-flex items-center justify-center rounded-md font-medium", {
  variants: {
    variant: {
      primary: "bg-action-primary text-white hover:bg-action-primary-hover",
      secondary: "bg-action-secondary text-text-primary hover:bg-gray-200",
      ghost: "hover:bg-action-secondary",
      danger: "bg-action-danger text-white hover:bg-red-700",
    },
    size: {
      sm: "h-8 px-3 text-sm",
      md: "h-10 px-4 text-sm",
      lg: "h-12 px-6 text-base",
    },
  },
  defaultVariants: {
    variant: "primary",
    size: "md",
  },
});

组合模式

• 复杂 UI 使用复合组件（Tabs、Accordion、Combobox）
• 使用基于插槽的组合实现灵活布局
• 使用 Render Props 实现最大程度的自定义
• 使用 Forward Refs 访问 DOM

阶段 4：主题与响应式设计

1. 通过替换 Token 实现浅色／深色主题
2. 使用容器查询定义断点系统
3. 构建响应式组件变体
4. 在不同视口和配色方案下进行测试

停止 — 在宣布完成前，确认主题切换正常工作。

Tailwind CSS v4 配置

/* app.css — Tailwind v4 uses CSS-based config */
@import "tailwindcss";

@theme {
  --color-primary-50: oklch(0.97 0.01 250);
  --color-primary-500: oklch(0.55 0.18 250);
  --color-primary-600: oklch(0.48 0.18 250);
  --color-primary-700: oklch(0.40 0.18 250);

  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'Geist Mono', monospace;

  --breakpoint-sm: 40rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
  --breakpoint-xl: 80rem;
}

深色／浅色主题

:root {
  color-scheme: light dark;
  --surface-primary: var(--color-white);
  --text-primary: var(--color-gray-900);
}

@media (prefers-color-scheme: dark) {
  :root {
    --surface-primary: var(--color-gray-950);
    --text-primary: var(--color-gray-50);
    --surface-elevated: var(--color-gray-900);
  }
}

/* Class-based override for manual toggle */
[data-theme="dark"] {
  --surface-primary: var(--color-gray-950);
  --text-primary: var(--color-gray-50);
}

响应式设计模式

断点系统

Mobile-first approach:
Default    -> 0px+     (mobile)
sm         -> 640px+   (large phone / small tablet)
md         -> 768px+   (tablet)
lg         -> 1024px+  (laptop)
xl         -> 1280px+  (desktop)
2xl        -> 1536px+  (large desktop)

容器查询（组件优先采用）

.card-container {
  container-type: inline-size;
  container-name: card;
}

@container card (min-width: 400px) {
  .card-content {
    flex-direction: row;
  }
}

响应式模式决策表

模式	移动端行为	桌面端行为
列转行	垂直排列	水平排列
收起侧边栏	抽屉式叠加层	固定侧边栏
表格转卡片	卡片列表	完整数据表格
隐藏／显示	隐藏次要内容	显示全部内容
重新排序	优先内容置前	标准顺序

验证清单

• 为所有原始值定义基础令牌
• 语义令牌将基础令牌映射到设计意图
• 组件令牌仅引用语义令牌
• 配置正确重新映射令牌的深色模式主题
• 定义断点系统（移动端优先）
• 使用容器查询实现组件级响应式布局
• 字体排印比例遵循一致的比例关系
• 间距比例以 4px/8px 为基准单位
• 焦点状态清晰可见且易于访问
• 颜色对比度符合 WCAG AA 标准（4.5:1）

反模式 / 常见错误

反模式	错误原因	应对方法
在组件中硬编码十六进制值	无法应用主题，也无法适配深色模式	使用语义令牌
通过反转颜色创建深色模式	效果很差，对比度也不正确	将令牌重新映射为适用于深色模式的值
使用 !important 覆盖系统	引发优先级之争，难以维护	修正层叠关系或使用数据属性
混用间距单位（px、rem、em）	布局不一致，缩放时出现问题	统一使用 rem，并引用令牌
不扩展现有组件，而是创建一次性组件	造成设计系统碎片化	为现有组件添加变体并进行扩展
跳过语义层	与基础令牌紧密耦合	始终按基础令牌 -> 语义令牌 -> 组件令牌的顺序映射
在组件中直接使用基础令牌	无法在不重写代码的情况下更换主题	组件仅引用语义令牌
组件未使用容器查询	组件在不同上下文中会出现问题	使用容器查询构建自适应组件

集成点

技能	集成方式
ui-ux-pro-max	提供样式、配色方案和 UX 指南
senior-frontend	在 React/Next.js 中实现设计系统
canvas-design	提供数据可视化令牌和图表主题
mobile-design	提供适用于移动端的令牌调整方案
artifacts-builder	生成设计系统预览产物
planning	像规划其他功能一样规划设计系统

技能类型

灵活 — 根据项目现有的约定和工具链调整令牌命名、组件结构和主题方案。强烈建议采用三层令牌层级（基础令牌 -> 语义令牌 -> 组件令牌），但小型项目可以适当简化。