design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Skill

设计技能

Version: 1.0 Source: Design Standards

Non-negotiable design and user interface standards. These are not preferences—they are requirements.

版本： 1.0 来源： 设计标准

不可协商的设计与用户界面标准。这些不是偏好——而是硬性要求。

Scope and Boundaries

范围与边界

This skill covers:

Design system philosophy and principles
Design token usage and enforcement
Semantic HTML patterns (element selection)
CSS formatting and quality rules
Component states (hover, focus, active, disabled)
Layout philosophy (Grid vs Flexbox selection)
Responsive design principles and breakpoints
Premium UI philosophy and anti-patterns

Defers to other skills:

```
web-accessibility
```
: Deep WCAG compliance, screen reader patterns, ARIA usage, keyboard navigation
```
web-css
```
: CSS architecture, file organization, naming conventions (BEM), dark mode implementation

Use this skill when: You need design principles, token enforcement, or semantic HTML guidance. Use web-accessibility when: You need WCAG compliance, screen reader support, or focus management. Use web-css when: You need CSS organization, variable architecture, or responsive implementation details.

本技能涵盖：

设计系统理念与原则
Design Token的使用与强制执行
语义化HTML模式（元素选择）
CSS格式化与质量规则
组件状态（hover、focus、active、disabled）
布局理念（Grid与Flexbox的选择）
响应式设计原则与断点
高端UI理念与反模式

需参考其他技能：

```
web-accessibility
```
：深入WCAG合规性、屏幕阅读器模式、ARIA使用、键盘导航
```
web-css
```
：CSS架构、文件组织、命名规范（BEM）、暗黑模式实现

适用场景： 当你需要设计原则、Token强制执行或语义化HTML指导时使用本技能。 适用web-accessibility场景： 当你需要WCAG合规、屏幕阅读器支持或焦点管理时。 适用web-css场景： 当你需要CSS组织、变量架构或响应式实现细节时。

Core Principles

核心原则

Users First — Prioritize user needs, workflows, and ease of use
Meticulous Craft — Precision and polish in every UI element
Speed & Performance — Fast load times, snappy interactions
Simplicity & Clarity — Clean interface, unambiguous labels
Focus & Efficiency — Help users achieve goals quickly
Consistency — Uniform design language throughout
Accessibility (WCAG AA) — Inclusive design for all users
Opinionated Defaults — Thoughtful defaults reduce decision fatigue

用户优先 —— 优先考虑用户需求、工作流程与易用性
精心打磨 —— 每个UI元素都追求精准与精致
速度与性能 —— 快速加载、流畅交互
简洁清晰 —— 界面干净、标签明确无歧义
聚焦高效 —— 帮助用户快速达成目标
一致性 —— 全平台统一设计语言
无障碍（WCAG AA） —— 面向所有用户的包容性设计
明确默认值 —— 经过深思熟虑的默认设置减少决策疲劳

Design System (Single Source of Truth)

设计系统（唯一可信来源）

Critical Rules

关键规则

ALWAYS use design tokens — NEVER use hardcoded values
All values come from
styles/global.css
— Single source of truth for CSS variables
No magic numbers — Every color, spacing, size uses a CSS variable

必须使用Design Token —— 绝对禁止使用硬编码值
所有值均来自
styles/global.css
—— CSS变量的唯一可信来源
禁止魔法数字 —— 所有颜色、间距、尺寸均使用CSS变量

Examples

示例

css

/* ✅ Correct - Uses design tokens */
.button {
  padding: var(--space-sm) var(--space-md);
  font-size: var(--font-size-body);
  background: var(--color-primary);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-sm);
}

/* ❌ Wrong - Hardcoded values */
.button {
  padding: 8px 16px;           /* Use var(--space-sm) var(--space-md) */
  font-size: 14px;             /* Use var(--font-size-body) */
  background: #3B82F6;         /* Use var(--color-primary) */
  border-radius: 4px;          /* Use var(--radius-sm) */
}

css

/* ✅ 正确示范 - 使用Design Token */
.button {
  padding: var(--space-sm) var(--space-md);
  font-size: var(--font-size-body);
  background: var(--color-primary);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-sm);
}

/* ❌ 错误示范 - 硬编码值 */
.button {
  padding: 8px 16px;           /* 应使用var(--space-sm) var(--space-md) */
  font-size: 14px;             /* 应使用var(--font-size-body) */
  background: #3B82F6;         /* 应使用var(--color-primary) */
  border-radius: 4px;          /* 应使用var(--radius-sm) */
}

What the Design System Contains

设计系统包含内容

Complete color palette (neutrals, semantic, dark mode)
Full typography scale (fonts, sizes, weights, line heights)
Spacing system (4px base)
Border radii
Shadows
Z-index layers
Animation durations and easings
Icon sizes
Breakpoint values

