# ONE-OS 全局设计规范（开发版）

| 项 | 说明 |
|---|---|
| 文档版本 | v1.0 |
| 适用范围 | Axhub Make 客户端内所有中后台列表页、台账页、运营配置页 |
| 视觉基底 | Linear 主题 **浅色 inverse** 模式 + ONE-OS 品牌绿主色 |
| 事实源 CSS | `src/prototypes/vehicle-management/style.css` |
| 列表页强制规范 | `src/prototypes/vm-shared/DESIGN.md` |
| 台账扩展规范 | `src/prototypes/ledger-shared/DESIGN.md` |

---

## 1. 设计原则

1. **一致性**：新建页面优先复用 `vm-*` 类名与公共组件，不另起一套视觉语言。
2. **信息密度适中**：列表首屏给筛选 + KPI + 表格，不在正文重复侧栏已有的大标题。
3. **可扫描**：表头弱对比、正文强对比；金额/数量用等宽数字 `tabular-nums`。
4. **可访问**：可见 focus 态、按钮/卡片可键盘操作；尊重 `prefers-reduced-motion`。
5. **左对齐数字**：金额、数量列与文本列统一左对齐，禁止右对齐金额列。

---

## 2. Design Tokens

定义于 `vehicle-management/style.css` 的 `:root`，Ant Design 页面通过 `ConfigProvider` 同步主色。

### 2.1 色彩

| Token | 值 | 用途 |
|---|---|---|
| `--ln-primary` | `#32a06e` | 主色：主按钮、选中 KPI、链接、当前页码 |
| `--ln-primary-hover` | `#3fb87c` | 主色悬停 |
| `--ln-primary-focus` | `#2b9260` | 主色按下 / 选中文字 |
| `--ln-primary-soft` | `rgba(50,160,110,0.1)` | 浅色选中底、选项高亮 |
| `--ln-ink` | `#18181b` | 标题、强调正文 |
| `--ln-body` | `#52525b` | 正文 |
| `--ln-muted` | `#71717a` | 次要文字、表头 |
| `--ln-muted-soft` | `#a1a1aa` | 占位符、弱图标 |
| `--ln-canvas-parchment` | `#f5f6f6` | 页面背景 |
| `--ln-surface-card` | `#ffffff` | 卡片、输入框、表格容器 |
| `--ln-canvas-soft` | `#f6f7f7` | 表头底、行 hover、次级表面 |
| `--ln-hairline` | `#e5e7eb` | 卡片边框、分割线 |
| `--ln-hairline-strong` | `#d4d4d8` | 输入框边框、分页按钮边框 |
| `--ln-success` | `#27a644` | 成功态 |
| `--ln-warning` | `#d97706` | 警告态 |
| `--ln-error` | `#e5484d` | 错误、删除、欠费强调 |
| `--ln-on-primary` | `#ffffff` | 主色按钮文字 |

### 2.2 字体

| 角色 | 值 |
|---|---|
| 正文字体 `--vm-font` | Inter, -apple-system, BlinkMacSystemFont, "SF Pro Display", "PingFang SC", "Microsoft YaHei", sans-serif |
| 等宽 `--vm-font-mono` | ui-monospace, JetBrains Mono, SFMono-Regular, Menlo, Consolas, monospace |
| 数字/金额 | 使用 `--vm-font-mono` + `tabular-nums`（全局见 `src/common/ln-numeric.css`，对齐 `.vm-expire-date`） |
| 金额格式 | `src/common/format-number.js`（千分位 + 2 位小数；Legacy 页可用 `window.__oneosFormatMoney`） |
| 页面基础字号 | `0.875rem`（14px） |
| 筛选标签 | `0.75rem` / 500 |
| 表头 | `0.75rem` / 500 |
| 表格单元格 | `0.8125rem`（13px） |
| 筛选卡片标题 | `1.125rem` / 600 |

### 2.3 圆角

