docs: Design doc (ant-design#20754)

* docs: Design doc * update overview & init data-format * update data-format doc * update buttons page * replace imags * add data-list doc * add visualization docs * update detail * Update visualization-page.md * Update detail-page.md * Update buttons.md (ant-design#20843) * Update data-list.md (ant-design#20844) * data list * update details * Update MorePage.tsx (ant-design#20965) * Update MorePage.tsx * Update visualization-page.md (ant-design#20977) * Update data-list.md (ant-design#20980) * Update detail-page.md (ant-design#20981) * chore: Update RecommendPage.tsx (ant-design#20989) * Update RecommendPage.tsx * Update RecommendPage.tsx * Update buttons.md (ant-design#21003) Co-authored-by: yingxirz <[email protected]> * Update buttons.md (ant-design#21004) Co-authored-by: yingxirz <[email protected]> * rm inner link * hide docs tmp * fix typo * adjust doc Co-authored-by: myeunhyuk <[email protected]> Co-authored-by: linye <[email protected]> Co-authored-by: yingxirz <[email protected]>
bujichong · Jan 20, 2020 · fd498a7 · fd498a7
1 parent bfcd00a
commit fd498a7
Show file tree

Hide file tree

Showing 30 changed files with 1,165 additions and 84 deletions.
diff --git a/components/auto-complete/demo/certain-category.md b/components/auto-complete/demo/certain-category.md
@@ -77,10 +77,7 @@ function Complete() {
       style={{ width: 250 }}
       options={options}
     >
-      <Input.Search
-        size="large"
-        placeholder="input here"
-      />
+      <Input.Search size="large" placeholder="input here" />
     </AutoComplete>
   );
 }

diff --git a/components/auto-complete/demo/uncertain-category.md b/components/auto-complete/demo/uncertain-category.md
@@ -49,9 +49,7 @@ function searchResult(query) {
                 {category}
               </a>
             </span>
-            <span>
-              {getRandomInt(200, 100)} results
-             </span>
+            <span>{getRandomInt(200, 100)} results</span>
           </div>
         ),
       };
@@ -79,11 +77,7 @@ class Complete extends React.Component {
         onSelect={onSelect}
         onSearch={this.handleSearch}
       >
-        <Input.Search
-          size="large"
-          placeholder="input here"
-          enterButton
-        />
+        <Input.Search size="large" placeholder="input here" enterButton />
       </AutoComplete>
     );
   }

