@moheng-design/ui-skill 1.0.0 → 3.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 +11 -4
- package/bin/lib/audit.mjs +21 -5
- package/bin/lib/feedback.mjs +20 -3
- package/bin/lib/install.mjs +6 -2
- package/bin/lib/upgrade.mjs +35 -8
- package/generated/SKILL.md +291 -83
- package/generated/contracts.json +2118 -703
- package/generated/plugin-data.js +512 -47
- package/generated/reference.md +1299 -513
- package/generated/rules.json +525 -48
- package/generated/skills/moheng-ui-audit/SKILL.md +16 -5
- package/generated/skills/moheng-ui-bootstrap/SKILL.md +10 -6
- package/generated/skills/moheng-ui-feedback/SKILL.md +8 -3
- package/generated/skills/moheng-ui-page/SKILL.md +37 -13
- package/generated/skills/moheng-ui-review/SKILL.md +8 -5
- package/generated/skills/moheng-ui-upgrade/SKILL.md +6 -4
- package/generated/unenforced.json +20 -5
- package/handwritten/anti-patterns.md +45 -25
- package/handwritten/canvas-model.md +189 -15
- package/handwritten/conventions.md +330 -194
- package/handwritten/skills/audit.md +9 -1
- package/handwritten/skills/bootstrap.md +8 -4
- package/handwritten/skills/feedback.md +6 -1
- package/handwritten/skills/page.md +33 -9
- package/handwritten/skills/upgrade.md +5 -3
- package/handwritten/unenforced.md +6 -3
- package/package.json +3 -3
|
@@ -13,26 +13,123 @@ Application
|
|
|
13
13
|
└─ Overlay Dialog / Drawer / Popover / Menu / Toast
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
### Shell
|
|
16
|
+
### Shell 导航带
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
固定骨架,**没有左侧全局栏**。导航带永不滚动。几何以 GAP Design kit「框架结构」为准,外壳有两种形态:
|
|
19
|
+
|
|
20
|
+
| 形态 | 带(自上而下) | Standard 总高 | Compact 总高 |
|
|
21
|
+
|---|---|---:|---:|
|
|
22
|
+
| 基础版 | 应用一级 + 应用二级 | 96px | 80px |
|
|
23
|
+
| 集团版 | 集团顶部 + 应用一级 + 应用二级 | 144px | 120px |
|
|
19
24
|
|
|
20
25
|
| 带 | 组件 | Standard | Compact |
|
|
21
26
|
|---|---|---:|---:|
|
|
22
|
-
|
|
|
23
|
-
| 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` |
|
|
27
|
+
| 集团顶部导航 `PLATFORM.TOP_USER_BAR`(仅集团版) | `TopNavigationPrimaryBar` | 48px | 40px |
|
|
28
|
+
| 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 48px | 40px |
|
|
24
29
|
| 应用二级导航 `APPLICATION.SECONDARY_NAV` | `ApplicationSecondaryNavigation` | 48px | 40px |
|
|
25
30
|
| Content Canvas | `ApplicationPageLayoutContainer` | 剩余视口 | 剩余视口 |
|
|
26
31
|
|
|
27
|
-
|
|
32
|
+
账户头像在基础版里是 `ApplicationPrimaryNavigation` 的 `account`,在集团版里在 `TopNavigationPrimaryBar`,
|
|
33
|
+
一个外壳只有一处。外壳总高读 `--ui-shell-application-total-height`:渲染了 `TopNavigationPrimaryBar` 时它自动计入
|
|
34
|
+
集团顶栏,宿主不必区分两种形态。
|
|
35
|
+
|
|
36
|
+
Compact 档在视口宽 ≤1180px 或高 ≤720px 时生效(`--ui-viewport-compact-max-width` / `-height`),
|
|
37
|
+
各带高度由同一组 `@media` 一并切换,宿主不得自行复刻断点。
|
|
38
|
+
|
|
39
|
+
宿主 padding 为零 —— padding 属于页面内容根。
|
|
40
|
+
|
|
41
|
+
### 宿主布局
|
|
42
|
+
|
|
43
|
+
本库不提供宿主组件(07 · C-5:组件留到第二个真实项目再抽),导航带 + Canvas 的宿主由应用
|
|
44
|
+
自己写,标准写法如下(类名由宿主自定,只读 `--application-*` 与 `--ui-*`):
|
|
45
|
+
|
|
46
|
+
```css
|
|
47
|
+
html,
|
|
48
|
+
body {
|
|
49
|
+
block-size: 100%;
|
|
50
|
+
margin: 0;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
.app-shell { /* 导航带 + Canvas,整体占满视口 */
|
|
54
|
+
display: flex;
|
|
55
|
+
flex-direction: column;
|
|
56
|
+
block-size: 100dvh;
|
|
57
|
+
background: var(--application-canvas);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
.app-shell__bands { /* 包住全部导航带;不进滚动容器,即永不滚动 */
|
|
61
|
+
flex: none;
|
|
62
|
+
z-index: var(--ui-z-shell);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
.app-shell__canvas { /* Content Canvas:必须是列向 flex */
|
|
66
|
+
display: flex;
|
|
67
|
+
flex: 1;
|
|
68
|
+
flex-direction: column;
|
|
69
|
+
min-block-size: 0;
|
|
70
|
+
overflow: auto;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
.app-shell__page { /* 页面根(ApplicationPageLayoutContainer 的 className) */
|
|
74
|
+
flex: 1;
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Canvas 必须是列向 flex 容器。** 写成块级 + `overflow: auto`(最自然的写法)时,
|
|
79
|
+
`ApplicationPageLayoutContainer` 按内容撑高,`ApplicationDataDisplay`「自身滚动、分页固定在底部」
|
|
80
|
+
随之失效 —— 05 · P2-1 实测 46 行时分页被推到首屏以下 533px。页面根 `flex: 1` 让内容不足一屏时
|
|
81
|
+
数据展示区的边框仍画到底。`DETAIL` 页的容器随内容增高,由同一个 Canvas 滚动,宿主不必区分页型。
|
|
82
|
+
|
|
83
|
+
**`GlobalSidebar` 与内容区并排**(工作台):两者包一层横向 flex 作为 Canvas 的直接子元素,
|
|
84
|
+
菜单栏 `sticky` 停在 Canvas 顶部、自己不滚动,内容区随内容撑高、由 Canvas 滚动:
|
|
85
|
+
|
|
86
|
+
```css
|
|
87
|
+
.workbench { /* Canvas 的直接子元素 */
|
|
88
|
+
display: flex;
|
|
89
|
+
flex: 1 0 auto;
|
|
90
|
+
align-items: flex-start;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
.workbench__rail { /* GlobalSidebar 的 className */
|
|
94
|
+
position: sticky;
|
|
95
|
+
inset-block-start: 0;
|
|
96
|
+
flex: none;
|
|
97
|
+
block-size: calc(100dvh - var(--ui-shell-application-total-height));
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
.workbench__main { /* ApplicationPageLayoutContainer 的 className */
|
|
101
|
+
flex: 1;
|
|
102
|
+
min-inline-size: 0;
|
|
103
|
+
align-self: stretch;
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### 纵向滚动归属
|
|
108
|
+
|
|
109
|
+
每个页面**有且只有一个**页面级纵向滚动持有者,按页型划分(06 · D-4 裁决):
|
|
110
|
+
|
|
111
|
+
| 页面 | 纵向滚动持有者 | 理由 |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| 结果集页面(见下「五层认知模型」) | `ApplicationDataDisplay` 的主体 | 上下文区、工具栏、分页条与批量条固定,只有结果滚动 |
|
|
114
|
+
| `WORKBENCH` / `DETAIL` / `ANALYSIS` 多面板 / 无结果集页面 | Content Canvas | 内容是若干面板或分节,整页一起滚;放进 DataDisplay 会只剩约 290px 可视高度 |
|
|
115
|
+
|
|
28
116
|
表格、看板、标签页、日历可以拥有正交的水平滚动或局部有界滚动;
|
|
29
|
-
|
|
117
|
+
不得堆叠无界的垂直滚动容器。多面板的 `ANALYSIS` 页不得把面板组塞进 `ApplicationDataDisplay`。
|
|
30
118
|
|
|
31
119
|
Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑、通知铃铛、页面标题、卡片、阴影。
|
|
32
120
|
|
|
33
121
|
### 五层认知模型
|
|
34
122
|
|
|
35
|
-
|
|
123
|
+
必填字段按页面有没有**结果集**划分(06 · D-1 裁决)。判据是页面是否有一份由
|
|
124
|
+
`ApplicationQueryToolbar` 驱动、由 `ApplicationDataDisplay` 展示的记录集合:
|
|
125
|
+
|
|
126
|
+
| 页面 | 必须声明的字段 | 典型 |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| 结果集页面 | 五层**全部**,缺一层即为结构不完整 | `MANAGEMENT` / `LEDGER` / `REPORT` 的列表页;以查询结果为主体的 `ANALYSIS` 页(单模式时 `pageMode` 取 `LIST`,切换器不渲染) |
|
|
129
|
+
| 无结果集页面 | 只声明 `pageType`,其余四层**不写**;不得为凑字段塞一个 `ApplicationDataDisplay` 或空工具栏 | `WORKBENCH` 工作台、`DETAIL` 详情页、配置页、协作工作台、编辑器型工作面 |
|
|
130
|
+
|
|
131
|
+
无结果集页面的 `pageType` 按所属业务取值:工作台取 `WORKBENCH`,详情页取 `DETAIL`,
|
|
132
|
+
配置页与协作工作台取其所属模块的类型(多为 `MANAGEMENT`),报表设计器随报表取 `REPORT`。
|
|
36
133
|
|
|
37
134
|
| 层 | 字段 | 取值 |
|
|
38
135
|
|---|---|---|
|
|
@@ -40,7 +137,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
|
|
|
40
137
|
| L2 页面模式 | `pageMode` | `LIST` / `CARD` / `SPLIT` / `BOARD` / `CALENDAR` |
|
|
41
138
|
| L3 业务视图 | `businessView` | 2–4 个稳定工作视角(全部 / 我的责任 / 最近处理) |
|
|
42
139
|
| L4 数据控制 | `dataControl` | search / filters / sort / pagination / appliedFilterTags |
|
|
43
|
-
| L5 数据呈现 | `dataPresentation` | `DataTable` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
|
|
140
|
+
| L5 数据呈现 | `dataPresentation` | `DataTable` / `RecordList` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
|
|
44
141
|
|
|
45
142
|
`DETAIL` 与 `COMPOSITE` **不是**页面模式,是特殊物理结构资产。
|
|
46
143
|
`Embedded` 是 `integrationMode`,不是页面模式。
|
|
@@ -50,14 +147,76 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
|
|
|
50
147
|
自上而下固定,不得重排:
|
|
51
148
|
|
|
52
149
|
```
|
|
53
|
-
|
|
150
|
+
内容根 ApplicationPageLayoutContainer L1,pageType 必填;包住以下四个区域
|
|
151
|
+
上下文区 ApplicationPageHeader L2 / L3 的承载者
|
|
54
152
|
指标区 ApplicationMetric*(可选) 不是每个页面都有
|
|
55
153
|
数据控制 ApplicationQueryToolbar L4
|
|
56
154
|
ApplicationFilterList L4 的已应用筛选标签
|
|
57
155
|
数据展示 ApplicationDataDisplay L5
|
|
58
156
|
```
|
|
59
157
|
|
|
60
|
-
|
|
158
|
+
上表是结果集页面的顺序。`SPLIT` 与无结果集页面的结构见下两节。
|
|
159
|
+
|
|
160
|
+
### SPLIT 的标准组件树
|
|
161
|
+
|
|
162
|
+
工具栏服务右栏,但放在横跨两栏的 `dataControl` 槽位 —— 它管的是右栏的结果集,
|
|
163
|
+
左栏目录只改变查询范围(06 · D-4 裁决):
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
ApplicationPageLayoutContainer pageType, dataControl
|
|
167
|
+
├─ header ApplicationPageHeader pageMode="SPLIT"
|
|
168
|
+
├─ dataControl ApplicationQueryToolbar businessView、search / filters / sort、viewModeSwitch
|
|
169
|
+
│ └─ moreFilters Popover > ApplicationFilterList(不得用 Collapsible 就地展开)
|
|
170
|
+
└─ children Resizable 左栏宽度取 --ui-sidebar-list-width(360 / Compact 300)
|
|
171
|
+
├─ ApplicationSplitListSidebar 目录定位,只改变查询范围
|
|
172
|
+
└─ ApplicationDataDisplay presentation = 当前 View Mode
|
|
173
|
+
└─ ApplicationRecordList / Table / 呈现配方
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
右栏需要再分「结果 / 概况」等内容标签时,`Tabs` 放在右栏顶部、`ApplicationDataDisplay`
|
|
177
|
+
作为当前标签的面板;概况标签下工具栏仍在,但不得为它另起第二个工具栏。
|
|
178
|
+
|
|
179
|
+
### 无结果集页面的结构
|
|
180
|
+
|
|
181
|
+
这类页面只声明 `pageType`,由 Content Canvas 整页滚动,没有工具栏与数据展示区。
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
WORKBENCH ApplicationPageLayoutContainer pageType="WORKBENCH"
|
|
185
|
+
├─ header ApplicationPageHeader(标题、数据时刻、刷新;不渲染 Page Mode Switch)
|
|
186
|
+
└─ children 分区导航 GlobalSidebar + 面板网格(指标区、待办、动态、应用入口)
|
|
187
|
+
|
|
188
|
+
DETAIL ApplicationPageLayoutContainer pageType="DETAIL"
|
|
189
|
+
├─ header ApplicationPageHeader(breadcrumb 返回来源列表;对象级动作放 actions)
|
|
190
|
+
└─ children ApplicationRecordDetailBody(分节;分节级动作放分节标题行)
|
|
191
|
+
|
|
192
|
+
编辑器 ApplicationPageLayoutContainer pageType 随所属业务
|
|
193
|
+
├─ header ApplicationPageHeader(标题、保存 / 发布等页面动作)
|
|
194
|
+
├─ dataControl Menubar(编辑命令就是这页的「数据控制」)
|
|
195
|
+
└─ children 工作面:Resizable 两栏,各栏自带有界 ScrollArea
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**对象级动作的落点**:详情页与协作工作台里针对「当前对象」的动作(编辑、指派、删除)
|
|
199
|
+
放 `ApplicationPageHeader` 的 `actions`;`ApplicationRecordDetailBody` 只放分节级动作。
|
|
200
|
+
|
|
201
|
+
### 呈现配方
|
|
202
|
+
|
|
203
|
+
`KanbanBoard` / `Calendar` / `Timeline` 暂无专属组件,按下面的标准拼装写法承载
|
|
204
|
+
(06 · D-2 裁决:先登记配方,组件留到第二个真实项目再抽)。三者都放在
|
|
205
|
+
`ApplicationDataDisplay` 的 `children` 里,仅 `state="ready"` 时渲染,不得自画外框。
|
|
206
|
+
|
|
207
|
+
- **看板(`KanbanBoard`)**:`ScrollArea horizontal` 包一行等宽列,列宽取
|
|
208
|
+
`--ui-card-min-width`;每列是「列标题 + 计数」与一串 `Card density="sm" interactive`;
|
|
209
|
+
卡片内勾选用 `ListSelectionCheckbox`,行级动作用 `DropdownMenu`(「更多 → 移至」代替拖拽)。
|
|
210
|
+
看板是「不得嵌套 `ScrollArea`」的登记例外(07 · C-14):外层 `ScrollArea horizontal` 撑满数据展示区
|
|
211
|
+
主体的高度、只管横向,每列的卡片串放进一个纵向 `ScrollArea`、高度取列的剩余高度,列内纵向滚动。
|
|
212
|
+
横向滚动条因此始终贴在可视区底部,不会被推到五列溢出的纵向末尾(06 · P2-7)。除看板外仍不得嵌套。
|
|
213
|
+
- **月历(`Calendar`)**:自拼 7 列月格,`role="grid"` / `row` / `gridcell`,周一起始,
|
|
214
|
+
月末空位补白格;每格最多列 3 条,其余收进「+N」按钮。月份游标(上一月 / 下一月 / 本月)
|
|
215
|
+
放在月格上方、数据展示区之内,不进工具栏。不得用 Foundation `Calendar` 控件充当月格。
|
|
216
|
+
- **时间轴(`Timeline`)**:按日期分组,每组是 `<section aria-label>` + `Separator label`
|
|
217
|
+
(分组标题)+ `<ol>`;每条用 `Message`(作者、时间、正文)。时间轴只按时间排序,
|
|
218
|
+
不提供行选择,切到时间轴时清空已选并不渲染批量条。
|
|
219
|
+
|
|
61
220
|
`DETAIL` 结构用 `ApplicationRecordDetailBody`。
|
|
62
221
|
|
|
63
222
|
### 三个绝不能混为一谈的切换器
|
|
@@ -66,18 +225,27 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
|
|
|
66
225
|
仅当页面真正开放 2 个以上模式时渲染,否则不占位。改 `pageMode`。
|
|
67
226
|
- **View Mode Switch** —— 仅 `SPLIT` 右栏。改 `dataPresentation`,**绝不改** `pageMode`。
|
|
68
227
|
- **Presentation Settings** —— 是一个*概念*,不是一个按钮名。
|
|
69
|
-
按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
|
|
228
|
+
按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
|
|
70
229
|
**禁止通用的「视图设置」按钮。** 呈现设置不得改变搜索、筛选、业务视图或页面模式,
|
|
71
|
-
|
|
230
|
+
它只调整当前呈现方式的展示细节。面板一律用 `Popover` 承载,与更多筛选同一承载(07 · C-7)。
|
|
72
231
|
|
|
73
232
|
### 六种数据状态
|
|
74
233
|
|
|
75
234
|
`ApplicationDataDisplay` 的 `state` 取六值:
|
|
76
235
|
`ready` / `loading` / `empty` / `error` / `no-permission` / `not-found`。
|
|
77
236
|
|
|
78
|
-
**六种状态的文案绝不共用同一句话。**
|
|
237
|
+
**六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「无权查看本模块」「请求失败」
|
|
79
238
|
是三句不同的话,成因不同,用户的下一步动作也不同。
|
|
80
|
-
另有 Partial Failure —— 部分数据加载失败,不等同于 `error
|
|
239
|
+
另有 Partial Failure —— 部分数据加载失败,不等同于 `error`:`state` 仍为 `ready`,
|
|
240
|
+
呈现照常渲染,缺失的那部分用 `Alert` 放进 `ApplicationDataDisplay` 的 `notice` 槽位说明并给出重试。
|
|
241
|
+
`notice` 固定在批量条之下、呈现之上,不随内容滚动,只在 `ready` 态渲染。
|
|
242
|
+
|
|
243
|
+
**空态按成因分两句**(07 · C-6):有搜索或筛选生效时是「没有符合当前筛选条件的记录」,
|
|
244
|
+
出路 `清除筛选`;当前视图下本就没有数据时是「当前视图下还没有记录」,出路 `新建`。
|
|
245
|
+
空态只由 `ApplicationDataDisplay` 的 `empty` 槽位承担,被承载的 `Table` 不再另设 `empty`。
|
|
246
|
+
|
|
247
|
+
**非 ready 状态下的工具栏**:`no-permission` 与 `not-found` 时不渲染 `ApplicationQueryToolbar`
|
|
248
|
+
(查询条件对这两种状态没有意义);`error` 时保留,改条件即可重新查询。
|
|
81
249
|
|
|
82
250
|
页面头部的数据状态(`ApplicationPageHeader` 的 `dataStatus`)另有三值:
|
|
83
251
|
`normal`(附最后更新时间)/ `refreshing` / `failed`(附重试入口)。
|
|
@@ -85,8 +253,11 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
|
|
|
85
253
|
### 关键尺寸
|
|
86
254
|
|
|
87
255
|
抽屉宽 680px(`--application-drawer-width: 1280px` 是宽/全屏变体);
|
|
88
|
-
表单对话框 720px / 960px;`SPLIT` 左栏 360px(Compact 300px);
|
|
256
|
+
表单对话框 720px / 960px / 1280px;`SPLIT` 左栏 360px(Compact 300px);
|
|
89
257
|
卡片网格默认 ≥1440 五列、Condensed 四列、Compact 三列,卡片最小宽 220px。
|
|
258
|
+
列数读 `--ui-card-columns-default`,三档由 `viewport.css` 的 `@media` 在 `:root` 上改写(5 / 4 / 3),
|
|
259
|
+
最小宽读 `--ui-card-min-width`,卡间距读 `--ui-card-gap`;系统内没有卡片网格组件,
|
|
260
|
+
`CARD` 呈现的网格由调用方用这三个 token 写,不得在组件或页面里另写断点改列数。
|
|
90
261
|
|
|
91
262
|
### Mock 数据
|
|
92
263
|
|
|
@@ -95,4 +266,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
|
|
|
95
266
|
`示例应用`(应用名)· `应用说明信息`(应用描述)· `模块名称`(当前模块)·
|
|
96
267
|
`模块 A` / `模块 B` / `模块 C`(模块菜单)· `Tab 1` / `Tab 2`(业务标签)· `企业名称`(品牌兜底)。
|
|
97
268
|
|
|
269
|
+
业务记录的占位符(07 · C-8):`成员 A` / `成员 B` / `成员 C`(人名)· `对象 A` / `对象 B` / `对象 C`(业务对象名)·
|
|
270
|
+
`编号 0001` / `编号 0002`(记录编号,四位补零递增)。同类条目按字母或序号顺延,不得换用真实人名。
|
|
271
|
+
|
|
98
272
|
`模块1` / `模块2` 作为标签文案被明令禁止。
|