| Token | 值 | 用途 |
|---|---|---|
| `--ln-radius-xs` | 4px | 小提示、图标按钮 |
| `--ln-radius-sm` | 6px | 多选框 |
| `--ln-radius-control` | 8px | 按钮、输入框、分页 |
| `--ln-radius-card` | 12px | 筛选卡、表格卡、KPI 卡 |
| `--ln-radius-xl` | 16px | 大面板 |
| `--ln-radius-pill` | 9999px | 徽章、胶囊 |

### 2.4 间距与尺寸

| Token | 值 | 用途 |
|---|---|---|
| 页面内边距 | `24px 32px 32px`（≤640px 为 16px） |
| 筛选卡片内边距 | `24px`（紧凑模式 16–20px） |
| 筛选栅格间距 | `16px 20px` |
| 区块垂直节奏 | 筛选 / KPI / 工具栏 / 表格之间约 **16–20px** |
| `--vm-control-height` | `32px` | 筛选输入、分页控件 |
| `--vm-btn-height` | `36px` | 按钮最小高度 |

### 2.5 阴影

| Token | 用途 |
|---|---|
| `--ln-shadow-soft` | 卡片默认 |
| `--ln-shadow-hover` | 下拉、Tooltip |
| `--ln-shadow-float` | 浮层 |
| `--ln-shadow-modal` | 弹窗 |

### 2.6 Focus 规则

- 使用 **边框变色**（`border-color: var(--vm-focus-border-color)`），不用外扩 outline 环（按钮、输入框统一）。
- 类名辅助：`.vm-focus-border:focus-visible`。

---

## 3. 页面壳层

### 3.1 标准列表页结构

```text
.vm-page                          # 页面根（必选）
├── .vm-filter-card                # 筛选区
├── .vm-kpi-row                    # KPI（可选）
└── .vm-table-section
    ├── .vm-table-toolbar          # 工具栏（右对齐操作）
    └── .vm-table-card
        ├── .vm-table-wrap         # 表格滚动区
        └── .vm-table-footer       # 底部分页
            └── <TablePagination />
```

### 3.2 页面类名扩展

| 类名 | 场景 |
|---|---|
| `vm-page` | 所有列表页基类 |
| `vm-page ldb-page` | 台账列表（租赁/维修等） |
| `vm-page lc-page` | 租赁合同 Ant Design 列表 |

### 3.3 必须引入的样式

```typescript
import '../vehicle-management/style.css';
// 台账页另加模块 styles；合同页另加 lease-contract.css
```

### 3.4 禁止

- 标准列表页在正文再放与侧栏重复的 `h1` 大标题 + 长说明段落。
- 工具栏在已有 KPI + 底部分页时重复写「共 N 条」。
- 列表主表格用「加载更多」代替分页（除非 PRD 明确排除分页）。

---

## 4. 组件规范

### 4.1 筛选区 `.vm-filter-card`

| 元素 | 类名 | 规格 |
|---|---|---|
| 容器 | `vm-filter-card` | 白底、12px 圆角、1px 边框、轻阴影 |
| 标题 | `vm-filter-title` | 「筛选条件」，1.125rem / 600 |
| 栅格 | `vm-filter-grid` | 默认 4 列；1280px 以下 2 列；640px 以下 1 列 |
| 字段 | `vm-filter-field` | 标签在上、控件在下；标签 12px / muted |
| 操作区 | `vm-filter-actions` | 顶部分割线；右对齐「重置」「查询」 |

**日期区间（强制）**

- 使用 `DateRangeFilterField`（`vehicle-management/components/DateRangeFilterField`）。
- 展示分隔符为中文「**至**」。
- 类名：`vm-date-range-field`、`vm-filter-picker-control`。
- **禁止**筛选区用 Ant `RangePicker`、双 `<input type="date">` 等替代方案。

**折叠筛选**

