Back to Details

frontend-ui-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Frontend UI Design

前端UI设计

Overview

概述

Guide the design and implementation of frontend user interfaces with consistent architecture, accessibility, responsive behavior, and performance. This skill covers component patterns, design system integration, state management selection, and WCAG compliance — producing components that are testable, accessible, and performant.
Announce at start: "I'm using the frontend-ui-design skill to design the UI."
指导前端用户界面的设计与实现，确保架构统一、可访问性达标、响应式表现正常且性能优异。本技能覆盖组件模式、设计系统集成、状态管理选型以及WCAG合规要求，能够产出可测试、可访问且高性能的组件。
开头告知： "我正在使用frontend-ui-design技能进行UI设计。"

Phase 1: Discovery

阶段1：需求调研

Ask these questions to understand the UI requirements:
#QuestionWhat It Determines
1What component or page are we building?Scope and complexity
2What framework/library? (React, Vue, Svelte, etc.)Code patterns
3Is there an existing design system or component library?Constraints
4What devices must be supported? (mobile, tablet, desktop)Responsive strategy
5Accessibility requirements? (WCAG level)A11y standards
6What data does this component need?State management approach
STOP after discovery — present a summary of constraints and approach before designing.
询问以下问题明确UI需求：
#问题作用
1我们要构建什么组件或页面？明确范围和复杂度
2使用什么框架/库？(React, Vue, Svelte等)确定代码模式
3是否有现成的设计系统或组件库？明确约束条件
4需要支持哪些设备？(移动端、平板、桌面端)确定响应式策略
5可访问性要求是什么？(WCAG等级)明确A11y标准
6该组件需要什么数据？确定状态管理方案
调研完成后停止——设计前先输出约束条件和实现方案的总结。

Phase 2: Component Architecture Selection

阶段2：组件架构选型

Architecture Pattern Decision Table

架构模式决策表

PatternWhen to UseWhen NOT to Use
Atomic DesignBuilding a component library from scratchAdding one component to existing system
Compound ComponentsMulti-part component needing layout flexibilitySimple single-purpose component
Hooks PatternSame logic reused across different UIsLogic tied to one specific component
Container/PresenterComponents need isolated testing or multiple data sourcesSimple components with minimal logic
模式适用场景不适用场景
原子设计（Atomic Design）从零搭建组件库向现有系统新增单个组件
复合组件（Compound Components）需要布局灵活性的多部分组件简单的单用途组件
Hooks模式不同UI之间需要复用相同逻辑逻辑仅和某个特定组件绑定
容器/展示层分离组件需要隔离测试或对接多个数据源逻辑极少的简单组件

Atomic Design Levels

原子设计层级

LevelDescriptionExamples
AtomsSmallest building blocks, single purposeButton, Input, Label, Icon
MoleculesGroups of atoms functioning togetherSearchBar (Input + Button), FormField (Label + Input + Error)
OrganismsComplex sections composed of moleculesHeader (Logo + Nav + SearchBar), ProductCard
TemplatesPage layouts with placeholder contentDashboardLayout, AuthLayout
PagesTemplates populated with real dataHomePage, SettingsPage
层级描述示例
原子（Atoms）最小的构建块，仅具备单一功能按钮、输入框、标签、图标
分子（Molecules）多个原子组合共同实现功能搜索栏（输入框 + 按钮）、表单项（标签 + 输入框 + 错误提示）
有机体（Organisms）由分子组成的复杂区块页头（Logo + 导航 + 搜索栏）、商品卡片
模板（Templates）带占位内容的页面布局仪表盘布局、认证页布局
页面（Pages）填充了真实数据的模板首页、设置页

Compound Components Example

复合组件示例

tsx
<Select value={selected} onChange={setSelected}>
  <Select.Trigger />
  <Select.Options>
    <Select.Option value="a">Option A</Select.Option>
    <Select.Option value="b">Option B</Select.Option>
  </Select.Options>
</Select>
Use when: a component has multiple sub-parts that must coordinate but consumers need layout flexibility.
tsx
<Select value={selected} onChange={setSelected}>
  <Select.Trigger />
  <Select.Options>
    <Select.Option value="a">Option A</Select.Option>
    <Select.Option value="b">Option B</Select.Option>
  </Select.Options>
</Select>
适用场景：组件包含多个需要协同的子部分，同时使用者需要灵活控制布局。

Hooks Pattern Example

Hooks模式示例

