ui-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UI/UX Design & Development Expert

UI/UX设计与开发专家

Comprehensive UI/UX design, review, and improvement for modern web applications.

Production-ready implementations with TailwindCSS + Radix UI + shadcn/ui and modern React patterns.

为现代Web应用提供全面的UI/UX设计、评审与优化服务。

基于TailwindCSS + Radix UI + shadcn/ui和现代React模式的生产级实现方案。

Stack Architecture

技术栈架构

The Three Pillars

三大核心支柱

Layer 1: TailwindCSS (Styling Foundation)

Utility-first CSS framework with build-time generation
Zero runtime overhead, minimal production bundles
Design tokens: colors, spacing, typography, breakpoints
Responsive utilities and dark mode support

Layer 2: Radix UI (Behavior & Accessibility)

Unstyled, accessible component primitives
WAI-ARIA compliant with keyboard navigation
Focus management and screen reader support
Unopinionated - full styling control

Layer 3: shadcn/ui (Beautiful Components)

Pre-built components = Radix primitives + Tailwind styling
Copy-paste distribution (you own the code)
Built-in React Hook Form + Zod validation
Customizable variants with type safety

第一层：TailwindCSS（样式基础）

基于构建时生成的优先实用类CSS框架
零运行时开销，最小化生产环境打包体积
设计令牌：颜色、间距、排版、断点
响应式工具类与深色模式支持

第二层：Radix UI（交互与可访问性）

无样式、支持可访问性的基础组件原语
符合WAI-ARIA标准，支持键盘导航
焦点管理与屏幕阅读器适配
无设计偏见，完全可控样式

第三层：shadcn/ui（美观组件）

预构建组件 = Radix原语 + Tailwind样式
复制粘贴即可使用（代码归你所有）
内置React Hook Form + Zod验证
支持类型安全的自定义变体

Architecture Hierarchy

架构层级

Application Layer
    ↓
shadcn/ui Components (Beautiful defaults, ready-to-use)
    ↓
Radix UI Primitives (Accessible behavior, unstyled)
    ↓
TailwindCSS Utilities (Design system, styling)

Key Principle: Each layer enhances the one below. Start with Tailwind for styling, add Radix for accessible behavior, use shadcn/ui for complete components.

Application Layer
    ↓
shadcn/ui Components (Beautiful defaults, ready-to-use)
    ↓
Radix UI Primitives (Accessible behavior, unstyled)
    ↓
TailwindCSS Utilities (Design system, styling)

核心原则： 每一层都为下一层提供增强。从Tailwind开始构建样式，添加Radix实现可访问交互，使用shadcn/ui获得完整组件。

Core Capabilities

核心能力

UI/UX Review & Audit

UI/UX评审与审计

Systematic evaluation of existing interfaces:

Component Architecture Review: Analyze component composition, reusability, and single responsibility
Accessibility Audit: WCAG 2.1/2.2 AA/AAA compliance, keyboard navigation, screen reader support
Performance Analysis: Core Web Vitals (LCP, FID, CLS), bundle size, render performance
Responsive Design Review: Mobile-first implementation, breakpoint usage, container queries
Design System Consistency: Token usage, spacing scale adherence, color palette compliance
Code Quality: React best practices, hooks usage, state management patterns
Visual Hierarchy: Typography scale, spacing rhythm, color contrast, focus indicators

对现有界面进行系统性评估：

组件架构评审：分析组件组合、复用性与单一职责
可访问性审计：WCAG 2.1/2.2 AA/AAA合规性、键盘导航、屏幕阅读器支持
性能分析：核心Web指标（LCP、FID、CLS）、打包体积、渲染性能
响应式设计评审：移动端优先实现、断点使用、容器查询
设计系统一致性：令牌使用、间距规范遵循、调色板合规性
代码质量：React最佳实践、Hooks使用、状态管理模式
视觉层级：排版比例、间距节奏、颜色对比度、焦点指示器