- 超过 4 项时其余放入 `vm-filter-expand`（见 `src/common/vm-filter-panel.ts`）。
- 切换按钮：`vm-filter-toggle` + 角标 `vm-filter-toggle-badge`。

### 4.2 输入框 `.vm-input`

| 场景 | 高度 | 字号 |
|---|---|---|
| 筛选区内 | 32px | 0.875rem |
| 表单页 | min 44px | 1rem（移动端友好） |

- 边框：`--ln-hairline-strong`；focus 时主题色边框。
- 占位符：`--ln-muted-soft`。

### 4.3 下拉选择 `.vm-filter-picker-*`

| 元素 | 说明 |
|---|---|
| `vm-filter-picker-control` | 触发器，与输入框同高 |
| `vm-filter-picker-popover` | 下拉面板，卡片圆角 + hover 阴影 |
| `vm-filter-picker-option.checked` | 主色浅底 + 深绿字 |

### 4.4 按钮 `.vm-btn`

| 变体 | 类名 | 用途 |
|---|---|---|
| 主按钮 | `vm-btn vm-btn-primary` | 查询、保存、提交 |
| 次要 | `vm-btn vm-btn-secondary` | 带边框白底 |
| 幽灵 | `vm-btn vm-btn-ghost` | 取消、重置、工具栏次要操作 |
| 文字链 | `vm-btn vm-btn-link` | 表格内操作、行内链接 |
| 返回 | `vm-btn vm-btn-back` | 表单/详情/编辑顶栏左上角；Chevron 图标 + 白底描边；hover 主色字/边框 + 浅绿底 |

**规格**：高度 36px；圆角 8px；字号 0.875rem / 500；禁用 opacity 0.5。

**弹窗底部**：次要操作用 `vm-btn-ghost`，主操作用 `vm-btn-primary`（或 Ant `Button type="primary"` 且主题色对齐）。

### 4.5 KPI 卡片 `.vm-kpi-row` / `.vm-kpi-card`

| 元素 | 说明 |
|---|---|
| 布局 | 默认 8 列网格；1600px→4 列；960px→2 列；640px→1 列 |
| 卡片 | 最小高度 88px；左图标 + 标题 + 数值 |
| 标题 | `vm-kpi-eyebrow` |
| 数值 | `vm-kpi-val`，等宽数字 |
| 说明 | 右上角 `vm-kpi-tip` + `vm-kpi-tooltip` |
| 选中 | `.active`：绿色描边 + 轻阴影；数值变 `--ln-primary-focus` |

台账扩展：`ldb-kpi-row` / `ldb-kpi-val--profit` / `ldb-kpi-val--loss`。

### 4.6 工具栏 `.vm-table-toolbar`

- 右对齐：`.vm-table-actions { margin-left: auto }`。
- 仅放：筛选开关、批量操作、新建、导入导出等。
- 不放：与分页重复的条数文案。

### 4.7 表格

#### 原生表格 `.vm-table`

| 项 | 规则 |
|---|---|
| 容器 | `vm-table-card` > `vm-table-wrap` > `vm-table` |
| 表头 | 粘性顶；背景 `--ln-canvas-soft`；文字 muted |
| 行 hover | 浅灰底；冻结列同步变色 |
| 冻结列 | `sticky-col` / `sticky-right`；台账用 `sticky-col-left` / `sticky-col-right` |
| 金额列 | `ldb-col-money` 或 `ln-modal-detail-table__money` + `tabular-nums`，**左对齐** |
| 空值 | 显示「—」或留白，不显示 undefined |

#### Ant Design Table

- 列表页类名：`vm-list-table`（随模块）。
- 弹窗内明细：`ln-modal-detail-table` + `tableLayout="fixed"` + 每列显式 `width`。
- 样式源：`src/common/modal-detail-table.css`。
- 通过全局规则覆盖 `cell-align-right` 为左对齐。

### 4.8 分页 `TablePagination`

**组件**：`src/common/TablePagination.tsx`（强制，禁止手写分页 DOM）。

