@moheng-design/ui-skill 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +227 -0
- package/bin/cli.js +35 -0
- package/bin/lib/audit.mjs +138 -0
- package/bin/lib/feedback.mjs +82 -0
- package/bin/lib/install.mjs +61 -0
- package/bin/lib/paths.mjs +47 -0
- package/bin/lib/upgrade.mjs +86 -0
- package/eslint/index.js +94 -0
- package/eslint/lib/factories.js +313 -0
- package/eslint/lib/match.js +188 -0
- package/eslint/lib/tiers.js +27 -0
- package/generated/SKILL.md +696 -0
- package/generated/contracts.json +9270 -0
- package/generated/mappings.schema.json +333 -0
- package/generated/plugin-data.js +6994 -0
- package/generated/reference.md +5651 -0
- package/generated/rules.json +3864 -0
- package/generated/skills/moheng-ui-audit/SKILL.md +66 -0
- package/generated/skills/moheng-ui-bootstrap/SKILL.md +109 -0
- package/generated/skills/moheng-ui-feedback/SKILL.md +65 -0
- package/generated/skills/moheng-ui-page/SKILL.md +75 -0
- package/generated/skills/moheng-ui-review/SKILL.md +55 -0
- package/generated/skills/moheng-ui-upgrade/SKILL.md +40 -0
- package/generated/unenforced.json +57 -0
- package/handwritten/anti-patterns.md +239 -0
- package/handwritten/canvas-model.md +98 -0
- package/handwritten/conventions.md +2082 -0
- package/handwritten/skills/audit.md +54 -0
- package/handwritten/skills/bootstrap.md +99 -0
- package/handwritten/skills/feedback.md +63 -0
- package/handwritten/skills/page.md +44 -0
- package/handwritten/skills/review.md +43 -0
- package/handwritten/skills/upgrade.md +38 -0
- package/handwritten/unenforced.md +27 -0
- package/package.json +66 -0
- package/stylelint/index.js +121 -0
|
@@ -0,0 +1,696 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui
|
|
3
|
+
description: 用 @moheng-design/ui 写 React 界面时加载。含 91 个组件的清单与常用 props、原生元素到组件的替换映射表、Application Module 层强绑定的五层 Canvas 模型使用前提,以及样式覆盖、换肤与暗色的正确做法。凡涉及按钮、输入、选择、表格、浮层、导航、页面骨架等任何界面代码,均适用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- 生成文件 —— 请勿手改。源:@moheng-design/ui 的 contracts/ 与 mappings.json,生成器:scripts/generate.mjs -->
|
|
7
|
+
|
|
8
|
+
# @moheng-design/ui 使用指南
|
|
9
|
+
|
|
10
|
+
适用版本:v1.0.0
|
|
11
|
+
|
|
12
|
+
> 请先确认项目 `package.json` 中 `@moheng-design/ui` 的版本与本文件声明一致。
|
|
13
|
+
> 若不一致,以 `node_modules/@moheng-design/ui-skill/generated/reference.md` 为准 ——
|
|
14
|
+
> 该文件永远跟着包版本走,不会过期。
|
|
15
|
+
|
|
16
|
+
## 核心约束
|
|
17
|
+
|
|
18
|
+
### 导入
|
|
19
|
+
|
|
20
|
+
组件与类型一律从包入口导入,样式表显式引一次:
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { Button, Card } from '@moheng-design/ui'
|
|
24
|
+
import '@moheng-design/ui/styles.css'
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
禁止深引 `@moheng-design/ui/dist/*` 或 `@moheng-design/ui/src/*` —— 内部路径不在 exports map 中,
|
|
28
|
+
不构成公开接口,任意小版本都可能改动。
|
|
29
|
+
|
|
30
|
+
### 换肤与暗色
|
|
31
|
+
|
|
32
|
+
换肤的唯一入口是 `--ds-color-theme-primary`。暗色靠 `.dark` 类。
|
|
33
|
+
|
|
34
|
+
**两者都必须挂在 `<html>` 上。** `--application-*` 别名层整层声明在 `:root`,
|
|
35
|
+
`var()` 代换在声明所在元素就完成了,挂在 `<body>` 或容器 div 上一律无效。
|
|
36
|
+
不存在「局部暗色区块」这种用法。
|
|
37
|
+
|
|
38
|
+
### 样式覆盖
|
|
39
|
+
|
|
40
|
+
传 `className` 叠加,或覆盖 CSS 自定义属性。组件内无内联 style,
|
|
41
|
+
`className` 不需要 `!important` 即可生效。
|
|
42
|
+
|
|
43
|
+
状态一律由 CSS 伪类表达(`:hover` / `:focus-visible` / `:disabled`),
|
|
44
|
+
**不要用 JS state 模拟 hover**。
|
|
45
|
+
|
|
46
|
+
### 可用的 token
|
|
47
|
+
|
|
48
|
+
组件的全部颜色、尺度与层级由 CSS 自定义属性表达,共 356 条。
|
|
49
|
+
覆盖样式、与组件对齐尺度时读它们,**不得写字面色值、尺寸、圆角、间距**。
|
|
50
|
+
|
|
51
|
+
消费方可用的是 `--application-*`(91 条)与 `--ui-*`(134 条),共 225 条。
|
|
52
|
+
`--ds-*`(131 条)是 Foundation 内部实现,不构成公开接口,
|
|
53
|
+
任意小版本都可能改动,唯一例外是上一节的换肤入口 `--ds-color-theme-primary`。
|
|
54
|
+
|
|
55
|
+
命名形如 `--<层>-<分组>-<项>`。消费方可用的分组与条数:
|
|
56
|
+
|
|
57
|
+
- **`--application-*`**(91 条)—— `categorical` 20、`radius` 6、`space` 6、`font-size` 5、`line-height` 5、`button` 4、`font-weight` 4、`form-dialog` 2;另有 39 条不带分组段,形如 `--application-canvas`
|
|
58
|
+
- **`--ui-*`**(134 条)—— `shell` 106、`viewport` 7、`z` 4、`card` 3、`duration` 2、`shadow` 2、`application` 1、`border` 1、`control` 1、`divider` 1、`ease` 1、`overlay` 1、`page` 1、`section` 1、`sidebar` 1、`surface` 1
|
|
59
|
+
|
|
60
|
+
356 条 token 的完整名值表见
|
|
61
|
+
`node_modules/@moheng-design/ui-skill/generated/reference.md` 的「Token 全表」一节 ——
|
|
62
|
+
该文件随包分发,不会过期。两层各自的取用规则见下文「组合约定」。
|
|
63
|
+
|
|
64
|
+
### 替换映射表
|
|
65
|
+
|
|
66
|
+
原生元素在本系统内都有对应组件,报错文案即替换指令:
|
|
67
|
+
|
|
68
|
+
| 不要写 | 改写成 | 替换指令 |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| `<button>` | `<Button>` | 请使用 Button 组件替代原生 <button>。导入方式:import { Button } from '@moheng-design/ui' |
|
|
71
|
+
| `<input>` | `<Input>` | 请使用 Input 组件替代原生 <input>。导入方式:import { Input } from '@moheng-design/ui'。type 为 checkbox / radio / range / search 时另有专用组件,见 no-native-checkbox / no-native-radio / no-native-range / no-native-search |
|
|
72
|
+
| `<input type="checkbox">` | `<Checkbox>` | 请使用 Checkbox 组件替代 <input type="checkbox">。导入方式:import { Checkbox } from '@moheng-design/ui'。列表行内的批量选择另用 ListSelectionCheckbox |
|
|
73
|
+
| `<input type="radio">` | `<RadioGroup>` | 请使用 RadioGroup 组件替代 <input type="radio">。RadioGroup 是组级控件,全部选项写在 items 数组里,不要逐个渲染单选项。导入方式:import { RadioGroup } from '@moheng-design/ui' |
|
|
74
|
+
| `<input type="range">` | `<Slider>` | 请使用 Slider 组件替代 <input type="range">。导入方式:import { Slider } from '@moheng-design/ui' |
|
|
75
|
+
| `<input type="search">` | `<SearchField>` | 请使用 SearchField 组件替代 <input type="search">。SearchField 的 ariaLabel 是必填。导入方式:import { SearchField } from '@moheng-design/ui' |
|
|
76
|
+
| `<textarea>` | `<Textarea>` | 请使用 Textarea 组件替代原生 <textarea>。导入方式:import { Textarea } from '@moheng-design/ui' |
|
|
77
|
+
| `<select>` | `<Select>` | 请使用 Select 组件替代原生 <select>。导入方式:import { Select } from '@moheng-design/ui'。选项极多或密集的表格行内编辑器改用 NativeSelect,需要输入筛选改用 Combobox |
|
|
78
|
+
| `<label>` | `<Label>` | 请使用 Label 组件替代原生 <label>。导入方式:import { Label } from '@moheng-design/ui'。表单项的标签与校验信息一并交给 Field 更合适 |
|
|
79
|
+
| `<table>` | `<Table>` | 请使用 Table 组件替代原生 <table>。Table 是数据驱动的:列写在 columns 数组,行数据写在 rows,不要手写 <tr> / <td>。导入方式:import { Table } from '@moheng-design/ui' |
|
|
80
|
+
| `<hr>` | `<Separator>` | 请使用 Separator 组件替代原生 <hr>。导入方式:import { Separator } from '@moheng-design/ui' |
|
|
81
|
+
| `<progress>` | `<Progress>` | 请使用 Progress 组件替代原生 <progress>。导入方式:import { Progress } from '@moheng-design/ui' |
|
|
82
|
+
| `<dialog>` | `<Dialog>` | 请使用 Dialog 组件替代原生 <dialog>。导入方式:import { Dialog } from '@moheng-design/ui'。表单类对话框用 ApplicationFormDialog,破坏性操作确认用 AlertDialog |
|
|
83
|
+
| `<details>` | `<Collapsible>` | 请使用 Collapsible 组件替代原生 <details>。导入方式:import { Collapsible } from '@moheng-design/ui'。多个互斥折叠项改用 Accordion |
|
|
84
|
+
| `<summary>` | `<Collapsible>` | 请使用 Collapsible 组件的 label 替代原生 <summary>。触发器文字写进 label,被折叠的内容写进 children。导入方式:import { Collapsible } from '@moheng-design/ui' |
|
|
85
|
+
| `<kbd>` | `<Kbd>` | 请使用 Kbd 组件替代原生 <kbd>。导入方式:import { Kbd } from '@moheng-design/ui' |
|
|
86
|
+
| `<svg>` | `<Icon>` | 请使用 Icon 组件替代逐页手写的内联 <svg>。导入方式:import { Icon } from '@moheng-design/ui',写作 <Icon name="登记名" size={16} />。name 只接受已登记字形,清单见 @moheng-design/ui 的 src/icon/registry.json(reference.md 亦有全表);未登记的名字渲染为等尺寸占位盒,确需新字形须先登记进该清单并随包发版。数据可视化改用 Chart 组件,不要手绘图形 |
|
|
87
|
+
| `@/components/ui/*` | `@moheng-design/ui` | 禁止从 @/components/ui/* 导入。该目录通常是 npx shadcn add 生成的平行组件实现,与 @moheng-design/ui 并存会造成同一界面两套视觉。请改为 import { ... } from '@moheng-design/ui' |
|
|
88
|
+
| `@moheng-design/ui/dist/*` | `@moheng-design/ui` | 禁止深引 @moheng-design/ui 的内部路径。请从包入口导入:import { ... } from '@moheng-design/ui'。样式表另有专用入口 @moheng-design/ui/styles.css |
|
|
89
|
+
|
|
90
|
+
已明确**不禁**的元素:`a` `img` `ul` `ol` `li` `p` `h1`–`h6` —— 系统里没有对应组件。
|
|
91
|
+
|
|
92
|
+
### 硬编码样式值
|
|
93
|
+
|
|
94
|
+
以下三条只在组件库内部生效(`scope: internal`),业务代码不受约束:
|
|
95
|
+
|
|
96
|
+
- **no-raw-hex-color** —— 禁止硬编码色值。请改用 --ds-color-* token,例如 color: var(--ds-color-text)。可用 token 见 packages/ui/tokens.json
|
|
97
|
+
色值写死后换肤入口 --ds-color-theme-primary 对它无效,暗色主题也覆盖不到。exceptFiles 豁免 token 源文件 —— 那里必须写字面值,色彩原语正是在那里定义的。
|
|
98
|
+
- **no-raw-px-value** —— 禁止硬编码尺寸。间距用 --ds-space-0 至 --ds-space-5(后缀是档位序号,六档依次为 0/4/8/12/16/24px),圆角用 --ds-radius-0/4/8/12/16/20(后缀即像素值),字号用 --ds-font-size-12/14/16/20/24、行高用 --ds-line-height-16/20/24/28/32(后缀同为像素值)。系统内没有 20 / 32 / 48 间距档,出现这类值说明取错了标尺
|
|
99
|
+
响应式密度靠 @media 改写 :root 变量实现,组件侧写死 px 会让三档密度在该处失效。1px 边框不受本条影响 —— 边框一律走 --ui-border-default,不在 cssProperties 列表内。
|
|
100
|
+
- **no-unregistered-font** —— 禁止直接书写字族。请改用 var(--ds-font-family),等宽场景用 var(--ds-font-family-mono)。系统只有单一字族,没有展示体,也没有搭配字体
|
|
101
|
+
字族栈是暖色中性 + 单一冷蓝强调这套视觉签名的一部分,逐处书写会在某处漏掉 PingFang TC 或 Microsoft YaHei,导致跨平台字形不一致。模式必须覆盖 font 简写:简写同样能落下一个字族(font: 14px/20px Menlo, monospace),且它一并重置 font-family,漏掉它等于给整条规则留一条改写字族的旁路;cssProperties 本就声明了 font 与 font-family 两项,模式只认后者时规则名实不符 —— 声明覆盖两个属性,实际只管住一个,且不报错不告警,即 §1.4 点名的「以为约束住了,实际没有」。(?:-family)? 用可选组而非另起一支,是为了让 font-size / font-weight 这类同前缀属性落空:可选组取空后 \s*: 撞上连字符即失配。起首的 \b 是简写支带来的新要求:没有它时 myfont: 这类粘连写法会被当成 font 属性。\b 只挡粘连,挡不住以连字符分隔的 --mh-x-font: —— 那一处靠 stylelint 侧的自定义属性守卫与 cssProperties 过滤,ESLint 侧则因组件内的局部尺度变量一律带 -size / -width 之类后缀而落空。两处豁免写在否定前瞻内:var(...) 是唯一正确写法;inherit 是控件继承祖先字族的标准重置,不构成书写字族,src/ 下现有 18 处 font-family: inherit 与 1 处 font: inherit(Breadcrumb.css)均为此用法。空白必须留在前瞻里 —— 写成 \s*(?!var\() 时前瞻会回退到冒号后零空白处求值,var(--ds-font-family) 反而必然误报。
|
|
102
|
+
|
|
103
|
+
## 组件清单
|
|
104
|
+
|
|
105
|
+
91 个组件全部在 `@moheng-design/ui` 单包内:Foundation 58 个、Application Atomic 7 个、Application Module 26 个。
|
|
106
|
+
|
|
107
|
+
表中 `*` 标记必填 prop,括号内是枚举的全部取值。完整签名见 reference.md。
|
|
108
|
+
|
|
109
|
+
### Foundation · icon(1)
|
|
110
|
+
|
|
111
|
+
| 组件 | 用途 | 常用 props |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| `Icon` | 已登记字形集中的单色图标 —— 规范要求图标的任何位置都用它。 | `name`*、`size`(14 / 16 / 18 / 20 / 24) |
|
|
114
|
+
|
|
115
|
+
### Foundation · actions(4)
|
|
116
|
+
|
|
117
|
+
| 组件 | 用途 | 常用 props |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `Button` | Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。 | `children`*、`variant`(primary / secondary / outline / ghost / destructive / link)、`size`(xs / sm / default / lg) |
|
|
120
|
+
| `ButtonGroup` | 把一组相关 Button 合并为一个分段控件或间隔簇。 | `orientation`(horizontal / vertical) |
|
|
121
|
+
| `Toggle` | 单个两态可按下控件 —— 用于一个独立的格式或显示开关。 | `size`(sm / default / lg) |
|
|
122
|
+
| `ToggleGroup` | 一组分段式开关,用于**一个局部显示选择** —— 密度、对齐方式、局部视图标记。 | `items`*、`type`(single / multiple)、`size`(sm / default / lg) |
|
|
123
|
+
|
|
124
|
+
### Foundation · input-selection(14)
|
|
125
|
+
|
|
126
|
+
| 组件 | 用途 | 常用 props |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| `Calendar` | 月格日期选择器,**周一为一周起始**(一…日)。 | — |
|
|
129
|
+
| `Checkbox` | 独立的布尔选择,16px 方形,4px 圆角,选中时填充强调色。 | — |
|
|
130
|
+
| `Combobox` | 输入即筛选的单选控件 —— 选项多到不便逐条扫视,但又不构成一次数据查询时使用。 | `options`* |
|
|
131
|
+
| `Field` | 表单行:标签 + 控件 + 一行说明**或**错误。 | — |
|
|
132
|
+
| `Input` | 单行文本控件。 | — |
|
|
133
|
+
| `InputGroup` | 单一焦点壳,包裹前置/后置附加物与一个控件 —— 图标、单位、提交按钮。 | — |
|
|
134
|
+
| `InputOTP` | 定长验证码输入 —— 每个字符一个 40px 方框,光标自动前进。 | — |
|
|
135
|
+
| `Label` | 独立控件标签,14/20 字号,色值 `--ds-color-text-label`。 | — |
|
|
136
|
+
| `NativeSelect` | 平台原生 `<select>`,套用已登记的外壳样式。 | `options`* |
|
|
137
|
+
| `RadioGroup` | 在 2–5 个可见选项中互斥择一,用于表单与筛选面板。 | `items`*、`orientation`(vertical / horizontal) |
|
|
138
|
+
| `Select` | 自绘单选下拉 —— 表单与筛选行中的默认选择控件。 | `options`* |
|
|
139
|
+
| `Slider` | 单值范围控件,4px 高轨道,已选部分填充强调色。 | — |
|
|
140
|
+
| `Switch` | 立即生效的开关控件,36×20 轨道 + 16px 滑块。 | — |
|
|
141
|
+
| `Textarea` | 多行文本控件,用于备注、说明与事由。 | — |
|
|
142
|
+
|
|
143
|
+
### Foundation · navigation-command(9)
|
|
144
|
+
|
|
145
|
+
| 组件 | 用途 | 常用 props |
|
|
146
|
+
|---|---|---|
|
|
147
|
+
| `Accordion` | 堆叠式渐进披露,区块之间以 1px 分隔线相隔 —— **无卡片、无阴影**。 | `items`*、`type`(single / multiple) |
|
|
148
|
+
| `Breadcrumb` | 真实层级的回溯路径。 | `items`* |
|
|
149
|
+
| `Command` | 键盘优先的命令面板 —— 放进 `Dialog` 里作为全局搜索与执行入口。 | `groups`* |
|
|
150
|
+
| `ContextMenu` | 内容区域上的右键菜单 —— 行、卡片、看板块。 | `items`* |
|
|
151
|
+
| `Menubar` | 桌面风格的水平菜单条,用于编辑器型工作面 —— 报表设计器、看板配置器。 | `menus`* |
|
|
152
|
+
| `NavigationMenu` | 水平导航,条目可展开富内容面板。 | `items`* |
|
|
153
|
+
| `Pagination` | 裸分页步进器。 | — |
|
|
154
|
+
| `Sidebar` | Content Canvas 内部的垂直导航面 —— SPLIT 左侧目录、设置导航、模块子导航。 | `groups`* |
|
|
155
|
+
| `Tabs` | 页面区域内的局部标签页 —— Business View 标签、SPLIT 右栏内容标签、详情分节。 | `items`* |
|
|
156
|
+
|
|
157
|
+
### Foundation · data-content-layout(18)
|
|
158
|
+
|
|
159
|
+
| 组件 | 用途 | 常用 props |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| `AspectRatio` | 锁定一个固定宽高比的槽位,使媒体或图表加载时**不产生布局跳动**。 | — |
|
|
162
|
+
| `Avatar` | 人员或组织的身份标记 —— 人员选择器、联系人列表、审计轨迹、记录负责人。 | `shape`(circle / rounded) |
|
|
163
|
+
| `Badge` | 紧凑的状态或分类标签 —— 行、卡片、指标、详情头。 | `tone`(neutral / accent / success / warning / danger / info)、`variant`(soft / outline) |
|
|
164
|
+
| `Bubble` | 会话中的单条消息气泡 —— 消息面板、评论流、办理讨论。 | `side`(own / other) |
|
|
165
|
+
| `Card` | 标准页面承载面 —— CardList 磁贴、工作台面板、图表容器、表单分节。 | `density`(default / sm) |
|
|
166
|
+
| `Carousel` | 水平分页内容。 | `slides`* |
|
|
167
|
+
| `Chart` | 图表基元 —— ANALYSIS 分析页、指标卡、报表摘要。 | `series`*、`type`(line / area / bar) |
|
|
168
|
+
| `Empty` | 结果集或区域的空状态。 | — |
|
|
169
|
+
| `Item` | 通用列表行 —— 目录、选择器、菜单、结构化列表复用的那一行。 | — |
|
|
170
|
+
| `Kbd` | 键盘按键提示,20px 高,等宽字体,浅色底 —— 工具提示、命令面板、帮助文案。 | — |
|
|
171
|
+
| `Message` | 消息流或活动流中的一条 —— 「消息」全局动作面板的行、活动/审计流的条目。 | — |
|
|
172
|
+
| `MessageScroller` | 消息流的滚动容器。 | — |
|
|
173
|
+
| `Progress` | 确定性进度条 —— 承载 `progress` 指标语义、批处理任务状态、配额使用率。 | `tone`(accent / success / warning / danger) |
|
|
174
|
+
| `Resizable` | 带可拖拽分隔条的双栏布局,支撑 SPLIT 工作面。 | — |
|
|
175
|
+
| `ScrollArea` | 有界滚动区域,带细样式滚动条 —— 长筛选列表、宽表格、必须单行的标签条。 | — |
|
|
176
|
+
| `Separator` | `--application-divider` 色的 1px 分隔线。 | `orientation`(horizontal / vertical) |
|
|
177
|
+
| `Skeleton` | 加载占位骨架 —— Loading 系统状态。 | — |
|
|
178
|
+
| `Table` | DataTable 承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏。 | `columns`*、`rows`*、`density`(default / sm) |
|
|
179
|
+
|
|
180
|
+
### Foundation · feedback-overlay(12)
|
|
181
|
+
|
|
182
|
+
| 组件 | 用途 | 常用 props |
|
|
183
|
+
|---|---|---|
|
|
184
|
+
| `Alert` | 就地的、**不打断**的区域内消息 —— 缓存数据提示、部分失败、权限说明。 | `tone`(info / success / warning / danger) |
|
|
185
|
+
| `AlertDialog` | 后果严重或不可逆动作前的**阻塞式确认** —— 删除、撤回、批量办结。 | — |
|
|
186
|
+
| `Collapsible` | 单个显隐区域,由一个触发器控制 —— 查询工具栏里的「更多筛选」模式。 | — |
|
|
187
|
+
| `Dialog` | 模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。 | — |
|
|
188
|
+
| `Drawer` | 侧边面板,保持列表上下文可见 —— DETAIL 的抽屉形态。 | `side`(right / left) |
|
|
189
|
+
| `DropdownMenu` | 触发器 + 菜单面板,低频动作的收纳处 —— 上下文区或行尾的「**更多**」按钮。 | `items`*、`align`(start / end) |
|
|
190
|
+
| `HoverCard` | 悬停时展示的富预览 —— 人员、机构、关联记录。 | — |
|
|
191
|
+
| `Popover` | 锚定式浮层面板 —— 筛选器、呈现设置、日期选择器。 | `align`(start / end) |
|
|
192
|
+
| `Sheet` | 从任意边缘滑出的面板,用于**辅助性内容** —— 从一级导航打开的「设置」面板、帮助面板、附件预览。 | `side`(right / left / top / bottom) |
|
|
193
|
+
| `Sonner` | 转瞬即逝的提示堆栈 —— **确认某件事已经发生**(已保存、已导出、3 条已办结)。 | `toasts`*、`position`(bottom-right / bottom-left / top-right / top-left) |
|
|
194
|
+
| `Spinner` | 不确定时长的**原地**等待 —— 刷新中的按钮、提交中的对话框。 | — |
|
|
195
|
+
| `Tooltip` | 悬停或聚焦时出现的短标签,用于**为纯图标控件命名** —— 五个全局动作触发器、工具栏图标按钮。 | `side`(top / bottom / left / right) |
|
|
196
|
+
|
|
197
|
+
### Application Atomic(7)
|
|
198
|
+
|
|
199
|
+
| 组件 | 用途 | 常用 props |
|
|
200
|
+
|---|---|---|
|
|
201
|
+
| `ApplicationFilterMenu` | 查询工具栏主控制行中的常驻快捷筛选 —— **一个高频维度**。 | `options`* |
|
|
202
|
+
| `ListSelectionCheckbox` | 列表 / 表格 / 卡片网格 / 看板的记录选择框。 | `scope`(row / all) |
|
|
203
|
+
| `ListTablePagination` | 列表 / 表格分页 —— 结果区间、总数、每页条数与翻页步进。 | — |
|
|
204
|
+
| `SearchField` | 共享的紧凑搜索入口 —— **产品内每一处纯文本搜索**: 查询工具栏、目录搜索、人员与文件选择器。 | `ariaLabel`* |
|
|
205
|
+
| `SidebarAppLinkButton` | 应用快捷入口 —— 从工作台侧栏或应用切换器跳转到另一个应用。 | — |
|
|
206
|
+
| `SidebarRailButton` | 工作台菜单栏条目 —— 56px 宽的列内,图标在上、标签在下。 | — |
|
|
207
|
+
| `SystemButton` | 应用语义按钮 —— **整个产品的默认动作按钮**。 | `intent`(primary / secondary / quiet / icon / link / destructive)、`size`(default / compact / icon) |
|
|
208
|
+
|
|
209
|
+
### Application Module · navigation(5)
|
|
210
|
+
|
|
211
|
+
| 组件 | 用途 | 常用 props |
|
|
212
|
+
|---|---|---|
|
|
213
|
+
| `ApplicationModuleSwitcher` | 应用二级导航的**左半部分** —— 你在哪个模块,以及如何切换。 | — |
|
|
214
|
+
| `ApplicationPrimaryNavigation` | `APPLICATION.PRIMARY_NAV` —— 固定 Shell 的**第二带**。 | `activeAction`(messages / todos / overview / risk / settings) |
|
|
215
|
+
| `ApplicationSecondaryNavigation` | `APPLICATION.SECONDARY_NAV` —— 固定 Shell 的**第三带**。 | — |
|
|
216
|
+
| `GlobalSidebar` | 工作台左侧 72px 菜单栏,由 `SidebarRailButton` 构成。 | — |
|
|
217
|
+
| `TopNavigationPrimaryBar` | `PLATFORM.TOP_USER_BAR` —— 固定 Shell 的**第一带**。 | — |
|
|
218
|
+
|
|
219
|
+
### Application Module · statistics(5)
|
|
220
|
+
|
|
221
|
+
| 组件 | 用途 | 常用 props |
|
|
222
|
+
|---|---|---|
|
|
223
|
+
| `ApplicationMetricChart` | `chart` 语义:数值 + 内嵌迷你走势线。 | — |
|
|
224
|
+
| `ApplicationMetricPrimarySecondary` | `primary-secondary` 语义:一个主数字 + 其拆解。 | — |
|
|
225
|
+
| `ApplicationMetricStatus` | `status` 语义:功能状态 + 其计数 —— 逾期数、规则违反、系统健康度。 | `status`(normal / warning / danger / info) |
|
|
226
|
+
| `ApplicationMetricStrip` | 指标区容器,同时承载 `numeric` 与 `icon` 两种基础语义。 | — |
|
|
227
|
+
| `ApplicationMetricTrend` | `trend` 语义:数值 + 环比变化量。 | `direction`(up / down / flat) |
|
|
228
|
+
|
|
229
|
+
### Application Module · content(7)
|
|
230
|
+
|
|
231
|
+
| 组件 | 用途 | 常用 props |
|
|
232
|
+
|---|---|---|
|
|
233
|
+
| `ApplicationDataDisplay` | Canvas 的**数据展示区**。 | `state`(ready / loading / empty / error / no-permission / not-found) |
|
|
234
|
+
| `ApplicationFilterList` | 完整的筛选维度列表 —— **「更多筛选」的面板主体**。 | — |
|
|
235
|
+
| `ApplicationPageHeader` | Canvas 的**上下文区**(源仓库名 `application-page-header`)。 | `dataStatus`(normal / refreshing / failed)、`pageMode`(LIST / CARD / SPLIT / BOARD / CALENDAR) |
|
|
236
|
+
| `ApplicationPageLayoutContainer` | 每个业务页面的脚手架 —— 直接放进 Content Canvas 内。 | — |
|
|
237
|
+
| `ApplicationQueryToolbar` | **数据控制区** —— 统一承载 Canvas 五层模型的 L3 业务视图与 L4 数据控制。 | `presentation`(DataTable / CardList / KanbanBoard / Calendar / Chart / Timeline) |
|
|
238
|
+
| `ApplicationRecordDetailBody` | **唯一的**业务详情主体,由抽屉形态与独立详情页共用 ——「一份详情,两个载体」。 | — |
|
|
239
|
+
| `ApplicationSplitListSidebar` | SPLIT 页面模式的**左栏**。 | — |
|
|
240
|
+
|
|
241
|
+
### Application Module · lists(2)
|
|
242
|
+
|
|
243
|
+
| 组件 | 用途 | 常用 props |
|
|
244
|
+
|---|---|---|
|
|
245
|
+
| `ApplicationRecordList` | 结构化记录列表 —— 非表格形态的 `structured list` 数据呈现方式。 | — |
|
|
246
|
+
| `ListBatchActionBar` | 当前选择集的批量动作条 —— 记录一被勾选就出现在结果集上方。 | — |
|
|
247
|
+
|
|
248
|
+
### Application Module · overlays(4)
|
|
249
|
+
|
|
250
|
+
| 组件 | 用途 | 常用 props |
|
|
251
|
+
|---|---|---|
|
|
252
|
+
| `ApplicationDetailDrawer` | DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后的列表。 | — |
|
|
253
|
+
| `ApplicationFormDialog` | 业务对象的新建与编辑表单对话框。 | `size`(small / large) |
|
|
254
|
+
| `ApplicationGlobalActionPanel` | 四个 popover 型全局动作**共享的同一个面板** —— 消息 / 待办 / 运行总览 / 风险预警。 | — |
|
|
255
|
+
| `PeoplePickerDialog` | 人员 / 组织选择器 —— 指派人、审核人、通知接收人、共享对象。 | — |
|
|
256
|
+
|
|
257
|
+
### Application Module · collaboration(3)
|
|
258
|
+
|
|
259
|
+
| 组件 | 用途 | 常用 props |
|
|
260
|
+
|---|---|---|
|
|
261
|
+
| `ContactsCollaborationWorkspace` | 「人员与组织」工作台 —— **三栏**:组织树定位器 · 成员列表 · 成员详情。 | — |
|
|
262
|
+
| `FilesCollaborationWorkspace` | 「文件」工作台 —— 左侧文件夹定位器 · 中间文件表 · 右侧可选预览栏。 | — |
|
|
263
|
+
| `ScheduleCollaborationWorkspace` | 「日程」工作台 —— 粒度切换 · 月格 · 当日议程栏。 | `grain`(day / week / month) |
|
|
264
|
+
|
|
265
|
+
## 五层 Canvas 模型
|
|
266
|
+
|
|
267
|
+
<!-- 手写文件。被 generate.mjs 嵌入 SKILL.md 的「五层 Canvas 模型」一节与 reference.md。
|
|
268
|
+
内部标题必须从 ### 起,否则嵌入后会与宿主文档的层级冲突。 -->
|
|
269
|
+
|
|
270
|
+
Application Module 层的 26 个组件**强绑定**本模型。装本库即意味着接受这套结构约定
|
|
271
|
+
(01 §1.8 已明确声明这一代价)。Foundation 与 Application Atomic 两层不受本节约束。
|
|
272
|
+
|
|
273
|
+
### 三层物理结构
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
Application
|
|
277
|
+
├─ Shell 跨页身份、应用、模块导航
|
|
278
|
+
├─ Canvas 当前业务页面
|
|
279
|
+
└─ Overlay Dialog / Drawer / Popover / Menu / Toast
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Shell 四带
|
|
283
|
+
|
|
284
|
+
固定骨架,**没有左侧全局栏**。三条导航带 `position: fixed`,永不滚动。
|
|
285
|
+
|
|
286
|
+
| 带 | 组件 | Standard | Compact |
|
|
287
|
+
|---|---|---:|---:|
|
|
288
|
+
| 顶部导航 `PLATFORM.TOP_USER_BAR` | `TopNavigationPrimaryBar` | 52px | 44px |
|
|
289
|
+
| 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 64px | 52px |
|
|
290
|
+
| 应用二级导航 `APPLICATION.SECONDARY_NAV` | `ApplicationSecondaryNavigation` | 48px | 40px |
|
|
291
|
+
| Content Canvas | `ApplicationPageLayoutContainer` | 剩余视口 | 剩余视口 |
|
|
292
|
+
|
|
293
|
+
**Content Canvas 是页面唯一的垂直滚动持有者。** 宿主 padding 为零 —— padding 属于页面内容根。
|
|
294
|
+
表格、看板、标签页、日历可以拥有正交的水平滚动或局部有界滚动;
|
|
295
|
+
不得堆叠无界的垂直滚动容器。
|
|
296
|
+
|
|
297
|
+
Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑、通知铃铛、页面标题、卡片、阴影。
|
|
298
|
+
|
|
299
|
+
### 五层认知模型
|
|
300
|
+
|
|
301
|
+
新页面必须把五层**全部**声明为状态字段。缺一层即为结构不完整。
|
|
302
|
+
|
|
303
|
+
| 层 | 字段 | 取值 |
|
|
304
|
+
|---|---|---|
|
|
305
|
+
| L1 页面类型 | `pageType` | `WORKBENCH` / `MANAGEMENT` / `LEDGER` / `ANALYSIS` / `REPORT` / `DETAIL` |
|
|
306
|
+
| L2 页面模式 | `pageMode` | `LIST` / `CARD` / `SPLIT` / `BOARD` / `CALENDAR` |
|
|
307
|
+
| L3 业务视图 | `businessView` | 2–4 个稳定工作视角(全部 / 我的责任 / 最近处理) |
|
|
308
|
+
| L4 数据控制 | `dataControl` | search / filters / sort / pagination / appliedFilterTags |
|
|
309
|
+
| L5 数据呈现 | `dataPresentation` | `DataTable` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
|
|
310
|
+
|
|
311
|
+
`DETAIL` 与 `COMPOSITE` **不是**页面模式,是特殊物理结构资产。
|
|
312
|
+
`Embedded` 是 `integrationMode`,不是页面模式。
|
|
313
|
+
|
|
314
|
+
### Canvas 标准区域顺序
|
|
315
|
+
|
|
316
|
+
自上而下固定,不得重排:
|
|
317
|
+
|
|
318
|
+
```
|
|
319
|
+
上下文区 ApplicationPageHeader L1 / L2 / L3 的承载者
|
|
320
|
+
指标区 ApplicationMetric*(可选) 不是每个页面都有
|
|
321
|
+
数据控制 ApplicationQueryToolbar L4
|
|
322
|
+
ApplicationFilterList L4 的已应用筛选标签
|
|
323
|
+
数据展示 ApplicationDataDisplay L5
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
`SPLIT` 模式另有左栏 `ApplicationSplitListSidebar`(360px,Compact 300px)。
|
|
327
|
+
`DETAIL` 结构用 `ApplicationRecordDetailBody`。
|
|
328
|
+
|
|
329
|
+
### 三个绝不能混为一谈的切换器
|
|
330
|
+
|
|
331
|
+
- **Page Mode Switch** —— 页面级,位于上下文区右侧、页面动作组之后。
|
|
332
|
+
仅当页面真正开放 2 个以上模式时渲染,否则不占位。改 `pageMode`。
|
|
333
|
+
- **View Mode Switch** —— 仅 `SPLIT` 右栏。改 `dataPresentation`,**绝不改** `pageMode`。
|
|
334
|
+
- **Presentation Settings** —— 是一个*概念*,不是一个按钮名。
|
|
335
|
+
按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
|
|
336
|
+
**禁止通用的「视图设置」按钮。** 呈现设置不得改变搜索、筛选、业务视图或页面模式,
|
|
337
|
+
它只调整当前呈现方式的展示细节。
|
|
338
|
+
|
|
339
|
+
### 六种数据状态
|
|
340
|
+
|
|
341
|
+
`ApplicationDataDisplay` 的 `state` 取六值:
|
|
342
|
+
`ready` / `loading` / `empty` / `error` / `no-permission` / `not-found`。
|
|
343
|
+
|
|
344
|
+
**六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「你没有权限」「请求失败」
|
|
345
|
+
是三句不同的话,成因不同,用户的下一步动作也不同。
|
|
346
|
+
另有 Partial Failure —— 部分数据加载失败,不等同于 `error`。
|
|
347
|
+
|
|
348
|
+
页面头部的数据状态(`ApplicationPageHeader` 的 `dataStatus`)另有三值:
|
|
349
|
+
`normal`(附最后更新时间)/ `refreshing` / `failed`(附重试入口)。
|
|
350
|
+
|
|
351
|
+
### 关键尺寸
|
|
352
|
+
|
|
353
|
+
抽屉宽 680px(`--application-drawer-width: 1280px` 是宽/全屏变体);
|
|
354
|
+
表单对话框 720px / 960px;`SPLIT` 左栏 360px(Compact 300px);
|
|
355
|
+
卡片网格默认 ≥1440 五列、Condensed 四列、Compact 三列,卡片最小宽 220px。
|
|
356
|
+
|
|
357
|
+
### Mock 数据
|
|
358
|
+
|
|
359
|
+
真实数据缺失时使用已登记的占位符,逐字复用,不得即兴发挥:
|
|
360
|
+
|
|
361
|
+
`示例应用`(应用名)· `应用说明信息`(应用描述)· `模块名称`(当前模块)·
|
|
362
|
+
`模块 A` / `模块 B` / `模块 C`(模块菜单)· `Tab 1` / `Tab 2`(业务标签)· `企业名称`(品牌兜底)。
|
|
363
|
+
|
|
364
|
+
`模块1` / `模块2` 作为标签文案被明令禁止。
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
## 组合约定
|
|
368
|
+
|
|
369
|
+
### 三层的取用顺序
|
|
370
|
+
|
|
371
|
+
组件分三层,选型时**自上而下**试,不要反过来:
|
|
372
|
+
|
|
373
|
+
1. **Application Module**(26 个)—— 页面级装配件。页面骨架、导航带、指标区、
|
|
374
|
+
数据控制与数据展示都已在这一层成型,直接用,不要用 Foundation 件自行拼装。
|
|
375
|
+
2. **Application Atomic**(7 个)—— 应用原子件。语义按钮、搜索框、列表分页等
|
|
376
|
+
带产品语义的小件。存在稳定语义适配器时**应当**优先于同职责的 Foundation 件。
|
|
377
|
+
3. **Foundation**(58 个)—— 通用基础件。前两层都没有对应物时才下探到这一层。
|
|
378
|
+
|
|
379
|
+
反向拼装的代价是可预测性:同一个控件在不同页面长得不一样,规范把这称为
|
|
380
|
+
「未登记元素」,是明令禁止的。
|
|
381
|
+
|
|
382
|
+
### token 的两层边界
|
|
383
|
+
|
|
384
|
+
| 前缀 | 定位 | 谁可以用 |
|
|
385
|
+
|---|---|---|
|
|
386
|
+
| `--ds-*` | Foundation 内部实现,可能变动 | 仅 Foundation 组件 |
|
|
387
|
+
| `--application-*` / `--ui-*` | 公共接口,稳定契约 | 应用代码、页面布局 |
|
|
388
|
+
|
|
389
|
+
业务代码只读 `--application-*` 与 `--ui-*`。下探 `--ds-*` 等于依赖内部实现,
|
|
390
|
+
小版本即可能失效。唯一的例外是换肤入口 `--ds-color-theme-primary`,
|
|
391
|
+
应用层可以且应当覆盖它。
|
|
392
|
+
|
|
393
|
+
**任何情况下都不得在业务代码中写字面色值、圆角与间距去对齐组件。**
|
|
394
|
+
需要与组件对齐时读同一个 token。
|
|
395
|
+
|
|
396
|
+
### 间距归属
|
|
397
|
+
|
|
398
|
+
外边距由**父容器**负责,组件自身只管内边距。
|
|
399
|
+
|
|
400
|
+
组件不带外边距,是为了让它在任何容器里都可预测。需要间隔时由布局容器给
|
|
401
|
+
`gap`,不要给组件加 `margin` —— 那会让同一个组件在不同页面有不同的外观。
|
|
402
|
+
|
|
403
|
+
### 状态一律由 CSS 表达
|
|
404
|
+
|
|
405
|
+
`:hover` / `:focus-visible` / `:disabled` / `:active` 全部已由组件内部的 CSS 伪类实现。
|
|
406
|
+
业务代码**不得**用 `useState` 模拟这些状态,也不得传 `onMouseEnter` / `onMouseLeave`
|
|
407
|
+
去驱动样式 —— 那会让组件强制成为 client component,且拿不到 `:focus-visible`
|
|
408
|
+
与 hover 可区分这条规范要求。
|
|
409
|
+
|
|
410
|
+
### 受控与非受控
|
|
411
|
+
|
|
412
|
+
同时接受 `value` 与 `defaultValue`(或 `open` 与 `defaultOpen`)的组件,
|
|
413
|
+
两者**互斥**:给了受控 prop 就必须同时给对应的变化回调,否则控件会锁死。
|
|
414
|
+
|
|
415
|
+
变化回调的命名一律是 `on<X>Change`,不是 `on<X>`。
|
|
416
|
+
提交语义的回调才叫 `onSubmit` —— 它与变化回调不是一回事,
|
|
417
|
+
`SearchField` 的 `onSubmit` 仅在 Enter 时触发,中途输入不触发。
|
|
418
|
+
|
|
419
|
+
### 无障碍的两条硬要求
|
|
420
|
+
|
|
421
|
+
- 任何 `iconOnly` 为 true 的控件**必须**给 `aria-label`,因为它没有可见文字。
|
|
422
|
+
- 浮层类组件的焦点陷阱、Esc 关闭与焦点恢复已由内部 Overlay 基座实现,
|
|
423
|
+
业务代码**不得**自行再挂一层 `keydown` 监听去处理 Esc,那会造成双重关闭。
|
|
424
|
+
|
|
425
|
+
### 滚动
|
|
426
|
+
|
|
427
|
+
Content Canvas 是页面唯一的主垂直滚动权持有者。
|
|
428
|
+
`ScrollArea` 与 `MessageScroller` 只用于**正交方向**(水平)或**局部有界**的溢出,
|
|
429
|
+
且必须给出显式高度或最大高度。不得堆叠无界的垂直滚动容器。
|
|
430
|
+
|
|
431
|
+
### 图标
|
|
432
|
+
|
|
433
|
+
图标一律走 `Icon` 组件。字形名必须先登记在组件库的 `src/icon/registry.json`,
|
|
434
|
+
尺寸只取 14 / 16 / 18 / 20 / 24 五档。
|
|
435
|
+
不得用 Emoji、系统字体符号(`✓ ★ ›`)、逐页手写内联 SVG 或临时换用其他图标库。
|
|
436
|
+
|
|
437
|
+
### 文案
|
|
438
|
+
|
|
439
|
+
用户可见标签是 2–4 字裸名词短语(`新建` / `列设置` / `关闭`),动词裸用,
|
|
440
|
+
不写 `点击新建` 这类祈使句。Loading / Empty / Error / No Permission / Not Found /
|
|
441
|
+
Partial Failure 六种状态的文案各不相同,不得共用。
|
|
442
|
+
Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
|
|
443
|
+
|
|
444
|
+
> 逐组件的组合约定(91 个章节:何时使用、何时改用其他组件、禁止与使用边界)
|
|
445
|
+
> 见 `node_modules/@moheng-design/ui-skill/generated/reference.md`。
|
|
446
|
+
|
|
447
|
+
## 反例
|
|
448
|
+
|
|
449
|
+
<!-- 手写文件。被 generate.mjs 嵌入 SKILL.md 的「反例」一节与 reference.md。
|
|
450
|
+
内部标题必须从 ### 起,否则嵌入后会与宿主文档的层级冲突。
|
|
451
|
+
|
|
452
|
+
§6.2:成对的 bad / good 例子,经验上比正面描述有效得多。
|
|
453
|
+
每一条都必须对应一个真实发生过或被规范明令禁止的写法,不要凭空设想。 -->
|
|
454
|
+
|
|
455
|
+
以下每一条都对应一个真实发生过、或被规范明令禁止的写法。
|
|
456
|
+
|
|
457
|
+
### 发明不存在的 prop
|
|
458
|
+
|
|
459
|
+
设计系统源的 `Button.prompt.md` 引用了 `variant="icon"` —— 该值在任何版本的契约中都不存在。
|
|
460
|
+
这是手写文档漂移的实证,不是假设。
|
|
461
|
+
|
|
462
|
+
```jsx
|
|
463
|
+
// 不要这样写
|
|
464
|
+
<Button variant="icon"><Icon name="rotate-cw" size={16} /></Button>
|
|
465
|
+
<Button size="icon"><Icon name="rotate-cw" size={16} /></Button>
|
|
466
|
+
|
|
467
|
+
// 要这样写 —— 尺寸与形状是两根轴,iconOnly 控制形状
|
|
468
|
+
<Button iconOnly aria-label="刷新"><Icon name="rotate-cw" size={16} /></Button>
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
`variant` 只有 `primary` / `secondary` / `outline` / `ghost` / `destructive` / `link`;
|
|
472
|
+
`size` 只有 `xs` / `sm` / `default` / `lg`。**shadcn 习惯的 `size="icon"` 在本库不存在。**
|
|
473
|
+
|
|
474
|
+
`iconOnly` 为 true 时按钮没有可见文字,**必须**另给 `aria-label`。
|
|
475
|
+
|
|
476
|
+
### 内联 style
|
|
477
|
+
|
|
478
|
+
```jsx
|
|
479
|
+
// 不要这样写
|
|
480
|
+
<div style={{ padding: 16, borderRadius: 16, background: '#f5f5f5' }}>
|
|
481
|
+
|
|
482
|
+
// 要这样写
|
|
483
|
+
<Card>…</Card>
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
组件内无内联 style(01 §1.7)。内联 style 优先级最高,会让调用方传的 `className` 失效,
|
|
487
|
+
且写不了 `:focus-visible` 这类伪类 —— 而规范要求焦点态必须与 hover / active 可区分。
|
|
488
|
+
|
|
489
|
+
需要动态尺度时走 CSS 自定义属性,不要走 style 对象里的字面值。
|
|
490
|
+
|
|
491
|
+
### 用 JS state 模拟 hover
|
|
492
|
+
|
|
493
|
+
```jsx
|
|
494
|
+
// 不要这样写
|
|
495
|
+
const [hover, setHover] = useState(false)
|
|
496
|
+
<Button onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
|
|
497
|
+
|
|
498
|
+
// 要这样写 —— 什么都不写,hover 已由 CSS 伪类实现
|
|
499
|
+
<Button>提交</Button>
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
`useState` 会让组件强制成为 client component。状态一律用 CSS 伪类
|
|
503
|
+
(`:hover` / `:focus-visible` / `:disabled` / `:active`)。
|
|
504
|
+
|
|
505
|
+
### 换肤改错了变量
|
|
506
|
+
|
|
507
|
+
```css
|
|
508
|
+
/* 不要这样写 —— 只会改到引用它的那部分组件 */
|
|
509
|
+
:root { --application-accent: #16a34a; }
|
|
510
|
+
|
|
511
|
+
/* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上一律无效 */
|
|
512
|
+
<div className="dark">…</div>
|
|
513
|
+
|
|
514
|
+
/* 要这样写 */
|
|
515
|
+
<html class="dark" style="--ds-color-theme-primary: #16a34a">
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
`--ds-color-theme-primary` 是换肤契约的唯一入口。
|
|
519
|
+
换肤与 `.dark` **必须挂在 `<html>` 上** —— `var()` 代换在声明所在元素就完成了,
|
|
520
|
+
挂在 `<body>` 或容器 div 上无效(已实测)。系统内不存在「局部暗色区块」这种用法。
|
|
521
|
+
|
|
522
|
+
### 手写表格结构
|
|
523
|
+
|
|
524
|
+
```jsx
|
|
525
|
+
// 不要这样写
|
|
526
|
+
<table><thead><tr><th>名称</th></tr></thead><tbody><tr><td>示例应用</td></tr></tbody></table>
|
|
527
|
+
|
|
528
|
+
// 要这样写 —— Table 是数据驱动的
|
|
529
|
+
<Table columns={[{ key: 'name', title: '名称' }]} rows={rows} />
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
`Table` 不接受复合子组件。`<tr>` / `<td>` 脱离 `<table>` 后本就无处可写。
|
|
533
|
+
|
|
534
|
+
### 逐个渲染单选项
|
|
535
|
+
|
|
536
|
+
```jsx
|
|
537
|
+
// 不要这样写
|
|
538
|
+
{options.map((o) => <input type="radio" name="scope" value={o.value} key={o.value} />)}
|
|
539
|
+
|
|
540
|
+
// 要这样写 —— 单选的语义单位就是组
|
|
541
|
+
<RadioGroup value={scope} onValueChange={setScope} items={[{ value: 'all', label: '全部' }]} />
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
系统内没有「单个单选项」组件。逐个渲染会丢掉分组的键盘导航与 `name` 绑定。
|
|
545
|
+
|
|
546
|
+
### 逐字实时搜索
|
|
547
|
+
|
|
548
|
+
```jsx
|
|
549
|
+
// 不要这样写
|
|
550
|
+
<input type="search" onChange={(e) => search(e.target.value)} />
|
|
551
|
+
|
|
552
|
+
// 要这样写 —— onSubmit 仅在 Enter 时触发
|
|
553
|
+
<SearchField ariaLabel="搜索记录" onSubmit={search} />
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
规范禁止逐字实时搜索作为默认行为。搜索必须通过 Enter 或明确的搜索动作提交。
|
|
557
|
+
`ariaLabel` 是必填。
|
|
558
|
+
|
|
559
|
+
### 引入平行的组件实现
|
|
560
|
+
|
|
561
|
+
```jsx
|
|
562
|
+
// 不要这样写
|
|
563
|
+
import { Button } from '@/components/ui/button'
|
|
564
|
+
import { Button } from '@moheng-design/ui/dist/components/foundation/actions/Button.js'
|
|
565
|
+
|
|
566
|
+
// 要这样写
|
|
567
|
+
import { Button } from '@moheng-design/ui'
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
`@/components/ui/` 目录通常是 `npx shadcn add` 生成的第二套组件源码,
|
|
571
|
+
与本库并存会造成同一界面两套视觉。本库**不提供** shadcn registry 分发(01 §1.2),
|
|
572
|
+
样式覆盖走 CSS 自定义属性与 `className` 叠加,不走改源码。
|
|
573
|
+
|
|
574
|
+
内部路径不在 exports map 中,不构成公开接口,任意小版本都可能改动。
|
|
575
|
+
|
|
576
|
+
### 忘记引样式表
|
|
577
|
+
|
|
578
|
+
```jsx
|
|
579
|
+
// 不要这样写 —— 组件渲染出来是无样式的裸结构
|
|
580
|
+
import { Button } from '@moheng-design/ui'
|
|
581
|
+
|
|
582
|
+
// 要这样写 —— 应用入口引一次即可
|
|
583
|
+
import { Button } from '@moheng-design/ui'
|
|
584
|
+
import '@moheng-design/ui/styles.css'
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
样式不随组件模块自动引入,这是为了让组件模块保持无副作用、不影响 tree-shaking。
|
|
588
|
+
代价是应用入口要显式引一行。
|
|
589
|
+
|
|
590
|
+
### 通用的「视图设置」按钮
|
|
591
|
+
|
|
592
|
+
```jsx
|
|
593
|
+
// 不要这样写
|
|
594
|
+
<Button>视图设置</Button>
|
|
595
|
+
|
|
596
|
+
// 要这样写 —— 按当前呈现方式命名
|
|
597
|
+
<Button>列设置</Button> {/* DataTable */}
|
|
598
|
+
<Button>看板设置</Button> {/* KanbanBoard */}
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
呈现设置是一个*概念*,不是一个按钮名。按钮必须按当前呈现方式命名:
|
|
602
|
+
`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
|
|
603
|
+
|
|
604
|
+
### 六种数据状态共用一句话
|
|
605
|
+
|
|
606
|
+
```jsx
|
|
607
|
+
// 不要这样写
|
|
608
|
+
{items.length === 0 && <Empty title="暂无数据" />}
|
|
609
|
+
|
|
610
|
+
// 要这样写 —— 成因不同,用户的下一步动作也不同
|
|
611
|
+
<ApplicationDataDisplay
|
|
612
|
+
state={state}
|
|
613
|
+
empty={<Empty title="当前视角下无数据" description="切换业务视图或调整筛选条件" />}
|
|
614
|
+
noPermission={<Empty title="没有查看权限" description="请联系管理员申请" />}
|
|
615
|
+
error={<Empty title="加载失败" description="请稍后重试" />}
|
|
616
|
+
/>
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
Loading / Empty / Error / No Permission / Not Found / Partial Failure
|
|
620
|
+
**绝不能共用同一句话**。
|
|
621
|
+
|
|
622
|
+
### 堆叠无界的垂直滚动容器
|
|
623
|
+
|
|
624
|
+
```jsx
|
|
625
|
+
// 不要这样写
|
|
626
|
+
<ScrollArea><ScrollArea>…</ScrollArea></ScrollArea>
|
|
627
|
+
<ScrollArea>{/* 没给高度,等于没有「有界」前提 */}</ScrollArea>
|
|
628
|
+
|
|
629
|
+
// 要这样写 —— 显式给界,或改用水平方向
|
|
630
|
+
<ScrollArea maxHeight={320}>…</ScrollArea>
|
|
631
|
+
<ScrollArea horizontal>…</ScrollArea>
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
Content Canvas 是页面唯一的主垂直滚动权持有者。
|
|
635
|
+
`ScrollArea` 与 `MessageScroller` 只用于正交方向或局部有界的溢出,且必须给出高度。
|
|
636
|
+
|
|
637
|
+
### 用 Emoji 或系统字符代替图标
|
|
638
|
+
|
|
639
|
+
```jsx
|
|
640
|
+
// 不要这样写
|
|
641
|
+
<span>✓ 已完成</span>
|
|
642
|
+
<span>★</span>
|
|
643
|
+
<svg viewBox="0 0 24 24"><path d="…" /></svg>
|
|
644
|
+
|
|
645
|
+
// 要这样写
|
|
646
|
+
<Icon name="check" size={16} />
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
Shell 契约点名禁止四件事:用 Emoji、用系统字体符号(`✓ ★ ›`)、
|
|
650
|
+
逐页手写内联 SVG、临时换用其他图标库。
|
|
651
|
+
|
|
652
|
+
字形名必须先登记在 `src/icon/registry.json`,尺寸只取 14 / 16 / 18 / 20 / 24 五档。
|
|
653
|
+
|
|
654
|
+
### 硬编码样式值(仅限库内)
|
|
655
|
+
|
|
656
|
+
```css
|
|
657
|
+
/* 不要这样写 */
|
|
658
|
+
.mh-card { padding: 16px; border-radius: 16px; background: #f5f5f5; }
|
|
659
|
+
|
|
660
|
+
/* 要这样写 */
|
|
661
|
+
.mh-card { padding: var(--ds-space-4); border-radius: var(--ds-radius-16); background: var(--ds-color-surface); }
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
这三条规则 `scope` 是 `internal`,**只在组件库内部生效**,业务代码不受约束
|
|
665
|
+
(01 §7.3:用户业务代码里出现色值是完全正常的,全量禁止会吵到用户直接关掉整条规则)。
|
|
666
|
+
|
|
667
|
+
库内写死 px 会让三档密度在该处失效 —— 响应式密度靠 `@media` 改写 `:root` 变量实现。
|
|
668
|
+
|
|
669
|
+
### Application Module 组件脱离五层模型
|
|
670
|
+
|
|
671
|
+
```jsx
|
|
672
|
+
// 不要这样写 —— 当成普通布局容器用
|
|
673
|
+
<ApplicationPageHeader title="标题" />
|
|
674
|
+
|
|
675
|
+
// 要这样写 —— 五层全部声明为状态字段
|
|
676
|
+
<ApplicationPageHeader
|
|
677
|
+
title="标题"
|
|
678
|
+
pageMode={pageMode}
|
|
679
|
+
pageModes={['LIST', 'CARD']}
|
|
680
|
+
onPageModeChange={setPageMode}
|
|
681
|
+
dataStatus="normal"
|
|
682
|
+
updatedAt={updatedAt}
|
|
683
|
+
/>
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `businessView` /
|
|
687
|
+
`dataControl` / `dataPresentation` 这套模型。装本库即意味着接受这套结构约定。
|
|
688
|
+
|
|
689
|
+
|
|
690
|
+
## 完整参考
|
|
691
|
+
|
|
692
|
+
组件完整 props 签名、契约原文与逐组件组合约定见
|
|
693
|
+
`node_modules/@moheng-design/ui-skill/generated/reference.md`。
|
|
694
|
+
|
|
695
|
+
lint 规则数据见 `node_modules/@moheng-design/ui-skill/generated/rules.json`,
|
|
696
|
+
接入方式见该包 README。
|