# Nex Design 设计规范指南

> 面向 React + Ant Design + Tailwind CSS 的前端设计语言规范

## 目录

- [概述](#概述)
- [设计原则](#设计原则)
- [颜色系统](#颜色系统)
- [排版规范](#排版规范)
- [间距系统](#间距系统)
- [组件规范](#组件规范)
- [布局规范](#布局规范)
- [交互规范](#交互规范)
- [响应式设计](#响应式设计)
- [页面模板](#页面模板)

---

## 概述

Nex Design 是为开发团队打造的一套标准化设计语言系统，旨在提供统一、高效、易维护的前端设计规范。

### 技术栈

- **框架**: React 18+
- **组件库**: Ant Design 5.x
- **样式方案**: Tailwind CSS 3.x
- **包管理**: Yarn
- **运行时**: Node.js 16+

### 设计目标

1. **一致性**: 确保所有页面和组件保持视觉与交互的一致性
2. **高效性**: 提供可复用的设计模式，加快开发速度
3. **可维护性**: 建立清晰的规范体系，降低维护成本
4. **用户体验**: 优先考虑用户体验，打造直观易用的界面

---

## 设计原则

### 1. 清晰明确
界面设计应当清晰直观，避免歧义，让用户能够快速理解和操作。

### 2. 一致性优先
保持视觉、交互、用词的一致性，减少用户学习成本。

### 3. 效率至上
优化操作流程，减少用户的操作步骤，提高工作效率。

### 4. 反馈及时
对用户的每一个操作都应给予明确的反馈，包括成功、失败、加载等状态。

### 5. 容错友好
预防用户错误，在错误发生时提供清晰的提示和解决方案。

---

## 颜色系统

### 主色调

```css
/* 品牌主色 - Primary (基于 NEX Logo 紫红色) */
--primary-50: #fce7f6;
--primary-100: #f5bae6;
--primary-200: #ee8dd6;
--primary-300: #e760c6;
--primary-400: #e033b6;
--primary-500: #b8178d;  /* 主色 - 匹配 NEX Logo */
--primary-600: #9c1477;
--primary-700: #801161;
--primary-800: #640d4b;
--primary-900: #480a35;
```

### 辅助色系

```css
/* 蓝色 - Blue (用于信息提示) */
--blue-50: #e6f4ff;
--blue-100: #bae0ff;
--blue-200: #91caff;
--blue-300: #69b1ff;
--blue-400: #4096ff;
--blue-500: #1677ff;  /* 信息色 */
--blue-600: #0958d9;
--blue-700: #003eb3;
--blue-800: #002c8c;
--blue-900: #001d66;
```

### 功能色

```css
/* 成功 - Success */
--success: #52c41a;
--success-bg: #f6ffed;
--success-border: #b7eb8f;

/* 警告 - Warning */
--warning: #faad14;
--warning-bg: #fffbe6;
--warning-border: #ffe58f;

/* 错误 - Error */
--error: #ff4d4f;
--error-bg: #fff2f0;
--error-border: #ffccc7;

/* 信息 - Info */
--info: #1677ff;
--info-bg: #e6f4ff;
--info-border: #91caff;
```

### 中性色

```css
/* 文本颜色 */
--text-primary: rgba(0, 0, 0, 0.88);    /* 主要文本 */
--text-secondary: rgba(0, 0, 0, 0.65);  /* 次要文本 */
--text-tertiary: rgba(0, 0, 0, 0.45);   /* 辅助文本 */
--text-disabled: rgba(0, 0, 0, 0.25);   /* 禁用文本 */

/* 背景颜色 */
--bg-primary: #ffffff;
--bg-secondary: #fafafa;
--bg-tertiary: #f5f5f5;
--bg-disabled: #f0f0f0;

/* 边框颜色 */
--border-primary: #d9d9d9;
--border-secondary: #f0f0f0;
```

### 颜色使用规范

1. **主色使用**: 主要用于关键操作按钮、重要信息高亮、链接等
2. **功能色使用**: 严格按照语义使用，不可混淆
3. **中性色使用**: 用于文本、背景、边框等基础元素
4. **对比度**: 确保文本与背景的对比度符合 WCAG 2.0 标准（至少 4.5:1）

---

## 排版规范

### 字体家族

```css
/* 默认字体栈 */
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
             'Helvetica Neue', Arial, 'Noto Sans', sans-serif,
             'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
             'Noto Color Emoji';

/* 等宽字体（代码、数字） */
font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Fira Code',
             'Fira Mono', 'Droid Sans Mono', 'Source Code Pro', monospace;
```

### 字号规范

| 用途 | 字号 | 行高 | Tailwind Class | 使用场景 |
|------|------|------|----------------|----------|
| 特大标题 | 32px | 1.35 | `text-4xl` | 页面主标题 |
| 大标题 | 24px | 1.35 | `text-2xl` | 区块标题 |
| 中标题 | 20px | 1.4 | `text-xl` | 卡片标题 |
| 小标题 | 16px | 1.5 | `text-base` | 表单标签 |
| 正文 | 14px | 1.5714 | `text-sm` | 正文内容 |
| 辅助文字 | 12px | 1.6667 | `text-xs` | 说明文字 |

### 字重规范

- **Regular (400)**: 正文内容
- **Medium (500)**: 表单标签、列表项
- **Semibold (600)**: 小标题、强调文本
- **Bold (700)**: 标题、重要信息

### 文本颜色使用

```jsx
// 主要文本
<p className="text-gray-900">主要内容</p>

// 次要文本
<p className="text-gray-600">次要内容</p>

// 辅助文本
<p className="text-gray-400">辅助说明</p>

// 禁用文本
<p className="text-gray-300">禁用状态</p>
```

---

## 间距系统

### 基础间距单位

基于 **8px** 网格系统，所有间距应为 8 的倍数。

| 名称 | 数值 | Tailwind Class | 用途 |
|------|------|----------------|------|
| xs | 4px | `space-1` / `p-1` / `m-1` | 紧凑间距 |
| sm | 8px | `space-2` / `p-2` / `m-2` | 小间距 |
| md | 16px | `space-4` / `p-4` / `m-4` | 标准间距 |
| lg | 24px | `space-6` / `p-6` / `m-6` | 大间距 |
| xl | 32px | `space-8` / `p-8` / `m-8` | 超大间距 |
| 2xl | 48px | `space-12` / `p-12` / `m-12` | 区块间距 |

### 间距使用场景

1. **组件内边距**: 通常使用 12px (p-3) 或 16px (p-4)
2. **组件外边距**: 标准使用 16px (m-4) 或 24px (m-6)
3. **区块间距**: 使用 32px (mb-8) 或 48px (mb-12)
4. **栅格间距**: 标准使用 16px 或 24px

---

## 组件规范

### 按钮 (Button)

#### 类型与场景

```jsx
import { Button } from 'antd';

// 主要按钮 - 用于主要操作
<Button type="primary">确定</Button>

// 次要按钮 - 用于次要操作
<Button>取消</Button>

// 文本按钮 - 用于辅助操作
<Button type="text">详情</Button>

// 链接按钮 - 用于跳转
<Button type="link">查看更多</Button>

// 危险按钮 - 用于删除等危险操作
<Button danger>删除</Button>
```

#### 尺寸规范

- **Large**: 高度 40px，用于页面主要操作
- **Middle**: 高度 32px，默认尺寸
- **Small**: 高度 24px，用于紧凑场景

#### 使用规范

1. 一个操作区域最多只有一个主要按钮
2. 按钮文字应简洁明确，建议不超过 4 个字
3. 危险操作必须使用二次确认
4. 按钮组内按钮间距为 8px

### 表单 (Form)

#### 布局规范

```jsx
import { Form, Input } from 'antd';

<Form layout="vertical" className="max-w-2xl">
  <Form.Item
    label="用户名"
    name="username"
    rules={[{ required: true, message: '请输入用户名' }]}
  >
    <Input placeholder="请输入用户名" />
  </Form.Item>
</Form>
```

#### 表单规范

1. **标签对齐**: 默认使用垂直布局 (vertical)
2. **必填标识**: 使用红色星号 (*) 标识
3. **字段宽度**: 根据内容长度设置合理宽度
4. **错误提示**: 实时验证，错误信息显示在字段下方
5. **表单间距**: 表单项之间间距 24px

### 表格 (Table)

#### 基础配置

```jsx
import { Table } from 'antd';

<Table
  columns={columns}
  dataSource={data}
  pagination={{
    pageSize: 10,
    showSizeChanger: true,
    showQuickJumper: true,
    showTotal: (total) => `共 ${total} 条`,
  }}
  scroll={{ x: 1200 }}
/>
```

#### 表格规范

1. **分页**: 默认每页 10 条，提供分页器
2. **行高**: 标准行高 54px (middle 模式)
3. **操作列**: 固定在右侧，宽度根据操作数量调整
4. **空状态**: 使用统一的空状态提示
5. **加载状态**: 使用 loading 属性显示加载状态

### 卡片 (Card)

```jsx
import { Card } from 'antd';

<Card
  title="卡片标题"
  extra={<Button type="link">更多</Button>}
  className="mb-4"
>
  <p>卡片内容</p>
</Card>
```

#### 卡片规范

1. **内边距**: 标准 24px
2. **圆角**: 8px (rounded-lg)
3. **阴影**: 默认使用 `shadow-sm`
4. **间距**: 卡片之间间距 16px

---

## 布局规范

### 页面布局结构

```
┌─────────────────────────────────────┐
│           Header (64px)              │
├─────────────────────────────────────┤
│ Sider │      Content Area            │
│ (200px)│                             │
│        │                             │
│        │                             │
└─────────────────────────────────────┘
```

### 栅格系统

采用 24 栏栅格系统，基于 Ant Design Grid 组件。

```jsx
import { Row, Col } from 'antd';

<Row gutter={[16, 16]}>
  <Col xs={24} sm={12} md={8} lg={6} xl={4}>
    内容
  </Col>
</Row>
```

### 布局规范

1. **页面内边距**: 24px
2. **内容最大宽度**: 1200px (根据实际需求调整)
3. **侧边栏宽度**: 200px (收起后 64px)
4. **顶部导航高度**: 64px
5. **栅格间距**: 水平 16px，垂直 16px

---

## 交互规范

### 反馈

#### 全局提示 (Message)

```jsx
import { message } from 'antd';

// 成功提示
message.success('操作成功');

// 错误提示
message.error('操作失败，请重试');

// 警告提示
message.warning('请注意数据安全');

// 加载提示
const hide = message.loading('加载中...');
```

#### 通知提醒 (Notification)

```jsx
import { notification } from 'antd';

notification.open({
  message: '系统通知',
  description: '您有新的消息，请及时查看',
  duration: 4.5,
});
```

#### 模态对话框 (Modal)

```jsx
import { Modal } from 'antd';

// 确认对话框
Modal.confirm({
  title: '确认删除',
  content: '删除后数据无法恢复，确定要删除吗？',
  okText: '确定',
  cancelText: '取消',
  onOk() {
    // 处理确认
  },
});
```

### 加载状态

1. **局部加载**: 使用 Spin 组件
2. **按钮加载**: 设置 loading 属性
3. **页面加载**: 骨架屏 (Skeleton)
4. **表格加载**: Table 的 loading 属性

### 动画效果

1. **过渡时间**: 标准 300ms
2. **缓动函数**: ease-in-out
3. **使用场景**: 展开/收起、显示/隐藏、页面切换

---

## 响应式设计

### 断点定义

| 断点 | 屏幕宽度 | 设备类型 | Tailwind 前缀 |
|------|----------|----------|---------------|
| xs | < 576px | 手机竖屏 | - |
| sm | ≥ 576px | 手机横屏 | `sm:` |
| md | ≥ 768px | 平板 | `md:` |
| lg | ≥ 992px | 桌面显示器 | `lg:` |
| xl | ≥ 1200px | 大桌面显示器 | `xl:` |
| 2xl | ≥ 1600px | 超大显示器 | `2xl:` |

### 响应式策略

1. **移动优先**: 先设计移动端，再扩展到桌面端
2. **弹性布局**: 使用 Flexbox 和 Grid
3. **自适应图片**: 使用相对单位和 max-width
4. **触摸友好**: 移动端可点击区域不小于 44x44px

---

## 页面模板

### 通用页面结构

```jsx
import { Layout, Breadcrumb } from 'antd';
const { Content } = Layout;

function PageTemplate() {
  return (
    <Content className="p-6">
      {/* 面包屑导航 */}
      <Breadcrumb className="mb-4">
        <Breadcrumb.Item>首页</Breadcrumb.Item>
        <Breadcrumb.Item>当前页面</Breadcrumb.Item>
      </Breadcrumb>

      {/* 页面标题区 */}
      <div className="mb-6">
        <h1 className="text-2xl font-semibold text-gray-900">页面标题</h1>
        <p className="text-sm text-gray-500 mt-1">页面描述信息</p>
      </div>

      {/* 主要内容区 */}
      <div className="bg-white rounded-lg shadow-sm p-6">
        {/* 页面内容 */}
      </div>
    </Content>
  );
}
```

### 已实现的页面模板

#### 1. 主框架页面 ✓

完整的应用框架布局，包含：
- 侧边菜单栏（支持收起/展开，两级菜单）
- 顶部导航栏（搜索、消息、用户信息）
- 内容区域（可滚动）

**详细文档**: [主框架页面设计规范](../docs/pages/main-layout.md)

**主要特性**：
- 基于 NEX Logo 的品牌配色 (#b8178d)
- 菜单数据 JSON 配置
- 响应式布局
- 徽章系统（HOT/NEW）
- 用户下拉菜单

**使用示例**：
```jsx
import MainLayout from './components/MainLayout'

function App() {
  return (
    <MainLayout>
      {/* 页面内容 */}
    </MainLayout>
  )
}
```

#### 2. 概览页 (Dashboard) ✓

数据概览页面，展示：
- 统计卡片（证书总量、资产数量等）
- 环形进度图表
- 数据走势图

**主要组件**：
- 响应式栅格布局 (Row/Col)
- 统计卡片 (Statistic)
- 进度条 (Progress)
- 图表区域

### 待完善的页面模板

后续将添加以下页面模板：

- [ ] **列表页**: 数据表格、筛选、操作
- [ ] **详情页**: 信息展示、关联数据
- [ ] **表单页**: 数据录入、验证、提交
- [ ] **设置页**: 配置管理、偏好设置

---

## 开发规范

### 代码组织

```
src/
├── components/        # 公共组件
│   ├── Button/
│   ├── Card/
│   └── ...
├── pages/            # 页面组件
│   ├── Dashboard/
│   ├── List/
│   └── ...
├── styles/           # 样式文件
│   ├── globals.css
│   └── variables.css
├── utils/            # 工具函数
└── constants/        # 常量定义
```

### 命名规范

1. **组件命名**: 大驼峰 (PascalCase)，如 `UserList`
2. **文件命名**: 与组件同名，如 `UserList.jsx`
3. **样式类命名**: 小写短横线 (kebab-case)
4. **常量命名**: 全大写下划线 (UPPER_SNAKE_CASE)

### CSS 使用规范

1. **优先使用 Tailwind**: 布局、间距、颜色等
2. **Ant Design 定制**: 通过主题配置实现
3. **自定义样式**: 仅在必要时使用，放在组件目录下

---

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2024-11-04 | 初始版本，建立基础设计规范 |
| 1.1.0 | 2024-11-04 | 更新品牌配色，完成主框架页面和概览页 |

---

## 参考资源

- [Ant Design 官方文档](https://ant.design/)
- [Tailwind CSS 官方文档](https://tailwindcss.com/)
- [React 官方文档](https://react.dev/)
- [Material Design 设计指南](https://material.io/design)

---

**维护者**: Nex Design Team
**最后更新**: 2024-11-04