# 风七六平台样式开发规范

## 1. 概述

本文档定义了风七六平台前端样式开发的规范和最佳实践，旨在确保整个平台的样式一致性、可维护性和可扩展性。所有前端开发人员在进行样式开发时应严格遵循本规范。

## 2. 规范与主流实践的契合度

本规范整体贴合现代前端样式开发的核心趋势，大部分设计和实现思路符合行业主流实践：

- **CSS 变量（Custom Properties）**：作为原生 CSS 特性，已成为现代样式主题化、动态样式管理的核心方案
- **BEM 命名规范**：仍是前端组件化开发中最主流的 CSS 类命名方案
- **响应式设计**：采用"移动优先 + 媒体查询 + 弹性布局"，符合行业对多端适配的标准思路
- **TypeScript 管理样式常量**：将样式常量纳入 TS 类型体系，兼顾类型安全与样式统一
- **分层变量体系**：遵循"原子化 → 组合化"的样式设计逻辑，与现代设计系统思路一致

同时，本规范涵盖了命名、变量体系、响应式、性能、可访问性、工具链、测试等全链路环节，符合大型前端项目对"样式工程化"的要求。

## 3. 技术栈

- **CSS 预处理器**：无（使用原生 CSS 变量）
- **样式管理**：CSS Variables + StyleManager + Design Token
- **UI 库**：Ant Design
- **响应式设计**：媒体查询 + 弹性布局 + 容器查询
- **构建工具**：Vite
- **工具链**：Prettier + Stylelint + ESLint
- **可访问性**：WCAG 2.1 AA 标准

## 4. 样式架构

### 4.1 目录结构

```
src/
├── styles/
│   ├── index.css          # 全局样式入口
│   ├── variables.css      # CSS 变量定义
│   ├── constants.ts       # 样式常量和配置
│   ├── StyleManager.ts    # 样式管理类
│   ├── SceneManager.ts    # 场景管理类
│   ├── tokens/            # Design Token 源文件
│   │   ├── colors.json    # 颜色 Token
│   │   ├── sizes.json     # 尺寸 Token
│   │   └── typography.json # 字体 Token
│   ├── token-transformer/ # Token 转换工具
│   └── STYLE_GUIDE.md     # 样式开发规范
├── components/
│   ├── SceneSwitcher.tsx
│   ├── ThemeSwitcher.tsx
│   ├── ThemedSwitch.tsx
│   └── utility/           # 原子化工具类组件
└── pages/
    └── styles/            # 样式管理页面
```

### 4.2 样式管理体系

- **全局样式**：定义在 `index.css` 中，应用于整个应用
- **CSS 变量**：定义在 `variables.css` 中，用于统一管理样式值
- **样式常量**：定义在 `constants.ts` 中，用于 TypeScript 代码中使用
- **Design Token**：定义在 `tokens/` 目录中，作为样式的唯一数据源
- **样式管理**：`StyleManager.ts` 提供动态样式管理能力
- **场景管理**：`SceneManager.ts` 提供场景化样式管理能力
- **原子化工具类**：基于 CSS 变量生成的通用工具类，用于快速搭建布局

## 5. 命名规范

### 5.1 CSS 类命名

- 使用 **BEM 命名规范**（Block, Element, Modifier）
- 类名使用小写字母，单词间用连字符 `-` 连接
- 块名使用语义化名称
- 元素名使用相对于块的语义化名称
- 修饰符用于表示状态或变体

**示例：**

```css
/* 块 */
.header {
  /* 样式 */
}

/* 元素 */
.header__logo {
  /* 样式 */
}

/* 修饰符 */
.header--collapsed {
  /* 样式 */
}
```

### 5.2 CSS 变量命名

- 使用 `--` 前缀
- 采用 kebab-case 命名方式
- 按照功能和层级组织命名
- 使用语义化的名称

**示例：**

```css
/* 颜色变量 */
--color-primary: #1890ff;
--color-background-primary: #ffffff;

/* 尺寸变量 */
--size-font-large: 18px;
--size-spacing-medium: 16px;

/* 组件变量 */
--component-button-radius: 4px;
--component-card-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
```

### 5.3 TypeScript 变量命名

- 颜色相关：使用 `colors` 对象，按功能和亮度层级组织
- 尺寸相关：使用 `sizes` 对象，按类型组织
- 字体相关：使用 `fonts` 对象，按属性组织
- 间距相关：使用 `spacing` 对象，按尺寸组织

**示例：**

```typescript
const colors = {
  primary: {
    500: '#1890ff',
    600: '#40a9ff',
    700: '#69c0ff',
  },
  background: {
    primary: '#ffffff',
    secondary: '#f0f2f5',
  },
}
```

### 5.4 Design Token 命名

- 采用 W3C Design Token 标准命名规范
- 使用 camelCase 命名方式（JSON 文件中）
- 按功能和层级组织命名
- 与 CSS 变量保持映射关系

**示例：**

```json
{
  "color": {
    "primary": {
      "500": "#1890ff",
      "600": "#40a9ff"
    },
    "background": {
      "primary": "#ffffff"
    }
  },
  "size": {
    "font": {
      "medium": "16px"
    },
    "spacing": {
      "medium": "16px"
    }
  }
}
```

## 6. CSS 变量与 Design Token 体系

### 6.1 Design Token 标准化

- **Token 类型**：颜色、尺寸、字体、间距、边框、阴影、断点等
- **Token 层级**：原子 Token → 组合 Token → 语义 Token
- **Token 源数据**：存储在 `tokens/` 目录的 JSON 文件中
- **Token 转换**：通过工具自动转换为 CSS 变量和 TypeScript 常量

**示例：**

```json
{
  "token": {
    "color": {
      "primary": {
        "value": "#1890ff",
        "type": "color"
      }
    },
    "size": {
      "spacing": {
        "medium": {
          "value": "16px",
          "type": "dimension"
        }
      }
    }
  }
}
```