tsx
function useDialog() {
  const [isOpen, setIsOpen] = useState(false);
  const open = () => setIsOpen(true);
  const close = () => setIsOpen(false);
  return { isOpen, open, close };
}
Use when: the same logic is needed across multiple components with different UI.
STOP after architecture selection — confirm the pattern choice before proceeding.
tsx
function useDialog() {
  const [isOpen, setIsOpen] = useState(false);
  const open = () => setIsOpen(true);
  const close = () => setIsOpen(false);
  return { isOpen, open, close };
}
适用场景：多个UI不同的组件需要使用相同的逻辑。
架构选型完成后停止——继续推进前先确认模式选择。

Phase 3: Responsive Design

阶段3：响应式设计

Mobile-First Breakpoints

移动端优先断点

BreakpointTargetMin-Width
smMobile landscape640px
mdTablet768px
lgDesktop1024px
xlLarge desktop1280px
2xlWide desktop1536px
断点标识适配目标最小宽度
sm横屏移动端640px
md平板768px
lg桌面端1024px
xl大屏桌面端1280px
2xl宽屏桌面端1536px

Responsive Strategy Decision Table

响应式策略决策表

NeedUseNot
Layout changes based on viewport sizeMedia queriesContainer queries
Component adapts to parent container sizeContainer queriesMedia queries
Text scales smoothly between breakpoints
clamp()
fluid typography		Fixed font sizes
Images adapt to viewport
srcset
+ 
sizes
Single fixed image
需求使用不使用
布局随视口尺寸变化媒体查询容器查询
组件适配父容器尺寸容器查询媒体查询
文本在断点之间平滑缩放
clamp()
流式排版		固定字体大小
图片适配视口
srcset
+ 
sizes
单张固定尺寸图片

Fluid Typography

流式排版示例

css
font-size: clamp(1rem, 0.5rem + 1.5vw, 1.5rem);
css
font-size: clamp(1rem, 0.5rem + 1.5vw, 1.5rem);

Phase 4: Accessibility (WCAG 2.1 AA)

阶段4：可访问性（WCAG 2.1 AA）

Semantic HTML Decision Table

语义化HTML决策表

NeedUseNOT
Navigation
<nav>
<div class="nav">
Button action
<button>
<div onClick>
Page sections
<main>
, 
<section>
, 
<aside>
<div>
Headings
<h1>
-
<h6>
in order
<div class="heading">
List of items
<ul>
, 
<ol>
Nested 
<div>
s
Form labels
<label for="...">
Placeholder text only
需求使用不使用
导航模块
<nav>
<div class="nav">
按钮操作
<button>
<div onClick>
页面区块
<main>
、
<section>
、
<aside>
<div>
标题按顺序使用
<h1>
-
<h6>
<div class="heading">
项目列表
<ul>
、
<ol>
嵌套
<div>
表单标签
<label for="...">
仅使用占位符文本

ARIA Usage Rules

ARIA使用规则

RuleWhen
Use semantic HTML firstAlways — ARIA is a fallback
aria-label
Labels for elements without visible text
aria-describedby
Associates descriptive text with an element
aria-live
Announces dynamic content changes
aria-expanded
Toggleable sections (accordions, menus)
role
Only when no semantic element exists
规则适用场景
优先使用语义化HTML所有场景——ARIA是降级方案
aria-label
没有可见文本的元素的标签
aria-describedby
为元素关联描述性文本
aria-live
播报动态内容变更
aria-expanded
可切换的区块（手风琴、菜单）
role
仅当没有对应语义元素时使用

Keyboard Navigation Requirements

键盘导航要求

  • All interactive elements focusable (naturally or 
    tabindex="0"
    )
  • Operable via keyboard (Enter, Space, Escape, Arrow keys)
  • Visible focus indicator (never 
    outline: none
    without replacement)
  • Logical tab order matching visual order
  • Focus traps for modals and dialogs
  • 所有可交互元素可聚焦（原生支持或设置
    tabindex="0"
    ）
  • 可通过键盘操作（Enter、Space、Escape、方向键）
  • 可见的聚焦指示器（不要仅设置
    outline: none
    而没有替代样式）
  • 逻辑Tab顺序和视觉顺序一致
  • 模态框和弹窗需要设置焦点陷阱

Color Contrast Requirements

颜色对比度要求

ElementMinimum Ratio
Normal text4.5:1
Large text (18px+ or 14px+ bold)3:1
UI components3:1 against adjacent colors
Information conveyed by colorMust also use icons, patterns, or text
元素最低对比度
普通文本4.5:1
大文本（18px+ 或14px+加粗）3:1
UI组件和相邻颜色对比度3:1
通过颜色传递的信息必须同时搭配图标、图案或文本说明