UI/UX Design

UI/UX设计

Creating production-ready interface designs:

Component Design: Atomic design principles, composition patterns, variant systems
Layout Architecture: Grid systems, flexbox patterns, responsive containers
Interaction Design: Hover states, focus states, loading states, error states
Design Tokens: Three-tier token system (primitive → semantic → component)
Color Systems: OKLCH color space, accessible palettes, dark mode support
Typography Systems: Scale design, hierarchy, readability optimization
Animation & Transitions: Micro-interactions, loading feedback, state changes

创建生产级界面设计：

组件设计：原子设计原则、组合模式、变体系统
布局架构：网格系统、Flexbox模式、响应式容器
交互设计：悬停状态、焦点状态、加载状态、错误状态
设计令牌：三级令牌系统（基础→语义→组件）
颜色系统：OKLCH色彩空间、可访问调色板、深色模式支持
排版系统：比例设计、层级结构、可读性优化
动画与过渡：微交互、加载反馈、状态切换

UI/UX Improvement

UI/UX优化

Enhancing existing implementations:

Accessibility Enhancement: ARIA patterns, semantic HTML, keyboard navigation
Performance Optimization: Code splitting, lazy loading, virtualization, image optimization
Responsive Refinement: Breakpoint optimization, mobile-first improvements
Component Refactoring: Extract shared patterns, reduce complexity, improve reusability
Visual Polish: Spacing consistency, typography refinement, color harmony
State Management: Optimistic updates, error handling, loading states
Developer Experience: Component documentation, Storybook stories, type safety

增强现有实现方案：

可访问性提升：ARIA模式、语义化HTML、键盘导航
性能优化：代码分割、懒加载、虚拟化、图片优化
响应式改进：断点优化、移动端优先改进
组件重构：提取共享模式、降低复杂度、提升复用性
视觉打磨：间距一致性、排版优化、色彩和谐
状态管理：乐观更新、错误处理、加载状态
开发者体验：组件文档、Storybook示例、类型安全

Styling Integration

样式集成

Framework-agnostic styling approaches:

Tailwind with Components: Utility-first styling for any framework
CSS-in-JS: emotion, styled-components, vanilla-extract
CSS Modules: Scoped styles without runtime overhead
Design System Integration: Token-based styling across frameworks

框架无关的样式实现方式：

Tailwind与组件结合：为任意框架提供优先实用类样式
CSS-in-JS：emotion、styled-components、vanilla-extract
CSS Modules：无运行时开销的作用域样式
设计系统集成：跨框架的基于令牌的样式

When to Use Each Layer

各层级适用场景

Use TailwindCSS Directly When:

直接使用TailwindCSS的场景：

Building custom layouts and spacing
Styling static content and containers
Rapid prototyping without complex interactions
Non-interactive UI elements

Example scenarios: Hero sections, grid layouts, cards without interaction, text styling

构建自定义布局与间距
为静态内容与容器设置样式
无需复杂交互的快速原型开发
非交互式UI元素

示例场景： Hero区域、网格布局、无交互卡片、文本样式

Use Radix UI Primitives When:

使用Radix UI原语的场景：

Building custom component libraries
Need accessibility but require custom design
shadcn/ui doesn't have the component you need
Full control over component structure required

Example scenarios: Custom date picker, unique navigation pattern, specialized modal behavior

构建自定义组件库
需要可访问性但需自定义设计
shadcn/ui没有你需要的组件
需要完全控制组件结构

示例场景： 自定义日期选择器、独特导航模式、特殊模态框交互

Use shadcn/ui Components When:

使用shadcn/ui组件的场景：

Building standard UI components quickly
Need beautiful defaults with customization options
Enterprise application development
Form-heavy applications with validation

Example scenarios: Admin dashboards, CRUD applications, settings pages, data tables

快速构建标准UI组件
需要美观默认样式且支持自定义
企业级应用开发
表单密集型应用（带验证）

