frontend-design

前端设计技能 — 系统化与创意化 Web 开发

技能位置：{project_path}/skills/frontend-design/

本技能通过系统化的设计 token 方法，将模糊的 UI 风格需求转化为可执行、生产级的前端代码，同时保持创意卓越性。它确保所有交付物在视觉一致性、无障碍合规性和可维护性方面达到标准。

---

何时使用本技能（触发模式）

必须在以下情况下应用本技能：

• 用户请求任何网站、Web 应用或 Web 组件开发
• 用户提及设计风格："modern"、"premium"、"minimalist"、"dark mode"、"SaaS-style"
• 构建仪表盘、落地页、管理面板或任何 Web UI
• 用户要求"让它看起来更好"或"改进设计"
• 创建组件库或设计系统
• 用户指定框架：React、Vue、Svelte、Next.js、Nuxt 等
• 将设计稿/原型图转换为代码
• 用户提及：Tailwind CSS、shadcn/ui、Material-UI、Chakra UI 等

触发短语：

• "build a website/app/component"
• "create a dashboard/landing page"
• "design a UI for..."
• "make it modern/clean/premium"
• "style this with..."
• "convert this design to code"

不适用于：

• 后端 API 开发
• 纯逻辑/算法实现
• 非视觉类代码任务

---

技能架构

本技能提供：

1. SKILL.md（本文件）：核心方法论与指南
2. examples/css/：生产级 CSS 示例
   • tokens.css - 设计 token 系统
   • components.css - 可复用组件样式
   • utilities.css - 工具类
3. examples/typescript/：TypeScript 实现示例
   • design-tokens.ts - 类型安全的 token 定义
   • theme-provider.tsx - 主题管理
   • sample-components.tsx - 组件示例
4. templates/：快速启动模板
   • tailwind-config.js - Tailwind 配置
   • globals.css - 全局样式模板

---

核心原则（不可妥协）

1. 双模式思维：系统 + 创意

系统化基础：

• 设计 token 优先，UI 组件其次
• 不使用任意硬编码值（颜色、间距、阴影、圆角）
• 排版、间距、圆角、层级使用一致的尺度
• 完整的状态覆盖（默认/悬停/激活/聚焦/禁用 + 加载/空/错误）
• 将无障碍视为约束条件，而非事后补充

创意化执行：

• 避免通用的"AI 味"审美（Inter/Roboto 字体、紫色渐变、千篇一律的布局）
• 选择大胆的审美方向：粗野主义、复古未来主义、奢华风、趣味风、编辑风等
• 在排版、色彩、布局和动效上做出出人意料的选择
• 每个设计都应独一无二，并针对其语境精心打造

2. Token 优先方法论

Design Tokens → Component Styles → Page Layouts → Interactive States

绝不要跳过 token 定义。 所有视觉属性都必须源自 token 系统。

3. 技术栈灵活性

默认技术栈（未指定时）：

• 框架：React + TypeScript
• 样式：Tailwind CSS
• 组件：shadcn/ui
• 主题：CSS 自定义属性（浅色/深色模式）

支持的替代方案：

• 框架：Vue、Svelte、Angular、原生 HTML/CSS
• 样式：CSS Modules、SCSS、Styled Components、Emotion
• 库：MUI、Ant Design、Chakra UI、Headless UI

4. Tailwind CSS 最佳实践

⚠️ 关键：绝不要通过 CDN 使用 Tailwind

必须使用构建时集成：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

为什么构建时集成是强制要求：

• ✅ 启用 tree-shaking（2-15KB vs 400KB+ 打包体积）
• ✅ 完整的设计 token 自定义能力
• ✅ IDE 自动补全和类型安全
• ✅ 与打包工具集成（Vite、webpack、Next.js）

CDN 仅可接受用于：

• 快速原型/演示
• 内部测试

---

实现工作流

阶段 1：设计分析与 Token 定义

步骤 1：理解上下文

- Purpose: What problem does this solve? Who uses it?
- Aesthetic Direction: Choose ONE bold direction
- Technical Constraints: Framework, performance, accessibility needs
- Differentiation: What makes this memorable?

步骤 2：生成设计 Token