完整调色板（中性色、语义色、暗黑模式）
完整排版体系（字体、尺寸、字重、行高）
间距系统（4px基准）
圆角半径
阴影效果
Z-index层级
动画时长与缓动函数
图标尺寸
断点值

Semantic HTML

语义化HTML

Required Practices

强制实践

Use semantic tags:

<header>

<nav>

<main>

<article>

<section>

<footer>

Buttons for actions (
```
<button>
```
), links for navigation (
```
<a>
```
)
Forms use
```
<form>
```
,
```
<label>
```
,
```
<input>
```
,
```
<select>
```
,
```
<textarea>
```
Lists use
```
<ul>
```
,
```
<ol>
```
,
```
<li>
```
(not divs with bullets)
Headings follow hierarchy:
```
<h1>
```
→
```
<h2>
```
→
```
<h3>
```
(no skipping)
Images have descriptive
```
alt
```
text
Tables use proper markup for tabular data

使用语义化标签：

<header>

、

<nav>

、

<main>

、

<article>

、

<section>

、

<footer>

按钮用于操作（
```
<button>
```
），链接用于导航（
```
<a>
```
）
表单使用
```
<form>
```
、
```
<label>
```
、
```
<input>
```
、
```
<select>
```
、
```
<textarea>
```
列表使用
```
<ul>
```
、
```
<ol>
```
、
```
<li>
```
（而非带项目符号的div）
标题遵循层级：
```
<h1>
```
→
```
<h2>
```
→
```
<h3>
```
（禁止跳过层级）
图片需包含描述性
```
alt
```
文本
表格使用适用于表格数据的正确标记

Examples

示例

html

<!-- ✅ Good - Semantic HTML -->
<article class="product-card">
  <header>
    <h2>Product Name</h2>
  </header>
  <img src="..." alt="Product description">
  <p>Product description goes here.</p>
  <footer>
    <button type="button">Add to Cart</button>
  </footer>
</article>

<!-- ❌ Bad - Non-semantic divs -->
<div class="prd-crd">
  <div class="hdr">
    <div class="ttl">Product Name</div>
  </div>
  <div class="img"></div>
  <div class="btn">Add to Cart</div>
</div>

html

<!-- ✅ 良好示范 - 语义化HTML -->
<article class="product-card">
  <header>
    <h2>产品名称</h2>
  </header>
  <img src="..." alt="产品描述">
  <p>产品描述内容。</p>
  <footer>
    <button type="button">加入购物车</button>
  </footer>
</article>

<!-- ❌ 不良示范 - 非语义化div -->
<div class="prd-crd">
  <div class="hdr">
    <div class="ttl">产品名称</div>
  </div>
  <div class="img"></div>
  <div class="btn">加入购物车</div>
</div>

HTML Cleanliness

HTML整洁性

Headings Are for Structure

标题用于结构

Headings (

<h1>

<h6>

) define document structure, not visual styling.

html

<!-- ❌ Wrong - Using heading for font size -->
<h3>Sale Price</h3>  <!-- Not a section heading, just wants bold text -->

<!-- ✅ Right - Use a class for styling -->
<p class="price-label">Sale Price</p>

标题（

<h1>

<h6>

）用于定义文档结构，而非视觉样式。

html

<!-- ❌ 错误示范 - 为字体大小使用标题标签 -->
<h3>促销价格</h3>  <!-- 并非章节标题，只是需要粗体文本 -->

<!-- ✅ 正确示范 - 使用类进行样式设置 -->
<p class="price-label">促销价格</p>

No Class Bloat

避免类名冗余

Elements should have 1-3 classes. More than 4 is a smell — consolidate into a semantic class.

html

<!-- ❌ Bad - Class soup -->
<button class="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:ring-2">
  Submit
</button>

<!-- ✅ Good - Semantic class (styling lives in CSS) -->
<button class="btn btn--primary">
  Submit
</button>

元素应包含1-3个类名。超过4个则存在问题——应合并为语义化类名。

html

<!-- ❌ 不良示范 - 类名堆砌 -->
<button class="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:ring-2">
  提交
</button>

<!-- ✅ 良好示范 - 语义化类名（样式定义在CSS中） -->
<button class="btn btn--primary">
  提交
</button>

No Inline Styles

禁止内联样式

HTML describes structure. CSS handles presentation. Keep them separated.

jsx

// ❌ Bad - Inline styles
<div style={{ marginTop: '16px', padding: '8px' }}>

// ✅ Good - CSS class
<div className="card-section">

Only exception: Truly dynamic values computed at runtime. Even then, prefer CSS custom properties.

HTML描述结构，CSS负责表现。保持两者分离。