Screen Reader Testing

屏幕阅读器测试

Test with at least one screen reader:
  • macOS: VoiceOver (built-in)
  • Windows: NVDA (free) or JAWS
  • Verify: content announced in logical order, form errors associated with inputs, dynamic updates announced
至少使用一款屏幕阅读器测试：
  • macOS：VoiceOver（系统自带）
  • Windows：NVDA（免费）或JAWS
  • 验证：内容按逻辑顺序播报、表单错误和输入框关联、动态更新可被播报

Phase 5: State Management & Performance

阶段5：状态管理与性能

State Management Decision Table

状态管理决策表

State TypeSolutionWhen
Local
useState
, 
useReducer
State used by one component or direct children
SharedContext, Zustand, JotaiState shared across multiple unrelated components
ServerTanStack Query, SWRData fetched from API, needs caching/revalidation
FormReact Hook Form, FormikComplex forms with validation and submission
URLSearch params, router stateState that should be bookmarkable/shareable
状态类型方案适用场景
本地状态
useState
、
useReducer
仅单个组件或其直接子组件使用的状态
共享状态Context、Zustand、Jotai多个不相关组件之间共享的状态
服务端状态TanStack Query、SWR从API获取、需要缓存/重新验证的数据
表单状态React Hook Form、Formik带校验和提交逻辑的复杂表单
URL状态搜索参数、路由状态需要可收藏/可分享的状态

Selection Heuristic

选型启发规则

  1. Start with 
    useState
    — only escalate when you hit a real limitation
  2. If prop drilling exceeds 2 levels, consider Context or state library
  3. If caching API responses, use a server state library (not Redux for server state)
  4. For forms with >3 fields and validation, use a form library
  1. 优先使用
    useState
    ——仅当遇到实际限制时再升级方案
  2. 如果属性透传超过2层，考虑使用Context或状态库
  3. 如果需要缓存API响应，使用服务端状态库（不要用Redux处理服务端状态）
  4. 字段数>3且带校验的表单，使用表单库

Performance Optimization Checklist

性能优化检查清单

TechniqueWhen to Apply
React.lazy()
+ 
Suspense
Route-level code splitting
loading="lazy"
on images		Below-the-fold images
VirtualizationLists with >50 items
useMemo
Expensive computations
useCallback
Callbacks passed to memoized children
Dynamic 
import()
Conditionally loaded heavy libraries
WebP/AVIF imagesAll image assets
Explicit 
width
/
height
on images		Prevent layout shift
技术适用场景
React.lazy()
+ 
Suspense
路由级别代码分割
图片添加
loading="lazy"
首屏之外的图片
虚拟滚动列表项超过50条的列表
useMemo
计算成本高的运算
useCallback
传递给 memo 化子组件的回调函数
动态
import()
条件加载的重型库
WebP/AVIF格式图片所有图片资源
图片显式设置
width
/
height
避免布局偏移

Design System Integration

设计系统集成

Design Tokens — define foundational values, not hard-coded:
ts
const tokens = {
  color: { primary: '#2563eb', secondary: '#64748b', error: '#dc2626' },
  spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2rem' },
  typography: { fontFamily: { sans: 'Inter, system-ui, sans-serif' } },
};
Component Variants — consistent variant API:
tsx
<Button variant="primary" size="md">Save</Button>
<Button variant="outline" size="sm">Cancel</Button>
Theme Support:
  • CSS custom properties for runtime theme switching
  • Support light + dark themes at minimum
  • Respect 
    prefers-color-scheme
    as default
  • Allow user override stored in localStorage
STOP after design — present the full component specification for review.
设计令牌（Design Tokens）——定义基础值，不要硬编码：
ts
const tokens = {
  color: { primary: '#2563eb', secondary: '#64748b', error: '#dc2626' },
  spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2rem' },
  typography: { fontFamily: { sans: 'Inter, system-ui, sans-serif' } },
};
组件变体——统一的变体API：
tsx
<Button variant="primary" size="md">Save</Button>
<Button variant="outline" size="sm">Cancel</Button>
主题支持：
  • 使用CSS自定义属性实现运行时主题切换
  • 最少支持浅色+深色主题
  • 默认尊重
    prefers-color-scheme
    系统设置
  • 允许用户覆盖偏好并存储在localStorage
设计完成后停止——输出完整的组件规格说明供评审。

Anti-Patterns / Common Mistakes

反模式/常见错误

