Merge pull request #954 from oceanbase/dengfuping-dev

feat(docs): Add 11 docs for design foundation and principles
oceanbase · Jan 21, 2025 · a23acc1 · a23acc1
2 parents 7c9f4df + 728d959
commit a23acc1
Show file tree

Hide file tree

Showing 24 changed files with 1,548 additions and 32 deletions.
diff --git 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<string, ReturnType<typeof useSidebarData>[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: (
+            <Link to={`${item.link}${search}`}>
+              {before}
+              {item?.title}
+              {after}
+            </Link>
+          ),
+          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: (
+                <Link to={`${item.link}${search}`}>
+                  {before}
+                  {item?.title}
+                  {after}
+                </Link>
+              ),
+              key: item.link.replace(/(-cn$)/g, ''),
+              children: getChildItems(item),
+            })),
+          });
+        }
+      });
+      return childItems;
+    };
+
+    console.log(sidebarItems);
+
     return (
       sidebarItems?.reduce<Exclude<MenuProps['items'], undefined>>((result, group) => {
         if (group?.title) {
@@ -52,11 +102,11 @@ const useMenu = (options: UseMenuOptions = {}): [MenuProps['items'], string] =>
             const childrenGroup = group.children.reduce<
               Record<string, ReturnType<typeof useSidebarData>[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: (
                       <Link to={`${item.link}${search}`}>
@@ -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
@@ -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
@@ -190,11 +190,11 @@ OBUI 主题色是在 logo 品牌色的基础上做了微调，以便于适应工
 <div style="display: flex">
   <div>
     <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/7JofT7KW6IQAAAAAAAAAAAAADv3-AQBr/original" />
-    <div class="image-description">图1</div>
+    <div class="image-description-center">图1</div>
   </div>
   <div>
     <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/p36BSIBT32sAAAAAAAAAAAAADv3-AQBr/original" />
-    <div class="image-description">图2</div>
+    <div class="image-description-center">图2</div>
   </div>
 </div>
 
@@ -203,17 +203,17 @@ OBUI 主题色是在 logo 品牌色的基础上做了微调，以便于适应工
 <div style="display: flex">
   <div>
     <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/e7CvTocrTR8AAAAAAAAAAAAADv3-AQBr/original" />
-    <div class="image-description">图3</div>
+    <div class="image-description-center">图3</div>
   </div>
   <div>
     <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/gBD9SK5xcjAAAAAAAAAAAAAADv3-AQBr/original" />
-    <div class="image-description">图4</div>
+    <div class="image-description-center">图4</div>
   </div>
 </div>
-
+<br />
 <div>
   <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/9_VNRJmASNIAAAAAAAAAAAAADv3-AQBr/original" />
-  <div class="image-description">完整色板</div>
+  <div class="image-description-center">完整色板</div>
 </div>
 
 ### 可读性验证

diff --git a/docs/spec/avoid-error.md b/docs/spec/avoid-error.md
@@ -0,0 +1,40 @@
+---
+group: Design Principles 设计原则
+title: 避免出错
+order: 3
+---
+
+当用户进行操作时，通过提供合理的约束和前置性检查、操作风险确认等手段，有效避免操作失误的发生，帮助用户顺畅完成任务。
+
+## 合理约束
+
+对操作行为施加必要的约束，来减少错误的可能性。如输入验证码时，通过6位数字输入框，避免用户输入位数出现偏差；禁用或隐藏不可用选项，避免用户点击后没反应或出现异常报错。
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/67k6Qo4Loe8AAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">避免用户输入位数出现偏差</div>
+  </div>
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/Fh7QQrYiQH0AAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">避免用户点击后没反应或出现异常报错</div>
+  </div>
+</div>
+
+## 合理性检查
+
+对用户输入内容进行验证，及时反馈错误并提供纠错帮助。例如在表单提交时，检查用户输入是否符合要求，如果存在错误及时提示用户修改。
+
+<div>
+  <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/JuDiSrreV2oAAAAAAAAAAAAADv3-AQBr/original" />
+  <div class="image-description-center"></div>
+</div>
+
+## 风险确认
+
+针对存在风险和不可撤销的危险场景提供操作确认，需要明确说明操作所带来的后续影响，为用户提供预期，同时减少出错几率，避免遭受不必要的损失。
+
+<div>
+  <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/C_xVR4qyzeQAAAAAAAAAAAAADv3-AQBr/original" />
+  <div class="image-description-center"></div>
+</div>
diff --git a/docs/spec/button-layout.md b/docs/spec/button-layout.md
@@ -0,0 +1,161 @@
+---
+group: Design Foundation 设计基础
+subGroup: Interaction 交互
+title: Button Layout 按钮布局
+order: 16
+---
+
+按钮通常会成组出现，根据用户的阅读顺序确定按钮组位置及按钮组内主次按钮的排列顺序，能够确保按钮及时出现在用户需要的位置。
+
+## 设计理念
+
+按钮组在页面中的位置，及按钮组内主次按钮的排列顺序，应该根据不同场景中用户的信息浏览动线而定，确保按钮组能够出现在用户需要的地方，同时用户最需要的按钮（主按钮）能够第一时间被看到。
+
+## 设计方法
+
+基于「Z 模式」、「F 模式」2 种模式进行按钮组设计：
+
+<div style="display: flex">
+  <div>
+    <strong style="display: block; text-align: center">Z 模式</strong>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/ZunWQbbEyZIAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description">适用于信息量少或信息无固定阅读顺序的场景。这种场景中用户视线遵循古腾堡原则，视线终点会停留在区块的右下角</div>
+  </div>
+  <div>
+    <strong style="display: block; text-align: center">F 模式</strong>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/sCQETqA-iFcAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description">适用于信息量大且信息需要遵循既定阅读顺序的场景。用户视线会跟随行文顺序进行流转，视线终点会停留在内容的结尾</div>
+  </div>
+</div>
+
+## Z 模式
+
+按钮组位于区块右下角，主按钮居右。
+
+<div style="display: flex">
+  <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/ihJSR5hDsLkAAAAAAAAAAAAADv3-AQBr/original" style="width: 60%" />
+  <div>1. 按钮组</div>
+</div>
+
+### 按钮组
+
+按钮按照重要程度从右到左依次排序：主按钮、次按钮。
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/NmutTYD83mgAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description"><Do></Do></div>
+    <div class="image-description">按钮组中支持放置多个按钮，建议不超过3个按钮</div>
+  </div>
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/v0xuTYim4TwAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description"><Donot></Donot></div>
+    <div class="image-description">避免将按钮放置到弹窗左下角</div>
+  </div>
+</div>
+
+### 应用场景
+
+Z 模式多用在反馈类容器和筛选卡片容器中。
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/edA3Q479KVwAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">对话框</div>
+  </div>
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/6ggkQJ2M_IwAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">气泡确认框</div>
+  </div>
+</div>
+
+<br />
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/2mHmTbOkSHUAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">筛选卡片</div>
+  </div>
+  <div style="visibility: hidden">
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/2mHmTbOkSHUAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">筛选卡片</div>
+  </div>
+</div>
+
+## F 模式
+
+<strong>按钮组置于用户浏览路径中，主按钮居左。</strong>根据重要程度从左到右依次排序：主按钮、次按钮、图标按钮。
+
+<div style="display: flex">
+  <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/RecTTLzVFbwAAAAAAAAAAAAADv3-AQBr/original" style="width: 60%" />
+  <div>
+    1. 标题区<br />
+    2. 内容区<br />
+    3. 页脚区
+  </div>
+</div>
+
+### 标题区
+
+页面级按钮组，执行页面级变更操作，位于一级标题右侧。
+
+<div>
+  <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/n9ziTajJnsQAAAAAAAAAAAAADv3-AQBr/original" />
+  <div class="image-description-center"></div>
+</div>
+
+### 内容区
+
+区块级按钮组，执行区块级变更操作，功能位置。
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/QqxeQpARApMAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description">用户浏览路径为从左到右时，按钮组置于操作对象右侧。</div>
+  </div>
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/38UbRJPA7VcAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description">用户浏览路径为从上到下时，按钮组置于操作对象下方。</div>
+  </div>
+</div>
+
+### 页脚区
+
+放置全局变更操作。
+
+<div style="display: flex">
+  <div style="width: 50%">
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/vES1SKp1cpMAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description"><strong>主按钮居左。</strong>按钮组中按钮之间不存在逻辑关系时，默认主按钮居左。</div>
+  </div>
+  <div style="width: 50%">
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/WC5UTotcdDsAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description"><strong>主按钮根据按钮逻辑顺序排列。</strong>当按钮组中按钮存在逻辑关系时，可以根据逻辑关系进行排序，其中推荐的操作按钮作为主按钮。</div>
+  </div>
+</div>
+
+### 应用场景
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/N45mSoKZ2hEAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">空页面</div>
+  </div>
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/3XznTpRBcgsAAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">列表页</div>
+  </div>
+</div>
+
+<br />
+
+<div style="display: flex">
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/Pu_pQqZTni0AAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">表单页</div>
+  </div>
+  <div>
+    <img src="https://mdn.alipayobjects.com/oceanbase_design/afts/img/ctioS6OVcG4AAAAAAAAAAAAADv3-AQBr/original" />
+    <div class="image-description-center">抽屉</div>
+  </div>
+</div>
diff --git 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
 ---
 
 图表是用户与复杂数据交流的可视化工具，图表可以通过颜色来区分不同数据类型或突出关键信息。