示例场景： 管理后台、CRUD应用、设置页面、数据表格

Critical Design Principles

关键设计原则

1. Progressive Enhancement

1. 渐进式增强

Start simple, enhance as needed:

Tailwind utilities for basic styling
Add Radix primitives for interaction
Use shadcn/ui for complete solutions
Customize components in your codebase

从简单开始，按需增强：

使用Tailwind工具类实现基础样式
添加Radix原语实现交互
使用shadcn/ui获得完整解决方案
在你的代码库中自定义组件

2. Composition Over Complexity

2. 组合优于复杂

Build complex UIs from simple, reusable components:

Small, focused components (single responsibility)
Compose primitives rather than creating monoliths
Leverage component slots and children patterns

通过简单、可复用组件构建复杂UI：

小巧、聚焦的组件（单一职责）
组合原语而非创建单体组件
利用组件插槽与子元素模式

3. Accessibility First

3. 可访问性优先

Radix UI handles accessibility automatically:

ARIA attributes applied correctly
Keyboard navigation built-in
Focus management and trapping
Screen reader compatibility

Never override accessibility features - enhance them.

Radix UI自动处理可访问性：

正确应用ARIA属性
内置键盘导航
自动焦点管理与捕获
屏幕阅读器兼容

永远不要覆盖可访问性功能 - 而是增强它们。

4. Design Token Consistency

4. 设计令牌一致性

Use Tailwind's design system consistently:

Stick to spacing scale (4, 8, 16, 24px)
Use color palette (50-950 shades)
Apply typography scale systematically
Avoid arbitrary values unless necessary

始终遵循Tailwind的设计系统：

坚持使用间距比例（4、8、16、24px）
使用调色板（50-950色调）
系统地应用排版比例
除非必要，避免使用任意值

5. Mobile-First Responsive

5. 移动端优先响应式

Always design mobile-first, scale up:

Base styles for mobile
Use breakpoints (sm, md, lg, xl, 2xl) to enhance
Test on actual devices, not just browser resize

始终从移动端开始设计，逐步扩展：

为移动端设置基础样式
使用断点（sm、md、lg、xl、2xl）进行增强
在真实设备上测试，而非仅靠浏览器缩放

Setup Strategy

搭建策略

Installation Order

安装顺序

TailwindCSS - Foundation
shadcn/ui CLI - Includes Radix dependencies
Add components - Install only what you need
Configure theme - CSS variables + Tailwind config
Setup dark mode - Theme provider + toggle

TailwindCSS - 基础
shadcn/ui CLI - 包含Radix依赖
添加组件 - 仅安装你需要的组件
配置主题 - CSS变量 + Tailwind配置
设置深色模式 - 主题提供者 + 切换器

Configuration Best Practices

配置最佳实践

Tailwind Config:

Use
```
content
```
paths correctly (scan all component files)
Extend theme with CSS variables, not hardcoded values
Enable dark mode with
```
class
```
strategy
Install
```
tailwindcss-animate
```
plugin

CSS Variables (Three-Tier System):

css

:root {
  /* Tier 1: Primitives (immutable) */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* Tier 2: Semantics (theme-aware) */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* Tier 3: Components */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* Only semantic tokens change */
  --background: var(--gray-900);
  --foreground: var(--gray-50);
}

Color Space Recommendation:

Modern: Use OKLCH for perceptual uniformity
Legacy support: Use HSL with fallbacks
Avoid: RGB/HEX for design tokens (not human-readable)

Token Storage:

Store in JSON for platform-agnostic distribution
Transform to CSS variables, Swift, XML using Style Dictionary
Version control tokens separately from component code

Path Aliases:

Configure
```
@/components
```
and
```
@/lib
```
in tsconfig
Ensure consistency between Next.js and TypeScript configs
Use aliases in imports for cleaner code

Tailwind配置：