diff --git a/docs/spec/buttons.md b/docs/spec/buttons.md
@@ -0,0 +1,174 @@
+---
+category:
+  zh-CN: 设计模式
+  en-US: Design Patterns
+type:
+  zh-CN: 全局规则
+  en-US: Global Rules
+order: 6
+title:
+  zh-CN: 按钮
+  en-US: Button
+---
+
+## 设计目标
+
+- 指导用户采取你希望他们采取的行动。
+- 帮助用户避免犯错。
+
+## 类型
+
+### 常规按钮
+
+<div>
+  <img alt="buttons" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*wsXrT7yQH2MAAAAAAAAAAABkARQnAQ">
+</div>
+
+#### ① 次按钮
+
+常规按钮，用于非主要动作。
+
+#### ② 主按钮
+
+突出“完成”、“推荐”类操作；一个按钮区最多使用一个主按钮。
+
+#### ③ 文字按钮
+
+弱化的按钮，采用更轻量的按钮样式，可用于需大面积展示按钮场景，例如表格组件中的操作列。
+
+#### ④ 图标按钮
+
+图标提供视觉线索，避免逐字阅读按钮文案，更高效地使用界面。
+
+- 需要在较小的空间内展示尽量多的按钮。
+- 使用纯图标按钮必须有 Tooltip 提示按钮含义。
+
+#### ⑤ 在按钮中添加图标
+
+用于对按钮含义补充解释，提高按钮识别效率。
+
+### 按钮强调
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*guusTZ6ZPxkAAAAAAAAAAABkARQnAQ">
+
+常规按钮类型呈现出不同的**强调程度**，使用者可以据此变化出合适的按钮类型：
+
+### Do&Don't
+
+<img class="preview-img no-padding bad" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*zBtTRq2xbTYAAAAAAAAAAABkARQnAQ" alt="错误示范" description="不要在按钮中放置两个图标。">
+<img class="preview-img no-padding good" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*EpwSTpaGPBgAAAAAAAAAAABkARQnAQ" alt="正确示范" description="按照主次展示全部操作。<br>将次要操作收纳至右侧下拉按钮中。">
+
+### 特殊按钮
+
+#### 虚线按钮  Dashed button
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*gPmNQ6_YCcoAAAAAAAAAAABkARQnAQ">
+
+用于引导用户在一个区域中添加内容。
+
+#### 危险按钮 Danger button
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*OvNaQJrmqVMAAAAAAAAAAABkARQnAQ">
+
+<img class="preview-img no-padding good" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*ujcXTqJ_IwwAAAAAAAAAAABkARQnAQ" alt="正确示范" description="用户的主要意图是删除，通过红色警示该操作存在风险。">
+
+<img class="preview-img no-padding good" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*o7EySrBPX9oAAAAAAAAAAABkARQnAQ" alt="正确示范" description="当系统不推荐用户执行删除操作时，可将取消按钮设置为主按钮。">
+
+警示用户该操作存在风险。
+
+#### 幽灵按钮 Ghost button
+
+置于复杂或较深的背景中，避免按钮突兀地破坏背景的整体性。该场景下可灵活定制样式。
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*-wORTrNJ6YUAAAAAAAAAAABkARQnAQ">
+
+#### 行动号召按钮 Call to action
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*32zdRqTjDhYAAAAAAAAAAABkARQnAQ">
+
+经常独立出现，行动号召按钮就像是电脑在对用户大声说“跟我来吧”，有点命令用户点击的意味，通常出现于 landing page 或者 一些引导性场景。最大可以将按钮放宽到与父区域等宽。
+
+## 位置
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*B8D0RJnirLkAAAAAAAAAAABkARQnAQ">
+
+将按钮区放置于用户浏览路径中，便于被用户发现，如 “F 浏览模式” 和 “Z 浏览模式” 。
+
+### 如何确定按钮区的放置位置？
+
+#### 页面/卡片/一组信息都能够呈现一个主题，主题的描述可以抽象为三个区域：
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*iVZpRpdN_2AAAAAAAAAAAABkARQnAQ">
+
+- Header：主题的标题和摘要信息内容区的导航等
+- Body：具体内容
+- Footer：主题的补充信息和工具栏等
+
+将按钮区放置在不同的区域，有不同的含义：见右图。
+
+也存在一些特殊情况，将“完成”主题类的动作放在 Header 区。例如，编辑器中为了最大化编辑空间，将“完成”类动作放到了右上角。
+
+### 什么时候需要在 Footer 中放置按钮区？
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*KGGWQLCBfm0AAAAAAAAAAABkARQnAQ">
+
+- Body 区部分内容被折叠或隐藏，例如单屏无法展示完整内容；
+- Body 区的内容复杂度高，例如有多个分组，分组中又有独立的按钮区，这时候需要将该主题的“完成”操作从 body 区区分出来，避免混淆按钮所能影响的内容范围。
+
+简而言之，Footer 的存在就是为了要和 Body 区区分开来。
+
+## 按钮顺序
+
+### 按钮顺序
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*NcPDQI3IX8YAAAAAAAAAAABkARQnAQ">
+
+推荐操作是阅读的起点，折叠内容始终在最右侧。
+
+**如何确定按钮顺序？**
+
+- 对话习惯：按钮放置顺序类似于电脑和用户的对话，**优先询问用户可能需要执行的操作，或你希望用户执行的操作，最后向用户提供存在风险的操作**。
+- 方向性含义：例如，具有返回意义的按钮，应该放在左侧，暗示其方向是回到之前，例如上一步。
+
+### 按钮组
+
+<img class="preview-img no-padding good" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*tK-AQaE5h1YAAAAAAAAAAABkARQnAQ" alt="正确示范">
+
+<img class="preview-img no-padding bad" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*_gU7ToHiZz4AAAAAAAAAAABkARQnAQ" alt="错误示范" description="连在一起的按钮组在外观上易与 Toggle Button 切换按钮混淆。">
+
+多个按钮形成一组时，将按钮排列在一起即可。
+
+### 按钮分组
+
+当需要布置的按钮数量过多，可以把相关的动作组成一组，并采用相似的视觉设计。当某一个按钮是首要动作时仍可使用主按钮强调。
+
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*x7YsTafH5osAAAAAAAAAAABkARQnAQ">
+
+**按主次折叠部分按钮**
+
+<br />
+
+<img class="preview-img no-padding good" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*Qn-mQKxaQ5kAAAAAAAAAAABkARQnAQ" alt="正确示范">
+<img class="preview-img no-padding bad" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*3bUZRbPiVBEAAAAAAAAAAABkARQnAQ" alt="错误示范" description="无需分组时不要使用短竖线分割">
+
+**平铺每个按钮**：优先推荐通过间距来区隔分组，也可以使用分割线来区隔视觉相似的按钮组。
+
+## 文案
+
+<img class="preview-img no-padding good" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*33KsR66zTY8AAAAAAAAAAABkARQnAQ" alt="正确示范">
+
+<img class="preview-img no-padding bad" align="right" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*238RTb4kaPwAAAAAAAAAAABkARQnAQ" alt="错误示范" description="应使用动词">
+
+文案需清楚传达用户按下按钮时系统将执行的操作。
+
+- 必须使用动词。（下拉按钮除外）
+- 与语境紧密关联，用语简练。
+
+Ant Design 组件中默认使用 “确定 / 取消”文案 ，但你仍然可以通过以下方式优化按钮文案：
+
+- 描述任务结果。
+
+  > 发布、登录、注册
+
+- 主要操作也为否定含义时，强调后果。
+  > 你确定要删除它吗？删除 / 取消
diff --git a/docs/spec/copywriting.md b/docs/spec/copywriting.md
@@ -5,7 +5,7 @@ category:
 type:
   zh-CN: 全局规则
   en-US: Global Rules
