ui-design-system
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUI Design System
UI设计系统
Overview
概述
Build and maintain scalable design systems with a token-first architecture. This skill covers the full pipeline from primitive design tokens through semantic mapping to themed component libraries, with deep expertise in Tailwind CSS v4, CSS custom properties, and responsive design patterns.
构建并维护以令牌优先架构为基础的可扩展设计系统。本技能覆盖从基础设计令牌到语义映射，再到主题化组件库的全流程，深度适配Tailwind CSS v4、CSS自定义属性和响应式设计模式。
Phase 1: Token Foundation
阶段1：令牌基础层
- Audit existing design assets (colors, fonts, spacing, shadows)
- Define primitive tokens (raw values with no semantic meaning)
- Create semantic token layer (map primitives to intentions)
- Build component token layer (map semantics to component parts)
STOP — Present the token hierarchy to user for review before building components.
- 审计现有设计资产（色彩、字体、间距、阴影）
- 定义基础令牌（无语义含义的原始值）
- 创建语义令牌层（将基础值映射到使用意图）
- 构建组件令牌层（将语义映射到组件局部属性）
暂停 — 在构建组件前先向用户展示令牌层级结构供审核。
Token Layer Decision Table
令牌层决策表
| Layer | Purpose | Naming Convention | Example |
|---|---|---|---|
| Primitive | Raw values, single source of truth | | |
| Semantic | Map to purpose/intention | | |
| Component | Scoped to specific components | | |
| 层级 | 用途 | 命名规范 | 示例 |
|---|---|---|---|
| 基础层 | 原始值，唯一真值来源 | | |
| 语义层 | 映射到使用目的/意图 | | |
| 组件层 | 限定在特定组件范围内使用 | | |
When to Create Each Layer
各层级适用场景
| Situation | Layers Needed |
|---|---|
| Brand new project | All three (primitive + semantic + component) |
| Adding dark mode to existing | Semantic + component (remap primitives) |
| Updating brand colors | Primitive only (semantic/component auto-update) |
| Adding new component | Component only (reference existing semantic) |
Tailwind project with | Primitive via @theme, semantic via CSS vars |
| 场景 | 需要的层级 |
|---|---|
| 全新项目 | 全部三层（基础+语义+组件） |
| 为现有项目添加暗色模式 | 语义+组件层（重新映射基础值） |
| 更新品牌色 | 仅基础层（语义/组件层自动同步更新） |
| 添加新组件 | 仅组件层（引用现有语义令牌） |
用 | 通过@theme定义基础层，通过CSS变量定义语义层 |
Phase 2: Token Implementation
阶段2：令牌落地实现
Level 1: Primitive Tokens
层级1：基础令牌
Raw values with systematic naming. Single source of truth for all values.
css
/* 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);采用系统化命名的原始值，是所有数值的唯一真值来源。
css
/* 色彩 — 使用OKLCH实现感知一致性 */
--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);
/* 间距 — 4px为基础单位 */
--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 */
/* 排版 */
--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;
/* 行高 */
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;
/* 圆角 */
--radius-sm: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-full: 9999px;
/* 阴影 */
--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);Level 2: Semantic Tokens
层级2：语义令牌
Map primitives to purpose. These are what components reference.
css
/* 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);将基础令牌映射到使用目的，组件直接引用该层令牌。
css
/* 容器表面 */
--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-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-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-default: var(--color-gray-200);
--border-strong: var(--color-gray-300);
--border-focus: var(--color-blue-500);
/* 状态 */
--status-success: var(--color-green-600);
--status-warning: var(--color-amber-500);
--status-error: var(--color-red-600);
--status-info: var(--color-blue-600);Level 3: Component Tokens
层级3：组件令牌
Scoped to specific components.
css
/* 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);限定在特定组件范围内使用的令牌。
css
/* 按钮 */
--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-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-padding: var(--space-6);
--card-radius: var(--radius-xl);
--card-shadow: var(--shadow-sm);
--card-border: var(--border-default);Phase 3: Component Architecture
阶段3：组件架构
- Identify atomic components (Button, Input, Badge, Avatar)
- Define molecule components (FormField, SearchBar, Card)
- Build organism components (Header, Sidebar, DataTable)
- Establish composition patterns (layouts, page templates)
STOP — Present component inventory for review before building variants.
- 识别原子组件（按钮、输入框、徽章、头像）
- 定义分子组件（表单项、搜索栏、卡片）
- 构建有机体组件（页头、侧边栏、数据表格）
- 建立组合模式（布局、页面模板）
暂停 — 在构建变体前先展示组件清单供审核。
Component Complexity Decision Table
组件复杂度决策表
| Level | Components | Composition |
|---|---|---|
| Atom | Button, Input, Badge, Avatar, Icon | Single element, no children |
| Molecule | FormField, SearchBar, Card, Tooltip | 2-3 atoms combined |
| Organism | Header, Sidebar, DataTable, Modal | Multiple molecules |
| Template | DashboardLayout, AuthLayout | Page-level composition |
| 层级 | 组件 | 组合方式 |
|---|---|---|
| 原子 | 按钮、输入框、徽章、头像、图标 | 单个元素，无子元素 |
| 分子 | 表单项、搜索栏、卡片、提示框 | 2-3个原子组合而成 |
| 有机体 | 页头、侧边栏、数据表格、弹窗 | 多个分子组合而成 |
| 模板 | 仪表盘布局、鉴权布局 | 页面级组合 |
Variant Pattern (using CVA or Tailwind Variants)
变体模式（使用CVA或Tailwind Variants实现）
typescript
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",
},
});typescript
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",
},
});Composition Patterns
组合模式
- Compound components for complex UI (Tabs, Accordion, Combobox)
- Slot-based composition for flexible layouts
- Render props for maximum customization
- Forward refs for DOM access
- 复杂UI使用复合组件（标签页、手风琴、组合框）
- 灵活布局使用基于插槽的组合
- 高自定义需求使用渲染属性
- DOM访问需求使用转发ref
Phase 4: Theming and Responsiveness
阶段4：主题化与响应式适配
- Implement light/dark themes via token swapping
- Define breakpoint system with container queries
- Build responsive component variants
- Test across viewports and color schemes
STOP — Verify theme switching works correctly before declaring complete.
- 通过令牌替换实现亮/暗色主题
- 定义带容器查询的断点系统
- 构建响应式组件变体
- 跨视口和配色方案测试
暂停 — 在宣告完成前验证主题切换功能正常运行。
Tailwind CSS v4 Configuration
Tailwind CSS v4 配置
css
/* 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;
}css
/* app.css — Tailwind v4使用基于CSS的配置 */
@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;
}Dark / Light Theming
暗色/亮色主题
css
: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);
}css
: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);
}
}
/* 基于类名的手动切换覆盖 */
[data-theme="dark"] {
--surface-primary: var(--color-gray-950);
--text-primary: var(--color-gray-50);
}Responsive Design Patterns
响应式设计模式
Breakpoint System
断点系统
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)移动端优先方案：
默认 -> 0px+ (移动端)
sm -> 640px+ (大屏手机/小平板)
md -> 768px+ (平板)
lg -> 1024px+ (笔记本)
xl -> 1280px+ (桌面端)
2xl -> 1536px+ (大屏桌面端)Container Queries (Preferred for Components)
容器查询（组件适配优先选择）
css
.card-container {
container-type: inline-size;
container-name: card;
}
@container card (min-width: 400px) {
.card-content {
flex-direction: row;
}
}css
.card-container {
container-type: inline-size;
container-name: card;
}
@container card (min-width: 400px) {
.card-content {
flex-direction: row;
}
}Responsive Patterns Decision Table
响应式模式决策表
| Pattern | Mobile Behavior | Desktop Behavior |
|---|---|---|
| Stack to Row | Vertical column | Horizontal row |
| Sidebar Collapse | Drawer overlay | Persistent sidebar |
| Table to Cards | Card list | Full data table |
| Hide/Show | Secondary content hidden | All content visible |
| Reorder | Priority content first | Standard order |
| 模式 | 移动端表现 | 桌面端表现 |
|---|---|---|
| 堆叠转行 | 垂直排列 | 水平排列 |
| 侧边栏收起 | 抽屉浮层 | 常驻侧边栏 |
| 表格转卡片 | 卡片列表 | 完整数据表格 |
| 隐藏/显示 | 隐藏次要内容 | 展示全部内容 |
| 重排序 | 优先级内容靠前 | 标准顺序 |
Verification Checklist
验证检查清单
- Primitive tokens defined for all raw values
- Semantic tokens map primitives to intentions
- Component tokens reference only semantic tokens
- Dark mode theme with proper token remapping
- Breakpoint system defined (mobile-first)
- Container queries used for component-level responsiveness
- Typography scale follows consistent ratio
- Spacing scale uses 4px/8px base unit
- Focus states visible and accessible
- Color contrast ratios meet WCAG AA (4.5:1)
- 所有原始值都定义了对应基础令牌
- 语义令牌将基础值映射到使用意图
- 组件令牌仅引用语义令牌
- 暗色模式主题完成了正确的令牌重映射
- 定义了移动端优先的断点系统
- 组件级响应式适配使用了容器查询
- 排版字号遵循统一的比例规则
- 间距体系使用4px/8px基础单位
- 聚焦状态可见且符合可访问性要求
- 色彩对比度满足WCAG AA标准（4.5:1）
Anti-Patterns / Common Mistakes
反模式/常见错误
| Anti-Pattern | Why It Is Wrong | What to Do Instead |
|---|---|---|
| Hard-coding hex values in components | Cannot theme, cannot dark-mode | Use semantic tokens |
| Creating dark mode by inverting colors | Looks terrible, wrong contrast | Remap tokens to dark-appropriate values |
Using | Specificity wars, unmaintainable | Fix the cascade or use data attributes |
| Mixing spacing units (px, rem, em) | Inconsistent layout, scaling issues | Use rem everywhere, reference tokens |
| One-off components instead of extending | Design system fragmentation | Extend existing components with variants |
| Skipping the semantic layer | Tight coupling to primitives | Always map primitives -> semantics -> components |
| Primitive tokens directly in components | Cannot retheme without rewriting | Components reference semantic tokens only |
| No container queries for components | Components break in different contexts | Use container queries for adaptive components |
| 反模式 | 问题原因 | 正确做法 |
|---|---|---|
| 组件中硬编码十六进制色值 | 无法主题化，无法适配暗色模式 | 使用语义令牌 |
| 通过颜色反转实现暗色模式 | 视觉效果差，对比度不符合要求 | 将令牌重映射为适配暗色模式的数值 |
使用 | 特异性冲突，难以维护 | 修复样式层级或使用data属性 |
| 混合使用间距单位（px、rem、em） | 布局不一致，缩放异常 | 全局使用rem，引用统一令牌 |
| 开发一次性组件而非扩展现有组件 | 设计系统碎片化 | 通过变体扩展现有组件 |
| 跳过语义层 | 与基础值强耦合 | 始终遵循 基础值->语义->组件的映射逻辑 |
| 组件中直接引用基础令牌 | 重写代码才能更换主题 | 组件仅引用语义令牌 |
| 组件未使用容器查询 | 组件在不同上下文中样式错乱 | 使用容器查询实现组件自适应 |
Integration Points
集成点
| Skill | Integration |
|---|---|
| Provides style, palette, and UX guidelines |
| Implements design system in React/Next.js |
| Data visualization tokens and chart theming |
| Mobile-specific token adaptations |
| Design system preview artifacts |
| Design system is planned like any feature |
| 技能 | 集成方式 |
|---|---|
| 提供样式、配色和UX规范 |
| 在React/Next.js中实现设计系统 |
| 数据可视化令牌和图表主题化 |
| 移动端专属令牌适配 |
| 设计系统预览产物 |
| 设计系统和其他功能一样纳入规划 |
Skill Type
技能类型
FLEXIBLE — Adapt token naming, component structure, and theming approach to the project's existing conventions and tooling. The three-layer token hierarchy (primitive -> semantic -> component) is strongly recommended but can be simplified for small projects.
灵活适配型 — 可根据项目现有规范和工具调整令牌命名、组件结构和主题方案。强烈推荐使用三层令牌层级（基础->语义->组件），但小型项目可适当简化。