### 6.2 CSS 变量体系

#### 6.2.1 基础变量

- **颜色系统**：主色、辅色、中性色、功能色
- **尺寸系统**：字体大小、间距、边框半径、阴影
- **字体系统**：字体家族、字重、行高
- **布局系统**：容器宽度、栅格系统、断点

#### 6.2.2 组件变量

为每个组件定义专属的 CSS 变量，用于控制组件的样式。组件变量应基于基础变量构建，确保样式的一致性。

**示例：**

```css
/* 按钮组件变量 */
--component-button-primary-color: var(--color-primary);
--component-button-secondary-color: var(--color-secondary);
--component-button-radius: var(--size-radius-medium);

/* 卡片组件变量 */
--component-card-background: var(--color-background-primary);
--component-card-shadow: var(--size-shadow-medium);
--component-card-radius: var(--size-radius-medium);
```

#### 6.2.3 平台变量

为不同平台（平台端、商家端、用户端、骑手端）定义专属的 CSS 变量，用于控制各平台的特定样式。

**示例：**

```css
/* 平台端变量 */
--platform-layout-header-height: 64px;
--platform-layout-sidebar-width: 200px;
--platform-color-header-bg: var(--color-background-primary);

/* 商家端变量 */
--merchant-layout-header-height: 56px;
--merchant-color-primary: var(--color-primary);
```

### 6.3 原子化工具类

基于 CSS 变量生成原子化工具类，用于快速搭建布局和样式。

**示例：**

```css
/* 间距工具类 */
.m-xs {
  margin: var(--size-spacing-xs);
}
.m-sm {
  margin: var(--size-spacing-sm);
}
.m-md {
  margin: var(--size-spacing-md);
}

/* 颜色工具类 */
.text-primary {
  color: var(--color-primary);
}
.bg-secondary {
  background-color: var(--color-background-secondary);
}

/* 布局工具类 */
.flex {
  display: flex;
}
.flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}
```

### 6.4 Token 自动化流程

1. **从设计工具导出**：从 Figma 等设计工具导出 Token 源文件
2. **转换为代码**：使用 style-dictionary 等工具转换为 CSS 变量和 TS 常量
3. **集成到构建**：在 Vite 构建过程中自动注入变量
4. **运行时使用**：通过 StyleManager 动态管理和更新

## 7. 样式管理

### 7.1 StyleManager

`StyleManager` 类用于动态管理和更新 CSS 变量，提供以下功能：

- 初始化 CSS 变量
- 更新单个或多个 CSS 变量
- 重置 CSS 变量到默认值
- 导出当前样式配置
- 导入样式配置
- 集成 Design Token 源数据

**使用示例：**

```typescript
import { styleManager } from '../styles/constants'

// 更新单个变量
styleManager.updateCSSVariable('--color-primary', '#1890ff')

// 更新多个变量
styleManager.updateCSSVariables({
  '--color-primary': '#1890ff',
  '--color-secondary': '#52c41a',
})

// 重置变量
styleManager.resetCSSVariables()

// 从 Token 源数据更新
styleManager.updateFromTokens(tokens)
```

### 7.2 场景管理

`SceneManager` 类用于管理不同场景的样式配置，提供以下功能：

- 创建和管理场景
- 切换场景
- 导出场景配置
- 导入场景配置

**使用示例：**

```typescript
import { sceneManager } from '../styles/SceneManager'

// 创建场景
sceneManager.createScene('dark', {
  '--color-primary': '#1890ff',
  '--color-background-primary': '#141414',
})

// 切换场景
sceneManager.switchScene('dark')
```

### 7.3 样式隔离

为避免样式冲突，确保组件样式的独立性，采用以下样式隔离策略：

#### 7.3.1 CSS Modules

- **默认方案**：使用 CSS Modules 为组件样式生成唯一类名
- **命名约定**：组件样式文件命名为 `Component.module.css`
- **使用方式**：通过 `import styles from './Component.module.css'` 导入使用

**示例：**

```tsx
import styles from './Button.module.css'

const Button = () => {
  return <button className={styles.button}>Click me</button>
}
```

#### 7.3.2 Shadow DOM

- **适用场景**：独立的通用组件、第三方组件
- **使用方式**：通过 `attachShadow({ mode: 'closed' })` 创建隔离的 DOM 环境

**示例：**

```tsx
class CustomElement extends HTMLElement {
  constructor() {
    super()
    const shadow = this.attachShadow({ mode: 'closed' })
    shadow.innerHTML = `
      <style>
        :host { display: block; }
        .button { color: var(--color-primary); }
      </style>
      <button class="button">Click me</button>
    `
  }
}
```

## 8. 响应式设计

### 8.1 断点系统

定义统一的断点系统，用于响应式布局：

- **小屏幕**：< 768px
- **中屏幕**：768px - 1024px
- **大屏幕**：1024px - 1440px
- **超大屏幕**：> 1440px

**示例：**

```css
:root {
  --breakpoint-sm: 768px;
  --breakpoint-md: 1024px;
  --breakpoint-lg: 1440px;
}

@media (min-width: var(--breakpoint-md)) {
  .container {
    max-width: 960px;
  }
}

@media (min-width: var(--breakpoint-lg)) {
  .container {
    max-width: 1200px;
  }
}
```

### 8.2 容器查询

使用容器查询实现组件级响应式设计：

**示例：**

```css
:root {
  --container-sm: 320px;
  --container-md: 640px;
  --container-lg: 960px;
}

.card-container {
  container-type: inline-size;
}

@container (min-width: var(--container-md)) {
  .card {
    display: flex;
    align-items: center;
  }

  .card__image {
    flex: 0 0 120px;
  }

  .card__content {
    flex: 1;
  }
}
```

### 8.3 布局策略

