From 728d9592aab494290a981d70ab28ba92e91153e7 Mon Sep 17 00:00:00 2001 From: dengfuping Date: Tue, 21 Jan 2025 14:25:01 +0800 Subject: [PATCH] feat(docs): Add 11 docs for design foundation and principles --- .dumi/hooks/useMenu.tsx | 69 ++++- .dumi/theme/slots/Sidebar/index.tsx | 4 + ...art-classification-palette-design-guide.md | 12 +- docs/spec/avoid-error.md | 40 +++ docs/spec/button-layout.md | 161 +++++++++++ docs/spec/chart-color.md | 5 +- docs/spec/collapse.md | 204 ++++++++++++++ docs/spec/data-format.md | 138 +++++++++ docs/spec/effective-feedback.md | 70 +++++ docs/spec/efficient.md | 72 +++++ docs/spec/i18n.md | 56 ++++ docs/spec/language-symbol.md | 176 ++++++++++++ docs/spec/loading.md | 5 +- docs/spec/navigation.md | 5 +- docs/spec/obvious.md | 97 +++++++ docs/spec/page-container.md | 5 +- docs/spec/product-graphic.md | 5 +- docs/spec/product-icon.md | 5 +- docs/spec/radius.md | 3 +- docs/spec/shadow.md | 3 +- docs/spec/system-color.md | 5 +- docs/spec/text-truncation.md | 172 ++++++++++++ docs/spec/typography.md | 3 +- docs/spec/ux-writing.md | 265 ++++++++++++++++++ 24 files changed, 1548 insertions(+), 32 deletions(-) create mode 100644 docs/spec/avoid-error.md create mode 100644 docs/spec/button-layout.md create mode 100644 docs/spec/collapse.md create mode 100644 docs/spec/data-format.md create mode 100644 docs/spec/effective-feedback.md create mode 100644 docs/spec/efficient.md create mode 100644 docs/spec/i18n.md create mode 100644 docs/spec/language-symbol.md create mode 100644 docs/spec/obvious.md create mode 100644 docs/spec/text-truncation.md create mode 100644 docs/spec/ux-writing.md diff --git a/.dumi/hooks/useMenu.tsx b/.dumi/hooks/useMenu.tsx index 687507cab..aa3ef3d61 100644 --- a/.dumi/hooks/useMenu.tsx +++ b/.dumi/hooks/useMenu.tsx @@ -4,6 +4,7 @@ import { Link, useFullSidebarData, useSidebarData } from 'dumi'; import React, { useMemo } from 'react'; import useLocation from './useLocation'; import useSiteToken from './useSiteToken'; +import { ISidebarGroup } from 'dumi/dist/client/theme-api/types'; export interface UseMenuOptions { before?: React.ReactNode; @@ -44,6 +45,55 @@ const useMenu = (options: UseMenuOptions = {}): [MenuProps['items'], string] => } } + const getChildItems = (group: ISidebarGroup) => { + const childrenGroup = group.children.reduce< + Record[number]['children']> + >((childrenResult, child) => { + const type = (child.frontmatter as any).type ?? 'default'; + if (!childrenResult[type]) { + childrenResult[type] = []; + } + childrenResult[type].push(child); + return childrenResult; + }, {}); + const childItems = []; + childItems.push( + ...(childrenGroup.default?.map(item => ({ + label: ( + + {before} + {item?.title} + {after} + + ), + key: item.link.replace(/(-cn$)/g, ''), + })) ?? []) + ); + Object.entries(childrenGroup).forEach(([type, children]) => { + if (type !== 'default') { + childItems.push({ + type: 'group', + label: type, + key: type, + children: children?.map(item => ({ + label: ( + + {before} + {item?.title} + {after} + + ), + key: item.link.replace(/(-cn$)/g, ''), + children: getChildItems(item), + })), + }); + } + }); + return childItems; + }; + + console.log(sidebarItems); + return ( sidebarItems?.reduce>((result, group) => { if (group?.title) { @@ -52,11 +102,11 @@ const useMenu = (options: UseMenuOptions = {}): [MenuProps['items'], string] => const childrenGroup = group.children.reduce< Record[number]['children']> >((childrenResult, child) => { - const type = (child.frontmatter as any).type ?? 'default'; - if (!childrenResult[type]) { - childrenResult[type] = []; + const subGroup = (child.frontmatter as any).subGroup ?? 'default'; + if (!childrenResult[subGroup]) { + childrenResult[subGroup] = []; } - childrenResult[type].push(child); + childrenResult[subGroup].push(child); return childrenResult; }, {}); const childItems = []; @@ -72,12 +122,11 @@ const useMenu = (options: UseMenuOptions = {}): [MenuProps['items'], string] => key: item.link.replace(/(-cn$)/g, ''), })) ?? []) ); - Object.entries(childrenGroup).forEach(([type, children]) => { - if (type !== 'default') { + Object.entries(childrenGroup).forEach(([subGroup, children]) => { + if (subGroup !== 'default') { childItems.push({ - type: 'group', - label: type, - key: type, + label: subGroup, + key: subGroup, children: children?.map(item => ({ label: ( @@ -92,6 +141,7 @@ const useMenu = (options: UseMenuOptions = {}): [MenuProps['items'], string] => } }); result.push({ + type: 'group', label: group?.title, key: group?.title, children: childItems, @@ -145,6 +195,7 @@ const useMenu = (options: UseMenuOptions = {}): [MenuProps['items'], string] => }, []) ?? [] ); }, [sidebarData, fullData, pathname, search, options]); + console.log(menuItems); return [menuItems, pathname]; }; diff --git a/.dumi/theme/slots/Sidebar/index.tsx b/.dumi/theme/slots/Sidebar/index.tsx index f6e1de493..144f7a29e 100644 --- a/.dumi/theme/slots/Sidebar/index.tsx +++ b/.dumi/theme/slots/Sidebar/index.tsx @@ -51,6 +51,10 @@ const useStyle = () => { > ${antCls}-menu-item-group > ${antCls}-menu-item-group-list > ${antCls}-menu-item, + > ${antCls}-menu-item-group + > ${antCls}-menu-item-group-list + > ${antCls}-menu-submenu + > ${antCls}-menu-submenu-title, &${antCls}-menu-inline > ${antCls}-menu-item-group > ${antCls}-menu-item-group-list diff --git a/docs/blog/chart-classification-palette-design-guide.md b/docs/blog/chart-classification-palette-design-guide.md index 59ae6c089..92bc59919 100644 --- a/docs/blog/chart-classification-palette-design-guide.md +++ b/docs/blog/chart-classification-palette-design-guide.md @@ -190,11 +190,11 @@ OBUI 主题色是在 logo 品牌色的基础上做了微调，以便于适应工
-
图1
+
图1
-
图2
+
图2
@@ -203,17 +203,17 @@ OBUI 主题色是在 logo 品牌色的基础上做了微调，以便于适应工
-
图3
+
图3
-
图4
+
图4
- +
-
完整色板
+
完整色板
### 可读性验证 diff --git a/docs/spec/avoid-error.md b/docs/spec/avoid-error.md new file mode 100644 index 000000000..fc00f2375 --- /dev/null +++ b/docs/spec/avoid-error.md @@ -0,0 +1,40 @@ +--- +group: Design Principles 设计原则 +title: 避免出错 +order: 3 +--- + +当用户进行操作时，通过提供合理的约束和前置性检查、操作风险确认等手段，有效避免操作失误的发生，帮助用户顺畅完成任务。 + +## 合理约束 + +对操作行为施加必要的约束，来减少错误的可能性。如输入验证码时，通过6位数字输入框，避免用户输入位数出现偏差；禁用或隐藏不可用选项，避免用户点击后没反应或出现异常报错。 + +
+
+ +
避免用户输入位数出现偏差
+
+
+ +
避免用户点击后没反应或出现异常报错
+
+
+ +## 合理性检查 + +对用户输入内容进行验证，及时反馈错误并提供纠错帮助。例如在表单提交时，检查用户输入是否符合要求，如果存在错误及时提示用户修改。 + +
+ +
+
+ +## 风险确认 + +针对存在风险和不可撤销的危险场景提供操作确认，需要明确说明操作所带来的后续影响，为用户提供预期，同时减少出错几率，避免遭受不必要的损失。 + +
+ +
+
diff --git a/docs/spec/button-layout.md b/docs/spec/button-layout.md new file mode 100644 index 000000000..d1012069c --- /dev/null +++ b/docs/spec/button-layout.md @@ -0,0 +1,161 @@ +--- +group: Design Foundation 设计基础 +subGroup: Interaction 交互 +title: Button Layout 按钮布局 +order: 16 +--- + +按钮通常会成组出现，根据用户的阅读顺序确定按钮组位置及按钮组内主次按钮的排列顺序，能够确保按钮及时出现在用户需要的位置。 + +## 设计理念 + +按钮组在页面中的位置，及按钮组内主次按钮的排列顺序，应该根据不同场景中用户的信息浏览动线而定，确保按钮组能够出现在用户需要的地方，同时用户最需要的按钮（主按钮）能够第一时间被看到。 + +## 设计方法 + +基于「Z 模式」、「F 模式」2 种模式进行按钮组设计： + +
+
+ Z 模式 + +
适用于信息量少或信息无固定阅读顺序的场景。这种场景中用户视线遵循古腾堡原则，视线终点会停留在区块的右下角
+
+
+ F 模式 + +
适用于信息量大且信息需要遵循既定阅读顺序的场景。用户视线会跟随行文顺序进行流转，视线终点会停留在内容的结尾
+
+
+ +## Z 模式 + +按钮组位于区块右下角，主按钮居右。 + +
+ +
1. 按钮组
+
+ +### 按钮组 + +按钮按照重要程度从右到左依次排序：主按钮、次按钮。 + +
+
+ +
+
按钮组中支持放置多个按钮，建议不超过3个按钮
+
+
+ +
+
避免将按钮放置到弹窗左下角
+
+
+ +### 应用场景 + +Z 模式多用在反馈类容器和筛选卡片容器中。 + +
+
+ +
对话框
+
+
+ +
气泡确认框
+
+
+ +
+ +
+
+ +
筛选卡片
+
+
+ +
筛选卡片
+
+
+ +## F 模式 + +按钮组置于用户浏览路径中，主按钮居左。根据重要程度从左到右依次排序：主按钮、次按钮、图标按钮。 + +
+ +
+ 1. 标题区
+ 2. 内容区
+ 3. 页脚区 +
+
+ +### 标题区 + +页面级按钮组，执行页面级变更操作，位于一级标题右侧。 + +
+ +
+
+ +### 内容区 + +区块级按钮组，执行区块级变更操作，功能位置。 + +
+
+ +
用户浏览路径为从左到右时，按钮组置于操作对象右侧。
+
+
+ +
用户浏览路径为从上到下时，按钮组置于操作对象下方。
+
+
+ +### 页脚区 + +放置全局变更操作。 + +
+
+ +
主按钮居左。按钮组中按钮之间不存在逻辑关系时，默认主按钮居左。
+
+
+ +
主按钮根据按钮逻辑顺序排列。当按钮组中按钮存在逻辑关系时，可以根据逻辑关系进行排序，其中推荐的操作按钮作为主按钮。
+
+
+ +### 应用场景 + +
+
+ +
空页面
+
+
+ +
列表页
+
+
+ +
+ +
+
+ +
表单页
+
+
+ +
抽屉
+
+
diff --git a/docs/spec/chart-color.md b/docs/spec/chart-color.md index 1a2221c95..fb3da8438 100644 --- a/docs/spec/chart-color.md +++ b/docs/spec/chart-color.md @@ -1,7 +1,8 @@ --- -group: Color 色彩 -order: 2 +group: Design Foundation 设计基础 +subGroup: Color 色彩 title: Chart color 图表色彩 +order: 10 --- 图表是用户与复杂数据交流的可视化工具，图表可以通过颜色来区分不同数据类型或突出关键信息。 diff --git a/docs/spec/collapse.md b/docs/spec/collapse.md new file mode 100644 index 000000000..2abd9a012 --- /dev/null +++ b/docs/spec/collapse.md @@ -0,0 +1,204 @@ +--- +group: Design Foundation 设计基础 +subGroup: Interaction 交互 +title: Collapse 信息折叠 +order: 15 +--- + +页面中空间有限，但出现复杂、相同类型、但可收纳信息时，使用折叠面板进行信息的整合及收拢，实现页面空间的释放，并减少页面的滚动。 + +## 设计原则 + +- 清晰：通过收起页面中使用场景较少，重要度低的信息，帮助用户关注页面重点，并提供清晰的阅读顺序 +- 可扩展：为信息，容器提供上下拓展的功能，增强页面信息的空间性及容纳度，为用户减少页面的不必要的上下滚动 + +## 信息折叠 + +以标题为指引，收起非必要信息；使用场景有：卡片、非默认配置项、列表等。 + +- 内容信息可被标题统一概括 +- 收起时标题位置不变，仅内容被折叠 + +
+ +
+ 1. 图标
+ 2. 标题
+ 3. 内容 +
+
+ +### 图标 + +使用实心箭头（Gray 6）作为折叠图标，位于标题左侧，阐述内容展开/收起的状态。 + +
+
+ +
+
收起时箭头方向朝右
+
+
+ +
+
内容展开时箭头方向朝下
+
+
+
+
+
+ +
+
避免收起状态图标方向朝上；避免使用状态色
+
+
+ +
+
若配置无需手动启动/关闭，默认可加载，仅作为次级信息进行收起，避免使用开关代替折叠面板
+
+
+ +### 标题 + +使用名词作为标题，对展开内容进行概括，需简短且清晰。 + +
+
+ +
+
使用名词作为标题
+
+
+ +
+
避免使用过长的动词语句
+
+
+ +### 内容区 + +折叠内容可为纯文字，表单，图表，不作限制。 + +
+
+ +
+
折叠内容为文字信息
+
+
+ +
+
折叠内容为配置项
+
+
+ +## 按钮折叠 + +以具体行动为指引，用于收起文字，卡片容器等内容。 + +- 按钮以行动为指引，无需对内容进行概括 +- 收起后按钮位置随着内容自适应 + +
+ +
+ 1. 图标（可选）
+ 2. 行动文案 +
+
+ +### 图标（可选） + +
+
+ +
+
收纳纯文字信息时，按钮紧跟文字末尾，不需显示图标
+
+
+ +
+
避免在文字中使用图标
+
+
+
+
+
+ +
+
收纳卡片内容时，需展示图标，图标位于行动文案左侧
+
+
+ +
+
避免将图标位于行动文案右侧，易于下拉菜单交互混淆
+
+
+
+
+
+ +
+
图标方向应与文案保持一致
+
+
+ +
+
避免图标交互与文案不一致
+
+
+ +### 行动文案 + +文案应与图标方向保持一致，以行动为引导。 + +
+
+ +
+
文案与图标方向，后续交互行为保持一致
+
+
+ +
+
避免使用内容概括作为文案
+
+
+ +## 使用格式 + +数据库场景中相关格式说明。 + +### 对齐 + +展开后内容文字应与标题左对齐。 + +
+
+ +
+
+
+ +
+
避免文字与图标对齐
+
+
+ +## 使用案例 + +数据库场景中折叠面板使用的典型场景。 + +### 列表 + +
+ +
+
+ +### 表格 + +
+ +
+
diff --git a/docs/spec/data-format.md b/docs/spec/data-format.md new file mode 100644 index 000000000..a56bc3044 --- /dev/null +++ b/docs/spec/data-format.md @@ -0,0 +1,138 @@ +--- +group: Design Foundation 设计基础 +subGroup: Communication 交流 +title: Data format 数据格式 +order: 19 +--- + +基于软件国际化（i18n）要求, 所定义的OB系统中不同类型数字和语言数据的呈现格式。 + +## 日期 + +| 单位 | 如何显示 | 中文 | 英文 | +| ---------- | -------------- | ---------- | ---------- | +| 月，日，年 | 显示日期和年份 | 2012-01-14 | 01/04/2012 | + +## 时间 + +| 单位 | 如何显示 | 中文 | 英文 | +| --- | --- | --- | --- | +| 24小时时钟 | 不显示上下午信息（AM/PM） | 14:00 | | +| 预估时间 | 四舍五入到最大和最近的日期或时间 | 5分钟内
3天前 | In 5 mintues
3 days ago | +| 绝对时间 | 显示具体日期或时间 | 2012-01-14 10:00 | 01/04/2012 10:00 | + +## 日期范围 + +| 范围 | 如何显示 | 中文 | 英文 | +| ---- | ---------------------- | ------------------------ | ------------------------ | +| 年 | 在开头和结尾都显示年份 | 2024-09-02 ～ 2024-10-12 | 09/02/2024 ～ 10/12/2024 | +| 时间 | 以24小时制显示 | 11:00 - 14:30 | 11:00 - 14:30 | + +## 时区 + +统一以 UTC 为单位呈现时间地区的偏移，UTC 非必要信息，可基于场景定义此信息是否显示。若显示，时间需以数据格式 yyyy-mm-dd 或 mm/dd/yyyy 呈现，时区信息以括号（UTC + X ）形式呈现在时间数据右侧。 + +
+
+ +
+
显示时区偏移信息时，日期时间需使用数据格式
+
+
+ +
+
+
+ +## 货币符号 + +英文站中，始终以【货币符号 + 货币数字】方式显示货币，符号放在数值前面。 + +
+
+ +
+
+
+ +
+
+
+ +## 数字、电话号码 + +数字及电话应该始终以数字显示，不用文本代替。 + +
+
+ +
+
+
+ +
+
+
+ +## 地址 + +英文书写顺序由小到大：房间号、楼层、楼号、道路、地区、市、省、国家；中文则相反。 + +
+
+ +
+
+
+ +
+
+
+ +## 品牌图标 + +UI组件中， 若使用品牌图标，图标需与文案分离显示；文案与图标不可同时存在于一张图片中。 + +
+
+ +
+
+
+ +
+
+
+ +## 数据脱敏 + +### 邮箱 + +用「\*」在 @ 前代表需要脱敏的邮箱信息。 + +
+
+ +
+
+
+ +
+
避免用省略号显示脱敏信息
+
+
+ +### 银行卡 + +信用卡和借记卡数据使用4个中线修订符\[····] 脱敏显示。 + +
+
+ +
+
+
+ +
+
+
diff --git a/docs/spec/effective-feedback.md b/docs/spec/effective-feedback.md new file mode 100644 index 000000000..3758ab030 --- /dev/null +++ b/docs/spec/effective-feedback.md @@ -0,0 +1,70 @@ +--- +group: Design Principles 设计原则 +title: 有效反馈 +order: 4 +--- + +## 及时恰当的反馈结果 + +通过恰当的反馈形态、简明扼要的反馈内容，告知用户操作结果，在反馈形态上，能在界面上展示就不用弹窗、能用非模态弹窗就不要用模态弹窗，避免过度反馈给用户带来不必要的干扰。 + +### 实时成功反馈，原地反馈优于消息通知反馈 + +实时成功的结果反馈，优先通过界面元素状态的变化进行反馈。如数据库创建成功的反馈，可省略全局性的反馈提示，通过列表新增数据行来告知用户结果。 + +
+
+ +
+
+
+ +
+
+
+ +### 异步结果反馈，提供全局通知 + +当系统执行耗时过长，用户需待其完成并进行后续任务时，在任务完成后提供全局性通知，告知用户结果并邀请用户继续完成后续任务。 + +
+ +
+
+ +## 告知任务进度状态 + +不确定性会引发焦虑，因此在操作过程中应尽可能向用户提供明确的信息。对于操作步骤长的任务，需要清楚告知用户他们当前所处的位置及下一步应进行的操作。 对于系统执行耗时较长的操作，除了提供系统执行状态提示外，还应告知用户预计耗时，以帮助用户建立合理的预期，从而缓解等待期间的焦虑。 + +### 提供步骤导航 + +通过分步导航，清晰展示用户当前所处位置和所需完成的步骤。 + +
+
+ +
+
+
+ +
+
+
+ +### 提供预计耗时提示 + +当任务执行耗时较长时，应显示预计完成时间，并随着操作的进行动态更新预计时间，以帮助用户建立合理的预期。对于时间特别长的任务，可以分阶段显示进度，并提供阶段性反馈，从而减轻用户的等待焦虑。 + +
+ +
+
+ +## 告知异常原因，帮助用户识别、诊断和恢复错误 + +错误消息应该以通俗易懂的语言（无代码）表达，准确地指出问题，并建设性地提出解决方案。 + +
+ +
+
diff --git a/docs/spec/efficient.md b/docs/spec/efficient.md new file mode 100644 index 000000000..202b60c97 --- /dev/null +++ b/docs/spec/efficient.md @@ -0,0 +1,72 @@ +--- +group: Design Principles 设计原则 +title: 高效操作 +order: 2 +--- + +通过简化产品操作流程和减少用户操作步骤等方式，提升高频场景任务完成的效率，帮助用户更快、更轻松地完成工作是提升用户体验的关键。 + +## 简化流程 + +通过整合重复步骤、缩短任务路径、减少不必要的跳转等方式，简化操作流程，提升操作效率。 + +
+
+ +
点击即编辑，减少非必要的弹窗
+
+
+ +
通过模态/非模态框，减少不必要的页面跳转
+
+
+ +## 提供快捷操作 + +针对用户高频操作的功能，可提供快捷入口、快捷键、快捷选项等方式，帮助用户提高操作效率。 + +
+
+ +
为高频操作提供快捷键
+
+
+ +
为高频输入场景提供快捷选项
+
+
+ +## 提供模板 + +通过提供模板，帮助用户快速创建对象，降低用户从头开始重复配置的操作成本。 + +
+
+ +
提供内置告警样例模板，提升告警创建效率
+
+
+ +
支持用户创建数据源模板并引用，提高配置效率
+
+
+ +## 自动化操作 + +为用户提供自动化的输入、智能生成与分析解读等能力，帮助用户减少操作需要花费的精力和时间。 + +
+
+ +
自动生成密码
+
+
+ +
通过 AI 自动生成代码
+
+
+
+
+ +
通过 AI 自动为用户分析问题
+
diff --git a/docs/spec/i18n.md b/docs/spec/i18n.md new file mode 100644 index 000000000..1a69989a9 --- /dev/null +++ b/docs/spec/i18n.md @@ -0,0 +1,56 @@ +--- +group: Design Principles 设计原则 +title: 适配国际化 +order: 5 +--- + +遵循国际化设计标准，设计出能够适应多种语言和国家地区的通用产品，以确保产品能被全球用户顺利使用。 + +## 通用的视觉元素 + +使用文化中立的颜色、图标和图像，避免使用可能引起误解或冒犯的文化特定符号。确保颜色、图像和图标在不同语言环境下具有相同的含义。 + +
+
+ +
+
+
+
+ +
+
避免使用国旗标识代表语言
+
+
+ +## 符合国际标准的数据格式 + +确保时区、日期、时间、货币、姓名、电话、地址等数据显示格式符合国际标准。 + +
+
+ +
货币符合国际化标准
+
+
+ +
时间格式适应国际化标准
+
+
+ +## 合理的界面布局 + +通过合理的布局、空间的预留、响应式规则设计，适应不同语言和屏幕尺寸，避免文字被截断或界面布局被破坏。 + +
+
+ +
+
通过合理的自适应宽度设计确保导航菜单完整显示
+
+
+ +
+
避免导航菜单出现裁剪或省略
+
+
diff --git a/docs/spec/language-symbol.md b/docs/spec/language-symbol.md new file mode 100644 index 000000000..84f0268f7 --- /dev/null +++ b/docs/spec/language-symbol.md @@ -0,0 +1,176 @@ +--- +group: Design Foundation 设计基础 +subGroup: Communication 交流 +title: Language symbol 语言符号 +order: 20 +--- + +中英文场景中数据库中常见的语言符号。 + +## 冒号 + +基于页面语言（中文/英文），使用该语言的字符符号。 + +
+
+ +
+
+
英文为语言时使用英文字符，字符后空格
+
中文为语言时使用中文字符，无需空格
+
+
+
+ +
+
+
避免使用英文符号后未空格
+
避免中文语言使用英文符号
+
+
+
+ +## 空格 + +以下场景需要在文字间使用空格： + +- 英文与非标点的中文之间需要有一个空格，例如 “创建 MySQL 数据源” +- 数字与非标点的中文之间需要有一个空格, 例如 “创建 2 个迁移任务” +- 数字与单位之间需要有一个空格，例如 ”1 GIB“ + +
+
+ +
+
数字、英文与非标点的中文之间需要有一个空格
+
+
+ +
+
避免中文中无空格直接插入数字、英文
+
+
+ +:::tips + +- 中文标点与其他字符间不加空格 +- 以下单位与数字间不使用空格： + - 秒（s） + - 百分号（%） + - 摄氏度（℃） + +::: + +
+
+ +
+
百分号与数字间不需要空格
+
+
+ +
+
+
+ +## 句号 + +对所有句子大写格式的消息、描述、公告信息，需要在文字末尾添加句号。 + +
+
+ +
+
内容需要添加标点符号
+
+
+ +
+
+
+ +
+ +
+
+ +
+
在链接文本的句子末尾使用句号，但不要在链接本身中使用句号
+
+
+ +
+
避免链接文本含有句号
+
+
+ +以下场景中不要使用句号: + +:::tips + +1. 组件标题 +2. 邮件地址 +3. 链接文本 +4. 标签 +5. 占位文字 +6. 表单 +7. 菜单选项 + +::: + +
+
+ +
+
如果网址或电子邮件地址是句子片段的一部分或单独在一行中，则不要在其后面使用句号
+
+
+ +
+
避免在网页或电子邮件地址中的末尾使用句号
+
+
+ +
+ +
+
+ +
+
若说明文字不构成句子，仅为单个名词，不添加句号
+
+
+ +
+
避免在名词补充/说明信息后增加句号
+
+
+ +
+ +
+
+ +
+
输入框内占位符使用句子大写，不添加句号
+
+
+ +
+
避免给占位符添加标点符号
+
+
+ +## 省略号 + +三个椭圆符号 \[…] 代表可用于表示未显示的字母、单词或短语信息。 + +
+
+ +
+
+
+ +
+
diff --git a/docs/spec/loading.md b/docs/spec/loading.md index 29bded74e..2ec63611f 100644 --- a/docs/spec/loading.md +++ b/docs/spec/loading.md @@ -1,7 +1,8 @@ --- -group: Interaction 交互 -order: 1 +group: Design Foundation 设计基础 +subGroup: Interaction 交互 title: Loading 系统加载 +order: 17 --- Loading 加载动画是加载数据或执行操作过程中的一种可视化表现方式，合适的加载动效有助于缓解用户的等待焦虑。 diff --git a/docs/spec/navigation.md b/docs/spec/navigation.md index dce9fa817..86a9f95f5 100644 --- a/docs/spec/navigation.md +++ b/docs/spec/navigation.md @@ -1,7 +1,8 @@ --- -group: Layout 布局 -order: 1 +group: Design Foundation 设计基础 +subGroup: Layout 布局 title: Navigation 导航 +order: 13 --- 导航是界面中的地图和路标，便于用户明确自己在系统中的位置，并能轻松找到所需功能。 diff --git a/docs/spec/obvious.md b/docs/spec/obvious.md new file mode 100644 index 000000000..1ac1da70b --- /dev/null +++ b/docs/spec/obvious.md @@ -0,0 +1,97 @@ +--- +group: Design Principles 设计原则 +title: 显而易见 +order: 1 +--- + +通过合理的信息层级设计、直白统一的概念表达、适时的前馈引导设计，让用户能够快速识别重点，看得懂产品概念，知道能做什么，找到所需内容。 + +## 层级清晰 + +通过合理的信息组织层级、交互流程和视觉层级设计，突出重要信息和操作，引导用户快速找到所需内容。 + +
+
+ +
+
通过流程优化让用户同时只聚焦在一件更重要的事情上
+
+
+ +
+
避免信息无差异展示增加用户认知负担
+
+
+ +## 简单直白 + +使用用户的语言简单直白的与用户沟通，必要的专业术语需提供解释说明。 + +
+
+ +
+
使用更直白的话语表达
+
+
+ +
+
避免非必要且无解释说明的新概念
+
+
+ +## 保持一致 + +具有相同含义的概念、相似的操作需保持一致，同时尽可能遵循用户既有的心智和使用习惯，减少用户理解和学习成本。 + +
+
+ +
+
+
+ +
+
+
+ +## 适时引导 + +当用户可能存在认知障碍时，可通过为用户提供初次体验引导、产品概念和价值说明、非可操作态原因说明等方式，为用户提供前馈引导，解答用户的疑问，帮助更快走出困境。 + +
+
+ +
为新用户提供新手旅程任务引导
+
+
+ +
利用空状态向新用户提供功能介绍
+
+
+
+
+
+ +
术语提供解释说明
+
+
+ +
利用暗提示提供引导
+
+
+ +
不可操作的功能说明禁用原因
+
+
+
+
+
+ +
说明数据输入格式要求
+
+
+ +
可能碰到问题的提供简明扼要的解释
+
+
diff --git a/docs/spec/page-container.md b/docs/spec/page-container.md index 80f5038b0..ae8fd052f 100644 --- a/docs/spec/page-container.md +++ b/docs/spec/page-container.md @@ -1,7 +1,8 @@ --- -group: Layout 布局 -order: 2 +group: Design Foundation 设计基础 +subGroup: Layout 布局 title: PageContainer 页容器 +order: 14 --- 页容器是框架中承载内容的唯一容器，与导航构成应用整体框架。 diff --git a/docs/spec/product-graphic.md b/docs/spec/product-graphic.md index dbd5af5a9..5e164cd86 100644 --- a/docs/spec/product-graphic.md +++ b/docs/spec/product-graphic.md @@ -1,7 +1,8 @@ --- -group: Icongraphy 图形 -order: 2 +group: Design Foundation 设计基础 +subGroup: Icongraphy 图形 title: Product graphic 产品缺省图 +order: 12 --- 产品缺省图是页面数据或内容缺失时的填充内容，配合文字引导用户操作，传达品牌形象，并保持用户体验的连续性。 diff --git a/docs/spec/product-icon.md b/docs/spec/product-icon.md index 33895dcf5..7a07f9480 100644 --- a/docs/spec/product-icon.md +++ b/docs/spec/product-icon.md @@ -1,7 +1,8 @@ --- -group: Icongraphy 图形 -order: 1 +group: Design Foundation 设计基础 +subGroup: Icongraphy 图形 title: Product icon 产品图标 +order: 11 --- 产品图标是一种高度概括和象征性的图形元素，用于在不同数字平台上快速传达信息、指示功能或代表应用。通过视觉简化交互过程，提升用户体验，并作为品牌识别的一部分，增强界面的美学与统一性。 diff --git a/docs/spec/radius.md b/docs/spec/radius.md index 7d15f05d0..1f784318a 100644 --- a/docs/spec/radius.md +++ b/docs/spec/radius.md @@ -1,6 +1,7 @@ --- +group: Design Foundation 设计基础 title: Radius 圆角 -order: 1 +order: 7 --- 应用于各类型组件的基准角尺寸。 diff --git a/docs/spec/shadow.md b/docs/spec/shadow.md index 998091514..e566bb6ca 100644 --- a/docs/spec/shadow.md +++ b/docs/spec/shadow.md @@ -1,6 +1,7 @@ --- +group: Design Foundation 设计基础 title: Shadow 投影 -order: 2 +order: 8 --- 阴影提供关于深度、运动方向和表面边缘的线索，一个表面的阴影是由它的高度和与其他表面的关系决定的。 diff --git a/docs/spec/system-color.md b/docs/spec/system-color.md index 9a8f6499e..5c3420367 100644 --- a/docs/spec/system-color.md +++ b/docs/spec/system-color.md @@ -1,7 +1,8 @@ --- -group: Color 色彩 -order: 1 +group: Design Foundation 设计基础 +subGroup: Color 色彩 title: System color 系统色彩 +order: 9 --- 色彩在产品中可以帮助用户建立品牌心智，也可以起到区分信息层级、传递信息状态、构建一致性的作用。 diff --git a/docs/spec/text-truncation.md b/docs/spec/text-truncation.md new file mode 100644 index 000000000..e729a22d7 --- /dev/null +++ b/docs/spec/text-truncation.md @@ -0,0 +1,172 @@ +--- +group: Design Foundation 设计基础 +subGroup: Communication 交流 +title: Text Truncation 文字截断 +order: 21 +--- + +当字符串超过容器尺寸，溢出容器时，截断或缩短内容的方式；通常，通过使用省略号（…）来完成。 + +## 设计原则 + +- 清晰：使用熟悉的符号与用户交流文字无法全部显示 +- 可扩展：一直提供用户查看被截断信息的方式 + +## 截断方法 + +共支持 2 种截断方式。 + +### 尾部截断 + +句子及文本信息无法显示完整时，在尾部以“...”的方式进行字符省略。 + +
+
+ +
+
确保所有信息在容器内显示
+
+
+ +
+
避免文字溢出容器
+
+
+ +### 中间截断 + +邮件无法显示完整时，使用中间截断的方式，为用户显示完整的域名信息。 + +
+
+ +
+
截断时保留完整的邮件域名
+
+
+ +
+
避免截断邮件域名
+
+
+ +## 截断剖析 + +用 3 个省略号（…）示意被截断的文本。 + +### 字符限制 + +截断文本时，保留不少于4个字符。在容器中的任何字符串中，如果没有足够的空间容纳完整拼写或用连字符连接的单词，考虑缩写文本。 + +
+
+ +
+
截断时至少保留 4 个字符
+
+
+ +
+
避免将“ demo1.internal-el6.satellite ”截断为“ de…
+
+
+ +### 符号限制 + +尽可能避免在标点符号之前或之后直接截断。 + +
+
+ +
+
在文字后截断
+
+
+ +
+
避免在标点后直接截断，多个符号难以分割
+
+
+ +### 扩展性 + +确保至少有一个方法供用户查看整个字符串。 + +
+
+ +
+
截断后在气泡展示完整信息
+
+
+ +
+
避免不提供查看完整信息的方式
+
+
+ +## 使用案例 + +### 导航 + +导航组件中的文字应完整展示，避免在导航项中使用缩写或截断的文本。 + +
+
+ +
+
完整显示导航文字
+
+
+ +
+
避免截断导航中的文字信息
+
+
+ +### 标题 + +定义表格列宽时应注意文字长度，不要截断列标题中的文本。 + +
+
+ +
+
标题文字应该完整显示，不被截断
+
+
+ +
+
避免以截断的方式显示标题
+
+
+ +### 链接 + +如果文本是链接的一部分，省略号也应该是链接的一部分。 + +
+
+ +
+
+
+ +
+
+
+ +### 帮助文字 + +对用户行为起到引导作用的帮助信息应完整展示，避免截断。 + +
+
+ +
+
+
+ +
+
+
diff --git a/docs/spec/typography.md b/docs/spec/typography.md index eafe5a586..baa538650 100644 --- a/docs/spec/typography.md +++ b/docs/spec/typography.md @@ -1,6 +1,7 @@ --- +group: Design Foundation 设计基础 title: Typography 字体 -order: 3 +order: 6 --- 用户通过文本来理解内容和完成工作，科学的字体系统将大大提升用户的阅读体验及工作效率。字体选择应遵循美观、清晰和好用的设计原则，保证内容的可读性和页面的整洁。 diff --git a/docs/spec/ux-writing.md b/docs/spec/ux-writing.md new file mode 100644 index 000000000..ccef1eac8 --- /dev/null +++ b/docs/spec/ux-writing.md @@ -0,0 +1,265 @@ +--- +group: Design Foundation 设计基础 +subGroup: Communication 交流 +title: UX Writing 最佳实践 +order: 18 +--- + +好的文案，应该从用户视角出发，捕捉用户核心诉求，有效传达产品功能和操作流程，帮助用户更快地完成任务。 + +## 设计原则 + +- 清晰：使用用户熟悉的语言，提供专用名词的解释及具体的行动指引 +- 简洁：使用精简且准确的语句，避免相同的词汇重复出现 +- 一致：相同操作、功能、及专有名词，在上下文中保持一致 + +## 为用户提供行动预期 + +数据库产品中，大多数操作涉及数据的修改、移除、及更新，容易对业务产生极大的影响。因此相比其他系统，操作上需要更加谨慎，从用户视角提供清晰的操作预期及提示尤为重要。明确告知可能存在的风险，可帮助用户减少出错的几率，避免遭受不必要的损失。 + +### 操作确认 + +点击按钮所触发的二次确认中，文案应注重说明操作所带来的后续影响，为用户提供预期，而非仅是重复的操作询问。 + +
+
+ +
+
清晰描述行动后所带来的影响
+
+
+ +
+
避免仅重复行动确认，却并未告知风险
+
+
+ +## 以用户价值为导向 + +在引导用户采取某个行动时，说明文字应该以用户价值为导向，告诉用户“你能从中获取什么”，为用户提供行动的动机；而不是仅说明 “我们需要你做什么” 或 “当前状态为...”。 + +### 空状态 + +当页面信息为空，需要用户采取一定行为进入下一步时，文案应： + +- 提供行动的动机 +- 说明采取行动后用户可获取的价值 +- 使用生动的语言增强引导性 +- 标题，说明文字，按钮文案间具备继承性 + +
+
+ +
+
    +
  • 以友好、清晰的行动引导用户
    • +
  • 强调使用后的价值，而非当前的状态
    • +
+
+
+ +
+
    +
  • 避免多次重复行动，却不提供行动价值
    • +
  • 避免过多描述当前状态
    • +
+
+
+ +:::tips 💡 按钮文案书写说明： + +- 以动词为开始，例如 Create Database +- 文案保持精简，控制在1至2个词 +- 每个单词均首字母大写 +- 用词引导 +- 若按钮文案中出现介词，使用以下规范： + - 介词出现在末尾，介词首字母大写，例如Save As + - 介词出现在文字中间，介词首字母小写，例如Print to File + +::: + +### 帮助文档 + +为复杂配置提供额外文档说明时，链接文案应以“用户能从中获得什么”为导向，而不是仅提供独立的文档名称。 + +
+
+ +
+
以问句交流，告知用户点击后能获取“创建同步任务”相关的信息
+
+
+ +
+
避免使用文档学名作为链接文案
+
+
+ +## 避免提供“无效”信息 + +当用户在页面中采取行动时，系统通常为用户提供引导信息，告诉用户当前行动的准确性。 + +### 占位信息 + +表单输入时，占位信息是一个为用户提供默认引导的区域。为了提升引导的有效性，书写占位引导时应注意： + +- 避免使用与标题重复的文字 +- 针对输入行为提供引导/说明 +- 使用句子大写, 只大写文本中第一个单词的首字母和其他需要大写的单词 + +
+
+ +
+
占位文字尽可能提供一些输入引导
+
+
+ +
+
避免使用与标题相同的文案
+
+
+ +### 搜索数据为空 + +当用户采取一定行为（搜索/ 点击）后，系统返回数据为空值，将对用户提供相关解释，此时文案应注意： + +- 清晰描述【什么数据】的为空以及为空的原因，例如：未有实例被创建 +- 尽可能提供改变空状态的行动引导（可选），例如：创建实例 + +
+
+ +
+
    +
  • 说明返回数据为空的原因
    • +
  • 提供获取数据的行动指引
    • +
+
+
+ +
+
    +
  • 避免使用不具体的文案
    • +
  • 避免未提供如何改善的指引或文案描述
    • +
+
+
+ +## 保持语言简洁与可读性 + +设计组件及页面交互时，组件中的语言的精简度尤为重要。大多数组件的空间有限，无法适应过长的字符；因此选用组件时，应重点关注组件内语言的长度，保持语言的精简及准确，避免使用过多不必要的动词及描述。 + +### 标签 + +产品中常使用标签交流某个信息的状态、属性、或额外信息，当使用此组件时，标签内文案应注意： + +- 不要在标签内文字后添加标点符号 +- 避免重复已知信息 +- 避免换行显示 +- 若文案过长，不建议使用标签组件 + +
+
+ +
+
标签内容应简短清晰
+
+
+ +
+
避免使用标签显示过长的文字
+
+
+ +### 表格标题 + +- 以简短的名词呈现，避免使用动词语句 +- 避免在标题直接进行数据、格式、名词的解释 +- 标题不添加冠词及标点符号，使用单词大写 + +
+
+ +
+
使用图标显示额外的解释信息
+
+
+ +
+
避免直接在标题解释名词
+
+
+ +## 全局一致的翻译规范 + +页面中的术语、相似操作的词汇，语句结构在各个产品功能中文案表述要统一，尽可能减少用户理解和学习的成本。 + +### 系统消息 + +系统对用户在页面中操作应给予及时的反馈，反馈有失败、成功、告警几种状态，书写格式以「动词+名词+成功」书写，例如 【新建数据源成功】。 + +
+
+ +
+
+
+ +
+
避免使用副词作为开头
+
+
+ +## 把“动机”说清楚 + +对于许多新增的配置，用户并不了解逻辑及价值，文案需要清楚告诉用户产品上出现的每一个选项可以用来做什么，这个新功能值得去尝试/使用的理由。 + +### 配置说明 + +当配置标题无法清晰说明使用场景时，可使用帮助信息，说明该功能配置后所带来的用户价值。 + +
+
+ +
+
与用户交流「Project」的功能价值
+
+
+ +
+
避免使用标题概述用户行动，而非行动价值
+
+
+ +## 不要让用户阅读“作文” + +系统中常需要对一个术语概念或系统逻辑进行详细的解释，大段落的说明无可避免。此时在文案设计上可通过信息分类、分行、精简的方法，降低用户的阅读成本，提升操作效率。 + +### 告警提示 + +当说明信息超过 2 点，且描述文字过长时： + +- 应使用符号进行分行说明 +- 应以结果为导向说明原因 +- 尽可能精简，避免过多使用重复的词汇与语句 + +
+
+ +
+
    +
  • 精简文字并分行说明，降低阅读成本
    • +
  • 精简多次出现且重复的名词
    • +
+
+
+ +
+
    +
  • 避免使用过长的标题
    • +
  • 避免重复出现相同名词，例如 Alert template
    • +
  • 避免在一个段落中描述多段信息
    • +
+
+