jsx

// ❌ 不良示范 - 内联样式
<div style={{ marginTop: '16px', padding: '8px' }}>

// ✅ 良好示范 - CSS类名
<div className="card-section">

唯一例外： 运行时计算的真正动态值。即便如此，也优先使用CSS自定义属性。

CSS Quality

CSS质量

Formatting Rules

格式化规则

One property per line
Use design tokens (CSS variables), not hardcoded values
Logical property order: Positioning → Box Model → Typography → Visual → Animation
Descriptive class names (BEM or semantic naming)
Generous spacing between rule sets
Comments for complex sections

每个属性单独一行
使用Design Token（CSS变量），而非硬编码值
逻辑属性顺序：定位 → 盒模型 → 排版 → 视觉 → 动画
描述性类名（BEM或语义化命名）
规则集之间保留充足间距
复杂部分添加注释

Example

示例

css

/* ✅ Good - Human-readable */
.product-card {
  display: flex;
  flex-direction: column;
  gap: var(--space-md);
  padding: var(--space-lg);
  background-color: var(--color-neutral-50);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
}

.product-card:hover {
  box-shadow: var(--shadow-md);
  transform: translateY(-2px);
  transition: all var(--duration-fast) var(--easing-standard);
}

css

/* ✅ 良好示范 - 易于人类阅读 */
.product-card {
  display: flex;
  flex-direction: column;
  gap: var(--space-md);
  padding: var(--space-lg);
  background-color: var(--color-neutral-50);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
}

.product-card:hover {
  box-shadow: var(--shadow-md);
  transform: translateY(-2px);
  transition: all var(--duration-fast) var(--easing-standard);
}

Component States (Required)

组件状态（强制要求）

All interactive components MUST have these five states:

State	Requirement	Example
Default	Base appearance	Normal button
Hover	Visual feedback on mouse over	Background darkens
Active	Visual feedback when pressed	Slight scale down
Focus	Clear focus indicator (keyboard nav)	`outline: 2px solid var(--color-focus); outline-offset: 2px;`
Disabled	Visually distinct, non-interactive	Grayed out, low opacity

所有交互组件必须实现以下五种状态：

状态	要求	示例
默认	基础外观	普通按钮
Hover	鼠标悬停时的视觉反馈	背景加深
Active	按下时的视觉反馈	轻微缩小
Focus	清晰的焦点指示器（键盘导航）	`outline: 2px solid var(--color-focus); outline-offset: 2px;`
Disabled	视觉区分明显，不可交互	灰度化，低透明度

Layout Philosophy

布局理念

CSS Grid vs Flexbox

Layout Need	Tool	Example
Page structure	Grid (named areas)	Header, sidebar, main, footer
Section layout	Grid (named areas)	Two-column content, form layout
Component structure	Grid (named areas)	Card internals, modal layout
Navigation items	Flexbox	Top nav items, menu items
Gallery/flowing items	Flexbox	Image grid, card gallery, tag list

Default to Grid for structure. Use Flexbox when items need to flow, distribute, or wrap.

布局需求	工具	示例
页面结构	Grid（命名区域）	页眉、侧边栏、主内容区、页脚
章节布局	Grid（命名区域）	两栏内容、表单布局
组件结构	Grid（命名区域）	卡片内部结构、模态框布局
导航项	Flexbox	顶部导航项、菜单项
画廊/流式项目	Flexbox	图片网格、卡片画廊、标签列表

默认使用Grid进行结构布局。当项目需要流式排列、分布或换行时，使用Flexbox。

Grid with Named Areas (Primary Layout Method)

带命名区域的Grid（主要布局方法）

css

#app-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  gap: var(--space-md);
}

#header { grid-area: header; }
#sidebar { grid-area: sidebar; }
#main { grid-area: main; }
#footer { grid-area: footer; }

css

#app-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  gap: var(--space-md);
}

#header { grid-area: header; }
#sidebar { grid-area: sidebar; }
#main { grid-area: main; }
#footer { grid-area: footer; }

White Space

留白

Use ample negative space to improve clarity
Consistent spacing using design tokens

使用充足的负空间提升清晰度
使用Design Token保持间距一致性

Accessibility (WCAG AA)

无障碍（WCAG AA）

Required Standards

强制标准

Color Contrast
- Normal text: 4.5:1 minimum
- Large text (18px+): 3:1 minimum
Keyboard Navigation
- All functionality available via keyboard
- Logical tab order
- Focus indicators visible
Screen Reader Support
- Proper ARIA labels
- Semantic HTML
- Skip links for navigation
Form Labels
- All inputs have associated labels
- Error messages linked to inputs