- **移动优先**：先设计移动端布局，再逐步适配更大屏幕
- **弹性布局**：使用 `flexbox` 和 `grid` 进行布局
- **相对单位**：使用 `rem`、`em`、`%` 等相对单位，避免硬编码固定值
- **响应式字体**：使用 `clamp()` 或媒体查询实现响应式字体大小
- **视口设置**：使用标准的视口元标签确保移动端正确显示

**视口元标签：**

```html
<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
/>
```

### 8.4 移动端优化

- **触摸目标**：确保所有可点击元素的尺寸至少为 48px × 48px
- **触摸反馈**：为触摸元素添加适当的点击反馈样式
- **滚动性能**：使用 `overflow-scrolling: touch` 启用 iOS 原生滚动
- **避免悬停**：为移动设备提供替代悬停效果的交互方式

**示例：**

```css
/* 触摸目标大小 */
.button {
  min-width: 48px;
  min-height: 48px;
}

/* 触摸反馈 */
.button {
  transition: opacity 0.2s;
}

.button:active {
  opacity: 0.8;
}

/* 滚动性能 */
.scroll-container {
  -webkit-overflow-scrolling: touch;
  overflow-scrolling: touch;
}
```

### 8.5 响应式工具类

基于断点定义响应式工具类，用于快速实现响应式布局：

**示例：**

```css
/* 响应式显示/隐藏 */
.d-none {
  display: none;
}

@media (min-width: var(--breakpoint-sm)) {
  .sm\:d-block {
    display: block;
  }
}

@media (min-width: var(--breakpoint-md)) {
  .md\:d-flex {
    display: flex;
  }
}

/* 响应式间距 */
@media (min-width: var(--breakpoint-md)) {
  .md\:m-md {
    margin: var(--size-spacing-md);
  }
  .md\:p-lg {
    padding: var(--size-spacing-lg);
  }
}

/* 响应式网格 */
.grid {
  display: grid;
  gap: var(--size-spacing-md);
}

@media (min-width: var(--breakpoint-md)) {
  .md\:grid-cols-2 {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: var(--breakpoint-lg)) {
  .lg\:grid-cols-3 {
    grid-template-columns: repeat(3, 1fr);
  }
}
```

## 9. 性能优化

### 9.1 CSS 加载策略

- **关键 CSS 内联**：将首屏关键样式内联到 HTML 头部，减少渲染阻塞
- **非关键 CSS 懒加载**：通过 `link rel="preload" as="style"` 或动态导入加载非首屏样式
- **CSS 分包**：按页面/组件拆分 CSS，避免单文件过大
- **CSS 压缩**：在构建过程中启用 CSS 压缩，减少文件体积

**示例：**

```html
<!-- 关键 CSS 内联 -->
<style>
  .header {
    background: var(--color-background-primary);
    height: var(--layout-header-height);
  }
</style>

<!-- 非关键 CSS 预加载 -->
<link
  rel="preload"
  href="/styles/non-critical.css"
  as="style"
  onload="this.onload=null;this.rel='stylesheet'"
/>
<noscript><link rel="stylesheet" href="/styles/non-critical.css" /></noscript>
```

### 9.2 选择器性能

- **避免低效选择器**：禁止使用 `*` 通配符、多层嵌套选择器
- **优先使用 ID 和类选择器**：ID 选择器 (`#id`) 和类选择器 (`.class`) 性能最优
- **扁平化选择器**：使用 BEM 规范，保持选择器层级扁平
- **避免属性选择器**：属性选择器 (`[attribute]`) 性能较低，尽量避免使用

**示例：**

```css
/* 不推荐 */
* {
  margin: 0;
  padding: 0;
}

.header .nav .link {
  color: var(--color-primary);
}

/* 推荐 */
.header {
  margin: 0;
  padding: 0;
}

.header__nav-link {
  color: var(--color-primary);
}
```

### 9.3 渲染性能

- **避免重排**：减少 DOM 操作，使用 CSS transforms 进行动画
- **避免重绘**：合理使用 `will-change` 属性，优化动画性能
- **使用 CSS 硬件加速**：对需要动画的元素使用 `transform: translateZ(0)` 或 `transform: translate3d(0, 0, 0)`
- **批量 DOM 操作**：使用 DocumentFragment 或批量更新，减少重排次数

**示例：**

```css
/* 不推荐（会触发重排） */
.animate {
  position: relative;
  top: 10px;
  left: 10px;
}

/* 推荐（不会触发重排） */
.animate {
  transform: translate(10px, 10px);
  will-change: transform;
}
```

### 9.4 CSS 动画优化

- **优先使用 transform/opacity**：这两个属性不会触发重排，性能最优
- **避免使用 top/left**：这些属性会触发重排，性能较差
- **使用 requestAnimationFrame**：对于复杂动画，使用 `requestAnimationFrame` 确保平滑执行
- **定义 will-change 规范**：仅对高频动画元素使用 `will-change`，避免过度使用

**示例：**

```css
/* 推荐的动画方式 */
.fade-in {
  animation: fadeIn 0.3s ease-in-out;
}

@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* 仅对高频动画元素使用 will-change */
.slider {
  will-change: transform;
}
```

## 10. 可访问性（A11y）

### 10.1 颜色对比度

- **文本对比度**：确保文本与背景的对比度符合 WCAG 2.1 AA 标准（普通文本至少 4.5:1，大文本至少 3:1）
- **UI 组件对比度**：确保按钮、链接等交互元素的对比度符合 WCAG 2.1 AA 标准
- **颜色检查工具**：使用 axe-core、Lighthouse 等工具检查颜色对比度

**示例：**

```css
/* 符合对比度要求的文本 */
.text-primary {
  color: #1890ff; /* 与白色背景对比度 > 4.5:1 */
}

/* 符合对比度要求的按钮 */
.button-primary {
  background-color: #1890ff;
  color: white; /* 对比度 > 4.5:1 */
}
```

