clougence/open-cdm/ui-layout-consistency

CloudDM 产品 UI 一致性规范

优先级：最高。 本规范优先于组件库默认样式、个人习惯、以及零散页面旧实现。

说明： 本文件是目标设计标准；存量页面尚未全量对齐，统一改版将另行推进。新增或改版 UI 时按本规范执行，勿复制旧页面的嵌套卡片、fixed 页脚等写法。

定位： CloudDM 是 扁平化、留白充足的编辑型 B 端 SaaS，不是卡片堆叠风、不是拟物/玻璃态、不是运营落地页。

涉及以下任一场景时，必须先阅读本 skill：

• 新增/改版 views/、components/layout/、弹窗、表单、列表、向导页
• 调整颜色、字号、间距、阴影、描边、Tab、页脚、面包屑
• 后端或协作者提交的前端 UI 改动

若改动无法在不破坏规范的前提下完成，停止提交，向用户说明具体违反项与建议改法。

Token 细节见 DESIGN.md；布局反例与代码片段见 reference.md。

0. 设计基调（必须先理解）

我们是什么风格

层次怎么建（优先级从高到低）

1. 壳层：侧栏 + 唯一浮层工作区卡片
2. 间距：4px 网格 — 8 / 16 / 24 / 32
3. 标题：page-section__title、面包屑、表头
4. 浅表面：page-aside、surface-soft（#f8fafc），无 border
5. 发丝线：仅输入框、表格、页脚顶线、可选 chip 激活态
6. 轻阴影：仅 app-main-card 外层 0 1px 3px 级别

禁止用第 5、6 项去补本可用第 2、3、4 项表达的层次。

一句话自检

拿掉所有 border 和 box-shadow 后，页面是否仍能通过留白和标题读懂结构？

若不能，先加间距/标题/浅底，而不是加线框。

1. 应用壳层（App Shell）

左侧 AppSidebar（全局导航）
└─ 右侧 app-main
   └─ app-main-card（唯一浮层卡片 — 全页唯一「容器感」）
      ├─ AppContentHeader
      │    左：页面标题 / 面包屑（业务上下文）
      │    右：系统级操作（数据查询、文档、联系我们、语言、用户）
      └─ app-main-card__body（router-view）

规则：

• 业务内容只在 app-main-card__body 内渲染。
• 禁止在 body 内再套「第二个大卡片」（白底 + 圆角 + 阴影 + 外边距 + 独立背景色）。
• 系统级操作不得与页面保存/提交按钮出现在同一视觉带。
• SQL 全屏模式是例外：独立 compact header，仍遵循扁平、少 chrome。

参考： src/views/home/index.vue、src/views/dataSource/DataSource.vue

2. 页面内结构（Page Shell）

page-shell（flex 列，height 100%，min-height 0）
├─ page-shell__body（唯一滚动区，padding 16px 24px）
└─ page-shell__footer（可选，页内主操作）

样式： src/styles/app-shell.less → .page-shell、.page-shell__footer

3. 内容分区（少线框）

app-main-card 已是唯一容器线框；内部默认无 border 分区。

page-shell__body
├─ 主列（flex column，gap: 32px）
│   ├─ page-section + page-section__title
│   └─ page-section
└─ page-aside（可选，浅底摘要/说明）

允许 border 的元素： 输入/Select、表格、分页、可选 type-card/chip、页脚顶线。 禁止： 每个 section 再包 1px solid 白底圆角盒；摘要区做成第二个线框卡片。

参考： src/views/cicd/ReleaseFlowPage.vue、src/views/dataSource/AddDataSource.vue

4. 页面类型模板

改页面前先判断类型，复用对应模板，不要发明新布局。

A. 列表页（实例、工单、角色…）

page-shell
└─ body: table-list-layout
   ├─ AppPageTabs（若有子视图）
   ├─ 工具栏（筛选左 + 主操作右，同一行）
   ├─ Table（border 由表格组件承担）
   └─ 分页 footer（表格下方，非 fixed）

• 不要给表格外再套带 shadow 的 card。
• 参考：src/views/ticket/index.vue、src/views/dataSource/DataSource.vue

B. 单页表单（新增数据源、编辑配置…）

page-shell
├─ body
│   ├─ AppPageTabs（多 panel 时）
│   ├─ page-panel-body 或 page-section
│   └─ page-aside（可选）
└─ footer: [次按钮] [主按钮]

• Tab 下无满宽灰线；仅激活 Tab 短下划线。
• 参考：src/views/dataSource/AddDataSource.vue

C. 多区块向导 / 创建流（CI/CD 创建…）