创建完整的 Token 系统（参见 examples/css/tokens.css 和 examples/typescript/design-tokens.ts）：

1. 语义色彩槽位（浅色 + 深色模式）：

   --background, --surface, --surface-subtle
   --text, --text-secondary, --text-muted
   --border, --border-subtle
   --primary, --primary-hover, --primary-active, --primary-foreground
   --secondary, --secondary-hover, --secondary-foreground
   --accent, --success, --warning, --danger
   

2. 字体排版比例：

   Display: 3.5rem/4rem (56px/64px), weight 700-800
   H1: 2.5rem/3rem (40px/48px), weight 700
   H2: 2rem/2.5rem (32px/40px), weight 600
   H3: 1.5rem/2rem (24px/32px), weight 600
   Body: 1rem/1.5rem (16px/24px), weight 400
   Small: 0.875rem/1.25rem (14px/20px), weight 400
   Caption: 0.75rem/1rem (12px/16px), weight 400
   

3. 间距比例（8px 系统）：

   0.5 → 4px, 1 → 8px, 2 → 16px, 3 → 24px, 4 → 32px
   5 → 40px, 6 → 48px, 8 → 64px, 12 → 96px, 16 → 128px
   

4. 圆角比例：

   xs: 2px (badges, tags)
   sm: 4px (buttons, inputs)
   md: 6px (cards, modals)
   lg: 8px (large cards, panels)
   xl: 12px (hero sections)
   2xl: 16px (special elements)
   full: 9999px (pills, avatars)
   

5. 阴影比例：

   sm: Subtle lift (buttons, inputs)
   md: Card elevation
   lg: Modals, dropdowns
   xl: Large modals, drawers
   

6. 动效 Token：

   Duration: 150ms (micro), 220ms (default), 300ms (complex)
   Easing: ease-out (enter), ease-in (exit), ease-in-out (transition)
   

阶段 2：组件开发

步骤 3：构建可复用组件

遵循以下结构（参见 examples/typescript/sample-components.tsx）：

interface ComponentProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  state?: 'default' | 'hover' | 'active' | 'disabled' | 'loading';
}

必需的组件状态：

• 默认、悬停、激活、聚焦、禁用
• 加载中（骨架屏/加载指示器）
• 空状态（清晰的提示信息）
• 错误状态（恢复指引）

必需的组件特性：

• 无障碍（ARIA 标签、键盘导航）
• 响应式（移动优先）
• 主题感知（浅色/深色模式）
• 基于 Token 的样式（无硬编码值）

阶段 3：页面组装

步骤 4：用组件组合页面

- Use established tokens and components only
- Mobile-first responsive design
- Loading states for async content
- Empty states with clear CTAs
- Error states with recovery options

阶段 4：质量保证

步骤 5：自查清单

• 所有颜色来自语义 Token（无随意的 hex/rgb）
• 所有间距来自间距比例
• 所有圆角来自圆角比例
• 阴影由层级关系决定其合理性
• 清晰的字体层级，配以舒适的行高（1.5+）
• 所有交互状态均已实现并测试
• 无障碍：WCAG AA 对比度、键盘导航、ARIA、焦点指示器
• 响应式：在移动端（375px）、平板（768px）、桌面端（1024px+）均可正常工作
• 包含加载/空/错误状态
• 代码可维护：DRY、命名清晰、有文档

---

设计方向模板

1. 极简高端 SaaS（最通用）

Visual Style: Minimal Premium SaaS
- Generous whitespace (1.5-2x standard padding)
- Near-white background with subtle surface contrast
- Light borders (1px, low-opacity)
- Very subtle elevation (avoid heavy shadows)
- Unified control height: 44-48px
- Medium-large radius: 6-8px
- Gentle hover states (background shift only)
- Clear but not harsh focus rings
- Low-contrast dividers
- Priority: Readability and consistency

最适合： 企业应用、B2B SaaS、生产力工具

2. 大胆编辑风

Visual Style: Bold Editorial
- Strong typographic hierarchy (large display fonts)
- High contrast (black/white or dark/light extremes)
- Generous use of negative space
- Asymmetric layouts with intentional imbalance
- Grid-breaking elements
- Minimal color palette (1-2 accent colors max)
- Sharp, geometric shapes
- Dramatic scale differences
- Priority: Visual impact and memorability