### 10.2 信息传达多样性

- **避免仅依赖颜色**：状态（成功/失败）需同时用图标+文本+颜色表示
- **使用多种感官反馈**：视觉、听觉、触觉反馈结合
- **提供文本描述**：为图表、图形、颜色编码提供文本描述

**示例：**

```tsx
// 不推荐（仅依赖颜色）
<div className="status success">成功</div>

// 推荐（多种信息传达）
<div className="status success">
  <CheckCircleOutlined className="status-icon" />
  <span className="status-text">成功</span>
</div>
```

### 10.3 键盘导航

- **确保键盘可访问**：所有交互元素都可以通过键盘访问
- **清晰的焦点样式**：禁止 `outline: none` 无替代方案，定义自定义焦点样式
- **合理的 tab 顺序**：避免使用 `tabindex` 属性改变默认的键盘导航顺序
- **跳过导航链接**：为长页面提供 "跳过导航" 链接，方便键盘用户

**示例：**

```css
/* 自定义焦点样式 */
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
  border-radius: var(--size-radius-sm);
}

/* 跳过导航链接 */
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: var(--color-primary);
  color: white;
  padding: 8px;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}
```

### 10.4 屏幕阅读器

- **语义化 HTML**：使用正确的 HTML 元素（`<button>`, `<input>`, `<nav>`, `<main>` 等）
- **替代文本**：为图片、图标等非文本内容提供 `alt` 属性
- **ARIA 属性**：合理使用 ARIA 属性增强可访问性
- **ARIA 标签**：为复杂组件提供 `aria-label` 或 `aria-labelledby`

**示例：**

```tsx
// 语义化 HTML
<nav aria-label="主导航">
  <ul>
    <li><a href="/">首页</a></li>
    <li><a href="/about">关于我们</a></li>
  </ul>
</nav>

// 替代文本
<img src="logo.png" alt="风七六平台 logo" />

// ARIA 标签
<button aria-label="关闭对话框">
  <CloseOutlined />
</button>
```

### 10.5 暗黑模式与高对比度模式

- **暗黑模式支持**：提供暗黑模式，减少夜间使用时的眼部疲劳
- **高对比度模式**：提供高对比度模式，满足视觉障碍用户需求
- **模式切换**：提供清晰的模式切换控件，记住用户偏好

**示例：**

```css
/* 暗黑模式变量 */
@media (prefers-color-scheme: dark) {
  :root {
    --color-background-primary: #141414;
    --color-text-primary: #ffffff;
  }
}

/* 高对比度模式变量 */
@media (prefers-contrast: high) {
  :root {
    --color-primary: #0066cc;
    --color-text-primary: #000000;
    --color-background-primary: #ffffff;
  }
}
```

### 10.6 可访问性测试

- **自动化测试**：集成 axe-core、Lighthouse 到 CI/CD 流程
- **手动测试**：定期进行手动可访问性测试
- **用户测试**：邀请有 disabilities 的用户参与测试
- **合规性检查**：确保符合 WCAG 2.1 AA 标准要求

**测试工具：**

- axe DevTools（浏览器扩展）
- Lighthouse（Chrome DevTools）
- Wave（浏览器扩展）
- WebAIM Contrast Checker（颜色对比度检查）

## 11. 工具和工作流

### 11.1 开发工具

- **编辑器**：VS Code
- **扩展**：
  - Prettier（代码格式化）
  - Stylelint（CSS linting）
  - ESLint（JavaScript/TypeScript linting）
  - axe DevTools（可访问性测试）
  - Lighthouse（性能测试）

### 11.2 代码格式化

使用 Prettier 进行代码格式化，确保代码风格一致。

**Prettier 配置：**

```json
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "endOfLine": "lf",
  "arrowParens": "always"
}
```

### 11.3 代码检查

使用 Stylelint 进行 CSS 代码检查，确保 CSS 代码质量。

**Stylelint 配置：**

```json
{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "color-hex-case": "lower",
    "color-hex-length": "short",
    "selector-class-pattern": "^[a-z][a-z0-9_-]*$",
    "declaration-no-important": true,
    "no-descending-specificity": true,
    "selector-max-compound-selectors": 3,
    "selector-max-id": 0,
    "selector-no-qualifying-type": true
  }
}
```

### 11.4 ESLint 配置

使用 ESLint 进行 JavaScript/TypeScript 代码检查，确保代码质量。

**ESLint 配置：**

```json
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-explicit-any": "warn",
    "react/prop-types": "off"
  }
}
```

### 11.5 构建与部署规则

#### 11.5.1 Vite 样式配置

- **CSS 提取**：在生产环境中启用 CSS 提取，减少 JavaScript 包体积
- **CSS 压缩**：在构建过程中启用 CSS 压缩，减少文件体积
- **变量注入**：通过 `css.preprocessorOptions` 注入全局变量

**Vite 配置示例：**

```typescript
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    extract: true,
    minify: true,
    preprocessorOptions: {
      css: {
        additionalData: `@import "./src/styles/variables.css";`,
      },
    },
  },
})
```

#### 11.5.2 样式分包策略

- **按页面拆分**：将不同页面的样式拆分为独立的 CSS 文件
- **按组件拆分**：将大型组件的样式拆分为独立的 CSS 文件
- **动态导入**：使用动态导入加载非首屏样式

**示例：**

```tsx
// 动态导入页面样式
const ProfilePage = () => {
  React.useEffect(() => {
    import('./ProfilePage.css')
  }, [])

  return <div>Profile Page</div>
}
```

#### 11.5.3 缓存策略

- **文件哈希**：为 CSS 文件添加哈希（如 `style.[hash].css`），确保文件更新时缓存失效
- **CDN 缓存**：配置 CDN 缓存策略，合理设置缓存过期时间
- **HTTP 缓存头**：设置合理的 HTTP 缓存头（如 `Cache-Control`）