page-shell
├─ body: grid(主列 minmax(0,1fr) + page-aside 280–320px)
│   ├─ 主列：多个 page-section 纵向 gap 32px
│   └─ 侧栏：page-aside 只读摘要
└─ footer: [上一步] [下一步/提交]

• 主列区块之间 不要 再画线框；双列发布源/库配置用 grid + 标题，不用两个 bordered panel。
• 参考：src/views/cicd/ReleaseFlowPage.vue

D. 详情页（工单详情、变更流详情…）

• 头部信息用 描述列表 / 标题 + meta 行，不用大 shadow 卡片包一行字段。
• 长内容 Tab 化时用 AppPageTabs。
• 行内操作为 text-link 或 ghost 按钮，不与页级主 CTA 并列抢焦点。

E. SQL 全屏工作台

• 脱离 app-main-card 布局；header 仅品牌 + 返回工作台 + 系统操作。
• 仍保持扁平：无渐变 header、无 heavy shadow。

5. 间距与尺寸

基于 4px 网格，禁止随意 28px 32px 36px 堆叠。

禁止： body 内 margin: 20px 造第二容器；多层 padding 相加 > 48px。

6. typography 与标题

• 面包屑用 / 分隔；末级为 current，不可点。
• 禁止页面内再做一个 22px/700 的「假页面标题」与 header 重复。

7. 色彩与按钮

View UI / Ant Design 默认色 必须覆盖到 token，不要直接沿用组件库绿/蓝主色 if 与 DESIGN 冲突。

8. Tab

唯一标准： AppPageTabs（src/components/layout/AppPageTabs.vue）

• 文字 Tab + 仅激活项 底部 2px 指示线（primary 色）
• Tab 容器 无 border-bottom 满宽灰线
• 禁止页面内 <Tabs> + 大量 :deep(.ivu-tabs-*) 重皮肤
• 面板内容放 page-panel-body，padding 与 body 对齐

9. 表格与空态

• 列表优先 table-list-layout + 现有 Table 封装。
• 表格 border 由组件承担，表格外不再套 card。
• 空态：简洁文案 + 一个主 CTA，不用插图堆满卡片。
• 加载：Spin 在 page-shell__body 内居中或表格 loading，不用全屏遮罩除非阻塞提交。

10. 弹窗与抽屉

• 标题 + 内容 + footer 按钮；footer 右对齐 [取消] [确定]。
• 弹窗内 不再套 带 shadow 的大 card；表单项间距与页面一致。
• 危险操作二次确认走现有 CCModal / second-confirm-modal 模式。

11. 组件与样式来源优先级

1. src/components/layout/ — AppSidebar、AppContentHeader、AppPageTabs
2. 同类型已有页面（工单、实例、数据源、CI/CD 创建）
3. src/styles/app-shell.less + styles/variables.less
4. DESIGN.md token
5. View UI Plus / Ant Design Vue — 仅行为，样式对齐 token

不得因赶进度新建：自定义 Tab 皮肤、fixed 全屏 footer、页面级第二背景层、独立 accent-title 体系。

12. 改 UI 前的决策流程

1. 属于哪种页面类型？（列表 / 表单 / 向导 / 详情 / SQL 全屏）
   → 套用 §4 模板
 
2. 内容是否已在 app-main-card 内？
   → 否：先修正壳层
 
3. 是否需要多个视觉区块？
   → 是：page-section + gap，不用 border 卡
 
4. 是否需要侧栏摘要？
   → 是：page-aside 浅底，不用 border 卡
 
5. 主操作放哪？
   → page-shell__footer 或列表工具栏；禁止 fixed 全屏
 
6. 是否需要 Tab？
   → AppPageTabs
 
7. 拿掉 border/shadow 后结构是否仍清晰？
   → 否：加间距/标题/浅底，不加线框

13. 提交前自检清单

风格

• [ ] 扁平：无渐变 hero、无多层 shadow 卡片
• [ ] 层次靠间距/标题/浅底，不靠堆线框
• [ ] 主 CTA 只有一个，近黑 primary

壳层与布局

• [ ] 无第二个大卡片/第二背景层
• [ ] page-shell 结构正确，滚动单一路径
• [ ] 页脚在 card 内，非 fixed 全屏

组件

• [ ] Tab 用 AppPageTabs，无满宽 Tab 底边
• [ ] 区块用 page-section / page-aside
• [ ] padding/gap 在规范档位内

工程

• [ ] 文案 i18n
• [ ] 未引入新 UI 框架
• [ ] 对照参考页目视检查

任一未通过 → 中断改动，先对齐规范再继续。