-order: 6
+order: 5
 title:
   zh-CN: 文案
   en-US: Copywriting

diff --git a/docs/spec/dark.md b/docs/spec/dark.md
@@ -0,0 +1,36 @@
+---
+category: 全局样式
+order: 6
+title:
+  zh-CN: 暗黑模式
+  en-US: Dark Theme
+skip: true
+---
+
+暗黑模式是指把所有 UI 换成黑色或者深色的一个主题模式。
+
+## 何时使用
+
+- 当需要长时间在暗光环境下工作时，建议使用暗黑模式，减小亮度对比带来的视觉压力，保证使用者的体验舒适
+- 当需要沉浸式的专注工作内容时，建议使用暗黑模式，可以帮助使用者更关注凸显出来的内容和操作
+  > 如同在电影院看电影时要全场关灯，是一样的原理
+
+## 设计原则
+
+**1、内容的舒适性** 暗黑模式下避免使用对比很强的色彩或内容，长时间使用会带来疲劳感
+
+**2、信息的一致性** 暗黑模式下的信息内容需要和浅色模式保持一致性，不应该打破原有的层级关系而应该延续。在浅色模式下越浅的代表信息的层级越弱，所以在暗色模式下应该越深，反之则越浅
+
+## 色彩
+
+暗黑模式中的颜色使用依旧可以延续浅色模式中的 12 套基础色板。应用思路上结合透明度规则处理，来让内容在不同的环境色下可以更好融合。
+
+### 基础色板
+
+TODO: Image
+
+### 色板生产工具
+
+我们也同样提供了一套暗色下的色板生成工具，需要选择你的主色以及页面的背景色，我们会为你生成一套暗色下的色板
+
+TODO: Panel
diff --git a/docs/spec/data-display.en-US.md b/docs/spec/data-display.en-US.md
@@ -1,7 +1,7 @@
 ---
 category: Design Patterns
 type: Global Rules