MistakeWhy It Is WrongWhat To Do Instead
<div onClick>
instead of 
<button>
Not keyboard accessible, no screen reader semanticsUse semantic HTML elements
outline: none
without replacement		Keyboard users cannot see focusReplace with visible focus style
Fixed font sizes (px)Cannot scale with user preferencesUse 
rem
and 
clamp()
Prop drilling through 4+ levelsMaintenance nightmareUse Context or state library
Fetching in useEffect + useStateNo caching, no dedup, race conditionsUse TanStack Query or SWR
Premature memoizationAdds complexity without measured benefitProfile first, optimize measured bottlenecks
Desktop-first responsive designMobile experience is an afterthoughtStart mobile-first, add complexity up
Color as sole information carrierInaccessible to colorblind usersAdd icons, patterns, or text labels
No loading/error statesUsers see blank screens or cryptic errorsDesign loading, error, and empty states
错误问题正确做法
用
<div onClick>
代替
<button>
不支持键盘访问，没有屏幕阅读器语义使用语义化HTML元素
仅设置
outline: none
无替代样式		键盘用户看不到聚焦状态替换为可见的聚焦样式
固定字体大小（px单位）无法跟随用户偏好缩放使用
rem
和
clamp()
4层以上的属性透传维护成本极高使用Context或状态库
在useEffect + useState中发起请求无缓存、无去重、存在竞态条件使用TanStack Query或SWR
过早 memo 化无明确收益的情况下增加复杂度先 profiling，再优化可测量的瓶颈
桌面端优先的响应式设计移动端体验被后置考虑从移动端优先开始，逐步向上增加复杂度
仅用颜色传递信息色盲用户无法识别增加图标、图案或文本标签
缺少加载/错误状态用户看到空白屏或晦涩的错误提示设计加载、错误和空状态

Anti-Rationalization Guards

反不合理要求规则

  • Do NOT skip accessibility — WCAG 2.1 AA is the minimum, not optional
  • Do NOT use 
    <div>
    with onClick instead of semantic elements
  • Do NOT skip keyboard navigation testing
  • Do NOT choose state management before understanding the actual need
  • Do NOT skip the discovery phase — understand constraints first
  • Do NOT optimize performance without measuring first
  • 禁止跳过可访问性要求——WCAG 2.1 AA是最低要求，不是可选项
  • 禁止使用带onClick的
    <div>
    代替语义化元素
  • 禁止跳过键盘导航测试
  • 禁止在了解实际需求前选择状态管理方案
  • 禁止跳过调研阶段——先明确约束条件
  • 禁止没有测量就提前优化性能

Integration Points

集成点

SkillRelationship
api-design
Upstream: API response shapes inform component data needs
spec-writing
Upstream: specs define component behavioral requirements
planning
Downstream: component designs become implementation tasks
test-driven-development
Downstream: component spec drives test-first implementation
senior-frontend
Parallel: specialist knowledge for React/Next.js specifics
ui-ux-pro-max
Upstream: UX design informs component requirements
ui-design-system
Parallel: design system tokens feed component styling
performance-optimization
Downstream: profile and optimize after implementation
技能关系
api-design
上游：API响应结构决定组件数据需求
spec-writing
上游：规格说明定义组件行为要求
planning
下游：组件设计转化为开发任务
test-driven-development
下游：组件规格驱动测试先行的开发
senior-frontend
并行：React/Next.js专项知识支持
ui-ux-pro-max
上游：UX设计决定组件需求
ui-design-system
并行：设计系统令牌支撑组件样式
performance-optimization
下游：开发完成后进行 profiling 和优化

Verification Gate

验证关口

Before claiming the UI design is complete:
  1. VERIFY component architecture pattern is explicitly chosen with rationale
  2. VERIFY responsive behavior is defined for all target breakpoints
  3. VERIFY accessibility requirements are specified (WCAG level, keyboard, color contrast)
  4. VERIFY state management approach is selected based on actual needs
  5. VERIFY loading, error, and empty states are designed
  6. VERIFY the user has approved the component specification
在声明UI设计完成前：
  1. 确认已明确选择组件架构模式并给出选型理由
  2. 确认已定义所有目标断点的响应式表现
  3. 确认已明确可访问性要求（WCAG等级、键盘导航、颜色对比度）
  4. 确认已基于实际需求选择状态管理方案
  5. 确认已设计加载、错误和空状态
  6. 确认用户已批准组件规格说明

Skill Type

技能类型

Flexible — Adapt component patterns, responsive strategy, and state management to project framework and constraints while preserving accessibility requirements and the discovery-first approach.
灵活适配——根据项目框架和约束调整组件模式、响应式策略和状态管理方案，同时保留可访问性要求和调研优先的工作流程。