**示例：**

```typescript
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        assetFileNames: {
          css: 'styles/[name].[hash].css',
        },
      },
    },
  },
})
```

## 12. 最佳实践

### 12.1 一般原则

- **保持简单**：使用简单、清晰的样式代码，避免过度复杂化
- **避免硬编码**：所有样式值都应使用 CSS 变量，避免硬编码固定值
- **遵循规范**：严格遵循本规范中的命名规范和代码组织原则
- **注重性能**：优化样式代码，提高渲染性能和加载速度
- **考虑可访问性**：确保样式对所有用户都可用，包括残障用户
- **代码复用**：通过原子化工具类和组件样式复用，减少重复代码
- **文档化**：为复杂的样式逻辑和组件样式提供清晰的文档

### 12.2 组件样式最佳实践

- **专属样式文件**：为每个组件创建专属的样式文件（如 `Component.module.css`）
- **基于变量构建**：组件样式应基于基础变量构建，确保样式的一致性
- **样式隔离**：使用 CSS Modules 或 Shadow DOM 确保组件样式隔离
- **配置选项**：提供组件样式的配置选项，通过 props 或 CSS 变量控制
- **响应式适配**：为组件提供响应式适配，确保在不同设备上的良好显示

**示例：**

```tsx
// Button 组件
import React from 'react'
import styles from './Button.module.css'

interface ButtonProps {
  variant?: 'primary' | 'secondary'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
}

const Button: React.FC<ButtonProps> = ({ variant = 'primary', size = 'md', children }) => {
  return (
    <button
      className={`${styles.button} ${styles[variant]} ${styles[size]}`}
      style={{
        '--button-primary-color': 'var(--color-primary)',
        '--button-secondary-color': 'var(--color-secondary)',
        '--button-sm-padding': 'var(--size-spacing-xs) var(--size-spacing-sm)',
        '--button-md-padding': 'var(--size-spacing-sm) var(--size-spacing-md)',
        '--button-lg-padding': 'var(--size-spacing-md) var(--size-spacing-lg)',
      }}
    >
      {children}
    </button>
  )
}

export default Button
```

### 12.3 响应式设计最佳实践

- **移动优先**：采用移动优先的设计理念，从移动端开始设计
- **断点使用**：合理使用断点，避免过多的断点导致维护困难
- **容器查询**：对组件级响应式使用容器查询，提高组件的复用性
- **测试覆盖**：测试在各种设备上的显示效果，确保响应式设计的完整性
- **触摸目标**：确保触摸目标足够大（至少 48px × 48px），提高移动端可用性

### 12.4 主题管理最佳实践

- **CSS 变量实现**：使用 CSS 变量实现主题切换，确保切换性能
- **完整主题配置**：为不同主题定义完整的样式配置，包括所有相关变量
- **主题切换界面**：提供直观的主题切换用户界面
- **用户偏好保存**：使用 localStorage 或其他方式保存用户的主题偏好
- **系统主题适配**：适配系统的深色/浅色模式偏好

**示例：**

```tsx
// ThemeSwitcher 组件
import React, { useState, useEffect } from 'react'
import { Switch } from 'antd'
import { MoonOutlined, SunOutlined } from '@ant-design/icons'
import { styleManager } from '../styles/constants'

const ThemeSwitcher: React.FC = () => {
  const [isDarkMode, setIsDarkMode] = useState(false)

  // 从 localStorage 加载主题偏好
  useEffect(() => {
    const savedTheme = localStorage.getItem('theme')
    if (savedTheme === 'dark') {
      setIsDarkMode(true)
      enableDarkMode()
    }
  }, [])

  // 启用暗黑模式
  const enableDarkMode = () => {
    styleManager.updateCSSVariables({
      '--color-background-primary': '#141414',
      '--color-background-secondary': '#1e1e1e',
      '--color-text-primary': '#ffffff',
      '--color-text-secondary': '#b0b0b0',
      '--color-border': '#333333',
    })
    localStorage.setItem('theme', 'dark')
  }

  // 启用浅色模式
  const enableLightMode = () => {
    styleManager.updateCSSVariables({
      '--color-background-primary': '#ffffff',
      '--color-background-secondary': '#f0f2f5',
      '--color-text-primary': '#262626',
      '--color-text-secondary': '#8c8c8c',
      '--color-border': '#d9d9d9',
    })
    localStorage.setItem('theme', 'light')
  }

  // 切换主题
  const handleThemeChange = (checked: boolean) => {
    setIsDarkMode(checked)
    if (checked) {
      enableDarkMode()
    } else {
      enableLightMode()
    }
  }

  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <SunOutlined style={{ color: isDarkMode ? '#b0b0b0' : '#faad14' }} />
      <Switch checked={isDarkMode} onChange={handleThemeChange} />
      <MoonOutlined style={{ color: isDarkMode ? '#1890ff' : '#b0b0b0' }} />
    </div>
  )
}

export default ThemeSwitcher
```

### 12.5 样式评审 Checklist

在进行代码审查时，使用以下 Checklist 确保样式代码符合规范：

#### 12.5.1 命名和组织

- [ ] 使用 BEM 命名规范
- [ ] 使用 CSS 变量而非硬编码值
- [ ] 样式文件组织合理
- [ ] 选择器使用正确且高效

#### 12.5.2 性能和优化

- [ ] 避免使用低效选择器
- [ ] 避免 CSS 阻塞
- [ ] 动画使用 `transform`/`opacity`
- [ ] 合理使用 `will-change`

#### 12.5.3 可访问性

- [ ] 颜色对比度符合 WCAG AA 标准
- [ ] 提供清晰的焦点样式
- [ ] 避免仅依赖颜色传达信息
- [ ] 键盘导航可用

#### 12.5.4 响应式设计

- [ ] 采用移动优先设计
- [ ] 断点使用合理
- [ ] 触摸目标足够大
- [ ] 在不同设备上测试通过