-order: 99
+order: 4
 title: Data Display
 ---
 

diff --git a/docs/spec/data-display.zh-CN.md b/docs/spec/data-display.zh-CN.md
@@ -1,7 +1,7 @@
 ---
 category: 设计模式
 type: 全局规则
-order: 99
+order: 4
 title: 数据展示
 ---
 
@@ -21,7 +21,7 @@ title: 数据展示
 > 注：
 >
 > 1. 表格中的时间、状态、操作栏需保持词语完整不过行。
-> 2. 当数据为空时，可使用「- -」来表示暂无数据。
+> 2. 当数据为空时，可使用『- -』来表示暂无数据。
 
 ## 折叠面板（Collapse）
 
@@ -31,20 +31,20 @@ title: 数据展示
 
 这类组件在导航中大量使用，同时也适合冗长的、无规则的内容管理。
 
-> 注：若折叠内容彼此之间关联度较低时，可使用更为节省空间的「手风琴」模式——「手风琴」是一种特殊的折叠面板，只允许单项内容区域展开。
+> 注：若折叠内容彼此之间关联度较低时，可使用更为节省空间的『手风琴』模式——『手风琴』是一种特殊的折叠面板，只允许单项内容区域展开。
 
 ---
 
 ## 卡片（Card）
 
-<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/zos/rmsportal/xtIGZmqUHAovPPKjwyVT.png" description="如页面内容加载过慢时，可采用「预加载」或「分步获取」的方式来缓解用户在等待时间中的焦虑感。">
+<img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/zos/rmsportal/xtIGZmqUHAovPPKjwyVT.png" description="如页面内容加载过慢时，可采用『预加载』或『分步获取』的方式来缓解用户在等待时间中的焦虑感。">
 
 卡片是一种承载信息的容器，对可承载的内容类型无过多限制，它让一类信息集中化，增强区块感的同时更易于操作；卡片通常以网格或矩阵的方式排列，传达相互之间的层级关系。适合较为轻量级和个性化较强的信息区块展示。
 
 > 注：
 >
 > 1.  卡片通常根据栅格进行排列，建议一行最多不超过四个
-> 2.  在有限的卡片空间内需注意信息之间的间距，若信息过长可做截断处理。例如「Ant Design 适用于中台…」
+> 2.  在有限的卡片空间内需注意信息之间的间距，若信息过长可做截断处理。例如『Ant Design 适用于中台…』
 
 ---
 
@@ -65,7 +65,7 @@ title: 数据展示
 
 <img class="preview-img no-padding" align="right" src="https://gw.alipayobjects.com/zos/rmsportal/QZyxnLWUkbIuTqGYxTQs.png">
 
-「树形控件」通过逐级大纲的形式来展现信息的层级关系，高效且具有极佳的视觉可视性，使得整体信息框架一目了然。
+『树形控件』通过逐级大纲的形式来展现信息的层级关系，高效且具有极佳的视觉可视性，使得整体信息框架一目了然。
 
 用户可同时浏览与处理多个树状层级的内容。适用于任何需要通过层级组织的信息场景，如文件夹、组织架构、生物分类、国家地区等等。
 

diff --git a/docs/spec/data-entry.en-US.md b/docs/spec/data-entry.en-US.md
@@ -1,7 +1,7 @@
 ---
 category: Design Patterns
 type: Global Rules
-order: 98
+order: 3
 title: Data Entry
 ---
 

diff --git a/docs/spec/data-entry.zh-CN.md b/docs/spec/data-entry.zh-CN.md
@@ -1,7 +1,7 @@
 ---
 category: 设计模式
 type: 全局规则
-order: 98
+order: 3
 title: 数据录入
 ---