Files

王冕 a27e3b8e43 feat: sync full workspace including web modules, docs, and configurations to Gitea

Optimized the root .gitignore to exclude virtual environments, node modules,
and temp folders to ensure clean and lightweight version tracking.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-09 18:12:25 +08:00

6.9 KiB

Raw Permalink Blame History

Ant Design（ANTD）设计规范

本文档汇总 Ant Design 官方设计理念 与 在本仓库（ONE-OS / web 端原型）中的落地约定。
官方参考：设计价值观 · 设计模式 · 组件总览

主题内更细的 Token 与主题说明见：axhub-make/src/themes/antd-new/DESIGN.md。

一、产品定位与适用场景

Ant Design 面向 企业级中后台：数据密集、流程复杂、角色多样。目标是 降低协作成本、保证一致性、提升交付效率。

适合	需谨慎
管理后台、运营台、审批与报表	强品牌 C 端营销页（需额外视觉体系）
表单、表格、筛选、仪表盘	与另一套 UI 库混用（易产生样式与交互冲突）
内部工具、B 端 SaaS	极简移动端 H5（可评估 Ant Design Mobile）

二、四大设计价值观（官方）

设计语言层面的「为什么这样设计」，实现组件与文档时应与之对齐。

1. 自然（Natural）

感知、行为符合用户习惯，减少刻意学习与记忆。
文案、隐喻贴近真实业务场景，避免生造概念。
动效克制，用于说明状态与空间关系，而非炫技。

2. 确定性（Certainty）

设计确定性：模式可预期（同类操作用同类组件与布局）。
实现确定性：设计 Token、组件 API 稳定，减少「同一需求多种写法」。
用户心智确定性：同一语义的按钮、颜色、反馈在全站一致。

3. 意义感（Meaning）

每个元素应有清晰目的：为何展示、为谁服务、与上下游任务的关系。
避免为填满版面而堆组件；信息层级服务于 主任务路径。

4. 生长感（Growth）

系统随业务扩展：模块、主题、国际化可演进。
优先使用 Token / ConfigProvider 扩展，而非大量硬编码覆盖组件内部样式。

三、页面与交互层面的设计原则（落地检查清单）

在画原型或写页面时，可逐条对照（与 Arco 等体系表述不同，但可并行使用）。

原则	要求
Stay on the Page	能在当前页完成的，尽量不跳转；必要时用抽屉、步骤条、标签页拆分。
React Immediately	点击、提交、加载、成功/失败要有即时可见反馈（按钮 loading、表格骨架屏、`message` 等）。
Provide an Invitation	主操作、可编辑区域通过主次按钮、留白与分组被自然发现。
Make it Direct	能直接点的不要藏三层菜单；表格行内操作与批量操作语义区分清楚。
Keep it Lightweight	同一屏信息密度可控；复杂筛选可折叠或分步；避免无意义装饰。
Use Transition	展开/收起、抽屉、模态出现与消失使用组件自带动效，保持节奏一致。

四、视觉与 Token（摘要）

详细数值与分类见 axhub-make/src/themes/antd-new/DESIGN.md。此处仅列 命名与用法约定。

1. 色彩语义

主色（Primary）：主按钮、链接、关键选中态。
功能色：Success / Warning / Error / Info 仅表达对应语义，不混用作装饰。
中性色：标题、正文、次要说明、边框、背景层级与 antd 文字色阶梯对齐。

2. 间距与布局

以 4px 基准网格 思考间距；列表、表单优先用 Space、Row/Col 而非零散 margin。
使用 24 栅格 做响应式分栏；断点含义与 antd 文档一致。

3. 字体与层级

正文默认 14px；标题用 Typography.Title 层级，避免随意放大字号破坏韵律。
辅助说明可用 12px 次要色，但需保证对比度与可读性。

4. 圆角与层级

控件与卡片圆角与主题 Token 一致；弹层类（Modal、Dropdown）阴影强于内容区卡片，体现 Z 轴层级。

五、组件选用与反馈层级

1. 反馈方式选择

场景	推荐
操作成功/失败一句话	`message`
需稍后查看或带标题的通告	`notification`
需用户明确确认或中断流程	`Modal` / `Popconfirm`
复杂表单、多步编辑、详情+编辑	`Drawer` 或独立页
行内轻确认	`Popconfirm`

原则：能不打断主流程就不弹 Modal；全局提示不要过于频繁堆叠。

2. 表单

使用 Form 管理字段、校验与提交；标签、必填星号、错误信息与 antd 默认模式一致。
长表单：分组（Divider / 卡片）、分步（Steps）或分 Tab，避免单屏过长。

3. 表格

小数据：常规分页即可。
大数据：虚拟滚动、列固定、合理 scroll；避免无分页的一次性超大渲染。
操作列：主次分明（主操作用 Button type="link" 或主色按钮，危险操作用 danger + 二次确认）。

4. 按钮语义

类型	用途
`primary`	每区块/每弹窗唯一主路径提交或强引导
`default`	次要操作
`dashed`	添加、可选扩展
`link`	表格行内、弱干扰文字链
`text`	工具栏内轻量操作

六、无障碍与国际化（建议）

键盘：焦点顺序合理，Modal 打开后焦点 trap；可交互元素可被 Tab 聚焦。
颜色：不单独依赖颜色传达状态（配合图标、文案）。
文案：按钮与标题用 动词或动宾结构（如「设为已读」「导出报表」）；错误信息说明原因与下一步。
国际化：面向多语言时避免写死拼接顺序，使用参数化文案；日期数字格式交给 ConfigProvider locale。

七、在本项目中的开发约定（web 端 JSX 原型）

入口：通过 window.antd 取组件时，保持与官方 API 一致，避免魔改组件封装导致文档与代码脱节。
主题：全局主题以 ConfigProvider + Token 为准；局部特殊色尽量与 Token 映射一致，减少 # 硬编码。
样式覆盖：优先 className + 外层布局控制；避免对 .ant-* 大段 !important。
一致性：同一业务场景（如列表筛选、详情抽屉）在不同页面复用相同结构与组件组合，便于用户形成习惯。

八、文档与协作

新增复杂页：在原型或 PR 中说明 主任务、信息架构、关键反馈 与本文档哪几条原则对应。
与设计师对齐时：以 antd 组件名为沟通基准，减少「自定义组件名」与实现不一致。

九、延伸阅读

定制主题
从 v4 到 v5（若仓库存在混版本引用）
仓库内主题细则：axhub-make/src/themes/antd-new/DESIGN.md

6.9 KiB Raw Permalink Blame History Unescape Escape