### 12.6 最佳实践对比

#### 12.6.1 颜色使用

**反例（硬编码颜色）：**

```css
.button {
  background-color: #1890ff;
  color: #ffffff;
}
```

**正例（使用 CSS 变量）：**

```css
.button {
  background-color: var(--color-primary);
  color: var(--color-text-light);
}
```

#### 12.6.2 组件样式

**反例（全局样式覆盖）：**

```css
/* global.css */
.button {
  padding: 8px 16px;
}

/* component.css */
.button {
  padding: 12px 24px; /* 覆盖全局样式 */
}
```

**正例（样式隔离）：**

```css
/* Button.module.css */
.button {
  padding: var(--size-spacing-sm) var(--size-spacing-md);
}

.buttonLarge {
  padding: var(--size-spacing-md) var(--size-spacing-lg);
}
```

#### 12.6.3 响应式设计

**反例（固定宽度）：**

```css
.container {
  width: 1200px;
}
```

**正例（响应式宽度）：**

```css
.container {
  width: 100%;
  max-width: var(--layout-container-max-width);
}

@media (max-width: var(--breakpoint-md)) {
  .container {
    padding: 0 var(--size-spacing-md);
  }
}
```

## 13. 样式设置界面

### 13.1 全局样式设置

全局样式设置页面用于配置整个平台的基础样式，包括：

- **颜色系统**：主色调、辅色调、文本颜色、背景颜色等
- **尺寸系统**：字体大小、间距、边框半径、阴影等
- **字体系统**：字体家族、字重、行高、字间距等
- **布局系统**：容器宽度、栅格系统、响应式断点等
- **Design Token**：统一管理和配置所有设计 Token

### 13.2 平台样式设置

为每个平台（平台端、商家端、用户端、骑手端）提供专属的样式设置页面，用于配置各平台的特定样式：

- **平台特定颜色**：各平台的主色调、辅色调等
- **平台特定布局**：各平台的布局尺寸、导航样式等
- **平台特定组件**：各平台的组件样式和配置

### 13.3 组件样式设置

为关键组件提供专属的样式设置页面，用于配置组件的样式：

- **按钮样式**：不同类型按钮的颜色、尺寸、形状等
- **卡片样式**：卡片的阴影、边框、圆角等
- **表单样式**：输入框、选择器、开关等表单组件的样式
- **导航样式**：菜单、面包屑、分页等导航组件的样式

### 13.4 场景管理

场景管理页面用于创建和管理不同场景的样式配置：

- **预设场景**：白天模式、夜间模式、高对比度模式
- **自定义场景**：节假日模式、特殊活动模式、品牌推广模式
- **场景切换**：提供场景预览和一键切换功能
- **场景导出/导入**：支持场景配置的导出和导入

### 13.5 样式设置最佳实践

- **实时预览**：提供实时样式预览功能，所见即所得
- **历史记录**：保存样式变更历史，支持回滚
- **批量修改**：支持批量修改相似样式属性
- **样式冲突检测**：检测并提示样式冲突
- **性能分析**：分析样式变更对性能的影响

## 14. 版本控制

### 14.1 版本控制策略

- **纳入版本控制**：所有样式文件（CSS、TS、JSON）都应纳入版本控制系统
- **代码审查**：对样式文件的修改应遵循代码审查流程，确保符合规范
- **分支管理**：样式变更应在专门的分支中进行，避免直接修改主分支
- **提交信息**：提交样式变更时，使用清晰、描述性的提交信息

**示例提交信息：**

```
feat(styles): 添加暗黑模式支持
- 更新颜色变量系统
- 添加暗黑模式主题配置
- 实现主题切换功能
```

### 14.2 变更管理

- **重大变更**：重大样式变更（如主色调调整、布局变更）应在发布前进行充分测试
- **向后兼容**：样式变更应保持向后兼容，避免破坏现有功能
- **变更日志**：记录样式变更的详细日志，包括变更内容、影响范围和迁移指南
- **灰度发布**：对于重大样式变更，考虑采用灰度发布策略

### 14.3 回滚机制

- **快照备份**：在进行重大样式变更前，创建样式配置的快照备份
- **快速回滚**：建立样式变更的快速回滚机制，以便在出现问题时及时恢复
- **回滚测试**：定期测试回滚机制，确保其可靠性

### 14.4 协作规范

- **冲突解决**：建立样式文件冲突的解决规范，避免样式代码冲突
- **代码所有权**：明确样式文件的代码所有权，确保责任明确
- **团队协作**：通过 Design Token 和共享样式库促进团队协作

## 15. 测试

### 15.1 视觉测试

- **跨浏览器测试**：在 Chrome、Firefox、Safari、Edge 等主流浏览器中测试样式显示
- **跨设备测试**：在桌面端、平板端、移动端等不同设备上测试响应式布局
- **分辨率测试**：在不同屏幕分辨率下测试样式显示效果
- **主题测试**：测试主题切换功能，确保各主题下样式显示正确
- **场景测试**：测试场景切换功能，确保各场景下样式显示符合预期
- **视觉回归测试**：使用 Percy、Chromatic 等工具进行视觉回归测试，检测意外的样式变更

### 15.2 性能测试

- **加载性能**：测试样式加载时间，确保 CSS 文件体积合理
- **渲染性能**：测试样式渲染性能，避免重排和重绘
- **动画性能**：测试 CSS 动画性能，确保动画流畅无卡顿
- **性能指标**：使用 Lighthouse 等工具测试性能指标，如 FCP、LCP、CLS 等
- **资源使用**：监控样式相关的 CPU、内存使用情况

**Lighthouse 性能测试示例：**

```bash
# 运行 Lighthouse 测试
npx lighthouse https://example.com --output=html --output-path=./lighthouse-report.html
```

### 15.3 可访问性测试