**布局顺序**（从左到右）：

```text
共 {total} 条  →  上一页 / 页码 / 下一页  →  每页 N 条
```

| 项 | 值 |
|---|---|
| 默认每页 | `DEFAULT_PAGE_SIZE` = 20 |
| 标准选项 | 10 / 20 / 50 / 100 |
| 紧凑选项 | 5 / 10 / 20 / 50（`COMPACT_PAGE_SIZE_OPTIONS`） |
| 样式类 | `vm-pagination*`（`src/common/vm-pagination.css`） |
| 当前页 | `vm-pagination-page active` 主色填充 |
| 无数据 | 仍显示「共 0 条」，隐藏页码控件 |

**交互**：筛选/重置/KPI 切换/改每页条数时 `page` 重置为 1。

**紧凑 footer**：追加 `vm-table-footer--compact`（详情 Tab 内嵌表）。

### 4.9 多选框 `.vm-checkbox`

样式源：`src/common/vm-checkbox.css`。

| 场景 | 用法 |
|---|---|
| 工具栏/表单 | `input.vm-checkbox` |
| 表格勾选列 | `vm-col-check` / `ldb-col-check`；列宽 48px 居中 |
| 下拉多选面板内 | `vm-ops-picker-option` 内用原生紧凑样式（例外） |

| 状态 | 表现 |
|---|---|
| 默认 | 18×18，白底细边框 |
| 选中 | 主色底 + 白色对勾 |
| 半选 | 主色底 + 白色横线（表头全选） |
| 禁用 | opacity 45% |

### 4.10 链接与标签

| 元素 | 类名 / 说明 |
|---|---|
| 文本链接 | `vm-link`；颜色 `--ln-link` |
| VIN/编码 | `vm-vin` + mono 字体 |
| 状态标签 | Ant `Tag`；签约等用模块类如 `lc-station-signed-tag` |
| 操作列 | 文字按钮组，左对齐；删除前 `Modal.confirm` |

### 4.11 弹窗 / 抽屉

| 项 | 规则 |
|---|---|
| Ant Modal | `centered: true`；圆角 8–12px；body `maxHeight: 78vh` + 滚动 |
| 次要按钮 | `vm-btn-ghost` 或 Ant 默认 + 模块封装 `renderH2GhostButton` 等 |
| 主按钮 | 主题绿 `#32a06e` |
| 表单 | `layout="vertical"`；标签 13px / 600（模块内表单） |
| 明细表 | `ln-modal-detail-table`；见 4.7 |

### 4.12 统计卡（下钻/对账等）

模块内常用模式（非全局类名，保持视觉一致即可）：

- 白底 + 1px 边框 + 12px 圆角。
- 标签 12–13px muted；数值 加粗 + `tabular-nums`。
- 三列横排统计卡间距 12–16px。

---

## 5. Ant Design 接入

使用 Ant Design 的页面（如加氢站、租赁合同）须通过 `ConfigProvider` 对齐 token：

```typescript
const vmTheme = {
  token: {
    colorPrimary: '#32a06e',
    colorLink: '#32a06e',
    colorLinkHover: '#3fb87c',
    borderRadius: 8,
    fontFamily: 'Inter, -apple-system, ...',
    fontSize: 14,
    colorText: '#18181b',
    colorTextSecondary: '#52525b',
    colorBorder: '#e5e7eb',
    colorBgContainer: '#ffffff',
  },
  components: {
    Table: {
      headerBg: '#f6f7f7',
      headerColor: '#71717a',
      rowHoverBg: '#f6f7f7',
      borderColor: '#e5e7eb',
      cellPaddingBlock: 8,
      cellPaddingInline: 12,
    },
    Card: { borderRadiusLG: 12 },
  },
};
```

**筛选区 Ant 控件**（`lc-page` 示例）：`Select` / `DatePicker` 高度与 `vm-input` 对齐（32px），圆角 8px，边框 `--ln-hairline-strong`。