正确使用
```
content
```
路径（扫描所有组件文件）
使用CSS变量扩展主题，而非硬编码值
启用
```
class
```
策略的深色模式
安装
```
tailwindcss-animate
```
插件

CSS变量（三级系统）：

css

:root {
  /* Tier 1: Primitives (immutable) */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* Tier 2: Semantics (theme-aware) */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* Tier 3: Components */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* Only semantic tokens change */
  --background: var(--gray-900);
  --foreground: var(--gray-50);
}

色彩空间推荐：

现代方案：使用OKLCH实现感知均匀性
兼容旧系统：使用HSL并提供降级方案
避免：为设计令牌使用RGB/HEX（不易读）

令牌存储：

存储在JSON中以实现跨平台分发
使用Style Dictionary转换为CSS变量、Swift、XML
将令牌与组件代码分开进行版本控制

路径别名：

在tsconfig中配置
```
@/components
```
和
```
@/lib
```
确保Next.js与TypeScript配置一致
在导入中使用别名以简化代码

Integration Patterns

集成模式

Pattern 1: shadcn/ui + Custom Tailwind

模式1：shadcn/ui + 自定义Tailwind

Use shadcn/ui components as base, customize with Tailwind classes:

Apply custom spacing, colors via className prop
Override default styles with Tailwind utilities
Maintain component accessibility

以shadcn/ui组件为基础，使用Tailwind类进行自定义：

通过className属性应用自定义间距、颜色
使用Tailwind工具类覆盖默认样式
保持组件可访问性

Pattern 2: Radix Primitives + Tailwind

模式2：Radix原语 + Tailwind

Build custom components from scratch:

Use Radix for behavior (Dialog, Dropdown, etc.)
Style completely with Tailwind utilities
Full control over structure and appearance

从零开始构建自定义组件：

使用Radix实现交互（Dialog、Dropdown等）
完全使用Tailwind工具类设置样式
完全控制结构与外观

Pattern 3: Hybrid Approach

模式3：混合方案

Modify shadcn/ui components in your codebase:

Edit component files in
```
components/ui/
```
Add new variants, sizes, or styles
Maintain type safety with CVA (Class Variance Authority)

在你的代码库中修改shadcn/ui组件：

编辑
```
components/ui/
```
中的组件文件
添加新变体、尺寸或样式
使用CVA（Class Variance Authority）保持类型安全

Pattern 4: Component Composition

模式4：组件组合

Combine multiple primitives for complex UIs:

Popover + Select for searchable dropdown
Dialog + Form for modal forms
Tabs + Cards for multi-section interfaces

组合多个原语构建复杂UI：

Popover + Select 实现可搜索下拉框
Dialog + Form 实现模态表单
Tabs + Cards 实现多区域界面

Design Token Architecture

设计令牌架构

Use three-tier token system for scalable, maintainable design systems:

Tier 1 (Primitive): Raw values (
```
gray-50
```
,
```
spacing-4
```
)
Tier 2 (Semantic): Purpose-driven (
```
background-primary
```
,
```
text-error
```
)
Tier 3 (Component): Component-specific (
```
button-height
```
,
```
card-padding
```
)

Modern Color: Use OKLCH color space for perceptual uniformity and better accessibility calculations.

📖 See DESIGN_TOKENS.md for:

Complete three-tier token system implementation
OKLCH color space guide and examples
Token naming conventions and best practices
CSS variable configuration
Multi-theme support patterns

使用三级令牌系统构建可扩展、可维护的设计系统：

第一层（基础）：原始值（
```
gray-50
```
、
```
spacing-4
```
）
第二层（语义）：基于用途的命名（
```
background-primary
```
、
```
text-error
```
）
第三层（组件）：组件特定值（
```
button-height
```
、
```
card-padding
```
）

现代色彩方案： 使用OKLCH色彩空间实现感知均匀性，便于更可靠、可预测的对比度计算。

📖 详情请查看 DESIGN_TOKENS.md：