最适合： 营销网站、作品集、内容密集型网站

3. 柔和有机风

Visual Style: Soft & Organic
- Rounded corners everywhere (12-24px radius)
- Soft shadows and subtle gradients
- Pastel or muted color palette
- Gentle animations (ease-in-out, 300-400ms)
- Curved elements and flowing layouts
- Generous padding (1.5-2x standard)
- Soft, blurred backgrounds
- Priority: Approachability and comfort

最适合： 消费类应用、健康养生、生活方式品牌

4. 暗色霓虹（克制版）

Visual Style: Dark Neon
- Dark background (#0a0a0a to #1a1a1a, NOT pure black)
- High contrast text (#ffffff or #fafafa)
- Accent colors ONLY for CTAs and key states
- Subtle glow on hover (box-shadow with accent color)
- Minimal borders (use subtle outlines)
- Optional: Subtle noise texture
- Restrained use of neon (less is more)
- Priority: Focus and sophisticated edge

最适合： 开发者工具、游戏、科技产品

5. 趣味多彩风

Visual Style: Playful & Colorful
- Vibrant color palette (3-5 colors)
- Rounded corners (8-16px)
- Micro-animations on hover/interaction
- Generous padding and breathing room
- Friendly, geometric illustrations
- Smooth transitions (200-250ms)
- High energy but balanced
- Priority: Delight and engagement

最适合： 消费类应用、儿童产品、创意工具

---

标准提示词工作流

主提示词模板

You are a Design Systems Engineer + Senior Frontend UI Developer with expertise in creative design execution.

[TECH STACK]
- Framework: {{FRAMEWORK = React + TypeScript}}
- Styling: {{STYLING = Tailwind CSS}}
- Components: {{UI_LIB = shadcn/ui}}
- Theme: CSS variables (light/dark modes)

[DESIGN SYSTEM RULES - MANDATORY]
1. Layout: 8px spacing system; mobile-first responsive
2. Typography: Clear hierarchy (Display/H1/H2/H3/Body/Small/Caption); line-height 1.5+
3. Colors: Semantic tokens ONLY (no hardcoded values)
4. Shape: Tiered radius system; tap targets ≥ 44px
5. Elevation: Minimal shadows; borders for hierarchy
6. Motion: Subtle transitions (150-220ms); restrained animations
7. Accessibility: WCAG AA; keyboard navigation; ARIA; focus indicators

[AESTHETIC DIRECTION]
Style: {{STYLE = Minimal Premium SaaS}}
Key Differentiator: {{UNIQUE_FEATURE}}
Target Audience: {{AUDIENCE}}

[INTERACTION STATES - REQUIRED]
✓ Default, Hover, Active, Focus, Disabled
✓ Loading (skeleton), Empty (with messaging), Error (with recovery)

[OUTPUT REQUIREMENTS]
1. Design Tokens (CSS variables + TypeScript types)
2. Component implementations (copy-paste ready)
3. Page layouts with all states
4. NO hardcoded values; reference tokens only
5. Minimal but clear code comments

Token 生成提示词

Generate a complete Design Token system including:

1. Semantic color slots (CSS custom properties):
   - Light mode + Dark mode variants
   - Background, surface, text, border, primary, secondary, accent, semantic colors
   - Interactive states for each (hover, active)

2. Typography scale:
   - Display, H1-H6, Body, Small, Caption, Monospace
   - Include: font-size, line-height, font-weight, letter-spacing

3. Spacing scale (8px base):
   - 0.5, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24 (in rem)

4. Radius scale:
   - xs (2px), sm (4px), md (6px), lg (8px), xl (12px), 2xl (16px), full

5. Shadow scale:
   - sm, md, lg, xl (with color and blur values)
   - Usage guidelines for each tier

6. Motion tokens:
   - Duration: fast (150ms), base (220ms), slow (300ms)
   - Easing: ease-out, ease-in, ease-in-out

7. Component density:
   - Button heights: sm (36px), md (44px), lg (48px)
   - Input heights: sm (36px), md (40px)
   - Padding scales

Output format:
- CSS custom properties (globals.css)
- Tailwind config integration
- TypeScript type definitions
- Usage examples for each token category

DO NOT write component code yet.

组件实现提示词

Using the established Design Tokens, implement: <{{COMPONENT_NAME}} />

Requirements:
- Props: variant, size, state, className (for composition)
- States: default, hover, focus, active, disabled, loading, error
- Accessibility: keyboard navigation, ARIA labels, focus management
- Responsive: mobile-first, touch-friendly (44px+ tap targets)
- Styling: Use tokens ONLY (no hardcoded values)
- TypeScript: Full type safety with exported interfaces

Include:
1. Component implementation
2. Usage examples (3-5 variants)
3. Loading state example
4. Error state example
5. Accessibility notes

Output: Production-ready, copy-paste code with JSDoc comments.

页面开发提示词

Build page: {{PAGE_NAME}}

Using:
- Established Design Tokens
- Implemented Components
- {{STYLE}} aesthetic direction

Requirements:
- Responsive layout (mobile/tablet/desktop)
- All interaction states (hover/focus/active/disabled)
- Loading skeleton for async content
- Empty state with clear CTA
- Error state with recovery options
- Accessible (keyboard nav, ARIA, WCAG AA)
- No hardcoded styles (components + utility classes only)

Include:
1. Page component with mock data
2. Loading state variant
3. Empty state variant
4. Error state variant
5. Responsive behavior notes

Output: Complete, runnable page component.

审查与优化提示词

You are a Frontend Code Reviewer specializing in design systems and accessibility.

Review the implementation and check:

1. Token Compliance:
   - Any hardcoded colors, sizes, shadows, radius?
   - All values from established scales?

2. Typography:
   - Clear hierarchy?
   - Comfortable line-height (1.5+)?
   - Appropriate font sizes for each level?

3. Spacing & Layout:
   - Consistent use of spacing scale?
   - Adequate whitespace?
   - No awkward gaps or cramped sections?

4. Interactive States:
   - Hover/focus/active clearly distinct?
   - Disabled state obviously different?
   - Loading/empty/error states implemented?

5. Accessibility:
   - WCAG AA contrast met?
   - Keyboard reachable?
   - ARIA labels complete?
   - Focus indicators visible?
   - Semantic HTML?

6. Responsive Design:
   - Mobile layout functional (375px)?
   - Tablet optimized (768px)?
   - Desktop enhanced (1024px+)?
   - Touch targets ≥ 44px?

7. Maintainability:
   - DRY principles followed?
   - Clear component boundaries?
   - Consistent naming?
   - Adequate comments?

8. Creative Execution:
   - Matches intended aesthetic?
   - Avoids generic patterns?
   - Unique and memorable?

Output:
- Findings (sorted by severity: Critical, High, Medium, Low)
- Specific fixes (code patches)
- Improvement suggestions

---

常见陷阱与解决方案

❌ 问题：审美描述含糊不清

✅ 解决方案：强制给出可执行的规格说明

DON'T: "Make it modern and clean"
DO: 
- Whitespace: 1.5x standard padding (24px instead of 16px)
- Typography: Display 56px, H1 40px, Body 16px, line-height 1.6
- Colors: Neutral gray scale (50-900) + single accent color
- Shadows: Maximum 2 shadow tokens (card + modal only)
- Radius: Consistent 6px (buttons/inputs) and 8px (cards)
- Borders: 1px with --border-subtle (#e5e7eb in light mode)
- Transitions: 150ms ease-out only

❌ 问题：每个组件自创样式

✅ 解决方案：强制仅使用 Token 规则

RULE: Every visual property must map to a token.

Violations:
- ❌ bg-gray-100 (hardcoded Tailwind color)
- ❌ p-[17px] (arbitrary padding not in scale)
- ❌ rounded-[5px] (radius not in scale)
- ❌ shadow-[0_2px_8px_rgba(0,0,0,0.1)] (arbitrary shadow)

Correct:
- ✅ bg-surface (semantic token)
- ✅ p-4 (maps to spacing scale: 16px)
- ✅ rounded-md (maps to radius scale: 6px)
- ✅ shadow-sm (maps to shadow token)

❌ 问题：缺少交互状态

✅ 解决方案：状态覆盖清单

For EVERY interactive element, implement:

Visual States:
- [ ] Default (base appearance)
- [ ] Hover (background shift, shadow, scale)
- [ ] Active (pressed state, slightly darker)
- [ ] Focus (visible ring, keyboard accessible)
- [ ] Disabled (reduced opacity, cursor not-allowed)

Data States:
- [ ] Loading (skeleton or spinner with same dimensions)
- [ ] Empty (clear message + CTA)
- [ ] Error (error message + retry option)

Test each state in isolation and in combination.

❌ 问题：千篇一律的 AI 审美

✅ 解决方案：强制创意差异化

BANNED PATTERNS (overused in AI-generated UIs):
- ❌ Inter/Roboto/System fonts as primary choice
- ❌ Purple gradients on white backgrounds
- ❌ Card-grid-card-grid layouts only
- ❌ Generic blue (#3b82f6) as primary
- ❌ Default Tailwind color palette with no customization

REQUIRED CREATIVE CHOICES:
- ✅ Select distinctive fonts (Google Fonts, Adobe Fonts, custom)
- ✅ Build custom color palette (not Tailwind defaults)
- ✅ Design unique layouts (asymmetry, overlap, grid-breaking)
- ✅ Add personality: illustrations, icons, textures, patterns
- ✅ Create signature elements (unique buttons, cards, headers)

Ask yourself: "Would someone recognize this as uniquely designed for this purpose?"

❌ 问题：将无障碍视为事后补充

✅ 解决方案：将无障碍作为约束条件

Build accessibility IN, not ON:

Color Contrast:
- Run contrast checker on all text/background pairs
- Minimum WCAG AA: 4.5:1 (normal text), 3:1 (large text)
- Use tools: WebAIM Contrast Checker, Chrome DevTools

Keyboard Navigation:
- Tab order follows visual flow
- All interactive elements keyboard reachable
- Focus indicator always visible (outline or ring)
- Escape closes modals/dropdowns

ARIA & Semantics:
- Use semantic HTML first (<button>, <nav>, <main>)
- Add ARIA only when semantic HTML insufficient
- aria-label for icon-only buttons
- aria-describedby for form errors
- aria-expanded for disclosure widgets

Test with:
- Keyboard only (no mouse)
- Screen reader (NVDA, JAWS, VoiceOver)
- Reduced motion preference (prefers-reduced-motion)

---

快速开始：完整示例

You are a Design Systems Engineer + Senior Frontend UI Developer.

[STACK]
React + TypeScript + Tailwind CSS + shadcn/ui

[TASK]
Build a Team Dashboard for a project management app.

[AESTHETIC]
Style: Minimal Premium SaaS
Unique Element: Subtle animated background gradient
Audience: Product managers and software teams

[REQUIREMENTS]
1. Components needed:
   - Header with search and user menu
   - Team members grid (name, role, avatar, status)
   - Invite modal (name, email, role selector)
   - Empty state (no team members yet)
   - Loading skeleton

2. Features:
   - Search/filter team members
   - Click to view member details
   - Invite button opens modal
   - Sort by name/role/status

3. States:
   - Loading (skeleton grid)
   - Empty (with invite CTA)
   - Populated (member cards)
   - Error (failed to load)

[OUTPUT]
1. Design Tokens (globals.css + tailwind.config.ts)
2. Component implementations:
   - TeamMemberCard
   - InviteModal
   - SearchBar
   - UserMenu
3. TeamDashboard page component
4. All states (loading/empty/error)
5. Full TypeScript types
6. Accessibility notes

Rules:
- Mobile-first responsive
- No hardcoded values (use tokens)
- WCAG AA compliance
- Include hover/focus/active states
- Add subtle micro-interactions

---

示例与模板

本技能在 examples/ 中提供了可直接用于生产的示例：

CSS 示例（examples/css/）

tokens.css — 完整的设计 Token 系统

• 语义色彩 Token（浅色 + 深色模式）
• 支持流式缩放的字体排版比例
• 间距、圆角、阴影、动效比例
• 可直接使用的 CSS 自定义属性

components.css — 组件样式库

• 按钮（变体、尺寸、状态）
• 输入框、文本域、下拉选择框
• 卡片、模态框、工具提示
• 导航、页头、页脚
• 加载骨架屏
• 全部包含状态变体（悬停/聚焦/激活/禁用）

utilities.css — 工具类库

• 布局工具类（flex、grid、container）
• 间距工具类（margin、padding）
• 排版工具类（字号、字重、行高）
• 状态工具类（悬停、聚焦、组变体）

TypeScript 示例（examples/typescript/）

design-tokens.ts — 类型安全的 token 定义

• Token 接口与类型
• 设计系统配置
• 主题类型定义
• Token 校验器

theme-provider.tsx — 主题管理系统

• 主题上下文 Provider
• 深色模式切换
• 系统偏好检测
• 主题持久化（localStorage）

sample-components.tsx — 生产级组件示例

• Button 组件（所有变体）
• Input 组件（带校验）
• Card 组件（带加载状态）
• Modal 组件（带焦点管理）
• 全部具备完整的 TypeScript 类型与无障碍支持

模板（templates/）

tailwind-config.js — 优化的 Tailwind 配置

• 自定义调色板
• 排版插件配置
• 间距与尺寸比例
• 插件配置

globals.css — 全局样式模板

• CSS reset/normalize
• Token 定义
• 基础元素样式
• 工具类

---

输出质量标准

每项交付物必须满足：

代码质量

• ✅ 生产就绪（复制粘贴即可部署）
• ✅ TypeScript 完整类型安全
• ✅ 符合 ESLint/Prettier 规范
• ✅ 无硬编码魔法数字
• ✅ DRY（Don't Repeat Yourself）
• ✅ 清晰、描述性的命名
• ✅ 复杂逻辑配有 JSDoc 注释

设计质量

• ✅ 独特、令人印象深刻的审美
• ✅ 一致的 token 使用
• ✅ 协调统一的视觉语言
• ✅ 精心设计的微交互
• ✅ 打磨细节（阴影、过渡、间距）

无障碍质量

• ✅ 至少满足 WCAG AA（优先 AAA）
• ✅ 可键盘导航
• ✅ 对屏幕阅读器友好
• ✅ 焦点管理
• ✅ 语义化 HTML
• ✅ 必要时使用 ARIA

性能质量

• ✅ 优化的打包体积（tree-shaking）
• ✅ 重型组件懒加载
• ✅ 尽可能使用纯 CSS 动画
• ✅ 最小化重渲染（React memo/useMemo）
• ✅ 响应式图片（srcset、sizes）

---

验证清单

交付代码前，请验证：

Token 与系统：

• 所有颜色来自语义化 token（无硬编码 hex/rgb）
• 所有间距来自间距比例（8px 体系）
• 所有圆角来自圆角比例（xs/sm/md/lg/xl/2xl/full）
• 阴影最少且有合理依据
• 排版层级清晰（Display/H1/H2/H3/Body/Small/Caption）
• 行高舒适（正文 1.5+）

状态与交互：

• 已实现默认状态
• 悬停状态（视觉反馈）
• 激活状态（按下外观）
• 聚焦状态（键盘焦点环可见）
• 禁用状态（降低不透明度，无指针）
• 加载状态（骨架屏或加载指示器）
• 空状态（清晰提示 + CTA）
• 错误状态（提示信息 + 恢复方式）

无障碍：

• WCAG AA 对比度（正文 4.5:1，大号文字 3:1）
• 键盘导航完整
• 焦点指示器始终可见
• 使用语义化 HTML
• 在需要处使用 ARIA 标签
• 表单标签已关联
• 图片配有替代文本

响应式设计：

• 移动端布局（375px+）可用
• 平板布局（768px+）优化
• 桌面布局（1024px+）增强
• 触控目标 ≥ 44px
• 文字在所有尺寸下均可读
• 无横向滚动

创意执行：

• 独特审美（非通用风格）
• 符合所述设计方向
• 令人印象深刻的视觉元素
• 协调统一的设计语言
• 打磨细节

代码质量：

• TypeScript 类型完整
• 无 linter 错误
• 遵循 DRY 原则
• 组件边界清晰
• 命名约定一致
• 注释充分
• 生产就绪（可直接部署）

---

进阶技巧

1. 流体排版

/* Responsive type scale using clamp() */
:root {
  --font-size-sm: clamp(0.875rem, 0.8rem + 0.2vw, 1rem);
  --font-size-base: clamp(1rem, 0.9rem + 0.3vw, 1.125rem);
  --font-size-lg: clamp(1.125rem, 1rem + 0.4vw, 1.25rem);
  --font-size-xl: clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);
  --font-size-2xl: clamp(1.5rem, 1.3rem + 0.7vw, 2rem);
  --font-size-3xl: clamp(1.875rem, 1.5rem + 1vw, 2.5rem);
  --font-size-4xl: clamp(2.25rem, 1.8rem + 1.5vw, 3.5rem);
}

2. 高级色彩系统

/* Color with opacity variants using oklch */
:root {
  --primary-base: oklch(60% 0.15 250);
  --primary-subtle: oklch(95% 0.02 250);
  --primary-muted: oklch(85% 0.05 250);
  --primary-emphasis: oklch(50% 0.18 250);
  --primary-foreground: oklch(98% 0.01 250);
}

/* Dark mode: adjust lightness only */
[data-theme="dark"] {
  --primary-base: oklch(70% 0.15 250);
  --primary-subtle: oklch(20% 0.02 250);
  --primary-muted: oklch(30% 0.05 250);
  --primary-emphasis: oklch(80% 0.18 250);
  --primary-foreground: oklch(10% 0.01 250);
}

3. 骨架屏加载模式

// Animated skeleton with shimmer effect
const Skeleton = ({ className }: { className?: string }) => (
  <div
    className={cn(
      "animate-pulse rounded-md bg-surface-subtle",
      "relative overflow-hidden",
      "before:absolute before:inset-0",
      "before:-translate-x-full before:animate-shimmer",
      "before:bg-gradient-to-r before:from-transparent before:via-white/10 before:to-transparent",
      className
    )}
  />
);

// Usage in components
<Card>
  <Skeleton className="h-4 w-3/4 mb-2" />
  <Skeleton className="h-4 w-1/2 mb-4" />
  <Skeleton className="h-32 w-full" />
</Card>

4. 高级动效

/* Page transitions */
@keyframes fade-in {
  from {
    opacity: 0;
    transform: translateY(8px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* Staggered animations */
.stagger-item {
  animation: fade-in 0.3s ease-out backwards;
}
.stagger-item:nth-child(1) { animation-delay: 0ms; }
.stagger-item:nth-child(2) { animation-delay: 50ms; }
.stagger-item:nth-child(3) { animation-delay: 100ms; }
.stagger-item:nth-child(4) { animation-delay: 150ms; }

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

---

卓越实践建议

1. 始终从 token 入手 — 绝不要直接跳到组件
2. 移动优先思维 — 以 375px 为基准设计，再向上增强
3. 尽早验证各种状态 — 单独测试每一个交互状态
4. 大胆追求美学 — 避免千篇一律的模式
5. 无障碍不可妥协 — 从一开始就内置其中
6. 使用真实内容 — 用实际文本、图片、数据来测试
7. 审查自己的作品 — 交付前先自我审核
8. 记录决策 — 解释复杂的样式选择
9. 保持可维护性 — 未来的开发者会感谢你
10. 交付生产级代码 — 交付物中不留 "TODO" 或 "FIXME"

---

参考资料与资源

• Tailwind CSS：https://tailwindcss.com/docs
• shadcn/ui：https://ui.shadcn.com
• WCAG 指南：https://www.w3.org/WAI/WCAG21/quickref/
• 颜色对比度检查器：https://webaim.org/resources/contrastchecker/
• 字号比例：https://typescale.com
• 模块化比例：https://www.modularscale.com
• CSS 自定义属性：https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

---

版本：2.0.0
最后更新：2024 年 12 月
许可证：MIT
维护者：z-ai 平台团队