---

## 6. 响应式断点

| 断点 | 主要变化 |
|---|---|
| ≤1600px | KPI 4 列 |
| ≤1280px | 筛选 2 列；台账 KPI 6→4 列 |
| ≤960px | KPI 2 列 |
| ≤640px | 页面/筛选 padding 缩小；筛选/KPI 1 列 |

---

## 7. 动效与无障碍

| 项 | 规则 |
|---|---|
| 过渡 | 按钮/卡片 0.2s；筛选展开 0.28s |
| 减少动效 | `@media (prefers-reduced-motion: reduce)` 关闭过渡与分页缩放 |
| 分页 | `role="navigation"`、`aria-label="表格分页"`、当前页 `aria-current="page"` |
| KPI/表头提示 | 支持 focus 显示 tooltip |
| 触控 | 可点击区域建议 ≥ 44×44px（表单页输入 44px 高） |
| 图标 | 使用 Lucide / Heroicons 等 SVG，**不用 emoji 作图标** |
| 对比度 | 正文对比度 ≥ 4.5:1 |

---

## 8. 禁止做法（汇总）

- 不自建分页 UI，不用 Ant `Pagination` 替代 `TablePagination`。
- 不在 `vm-page` 内自定义 checkbox 皮肤。
- 不用 RangePicker 做筛选区日期区间。
- 不对金额列 `align: right`。
- 不在列表工具栏重复总条数。
- 不引入与 Linear/vm token 冲突的第三方分页/表格皮肤。
- 弹窗内表格须 `tableLayout="fixed"`，避免列宽错位。

---

## 9. 文件与参考实现索引

| 类型 | 路径 |
|---|---|
| 全局样式入口 | `src/prototypes/vehicle-management/style.css` |
| 分页组件 | `src/common/TablePagination.tsx` |
| 分页样式 | `src/common/vm-pagination.css` |
| 多选框样式 | `src/common/vm-checkbox.css` |
| 弹窗表格样式 | `src/common/modal-detail-table.css` |
| 日期区间组件 | `src/prototypes/vehicle-management/components/DateRangeFilterField` |
| 筛选折叠逻辑 | `src/common/vm-filter-panel.ts` |
| 列表页规范 | `src/prototypes/vm-shared/DESIGN.md` |
| 台账扩展规范 | `src/prototypes/ledger-shared/DESIGN.md` |
| 合同 Ant 对齐 | `src/prototypes/lease-contract-management/styles/lease-contract.css` |
| 参考：车辆管理 | `src/prototypes/vehicle-management/index.tsx` |
| 参考：租赁合同 | `src/prototypes/lease-contract-management/LeaseContractManagement.jsx` |
| 参考：加氢站站点 | `src/prototypes/oneos-web-h2-station/pages/03-站点信息.jsx` |
| 主题 token 来源 | `src/themes/linear/DESIGN.md`（inverse 浅色用于 vm） |

---

## 10. 新页面开发检查清单

- [ ] 根节点使用 `vm-page`（及必要的 `ldb-page` / `lc-page`）
- [ ] 已 `import` `vehicle-management/style.css`
- [ ] 筛选区使用 `vm-filter-card` + `vm-filter-grid` + `vm-filter-actions`
- [ ] 日期区间使用 `DateRangeFilterField`
- [ ] 按钮使用 `vm-btn-*` 变体
- [ ] 表格底部分页使用 `TablePagination` + `vm-table-footer`
- [ ] 金额列左对齐 + `tabular-nums`
- [ ] 多选使用 `vm-checkbox` 或勾选列约定
- [ ] Ant 页面已配置 `ConfigProvider` 主题色
- [ ] 无重复页面大标题、无重复总条数文案
- [ ] Focus 态、键盘操作、减少动效已验证

---

## 修订记录

| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-07-09 | 首版：汇总 vm-shared、ledger-shared、vehicle-management token 与组件规范 |