完整的三级令牌系统实现
OKLCH色彩空间指南与示例
令牌命名规范与最佳实践
CSS变量配置
多主题支持模式

Responsive Design Strategy

响应式设计策略

Mobile-first approach: Start with mobile (0-639px), scale up through sm/md/lg/xl/2xl breakpoints.

Key patterns: Layout shifts (column→row), component switching (Dialog→Drawer), container queries for modular responsiveness.

📖 See RESPONSIVE_PATTERNS.md for:

Complete breakpoint strategy and implementation
Responsive component patterns and examples
Container queries guide
Image optimization strategies
Performance considerations for responsive design
Comprehensive testing checklist

移动端优先方案： 从移动端（0-639px）开始，逐步扩展到sm/md/lg/xl/2xl断点。

关键模式： 布局切换（列→行）、组件切换（Dialog→Drawer）、容器查询实现模块化响应式。

📖 详情请查看 RESPONSIVE_PATTERNS.md：

完整的断点策略与实现
响应式组件模式与示例
容器查询指南
图片优化策略
响应式设计的性能考量
全面的测试清单

Form Architecture

表单架构

Strategy: React Hook Form + Zod for schema-first validation with type inference and accessible error handling.

📖 See CUSTOMIZATION.md for:

Complete React Hook Form + Zod setup
Reusable field wrapper patterns
Multi-step form implementation
Accessibility requirements checklist

策略： 使用React Hook Form + Zod实现基于Schema的验证，支持类型推断与可访问错误处理。

📖 详情请查看 CUSTOMIZATION.md：

完整的React Hook Form + Zod搭建
可复用字段包装器模式
多步骤表单实现
可访问性要求清单

Performance Best Practices

性能最佳实践

Core strategies: Code splitting (React.lazy), Tailwind optimization (accurate content paths), virtualization (@tanstack/react-virtual for long lists).

📖 See PERFORMANCE_OPTIMIZATION.md for:

Complete performance optimization guide
Core Web Vitals optimization strategies
Bundle analysis and tree shaking
Common pitfalls and solutions
Performance monitoring setup

核心策略： 代码分割（React.lazy）、Tailwind优化（准确的content路径）、虚拟化（@tanstack/react-virtual处理长列表）。

📖 详情请查看 PERFORMANCE_OPTIMIZATION.md：

完整的性能优化指南
核心Web指标优化策略
打包分析与树摇
常见陷阱与解决方案
性能监控搭建

Component Customization & Dark Mode

组件定制与深色模式

Customization Strategies

定制策略

Direct Modification: Edit shadcn/ui files in your codebase
Variant Extension: Use CVA for type-safe variants
Wrapper Components: Add custom logic around base components
Theme Customization: Modify CSS variables globally

直接修改：在你的代码库中编辑shadcn/ui文件
变体扩展：使用CVA实现类型安全的变体
包装组件：在基础组件外添加自定义逻辑
主题定制：全局修改CSS变量

Dark Mode Setup

深色模式搭建

ThemeProvider with next-themes
Class strategy (
```
class
```
, not media query)
CSS variables in
```
.dark
```
class
Accessible toggle component

📖 See CUSTOMIZATION.md for:

Complete customization strategies with examples
CVA variant implementation guide
Dark mode setup and configuration
Design considerations and testing
Form architecture patterns

ThemeProvider 结合next-themes
Class策略（
```
class
```
，而非媒体查询）
.dark类中的CSS变量
可访问的切换器组件

📖 详情请查看 CUSTOMIZATION.md：

完整的定制策略与示例
CVA变体实现指南
深色模式搭建与配置
设计考量与测试
表单架构模式

Accessibility Standards

可访问性标准

Radix UI Built-In Guarantees

Radix UI内置保障

✅ ARIA attributes applied correctly
✅ Keyboard navigation functional
✅ Focus management and trapping automatic
✅ Screen reader compatible

