Back to Details

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

核心原则

  1. Users First — Prioritize user needs, workflows, and ease of use
  2. Meticulous Craft — Precision and polish in every UI element
  3. Speed & Performance — Fast load times, snappy interactions
  4. Simplicity & Clarity — Clean interface, unambiguous labels
  5. Focus & Efficiency — Help users achieve goals quickly
  6. Consistency — Uniform design language throughout
  7. Accessibility (WCAG AA) — Inclusive design for all users
  8. Opinionated Defaults — Thoughtful defaults reduce decision fatigue
  1. 用户优先 —— 优先考虑用户需求、工作流程与易用性
  2. 精心打磨 —— 每个UI元素都追求精准与精致
  3. 速度与性能 —— 快速加载、流畅交互
  4. 简洁清晰 —— 界面干净、标签明确无歧义
  5. 聚焦高效 —— 帮助用户快速达成目标
  6. 一致性 —— 全平台统一设计语言
  7. 无障碍（WCAG AA） —— 面向所有用户的包容性设计
  8. 明确默认值 —— 经过深思熟虑的默认设置减少决策疲劳

Design System (Single Source of Truth)

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

Critical Rules

关键规则

  1. ALWAYS use design tokens — NEVER use hardcoded values
  2. All values come from 
    styles/global.css
     — Single source of truth for CSS variables
  3. No magic numbers — Every color, spacing, size uses a CSS variable
  1. 必须使用Design Token —— 绝对禁止使用硬编码值
  2. 所有值均来自
    styles/global.css
     —— CSS变量的唯一可信来源
  3. 禁止魔法数字 —— 所有颜色、间距、尺寸均使用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

强制实践

  1. Use semantic tags: 
    <header>
    , 
    <nav>
    , 
    <main>
    , 
    <article>
    , 
    <section>
    , 
    <footer>
  2. Buttons for actions (
    <button>
    ), links for navigation (
    <a>
    )
  3. Forms use 
    <form>
    , 
    <label>
    , 
    <input>
    , 
    <select>
    , 
    <textarea>
  4. Lists use 
    <ul>
    , 
    <ol>
    , 
    <li>
    (not divs with bullets)
  5. Headings follow hierarchy: 
    <h1>
    → 
    <h2>
    → 
    <h3>
    (no skipping)
  6. Images have descriptive 
    alt
    text
  7. Tables use proper markup for tabular data
  1. 使用语义化标签：
    <header>
    、
    <nav>
    、
    <main>
    、
    <article>
    、
    <section>
    、
    <footer>
  2. 按钮用于操作（
    <button>
    ），链接用于导航（
    <a>
    ）
  3. 表单使用
    <form>
    、
    <label>
    、
    <input>
    、
    <select>
    、
    <textarea>
  4. 列表使用
    <ul>
    、
    <ol>
    、
    <li>
    （而非带项目符号的div）
  5. 标题遵循层级：
    <h1>
    → 
    <h2>
    → 
    <h3>
    （禁止跳过层级）
  6. 图片需包含描述性
    alt
    文本
  7. 表格使用适用于表格数据的正确标记

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

格式化规则

  1. One property per line
  2. Use design tokens (CSS variables), not hardcoded values
  3. Logical property order: Positioning → Box Model → Typography → Visual → Animation
  4. Descriptive class names (BEM or semantic naming)
  5. Generous spacing between rule sets
  6. Comments for complex sections
  1. 每个属性单独一行
  2. 使用Design Token（CSS变量），而非硬编码值
  3. 逻辑属性顺序：定位 → 盒模型 → 排版 → 视觉 → 动画
  4. 描述性类名（BEM或语义化命名）
  5. 规则集之间保留充足间距
  6. 复杂部分添加注释

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:
StateRequirementExample
DefaultBase appearanceNormal button
HoverVisual feedback on mouse overBackground darkens
ActiveVisual feedback when pressedSlight scale down
FocusClear focus indicator (keyboard nav)
outline: 2px solid var(--color-focus); outline-offset: 2px;
DisabledVisually distinct, non-interactiveGrayed out, low opacity
所有交互组件必须实现以下五种状态：
状态要求示例
默认基础外观普通按钮
Hover鼠标悬停时的视觉反馈背景加深
Active按下时的视觉反馈轻微缩小
Focus清晰的焦点指示器（键盘导航）
outline: 2px solid var(--color-focus); outline-offset: 2px;
Disabled视觉区分明显，不可交互灰度化，低透明度

Layout Philosophy

布局理念

CSS Grid vs Flexbox

CSS Grid vs Flexbox

Layout NeedToolExample
Page structureGrid (named areas)Header, sidebar, main, footer
Section layoutGrid (named areas)Two-column content, form layout
Component structureGrid (named areas)Card internals, modal layout
Navigation itemsFlexboxTop nav items, menu items
Gallery/flowing itemsFlexboxImage 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

