design-system-starter

用途

Design System Starter 是一个用于创建或演进应用设计系统的技能，旨在帮助团队建立健壮、可扩展的设计系统，以保证视觉一致性、提升开发速度并改善用户体验。

适用场景包括：

从零创建新的设计系统
演进或重构现有设计系统
建立设计令牌标准
定义组件架构
编写设计文档
确保无障碍合规（WCAG 2.1）
实现主题化与暗色模式

设计系统理念

设计系统不只是组件库，它包含多个层次：

设计令牌：基础设计决策，如颜色、间距、排版
组件：可复用的 UI 构建块，如 Button、Input、Card、Modal
模式：常见 UX 解决方案，如表单、导航、布局
指南：规则与最佳实践，如无障碍、命名、API
文档：如何使用所有内容，如 Storybook、用法示例

核心原则：

一致性优先于创造性：可预测的模式降低认知负荷
默认无障碍：最低满足 WCAG 2.1 Level AA
可扩展与可维护：设计令牌支持全局变更
开发者友好：清晰的 API 契约与文档

主要能力

设计令牌

覆盖主题包括：颜色刻度（原始 50-950、语义令牌）、排版系统（字体族、字号、字重、行高）、间距刻度（4px 基准）、圆角与阴影令牌、W3C 设计令牌格式、Tailwind @theme 集成。

令牌类别快速参考：

颜色：blue.500、text.primary、feedback.error，刻度 50-950
排版：fontSize.base、fontWeight.semibold，刻度 xs-5xl
间距：spacing.4、spacing.8，刻度 0-24（4px 基准）
圆角：borderRadius.md、borderRadius.full，刻度 none-full
阴影：shadow.sm、shadow.lg，刻度 xs-xl

示例令牌结构：

const tokens = {
  colors: {
    primary: { base: "#0066cc", hover: "#0052a3" },
    semantic: { success: "#28a745", error: "#dc3545" }
  },
  spacing: { xs: "4px", sm: "8px", md: "16px", lg: "24px" }
};

组件架构

覆盖主题包括：原子设计方法论（原子到页面）、Props 最佳实践（可预测命名、合理默认值）、组合优于配置、复合组件模式、多态组件、CVA 变体模式。

原子设计快速参考：

原子：不可分割的基础元素，如 Button、Input、Label、Icon
分子：简单组合，如 FormField、SearchBar、Card
有机体：复杂组合，如 Navigation、Modal、DataTable
模板：页面布局，如 DashboardLayout、AuthLayout
页面：具体实例，如 HomePage、SettingsPage

主题化

覆盖主题包括：主题结构与 TypeScript 接口、暗色模式实现方式、Tailwind @theme 指令（推荐）、Tailwind dark 模式变体、Styled Components ThemeProvider、主题切换组件、系统偏好检测。

暗色模式方案快速参考：

Tailwind @theme：适合新项目，复杂度低
Tailwind dark: 变体：适合快速实现，复杂度低
CSS 变量：框架无关，复杂度中
ThemeProvider：适合 CSS-in-JS 应用，复杂度中

无障碍指南

WCAG 2.1 Level AA 要求：

普通文本对比度：最低 4.5:1
大号文本对比度：最低 3:1
UI 组件对比度：最低 3:1

关键模式：

键盘导航：所有交互元素必须可键盘访问
焦点管理：在模态框中使用焦点陷阱，保持逻辑焦点顺序
语义 HTML：使用 <button>、<nav>、<main> 而非通用 div
ARIA 属性：aria-label、aria-expanded、aria-controls、aria-live
屏幕阅读器：提供有意义的标签，播报动态内容

使用方式

快速开始清单（创建新设计系统时）

定义设计原则与价值观
建立设计令牌结构（颜色、排版、间距）
创建原始色板（50-950 刻度）
定义语义颜色令牌（品牌、文本、背景、反馈）
设置排版刻度与字体族
建立间距刻度（4px 或 8px 基准）
使用 Tailwind @theme 指令定义令牌
组件使用 Tailwind 工具类（bg-primary、text-text-primary）
设计原子组件（Button、Input、Label 等）
实现主题系统（亮色/暗色模式）
确保 WCAG 2.1 Level AA 合规
搭建文档（Storybook 或类似工具）
为每个组件创建用法示例
建立版本与发布策略

当前实现（2026 年 1 月）：

所有颜色在 frontend/src/styles/tokens.css 中使用 @theme 指令定义
组件使用 Tailwind 工具类：bg-primary、text-text-primary、border-border
不要在 className 中使用 CSS 变量：bg-[var(--color-primary)]

设计系统工作流

设计阶段：审计现有模式并识别不一致；定义设计令牌；创建组件清单；在 Figma 中设计（创建组件库）
开发阶段：搭建工具链（Storybook、TypeScript、测试）；实现令牌（CSS 变量或主题配置）；先构建原子再向上组合；边做边写文档
采用阶段：为团队创建迁移指南；提供 codemod 自动化迁移；举办工作坊培训团队；收集反馈并迭代
维护阶段：语义化版本（major/minor/patch）；定义弃用策略；维护变更日志；监控各产品的采用情况

附带资源

references/design-tokens.md：完整令牌定义
references/component-patterns.md：架构模式
references/component-examples.md：完整组件实现
references/theming.md：主题与暗色模式模式
assets/design-tokens-template.json：W3C 设计令牌格式
assets/component-template.tsx：React 组件模板
checklists/design-system-checklist.md：设计系统审计清单

与智能体集成

Rapid UI Designer：使用令牌实现一致界面，引用组件
Frontend UI Developer：按模式实现组件
Code Quality Reviewer：验证设计系统遵循情况

关键决策

令牌格式：W3C Design Tokens，行业标准、工具无关、支持主题化
组件架构：原子设计，从原子到页面的可扩展层级
样式方案：Tailwind @theme 指令，原生 CSS 变量集成、零运行时
变体管理：CVA（Class Variance Authority），类型安全变体、可组合样式
文档：Storybook，交互式组件演练场、视觉测试

限制

技能版本 1.0.0，最后更新 2025-10-31。关于具体收费、价格、平台支持范围等信息，资料中暂未提供。

技能介绍

用途