✅ 正确应用ARIA属性
✅ 键盘导航可用
✅ 自动焦点管理与捕获
✅ 屏幕阅读器兼容

WCAG Contrast Requirements (Critical)

WCAG对比度要求（关键）

WCAG 2.1 Level AA (Legal Minimum):

Normal text: 4.5:1 minimum contrast ratio
Large text (18pt/14pt bold+): 3:1 minimum
UI components/graphics: 3:1 minimum
Industry standard: Most legal requirements specify AA

WCAG Level AAA (Enhanced):

Normal text: 7:1 contrast ratio
Large text: 4.5:1 contrast ratio
Best practice: Aim for AAA when design constraints allow

Measurement:

Contrast ratio range: 1:1 (white on white) to 21:1 (black on white)
Use tools: WebAIM Color Contrast Checker, browser DevTools
Test during design phase, not after implementation

OKLCH Advantage: Perceptually uniform color space makes contrast calculations more reliable and predictable compared to HSL.

WCAG 2.1 AA级别（法定最低要求）：

普通文本：4.5:1 最低对比度
大文本（18pt/14pt加粗+）：3:1 最低对比度
UI组件/图形：3:1 最低对比度
行业标准：多数法定要求指定AA级别

WCAG AAA级别（增强要求）：

普通文本：7:1 对比度
大文本：4.5:1 对比度
最佳实践：在设计约束允许时追求AAA级别

测量方式：

对比度范围：1:1（白对白）到21:1（黑对白）
使用工具：WebAIM Color Contrast Checker、浏览器开发者工具
在设计阶段测试，而非实现后

OKLCH优势： 感知均匀的色彩空间使对比度计算比HSL更可靠、可预测。

Implementation Checklist

实现清单

✅ All text meets 4.5:1 minimum (AA standard)
✅ Interactive elements meet 3:1 minimum
✅ Provide descriptive labels (
```
aria-label
```
,
```
<label>
```
)
✅ Test complete keyboard navigation flow
✅ Verify visible focus indicators (not just browser default)
✅ Test with screen readers (NVDA, JAWS, VoiceOver)
✅ Use semantic HTML elements (
```
<button>
```
,
```
<nav>
```
,
```
<main>
```
)
✅ Provide alternative text for images and icons
✅ Ensure dark mode maintains contrast standards

✅ 所有文本满足4.5:1最低标准（AA级别）
✅ 交互元素满足3:1最低标准
✅ 提供描述性标签（
```
aria-label
```
、
```
<label>
```
）
✅ 测试完整键盘导航流程
✅ 验证可见的焦点指示器（不仅仅是浏览器默认样式）
✅ 使用屏幕阅读器测试（NVDA、JAWS、VoiceOver）
✅ 使用语义化HTML元素（
```
<button>
```
、
```
<nav>
```
、
```
<main>
```
）
✅ 为图片与图标提供替代文本
✅ 确保深色模式维持对比度标准

Testing Strategy

测试策略

Automated: Use contrast checkers during design
Manual: Tab through entire interface
Screen readers: Test with at least one screen reader
Real users: Include users with disabilities in testing

自动化：在设计阶段使用对比度检查工具
手动：通过Tab键遍历整个界面
屏幕阅读器：至少使用一种屏幕阅读器测试
真实用户：将残障用户纳入测试

Common Pitfalls

常见陷阱

Avoid these frequent issues:

Dynamic classes: Tailwind doesn't generate at runtime → use conditionals
Content config: Verify paths include all component files
Import paths: Check tsconfig.json aliases
Dark mode: Ensure ThemeProvider setup and CSS variables
Accessibility: Never remove ARIA attributes

📖 See PERFORMANCE_OPTIMIZATION.md for complete troubleshooting guide with 10+ common issues and solutions.

避免这些常见问题：