强制标准

  1. Color Contrast
    • Normal text: 4.5:1 minimum
    • Large text (18px+): 3:1 minimum
  2. Keyboard Navigation
    • All functionality available via keyboard
    • Logical tab order
    • Focus indicators visible
  3. Screen Reader Support
    • Proper ARIA labels
    • Semantic HTML
    • Skip links for navigation
  4. Form Labels
    • All inputs have associated labels
    • Error messages linked to inputs
  1. 颜色对比度
    • 普通文本：最低4.5:1
    • 大文本（18px及以上）：最低3:1
  2. 键盘导航
    • 所有功能均可通过键盘访问
    • 合理的Tab顺序
    • 焦点指示器可见
  3. 屏幕阅读器支持
    • 正确的ARIA标签
    • 语义化HTML
    • 导航跳转链接
  4. 表单标签
    • 所有输入框均关联标签
    • 错误信息与输入框关联

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-PatternWhy BadDo Instead
Floating labelsConfusingLabels above inputs
Inline validationAnnoyingValidate on blur/submit
Generic error messagesUnhelpfulSpecific, actionable errors
Tooltips for critical infoEasy to missShow directly
Disabled buttons without explanationFrustratingShow why disabled
Custom scrollbarsInconsistent UXSystem scrollbars
Hamburger menu on desktopHides navigationFull nav on desktop
反模式危害正确做法
浮动标签易混淆标签置于输入框上方
实时内联验证烦人在失焦/提交时验证
通用错误提示无帮助具体、可操作的错误信息
关键信息使用工具提示易被忽略直接显示信息
无说明的禁用按钮令人沮丧显示禁用原因
自定义滚动条用户体验不一致使用系统滚动条
桌面端使用汉堡菜单隐藏导航桌面端显示完整导航

Quick Reference Checklist

快速参考检查表

Design System

设计系统

  • ALL values use design tokens
  • No magic numbers or hardcoded colors
  • Design system is source of truth
  • 所有值均使用Design Token
  • 无魔法数字或硬编码颜色
  • 设计系统为唯一可信来源

Semantic HTML

语义化HTML

  • Semantic tags used appropriately
  • Buttons for actions, links for navigation
  • Heading hierarchy followed
  • Alt text on all images
  • 语义化标签使用恰当
  • 按钮用于操作，链接用于导航
  • 标题层级遵循规范
  • 所有图片均有alt文本

CSS

CSS

  • Human-readable formatting
  • Design tokens used throughout
  • Logical property order
  • 格式易于人类阅读
  • 全程使用Design Token
  • 属性顺序符合逻辑

Component States

组件状态

  • Default state implemented
  • Hover state implemented
  • Active state implemented
  • Focus state implemented
  • Disabled state implemented
  • 已实现默认状态
  • 已实现Hover状态
  • 已实现Active状态
  • 已实现Focus状态
  • 已实现Disabled状态

Accessibility

无障碍

  • Color contrast meets WCAG AA
  • Keyboard navigation works
  • Screen reader tested
  • Focus indicators visible
  • Form labels present
  • 颜色对比度符合WCAG AA标准
  • 键盘导航正常工作
  • 已测试屏幕阅读器支持
  • 焦点指示器可见
  • 表单标签存在

Responsive

响应式

  • Mobile-first approach
  • Standard breakpoints used
  • Works on all screen sizes
  • 采用移动端优先方法
  • 使用标准断点
  • 在所有屏幕尺寸下正常工作

Anti-Patterns Avoided

已避免反模式

  • No floating labels
  • No inline validation
  • No generic errors
  • No tooltips for critical info
  • No unexplained disabled buttons
  • No custom scrollbars
  • No hamburger on desktop
  • 无浮动标签
  • 无实时内联验证
  • 无通用错误提示
  • 无关键信息使用工具提示
  • 无未说明的禁用按钮
  • 无自定义滚动条
  • 桌面端无汉堡菜单

References

参考资料

  • references/semantic-html.md
    — Complete semantic HTML guide
  • references/css-formatting.md
    — CSS best practices
  • references/accessibility-guide.md
    — WCAG AA compliance
  • references/responsive-breakpoints.md
    — Responsive design patterns
  • references/semantic-html.md
    —— 完整语义化HTML指南
  • references/css-formatting.md
    —— CSS最佳实践
  • references/accessibility-guide.md
    —— WCAG AA合规指南
  • references/responsive-breakpoints.md
    —— 响应式设计模式

Assets

资源

  • assets/component-states-checklist.md
    — State implementation guide
  • assets/anti-patterns.md
    — Detailed anti-pattern explanations
  • assets/layout-examples.md
    — CSS Grid and Flexbox examples
  • assets/component-states-checklist.md
    —— 状态实现指南
  • assets/anti-patterns.md
    —— 反模式详细说明
  • assets/layout-examples.md
    —— CSS Grid与Flexbox示例

Scripts

脚本

  • scripts/validate_design_tokens.py
    — Check for hardcoded values
  • scripts/check_accessibility.py
    — Basic a11y validation
  • scripts/validate_design_tokens.py
    —— 检查硬编码值
  • scripts/check_accessibility.py
    —— 基础无障碍验证