docs: add help text for token customization

ammar-knowledge · Aug 30, 2023 · 3f148d9 · 3f148d9
1 parent e88581c
commit 3f148d9
Show file tree

Hide file tree

Showing 64 changed files with 111 additions and 73 deletions.
diff --git a/.dumi/theme/builtins/ComponentTokenTable/index.tsx b/.dumi/theme/builtins/ComponentTokenTable/index.tsx
@@ -1,5 +1,6 @@
 import { RightOutlined } from '@ant-design/icons';
 import { createStyles, css, useTheme } from 'antd-style';
+import Link from '../../common/Link';
 import { getDesignToken } from 'antd-token-previewer';
 import React, { useMemo, useState } from 'react';
 import tokenMeta from 'antd/es/version/token-meta.json';
@@ -18,6 +19,9 @@ const locales = {
     value: '默认值',
     componentToken: '组件 Token',
     globalToken: '全局 Token',
+    help: '如何定制？',
+    customizeTokenLink: '/docs/react/customize-theme-cn#修改主题变量',
+    customizeComponentTokenLink: '/docs/react/customize-theme-cn#修改主题变量',
   },
   en: {
     token: 'Token Name',
@@ -26,6 +30,9 @@ const locales = {
     value: 'Default Value',
     componentToken: 'Component Token',
     globalToken: 'Global Token',
+    help: 'How to customize?',
+    customizeTokenLink: '/docs/react/customize-theme#customize-design-token',
+    customizeComponentTokenLink: 'docs/react/customize-theme#customize-component-token',
   },
 };
 