动态类：Tailwind不会在运行时生成→使用条件判断
Content配置：验证路径包含所有组件文件
导入路径：检查tsconfig.json别名
深色模式：确保ThemeProvider搭建与CSS变量正确
可访问性：永远不要移除ARIA属性

📖 完整的故障排除指南包含10+常见问题与解决方案，请查看 PERFORMANCE_OPTIMIZATION.md。

Resources

资源

Official Documentation

官方文档

TailwindCSS: https://tailwindcss.com/docs
Radix UI: https://www.radix-ui.com/primitives
shadcn/ui: https://ui.shadcn.com | https://ui.shadcn.com/llms.txt

TailwindCSS: https://tailwindcss.com/docs
Radix UI: https://www.radix-ui.com/primitives
shadcn/ui: https://ui.shadcn.com | https://ui.shadcn.com/llms.txt

Authoritative Design System Sources

权威设计系统资源

USWDS Design Tokens: https://designsystem.digital.gov/design-tokens/
Smashing Magazine Naming: https://www.smashingmagazine.com/2024/05/naming-best-practices/
OKLCH Color Space: https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
WCAG Contrast: https://webaim.org/articles/contrast/

USWDS Design Tokens: https://designsystem.digital.gov/design-tokens/
Smashing Magazine Naming: https://www.smashingmagazine.com/2024/05/naming-best-practices/
OKLCH Color Space: https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
WCAG Contrast: https://webaim.org/articles/contrast/

Reference Files (Detailed Guides & Patterns)

参考文件（详细指南与模式）

Core Concepts:

DESIGN_TOKENS.md - Three-tier token system, OKLCH, naming
RESPONSIVE_PATTERNS.md - Breakpoints, container queries, testing
CUSTOMIZATION.md - Component customization, dark mode, forms
PERFORMANCE_OPTIMIZATION.md - Performance, Core Web Vitals, pitfalls

Implementation References:

TAILWIND_REFERENCE.md - Complete utilities
RADIX_REFERENCE.md - Primitives with code
SHADCN_REFERENCE.md - Components with install
INTEGRATION_PATTERNS.md - Advanced patterns

核心概念：

DESIGN_TOKENS.md - 三级令牌系统、OKLCH、命名规范
RESPONSIVE_PATTERNS.md - 断点、容器查询、测试
CUSTOMIZATION.md - 组件定制、深色模式、表单
PERFORMANCE_OPTIMIZATION.md - 性能、核心Web指标、陷阱

实现参考：

TAILWIND_REFERENCE.md - 完整工具类
RADIX_REFERENCE.md - 带代码的原语
SHADCN_REFERENCE.md - 带安装指南的组件
INTEGRATION_PATTERNS.md - 高级模式

Triggers & Use Cases

触发条件与适用场景

Behavioral Traits

行为特征

Code Quality: Component composition | Single responsibility | Proper hooks usage | Optimized rendering | Comprehensive testing

代码质量： 组件组合 | 单一职责 | 正确Hooks使用 | 优化渲染 | 全面测试

Response Approach

响应方法

Review: Understand context → Systematic audit → Identify issues → Provide evidence → Recommend solutions → Prioritize

Design: Gather requirements → Choose architecture → Design tokens → Component structure → Implement accessibly → Include states → Responsive → Document

Improve: Analyze current state → Identify bottlenecks → Plan improvements → Implement incrementally → Measure impact → Document → Test

Integration: Verify compatibility → Follow official patterns → Best practices → Type safety → Performance budget → Error boundaries

评审： 理解上下文 → 系统性审计 → 识别问题 → 提供证据 → 推荐解决方案 → 优先级排序

设计： 收集需求 → 选择架构 → 设计令牌 → 组件结构 → 可访问实现 → 包含状态 → 响应式 → 文档

优化： 分析当前状态 → 识别瓶颈 → 规划改进 → 增量实现 → 衡量影响 → 文档 → 测试

集成： 验证兼容性 → 遵循官方模式 → 最佳实践 → 类型安全 → 性能预算 → 错误边界

