design-systems

设计系统最佳实践

创建和维护设计系统的指南，确保数字产品在视觉上保持一致、符合无障碍要求，并具备可扩展的组件架构。

工作流：搭建设计系统

1. 审查现有 UI — 梳理产品中现有的组件、颜色、字体排版和间距，找出不一致之处与可复用模式。
2. 定义设计令牌 — 将基础令牌（颜色、间距、字体排版、阴影）设为 CSS 自定义属性，或采用令牌格式（例如 Style Dictionary），作为唯一可信来源。
3. 构建基础组件 — 创建使用设计令牌的原子组件（Button、Input、Text、Icon），并通过 TypeScript 类型提供清晰的 props API。
4. 组合模式与布局 — 将原子组件组合为更高层级的模式（表单、卡片、导航），并提供有文档说明的使用指南。
5. 设置文档和 Storybook — 配置 Storybook，为每个组件变体、状态和无障碍标注编写 stories。将其发布为持续更新的样式指南。
6. 整合测试与治理 — 添加视觉回归测试（例如 Chromatic）、无障碍 lint 检查（例如 axe-core），并为新组件建立贡献和评审流程。
7. 发布并迭代 — 将组件库发布为带版本号的包，收集使用方反馈，并定期开展无障碍和性能审查。

基础要素

配色系统

• 定义主色、次色和强调色
• 为成功、警告、错误和信息状态设置语义颜色
• 确保所有颜色组合都符合 WCAG 对比度要求
• 编写颜色使用指南并说明适用场景
• 提供浅色和深色模式变体

字体排版

• 建立比例一致的字号阶梯
• 为标题和正文定义字体系列
• 制定行高和字间距标准
• 记录字重及其使用方式
• 确保在各种屏幕尺寸下都具有良好的可读性

间距系统

• 定义统一的间距阶梯（4px、8px、16px、24px 等）
• 为常见模式创建布局基础元素
• 编写外边距和内边距规范
• 确保间距能够适应不同屏幕尺寸
• 使用 CSS 自定义属性，便于维护

图标与图像

• 保持图标风格和尺寸一致
• 定义图标网格和描边粗细
• 编写图标命名规范
• 优化资源，提升 Web 性能
• 在需要时提供多种格式（SVG、PNG）

组件架构

组件结构

• 创建原子化、可复用的组件
• 定义清晰的组件 API（props/attributes）
• 编写变体和状态文档
• 确保组件默认具备无障碍特性
• 制定清晰的命名规范

组件状态

• 默认状态
• 悬停状态
• 焦点状态（键盘导航）
• 激活/按下状态
• 禁用状态
• 加载状态
• 错误状态

组件变体

• 尺寸变体（小、中、大）
• 颜色/主题变体
• 布局变体
• 情境变体

无障碍要求

• 至少遵循 WCAG 2.1 AA 指南
• 使用语义化 HTML 元素
• 在需要时提供 ARIA 标签
• 确保支持键盘导航
• 使用屏幕阅读器进行测试
• 保持颜色对比度
• 支持减少动态效果偏好

文档规范

组件文档

• 用途和使用场景
• Props/API 参考
• 代码示例
• 应做事项和禁忌事项
• 无障碍说明
• 相关组件

模式文档

• 适用场景
• 结构拆解
• 行为规范
• 响应式设计注意事项
• 边界情况

实施指南

CSS 架构

• 使用 CSS 自定义属性定义令牌
• 为常见模式实现工具类
• 遵循 BEM 或类似的命名约定
• 确保选择器优先级易于管理
• 支持主题和自定义

组件库

• 尽可能与框架无关
• 支持 Tree-shaking 的导出
• 支持 TypeScript
• 全面的测试覆盖
• 集成 Storybook

治理

贡献指南

• 如何提议新组件
• 审核与批准流程
• 版本管理策略
• 重大变更政策
• 弃用流程

维护

• 定期进行无障碍审查
• 性能监控
• 浏览器兼容性测试
• 更新文档
• 纳入社区反馈

设计令牌

令牌类别

• 颜色
• 字体排版（字号、字重、行高）
• 间距
• 边框圆角
• 阴影
• 断点
• 动画时长
• Z-index 值

令牌实现

:root {
  /* Colors */
  --color-primary-500: #0066cc;
  --color-neutral-100: #f5f5f5;

  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;

  /* Typography */
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
}

示例：使用设计令牌的 React 按钮组件

import React from "react";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "danger";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
}

const sizeStyles: Record<string, React.CSSProperties> = {
  sm: { padding: "var(--space-1) var(--space-2)", fontSize: "var(--font-size-sm)" },
  md: { padding: "var(--space-2) var(--space-4)", fontSize: "var(--font-size-base)" },
  lg: { padding: "var(--space-3) var(--space-6)", fontSize: "var(--font-size-lg)" },
};

export const Button: React.FC<ButtonProps> = ({
  variant = "primary",
  size = "md",
  loading = false,
  disabled,
  children,
  ...props
}) => (
  <button
    style={{
      ...sizeStyles[size],
      backgroundColor: `var(--color-${variant}-500)`,
      color: "var(--color-neutral-100)",
      borderRadius: "var(--radius-md)",
      boxShadow: "var(--shadow-sm)",
      cursor: disabled || loading ? "not-allowed" : "pointer",
      opacity: disabled ? 0.5 : 1,
    }}
    disabled={disabled || loading}
    aria-busy={loading}
    {...props}
  >
    {loading ? "Loading…" : children}
  </button>
);

示例：Storybook 配置

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import "../src/tokens.css"; // import design tokens globally

const preview: Preview = {
  parameters: {
    a11y: { element: "#storybook-root" },
    backgrounds: {
      default: "light",
      values: [
        { name: "light", value: "#ffffff" },
        { name: "dark", value: "#1a1a1a" },
      ],
    },
  },
};

export default preview;

质量保障

• 视觉回归测试
• 自动化无障碍测试
• 跨浏览器测试
• 性能基准测试
• 组件单元测试
• 集成测试

演进设计系统时，请依据 WCAG 2.1 AA 验证变更，运行视觉回归测试，并确保令牌更新能正确传递到所有使用这些令牌的应用中。