- **颜色对比度测试**：使用 axe-core、Lighthouse 等工具测试颜色对比度，确保符合 WCAG 2.1 AA 标准
- **键盘导航测试**：测试所有交互元素是否可通过键盘访问，确保键盘导航流畅
- **屏幕阅读器测试**：使用 NVDA、VoiceOver 等屏幕阅读器测试页面可访问性
- **ARIA 属性测试**：确保 ARIA 属性使用正确，增强可访问性
- **可访问性评分**：使用 axe-core 等工具获取可访问性评分，目标达到 100%

**axe-core 可访问性测试示例：**

```bash
# 安装 axe-core
npm install --save-dev axe-core

# 在测试中使用
import axe from 'axe-core';

test('页面可访问性测试', async () => {
  const results = await axe.run(document.body);
  expect(results.violations.length).toBe(0);
});
```

### 15.4 测试自动化

- **CI/CD 集成**：将样式测试集成到 CI/CD 流程中，确保每次提交都通过测试
- **自动化测试脚本**：编写自动化测试脚本，定期运行样式测试
- **测试覆盖率**：确保样式测试覆盖所有关键组件和页面
- **测试报告**：生成详细的测试报告，包括测试结果和改进建议

### 15.5 测试最佳实践

- **测试环境一致性**：确保测试环境与生产环境一致，避免测试偏差
- **测试数据多样性**：使用多样化的测试数据，确保样式在不同情况下都能正常显示
- **测试用例维护**：定期更新和维护测试用例，确保测试的有效性
- **测试文档**：为样式测试提供清晰的文档，包括测试方法、测试用例和预期结果

## 16. 总结

### 16.1 规范价值

本规范为风七六平台的样式开发提供了全面的指导和标准，具有以下核心价值：

- **一致性**：通过统一的命名规范、变量体系和组件样式，确保整个平台的样式一致，提升用户体验
- **可维护性**：通过模块化的样式架构、清晰的文档和工具链，提高样式代码的可维护性
- **可扩展性**：通过 Design Token、场景管理和主题系统，支持平台的持续扩展和演进
- **性能优化**：通过性能优化策略和最佳实践，提升平台的加载速度和渲染性能
- **可访问性**：通过符合 WCAG 2.1 AA 标准的设计，确保平台对所有用户都可用
- **团队协作**：通过明确的规范和工作流，促进团队成员之间的有效协作

### 16.2 优化建议响应

本规范充分吸收了现代前端样式开发的最佳实践，针对之前提出的优化建议，我们做出了以下改进：

- **Design Token 标准化**：引入了完整的 Design Token 体系，包括源数据管理、转换工具和自动化流程
- **原子化工具类**：添加了基于 CSS 变量的原子化工具类，用于快速搭建布局
- **容器查询**：集成了容器查询，实现组件级响应式设计
- **样式隔离**：提供了 CSS Modules 和 Shadow DOM 两种样式隔离方案
- **精细化性能优化**：补充了 CSS 加载策略、选择器性能和动画优化的详细规则
- **完整的可访问性规则**：覆盖了 WCAG 2.1 AA 标准的全部要求，提供了具体的落地规则
- **工程化构建规则**：添加了 Vite 样式配置、样式分包策略和缓存策略
- **增强的文档和落地性**：提供了详细的示例、Checklist 和最佳实践对比

### 16.3 未来发展

随着前端技术的不断演进，本规范也将持续更新和完善，重点关注以下方向：

- **CSS 新特性**：跟踪和采用 CSS 新特性，如 `@layer`、`anchor()` 等
- **AI 辅助样式开发**：探索 AI 工具在样式开发中的应用，如自动生成样式代码、智能优化
- **性能进一步优化**：持续探索样式性能优化的新方法和新技术
- **可访问性提升**：不断提升平台的可访问性，向 WCAG 2.1 AAA 标准努力
- **设计系统演进**：完善和演进平台的设计系统，提供更丰富的组件和样式库
- **跨端一致性**：确保平台在不同端（Web、App、小程序）的样式一致性

### 16.4 结语

本规范是风七六平台样式开发的基础指南，希望所有前端开发人员能够严格遵循并不断完善。通过共同的努力，我们将打造一个样式一致、性能优异、用户友好的现代化平台。

样式开发是一个持续演进的过程，我们鼓励开发人员在遵循规范的基础上，积极探索和创新，为平台的样式系统贡献新的思路和方法。

让我们一起构建更美好的风七六平台！

## 17. 附录

### 17.1 颜色系统

| 颜色类型 | 变量名                          | 默认值     | 用途           |
|------|------------------------------|---------|--------------|
| 主色   | --color-primary              | #1890ff | 主要按钮、链接、高亮元素 |
| 辅色   | --color-secondary            | #52c41a | 次要按钮、提示信息    |
| 警告色  | --color-warning              | #faad14 | 警告信息、待处理状态   |
| 错误色  | --color-error                | #f5222d | 错误信息、危险操作    |
| 成功色  | --color-success              | #52c41a | 成功信息、完成状态    |
| 文本主色 | --color-text-primary         | #262626 | 主要文本         |
| 文本次色 | --color-text-secondary       | #8c8c8c | 次要文本         |
| 文本浅色 | --color-text-light           | #bfbfbf | 辅助文本         |
| 背景主色 | --color-background-primary   | #ffffff | 主要背景         |
| 背景次色 | --color-background-secondary | #f0f2f5 | 次要背景         |
| 背景浅色 | --color-background-light     | #fafafa | 辅助背景         |
| 边框颜色 | --color-border               | #d9d9d9 | 边框           |
| 焦点颜色 | --color-focus                | #1890ff | 元素焦点状态       |
| 禁用颜色 | --color-disabled             | #d9d9d9 | 禁用状态         |

### 17.2 尺寸系统