Implementation Checklist

实现清单

Setup: Install Tailwind + shadcn/ui | Configure three-tier tokens | Set up dark mode | Create

cn()

helper

Development: Apply mobile-first design | Implement dark mode | Test accessibility | Verify WCAG AA contrast

Production: Validate Tailwind purging | Test all states | Cross-browser testing | Performance audit

📖 Detailed checklists available in:

DESIGN_TOKENS.md
RESPONSIVE_PATTERNS.md
CUSTOMIZATION.md
PERFORMANCE_OPTIMIZATION.md

搭建： 安装Tailwind + shadcn/ui | 配置三级令牌 | 设置深色模式 | 创建

cn()

助手

开发： 应用移动端优先设计 | 实现深色模式 | 测试可访问性 | 验证WCAG AA对比度

生产： 验证Tailwind清除无用代码 | 测试所有状态 | 跨浏览器测试 | 性能审计

📖 详细清单请查看：

DESIGN_TOKENS.md
RESPONSIVE_PATTERNS.md
CUSTOMIZATION.md
PERFORMANCE_OPTIMIZATION.md

Best Practices Summary

最佳实践总结

Skill Summary

技能总结

Primary Functions:

Review: Audit UI/UX for accessibility, performance, and design system consistency
Design: Create production-ready interfaces with modern React and styling systems
Improve: Enhance existing implementations for better UX, performance, and maintainability

Technology Focus:

TailwindCSS, Radix UI, shadcn/ui (styling layer)
Design tokens and design systems
Accessibility standards (WCAG 2.1/2.2)
Responsive design and mobile-first patterns
Color systems (OKLCH) and typography

Activation Triggers:

UI/UX review, audit, or analysis requests
Design system architecture and token design
Accessibility improvements (WCAG compliance)
Tailwind/Radix/shadcn/ui implementation
Responsive design and mobile-first development
Color system and typography design

Boundaries: ✅ Design systems, styling, accessibility, design tokens, UI patterns ❌ React architecture (react-nextjs-expert), state management, backend APIs, infrastructure

Skill Version: 2.1.0 Last Updated: 2025-11-15 Enhanced With: UI/UX review capabilities, design system architecture, framework-agnostic patterns Authoritative Sources: WCAG 2.1/2.2, OKLCH color science, industry design systems (USWDS, Carbon, Polaris) Progressive Disclosure: Reference files for detailed guides ✅ Scope: Design systems, styling, accessibility, UI/UX patterns (framework-agnostic) Companion Skills: react-nextjs-expert (for React/Next.js architecture and state management)

主要功能：

评审：审计UI/UX的可访问性、性能与设计系统一致性
设计：使用现代React与样式系统创建生产级界面
优化：增强现有实现以提升UX、性能与可维护性

技术重点：

TailwindCSS、Radix UI、shadcn/ui（样式层）
设计令牌与设计系统
可访问性标准（WCAG 2.1/2.2）
响应式设计与移动端优先模式
颜色系统（OKLCH）与排版

触发条件：

UI/UX评审、审计或分析请求
设计系统架构与令牌设计
可访问性改进（WCAG合规）
Tailwind/Radix/shadcn/ui实现
响应式设计与移动端优先开发
颜色系统与排版设计

边界： ✅ 设计系统、样式、可访问性、UI/UX模式（框架无关） ❌ React架构（react-nextjs-expert）、状态管理、后端API、基础设施

技能版本： 2.1.0 最后更新： 2025-11-15 增强内容： UI/UX评审能力、设计系统架构、框架无关模式 权威来源： WCAG 2.1/2.2、OKLCH色彩科学、行业设计系统（USWDS、Carbon、Polaris） 渐进式披露： 参考文件提供详细指南 ✅ 范围： 设计系统、样式、可访问性、UI/UX模式（框架无关） 配套技能： react-nextjs-expert（用于React/Next.js架构与状态管理）