@@ -45,16 +52,32 @@ const useStyle = createStyles(() => ({
       transition: all 0.3s;
     }
   `,
+  help: css`
+    margin-left: 6px;
+    font-size: 13px;
+    font-weight: normal;
+    color: #999;
+    a {
+      color: #999;
+    }
+  `,
 }));
 
 interface SubTokenTableProps {
   defaultOpen?: boolean;
   title: string;
+  help: React.ReactNode;
   tokens: string[];
   component?: string;
 }
 
-const SubTokenTable: React.FC<SubTokenTableProps> = ({ defaultOpen, tokens, title, component }) => {
+const SubTokenTable: React.FC<SubTokenTableProps> = ({
+  defaultOpen,
+  help,
+  tokens,
+  title,
+  component,
+}) => {
   const [, lang] = useLocale(locales);
   const token = useTheme();
   const columns = useColumns();
@@ -105,10 +128,13 @@ const SubTokenTable: React.FC<SubTokenTableProps> = ({ defaultOpen, tokens, titl
     .filter(Boolean);
 
   return (
-    <div>
+    <>
       <div className={styles.tableTitle} onClick={() => setOpen(!open)}>
         <RightOutlined className={styles.arrowIcon} rotate={open ? 90 : 0} />
-        <h3>{title}</h3>
+        <h3>
+          {title}
+          <span className={styles.help}>({help})</span>
+        </h3>
       </div>
       {open && (
         <ConfigProvider theme={{ token: { borderRadius: 0 } }}>
@@ -123,7 +149,7 @@ const SubTokenTable: React.FC<SubTokenTableProps> = ({ defaultOpen, tokens, titl
           />
         </ConfigProvider>
       )}
-    </div>
+    </>
   );
 };
 
@@ -152,11 +178,17 @@ const ComponentTokenTable: React.FC<ComponentTokenTableProps> = ({ component })
       {tokenMeta.components[component] && (
         <SubTokenTable
           title={locale.componentToken}
+          help={<Link to={locale.customizeTokenLink}>{locale.help}</Link>}
           tokens={tokenMeta.components[component].map((item) => item.token)}
           component={component}
+          defaultOpen
         />
       )}
-      <SubTokenTable title={locale.globalToken} tokens={mergedGlobalTokens} />
+      <SubTokenTable
+        title={locale.globalToken}
+        help={<Link to={locale.customizeComponentTokenLink}>{locale.help}</Link>}
+        tokens={mergedGlobalTokens}
+      />
     </>
   );
 };

diff --git a/components/anchor/index.zh-CN.md b/components/anchor/index.zh-CN.md
@@ -76,6 +76,6 @@ group:
 | target | 该属性指定在何处显示链接的资源 | string    | -      |      |
 | title  | 文字内容                       | ReactNode | -      |      |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Anchor"></ComponentTokenTable>
diff --git a/components/app/index.zh-CN.md b/components/app/index.zh-CN.md
@@ -30,8 +30,8 @@ tag: New
 App 组件通过 `Context` 提供上下文方法调用，因而 useApp 需要作为子组件才能使用，我们推荐在应用中顶层包裹 App。
 
 ```tsx
-import { App } from 'antd';
 import React from 'react';
+import { App } from 'antd';
 
 const MyPage: React.FC = () => {
   const { message, notification, modal } = App.useApp();
@@ -103,8 +103,9 @@ export { message, notification, modal };
 
 ```tsx
 // sub page
-import { Button, Space } from 'antd';
 import React from 'react';
+import { Button, Space } from 'antd';
+
 import { message } from './store';
 
 export default () => {
@@ -133,6 +134,6 @@ export default () => {
 | message | App 内 Message 的全局配置 | [MessageConfig](/components/message-cn/#messageconfig) | - | 5.3.0 |
 | notification | App 内 Notification 的全局配置 | [NotificationConfig](/components/notification-cn/#notificationconfig) | - | 5.3.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="App"></ComponentTokenTable>
diff --git a/components/auto-complete/index.zh-CN.md b/components/auto-complete/index.zh-CN.md
@@ -79,7 +79,7 @@ demo:
 | blur()  | 移除焦点 |      |
 | focus() | 获取焦点 |      |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Select"></ComponentTokenTable>
 

diff --git a/components/avatar/index.zh-CN.md b/components/avatar/index.zh-CN.md
@@ -62,6 +62,6 @@ group:
 | size | 设置头像的大小 | number \| `large` \| `small` \| `default` \| { xs: number, sm: number, ...} | `default` | 4.8.0 |
 | shape | 设置头像的形状 | `circle` \| `square` | `circle` | 5.8.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Avatar"></ComponentTokenTable>
diff --git a/components/badge/index.zh-CN.md b/components/badge/index.zh-CN.md
@@ -70,6 +70,6 @@ group: 数据展示
 | root      | 设置根元素   | 5.7.0 |
 | indicator | 设置徽标元素 | 5.7.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Badge"></ComponentTokenTable>
diff --git a/components/breadcrumb/index.zh-CN.md b/components/breadcrumb/index.zh-CN.md
@@ -131,6 +131,6 @@ function itemRender(item, params, items, paths) {
 return <Breadcrumb itemRender={itemRender} items={items} />;
 ```
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Breadcrumb"></ComponentTokenTable>
diff --git a/components/button/index.zh-CN.md b/components/button/index.zh-CN.md
@@ -85,7 +85,7 @@ group:
 | ---- | ------------ | ----- |
 | icon | 设置图标元素 | 5.5.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Button"></ComponentTokenTable>
 

diff --git a/components/calendar/index.zh-CN.md b/components/calendar/index.zh-CN.md
@@ -66,7 +66,7 @@ coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*-p-wQLik200AAA
 | onPanelChange | 日期面板变化回调 | function(date: Dayjs, mode: string) | - |  |
 | onSelect | 选择日期回调，包含来源信息 | function(date: Dayjs, info: { source: 'year' \| 'month' \| 'date' \| 'customize' }) | - | `info`: 5.6.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Calendar"></ComponentTokenTable>
 

diff --git a/components/card/index.zh-CN.md b/components/card/index.zh-CN.md
@@ -76,6 +76,6 @@ coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*a-8zR6rrupgAAA
 | style       | 定义容器类名的样式 | CSSProperties | -      |      |
 | title       | 标题内容           | ReactNode     | -      |      |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Card"></ComponentTokenTable>
diff --git a/components/carousel/index.zh-CN.md b/components/carousel/index.zh-CN.md
@@ -51,7 +51,7 @@ demo:
 
 更多 API 可参考：<https://react-slick.neostack.com/docs/api>
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Carousel"></ComponentTokenTable>
 

diff --git a/components/cascader/index.zh-CN.md b/components/cascader/index.zh-CN.md
@@ -123,6 +123,6 @@ interface Option {
 
 > 注意，如果需要获得中国省市区数据，可以参考 [china-division](https://gist.github.com/afc163/7582f35654fd03d5be7009444345ea17)。
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Cascader"></ComponentTokenTable>
diff --git a/components/checkbox/index.zh-CN.md b/components/checkbox/index.zh-CN.md
@@ -73,6 +73,6 @@ interface Option {
 | blur()  | 移除焦点 |      |
 | focus() | 获取焦点 |      |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Checkbox"></ComponentTokenTable>
diff --git a/components/collapse/index.zh-CN.md b/components/collapse/index.zh-CN.md
@@ -105,6 +105,6 @@ const items: CollapseProps['items'] = [
 | key | 对应 activeKey | string \| number | - |  |
 | showArrow | 是否展示当前面板上的箭头（为 false 时，collapsible 不能置为 icon） | boolean | true |  |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Collapse"></ComponentTokenTable>
diff --git a/components/date-picker/index.zh-CN.md b/components/date-picker/index.zh-CN.md
@@ -58,6 +58,7 @@ demo:
 
 ```jsx
 import 'dayjs/locale/zh-cn';
+
 import locale from 'antd/es/date-picker/locale/zh_CN';
 
 <DatePicker locale={locale} />;
@@ -66,7 +67,9 @@ import locale from 'antd/es/date-picker/locale/zh_CN';
 ```jsx
 // 默认语言为 en-US，如果你需要设置其他语言，推荐在入口文件全局设置 locale
 import dayjs from 'dayjs';
+
 import 'dayjs/locale/zh-cn';
+
 import locale from 'antd/locale/zh_CN';
 
 <ConfigProvider locale={locale}>
@@ -216,7 +219,7 @@ type GenericFn = (value: Dayjs) => string;
 export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;
 ```
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="DatePicker"></ComponentTokenTable>
 
@@ -244,6 +247,7 @@ export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;
 
 ```js
 import dayjs from 'dayjs';
+
 import 'dayjs/locale/zh-cn';
 
 import updateLocale from 'dayjs/plugin/updateLocale';

diff --git a/components/descriptions/index.zh-CN.md b/components/descriptions/index.zh-CN.md
@@ -103,6 +103,6 @@ const items: DescriptionsProps['items'] = [
 
 > span 是 Description.Item 的数量。 span={2} 会占用两个 DescriptionItem 的宽度。当同时配置 `style` 和 `labelStyle`（或 `contentStyle`）时，两者会同时作用。样式冲突时，后者会覆盖前者。
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Descriptions"></ComponentTokenTable>
diff --git a/components/divider/index.zh-CN.md b/components/divider/index.zh-CN.md
@@ -42,6 +42,6 @@ group:
 | style | 分割线样式对象 | CSSProperties | - |  |
 | type | 水平还是垂直类型 | `horizontal` \| `vertical` | `horizontal` |  |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Divider"></ComponentTokenTable>
diff --git a/components/drawer/index.zh-CN.md b/components/drawer/index.zh-CN.md
@@ -72,6 +72,6 @@ demo:
 | zIndex | 设置 Drawer 的 `z-index` | number | 1000 |  |
 | onClose | 点击遮罩层或左上角叉或取消按钮的回调 | function(e) | - |  |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Drawer"></ComponentTokenTable>
diff --git a/components/dropdown/index.zh-CN.md b/components/dropdown/index.zh-CN.md
@@ -80,7 +80,7 @@ demo:
 
 请确保 `Dropdown` 的子元素能接受 `onMouseEnter`、`onMouseLeave`、`onFocus`、`onClick` 事件。
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Dropdown"></ComponentTokenTable>
 

diff --git a/components/empty/index.zh-CN.md b/components/empty/index.zh-CN.md
@@ -66,6 +66,6 @@ coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*obM7S5lIxeMAAA
   }
 </style>
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Empty"></ComponentTokenTable>
diff --git a/components/float-button/index.zh-CN.md b/components/float-button/index.zh-CN.md
@@ -71,6 +71,6 @@ tag: New
 | visibilityHeight | 滚动高度达到此参数值才出现 BackTop | number            | 400          |      |
 | onClick          | 点击按钮的回调函数                 | () => void        | -            |      |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="FloatButton"></ComponentTokenTable>
diff --git a/components/form/index.zh-CN.md b/components/form/index.zh-CN.md
@@ -524,7 +524,7 @@ type Rule = RuleConfig | ((form: FormInstance) => RuleConfig);
 | form     | 指定 Form 实例                        | FormInstance | 当前 context 中的 Form | 5.4.0 |
 | preserve | 是否监视没有对应的 `Form.Item` 的字段 | boolean      | false                  | 5.4.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Form"></ComponentTokenTable>
 

diff --git a/components/grid/index.zh-CN.md b/components/grid/index.zh-CN.md
@@ -87,6 +87,6 @@ Ant Design 的布局组件若不能满足你的需求，你也可以直接使用
 
 响应式栅格的断点扩展自 [BootStrap 4 的规则](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)（不包含链接里 `occasionally` 的部分)。
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Grid"></ComponentTokenTable>
diff --git a/components/icon/index.zh-CN.md b/components/icon/index.zh-CN.md
@@ -103,8 +103,8 @@ getTwoToneColor(); // #eb2f96
 
 ```jsx
 import React from 'react';
-import ReactDOM from 'react-dom/client';
 import { createFromIconfontCN } from '@ant-design/icons';
+import ReactDOM from 'react-dom/client';
 
 const MyIcon = createFromIconfontCN({
   scriptUrl: '//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js', // 在 iconfont.cn 上生成
@@ -152,9 +152,10 @@ module.exports = {
 
 ```jsx
 import React from 'react';
-import ReactDOM from 'react-dom/client';
 import Icon from '@ant-design/icons';
 import MessageSvg from 'path/to/message.svg'; // 你的 '*.svg' 文件路径
+import ReactDOM from 'react-dom/client';
+
 // in create-react-app:
 // import { ReactComponent as MessageSvg } from 'path/to/message.svg';
 
@@ -171,6 +172,6 @@ ReactDOM.createRoot(mountNode).render(<Icon component={MessageSvg} />);
 | style     | 计算后的 `svg` 元素样式 | CSSProperties    | -              |      |
 | width     | `svg` 元素宽度          | string \| number | `1em`          |      |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Icon"></ComponentTokenTable>
diff --git a/components/image/index.zh-CN.md b/components/image/index.zh-CN.md
@@ -162,6 +162,6 @@ type TransformAction =
 }
 ```
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Image"></ComponentTokenTable>
diff --git a/components/input-number/index.zh-CN.md b/components/input-number/index.zh-CN.md
@@ -71,7 +71,7 @@ demo:
 | blur()  | 移除焦点 |
 | focus() | 获取焦点 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="InputNumber"></ComponentTokenTable>
 

diff --git a/components/input/index.zh-CN.md b/components/input/index.zh-CN.md
@@ -141,7 +141,7 @@ Input 的其他属性和 React 自带的 [input](https://reactjs.org/docs/dom-el
 | textarea | `textarea` 元素 | 5.4.0 |
 | count    | 文字计数元素    | 5.4.0 |
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Input"></ComponentTokenTable>
 

diff --git a/components/layout/index.zh-CN.md b/components/layout/index.zh-CN.md
@@ -131,6 +131,6 @@ coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*HdS6Q5vUCDcAAA
 }
 ```
 
-## Design Token
+## 主题变量（Design Token）
 
 <ComponentTokenTable component="Layout"></ComponentTokenTable>