| 尺寸类型      | 变量名                | 默认值                            | 用途     |
|-----------|--------------------|--------------------------------|--------|
| 字体大小 xs   | --size-font-xs     | 12px                           | 极小文本   |
| 字体大小 sm   | --size-font-sm     | 14px                           | 小文本    |
| 字体大小 md   | --size-font-md     | 16px                           | 中等文本   |
| 字体大小 lg   | --size-font-lg     | 18px                           | 大文本    |
| 字体大小 xl   | --size-font-xl     | 20px                           | 超大文本   |
| 字体大小 2xl  | --size-font-2xl    | 24px                           | 标题文本   |
| 字体大小 3xl  | --size-font-3xl    | 30px                           | 大标题文本  |
| 间距 xs     | --size-spacing-xs  | 4px                            | 极小间距   |
| 间距 sm     | --size-spacing-sm  | 8px                            | 小间距    |
| 间距 md     | --size-spacing-md  | 16px                           | 中等间距   |
| 间距 lg     | --size-spacing-lg  | 24px                           | 大间距    |
| 间距 xl     | --size-spacing-xl  | 32px                           | 超大间距   |
| 间距 2xl    | --size-spacing-2xl | 48px                           | 特大间距   |
| 边框半径 sm   | --size-radius-sm   | 2px                            | 小边框半径  |
| 边框半径 md   | --size-radius-md   | 4px                            | 中等边框半径 |
| 边框半径 lg   | --size-radius-lg   | 8px                            | 大边框半径  |
| 边框半径 xl   | --size-radius-xl   | 16px                           | 超大边框半径 |
| 边框半径 full | --size-radius-full | 9999px                         | 圆形边框   |
| 阴影 sm     | --size-shadow-sm   | 0 1px 2px rgba(0, 0, 0, 0.05)  | 小阴影    |
| 阴影 md     | --size-shadow-md   | 0 2px 8px rgba(0, 0, 0, 0.1)   | 中等阴影   |
| 阴影 lg     | --size-shadow-lg   | 0 4px 16px rgba(0, 0, 0, 0.15) | 大阴影    |
| 阴影 xl     | --size-shadow-xl   | 0 8px 32px rgba(0, 0, 0, 0.2)  | 超大阴影   |

### 17.3 布局系统

| 布局类型    | 变量名                              | 默认值    | 用途      |
|---------|----------------------------------|--------|---------|
| 容器最大宽度  | --layout-container-max-width     | 1200px | 容器最大宽度  |
| 容器最小宽度  | --layout-container-min-width     | 320px  | 容器最小宽度  |
| 头部高度    | --layout-header-height           | 64px   | 头部高度    |
| 侧边栏宽度   | --layout-sidebar-width           | 200px  | 侧边栏宽度   |
| 侧边栏折叠宽度 | --layout-sidebar-collapsed-width | 80px   | 侧边栏折叠宽度 |
| 内容区域内边距 | --layout-content-padding         | 24px   | 内容区域内边距 |
| 断点 sm   | --breakpoint-sm                  | 768px  | 小屏幕断点   |
| 断点 md   | --breakpoint-md                  | 1024px | 中屏幕断点   |
| 断点 lg   | --breakpoint-lg                  | 1440px | 大屏幕断点   |
| 断点 xl   | --breakpoint-xl                  | 1920px | 超大屏幕断点  |
| 容器断点 sm | --container-sm                   | 320px  | 小容器断点   |
| 容器断点 md | --container-md                   | 640px  | 中容器断点   |
| 容器断点 lg | --container-lg                   | 960px  | 大容器断点   |

### 17.4 字体系统

| 字体类型        | 变量名                    | 默认值                                                                                        | 用途    |
|-------------|------------------------|--------------------------------------------------------------------------------------------|-------|
| 字体家族        | --font-family-base     | -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif | 基础字体  |
| 字体家族代码      | --font-family-code     | 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, Courier, monospace                   | 代码字体  |
| 字重 normal   | --font-weight-normal   | 400                                                                                        | 正常字重  |
| 字重 medium   | --font-weight-medium   | 500                                                                                        | 中等字重  |
| 字重 semibold | --font-weight-semibold | 600                                                                                        | 半粗体字重 |
| 字重 bold     | --font-weight-bold     | 700                                                                                        | 粗体字重  |
| 行高 tight    | --line-height-tight    | 1.25                                                                                       | 紧凑行高  |
| 行高 normal   | --line-height-normal   | 1.5                                                                                        | 正常行高  |
| 行高 relaxed  | --line-height-relaxed  | 1.75                                                                                       | 宽松行高  |

### 17.5 动画系统

| 动画类型             | 变量名                         | 默认值                          | 用途     |
|------------------|-----------------------------|------------------------------|--------|
| 动画时长 fast        | --animation-duration-fast   | 150ms                        | 快速动画   |
| 动画时长 normal      | --animation-duration-normal | 250ms                        | 正常动画   |
| 动画时长 slow        | --animation-duration-slow   | 350ms                        | 慢速动画   |
| 动画曲线 ease-in     | --animation-ease-in         | cubic-bezier(0.4, 0, 1, 1)   | 缓入动画   |
| 动画曲线 ease-out    | --animation-ease-out        | cubic-bezier(0, 0, 0.2, 1)   | 缓出动画   |
| 动画曲线 ease-in-out | --animation-ease-in-out     | cubic-bezier(0.4, 0, 0.2, 1) | 缓入缓出动画 |

### 17.6 平台特定变量

| 平台类型 | 变量前缀        | 示例                              | 用途      |
|------|-------------|---------------------------------|---------|
| 平台端  | --platform- | --platform-layout-header-height | 平台端特定样式 |
| 商家端  | --merchant- | --merchant-color-primary        | 商家端特定样式 |
| 用户端  | --user-     | --user-layout-header-height     | 用户端特定样式 |
| 骑手端  | --rider-    | --rider-color-primary           | 骑手端特定样式 |