颜色对比度
- 普通文本：最低4.5:1
- 大文本（18px及以上）：最低3:1
键盘导航
- 所有功能均可通过键盘访问
- 合理的Tab顺序
- 焦点指示器可见
屏幕阅读器支持
- 正确的ARIA标签
- 语义化HTML
- 导航跳转链接
表单标签
- 所有输入框均关联标签
- 错误信息与输入框关联

Respect User Preferences

尊重用户偏好

css

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

css

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Responsive Design

响应式设计

Mobile-First Breakpoints

移动端优先断点

css

/* Mobile: 0-767px (base styles, no media query needed) */

/* Tablet: 768px and up */
@media (min-width: 768px) { }

/* Desktop: 1024px and up */
@media (min-width: 1024px) { }

/* Large Desktop: 1280px and up */
@media (min-width: 1280px) { }

Never use:

@media (max-width: ...)

— Always use min-width (mobile-first)

css

/* 移动端：0-767px（基础样式，无需媒体查询） */

/* 平板：768px及以上 */
@media (min-width: 768px) { }

/* 桌面端：1024px及以上 */
@media (min-width: 1024px) { }

/* 大桌面端：1280px及以上 */
@media (min-width: 1280px) { }

禁止使用：

@media (max-width: ...)

—— 始终使用min-width（移动端优先）

Container max-widths

容器最大宽度

Mobile: 100% (with padding)
Tablet: 768px
Desktop: 1024px
Large: 1280px

移动端：100%（带内边距）
平板：768px
桌面端：1024px
大桌面端：1280px

Premium UI Philosophy

高端UI理念

We follow S-Tier SaaS standards (Stripe, Airbnb, Linear):

Sophisticated typography with perfect spacing
Premium color palettes with subtle gradients
Purposeful animations (150-300ms)
Delightful micro-interactions
Meticulous attention to detail

Goal: Make every interface feel premium. Subtle sophistication over flashy effects.

我们遵循S级SaaS标准（Stripe、Airbnb、Linear）：

精致的排版与完美的间距
高端调色板与微妙渐变
有意义的动画（150-300ms）
愉悦的微交互
对细节的极致关注

目标： 让每个界面都显得高端。优先选择微妙的精致感，而非花哨的效果。

Anti-Patterns (DO NOT DO THESE)

反模式（禁止操作）

Anti-Pattern	Why Bad	Do Instead
Floating labels	Confusing	Labels above inputs
Inline validation	Annoying	Validate on blur/submit
Generic error messages	Unhelpful	Specific, actionable errors
Tooltips for critical info	Easy to miss	Show directly
Disabled buttons without explanation	Frustrating	Show why disabled
Custom scrollbars	Inconsistent UX	System scrollbars
Hamburger menu on desktop	Hides navigation	Full nav on desktop

反模式	危害	正确做法
浮动标签	易混淆	标签置于输入框上方
实时内联验证	烦人	在失焦/提交时验证
通用错误提示	无帮助	具体、可操作的错误信息
关键信息使用工具提示	易被忽略	直接显示信息
无说明的禁用按钮	令人沮丧	显示禁用原因
自定义滚动条	用户体验不一致	使用系统滚动条
桌面端使用汉堡菜单	隐藏导航	桌面端显示完整导航

design

Original

Translation

Design Skill

设计技能

Scope and Boundaries

范围与边界

Core Principles

核心原则

Design System (Single Source of Truth)

设计系统（唯一可信来源）

Critical Rules

关键规则

Examples

示例

What the Design System Contains

设计系统包含内容

Semantic HTML

语义化HTML

Required Practices

强制实践

Examples

示例

HTML Cleanliness

HTML整洁性

Headings Are for Structure

标题用于结构

No Class Bloat

避免类名冗余

No Inline Styles

禁止内联样式

CSS Quality

CSS质量

Formatting Rules

格式化规则

Example

示例

Component States (Required)

组件状态（强制要求）

Layout Philosophy

布局理念

CSS Grid vs Flexbox

CSS Grid vs Flexbox

Grid with Named Areas (Primary Layout Method)

带命名区域的Grid（主要布局方法）

White Space

留白

Accessibility (WCAG AA)

无障碍（WCAG AA）

Required Standards

强制标准

Respect User Preferences

尊重用户偏好

Responsive Design

响应式设计

Mobile-First Breakpoints

移动端优先断点

Container max-widths

容器最大宽度

Premium UI Philosophy

高端UI理念

Anti-Patterns (DO NOT DO THESE)

反模式（禁止操作）

Quick Reference Checklist

快速参考检查表

Design System

设计系统

Semantic HTML

语义化HTML

CSS

CSS

Component States

组件状态

Accessibility

无障碍

Responsive

响应式

Anti-Patterns Avoided

已避免反模式

References