@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.
Files changed (36) hide show
  1. package/README.md +227 -0
  2. package/bin/cli.js +35 -0
  3. package/bin/lib/audit.mjs +138 -0
  4. package/bin/lib/feedback.mjs +82 -0
  5. package/bin/lib/install.mjs +61 -0
  6. package/bin/lib/paths.mjs +47 -0
  7. package/bin/lib/upgrade.mjs +86 -0
  8. package/eslint/index.js +94 -0
  9. package/eslint/lib/factories.js +313 -0
  10. package/eslint/lib/match.js +188 -0
  11. package/eslint/lib/tiers.js +27 -0
  12. package/generated/SKILL.md +696 -0
  13. package/generated/contracts.json +9270 -0
  14. package/generated/mappings.schema.json +333 -0
  15. package/generated/plugin-data.js +6994 -0
  16. package/generated/reference.md +5651 -0
  17. package/generated/rules.json +3864 -0
  18. package/generated/skills/moheng-ui-audit/SKILL.md +66 -0
  19. package/generated/skills/moheng-ui-bootstrap/SKILL.md +109 -0
  20. package/generated/skills/moheng-ui-feedback/SKILL.md +65 -0
  21. package/generated/skills/moheng-ui-page/SKILL.md +75 -0
  22. package/generated/skills/moheng-ui-review/SKILL.md +55 -0
  23. package/generated/skills/moheng-ui-upgrade/SKILL.md +40 -0
  24. package/generated/unenforced.json +57 -0
  25. package/handwritten/anti-patterns.md +239 -0
  26. package/handwritten/canvas-model.md +98 -0
  27. package/handwritten/conventions.md +2082 -0
  28. package/handwritten/skills/audit.md +54 -0
  29. package/handwritten/skills/bootstrap.md +99 -0
  30. package/handwritten/skills/feedback.md +63 -0
  31. package/handwritten/skills/page.md +44 -0
  32. package/handwritten/skills/review.md +43 -0
  33. package/handwritten/skills/upgrade.md +38 -0
  34. package/handwritten/unenforced.md +27 -0
  35. package/package.json +66 -0
  36. package/stylelint/index.js +121 -0
@@ -0,0 +1,239 @@
1
+ <!-- 手写文件。被 generate.mjs 嵌入 SKILL.md 的「反例」一节与 reference.md。
2
+ 内部标题必须从 ### 起,否则嵌入后会与宿主文档的层级冲突。
3
+
4
+ §6.2:成对的 bad / good 例子,经验上比正面描述有效得多。
5
+ 每一条都必须对应一个真实发生过或被规范明令禁止的写法,不要凭空设想。 -->
6
+
7
+ 以下每一条都对应一个真实发生过、或被规范明令禁止的写法。
8
+
9
+ ### 发明不存在的 prop
10
+
11
+ 设计系统源的 `Button.prompt.md` 引用了 `variant="icon"` —— 该值在任何版本的契约中都不存在。
12
+ 这是手写文档漂移的实证,不是假设。
13
+
14
+ ```jsx
15
+ // 不要这样写
16
+ <Button variant="icon"><Icon name="rotate-cw" size={16} /></Button>
17
+ <Button size="icon"><Icon name="rotate-cw" size={16} /></Button>
18
+
19
+ // 要这样写 —— 尺寸与形状是两根轴,iconOnly 控制形状
20
+ <Button iconOnly aria-label="刷新"><Icon name="rotate-cw" size={16} /></Button>
21
+ ```
22
+
23
+ `variant` 只有 `primary` / `secondary` / `outline` / `ghost` / `destructive` / `link`;
24
+ `size` 只有 `xs` / `sm` / `default` / `lg`。**shadcn 习惯的 `size="icon"` 在本库不存在。**
25
+
26
+ `iconOnly` 为 true 时按钮没有可见文字,**必须**另给 `aria-label`。
27
+
28
+ ### 内联 style
29
+
30
+ ```jsx
31
+ // 不要这样写
32
+ <div style={{ padding: 16, borderRadius: 16, background: '#f5f5f5' }}>
33
+
34
+ // 要这样写
35
+ <Card>…</Card>
36
+ ```
37
+
38
+ 组件内无内联 style(01 §1.7)。内联 style 优先级最高,会让调用方传的 `className` 失效,
39
+ 且写不了 `:focus-visible` 这类伪类 —— 而规范要求焦点态必须与 hover / active 可区分。
40
+
41
+ 需要动态尺度时走 CSS 自定义属性,不要走 style 对象里的字面值。
42
+
43
+ ### 用 JS state 模拟 hover
44
+
45
+ ```jsx
46
+ // 不要这样写
47
+ const [hover, setHover] = useState(false)
48
+ <Button onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
49
+
50
+ // 要这样写 —— 什么都不写,hover 已由 CSS 伪类实现
51
+ <Button>提交</Button>
52
+ ```
53
+
54
+ `useState` 会让组件强制成为 client component。状态一律用 CSS 伪类
55
+ (`:hover` / `:focus-visible` / `:disabled` / `:active`)。
56
+
57
+ ### 换肤改错了变量
58
+
59
+ ```css
60
+ /* 不要这样写 —— 只会改到引用它的那部分组件 */
61
+ :root { --application-accent: #16a34a; }
62
+
63
+ /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上一律无效 */
64
+ <div className="dark">…</div>
65
+
66
+ /* 要这样写 */
67
+ <html class="dark" style="--ds-color-theme-primary: #16a34a">
68
+ ```
69
+
70
+ `--ds-color-theme-primary` 是换肤契约的唯一入口。
71
+ 换肤与 `.dark` **必须挂在 `<html>` 上** —— `var()` 代换在声明所在元素就完成了,
72
+ 挂在 `<body>` 或容器 div 上无效(已实测)。系统内不存在「局部暗色区块」这种用法。
73
+
74
+ ### 手写表格结构
75
+
76
+ ```jsx
77
+ // 不要这样写
78
+ <table><thead><tr><th>名称</th></tr></thead><tbody><tr><td>示例应用</td></tr></tbody></table>
79
+
80
+ // 要这样写 —— Table 是数据驱动的
81
+ <Table columns={[{ key: 'name', title: '名称' }]} rows={rows} />
82
+ ```
83
+
84
+ `Table` 不接受复合子组件。`<tr>` / `<td>` 脱离 `<table>` 后本就无处可写。
85
+
86
+ ### 逐个渲染单选项
87
+
88
+ ```jsx
89
+ // 不要这样写
90
+ {options.map((o) => <input type="radio" name="scope" value={o.value} key={o.value} />)}
91
+
92
+ // 要这样写 —— 单选的语义单位就是组
93
+ <RadioGroup value={scope} onValueChange={setScope} items={[{ value: 'all', label: '全部' }]} />
94
+ ```
95
+
96
+ 系统内没有「单个单选项」组件。逐个渲染会丢掉分组的键盘导航与 `name` 绑定。
97
+
98
+ ### 逐字实时搜索
99
+
100
+ ```jsx
101
+ // 不要这样写
102
+ <input type="search" onChange={(e) => search(e.target.value)} />
103
+
104
+ // 要这样写 —— onSubmit 仅在 Enter 时触发
105
+ <SearchField ariaLabel="搜索记录" onSubmit={search} />
106
+ ```
107
+
108
+ 规范禁止逐字实时搜索作为默认行为。搜索必须通过 Enter 或明确的搜索动作提交。
109
+ `ariaLabel` 是必填。
110
+
111
+ ### 引入平行的组件实现
112
+
113
+ ```jsx
114
+ // 不要这样写
115
+ import { Button } from '@/components/ui/button'
116
+ import { Button } from '@moheng-design/ui/dist/components/foundation/actions/Button.js'
117
+
118
+ // 要这样写
119
+ import { Button } from '@moheng-design/ui'
120
+ ```
121
+
122
+ `@/components/ui/` 目录通常是 `npx shadcn add` 生成的第二套组件源码,
123
+ 与本库并存会造成同一界面两套视觉。本库**不提供** shadcn registry 分发(01 §1.2),
124
+ 样式覆盖走 CSS 自定义属性与 `className` 叠加,不走改源码。
125
+
126
+ 内部路径不在 exports map 中,不构成公开接口,任意小版本都可能改动。
127
+
128
+ ### 忘记引样式表
129
+
130
+ ```jsx
131
+ // 不要这样写 —— 组件渲染出来是无样式的裸结构
132
+ import { Button } from '@moheng-design/ui'
133
+
134
+ // 要这样写 —— 应用入口引一次即可
135
+ import { Button } from '@moheng-design/ui'
136
+ import '@moheng-design/ui/styles.css'
137
+ ```
138
+
139
+ 样式不随组件模块自动引入,这是为了让组件模块保持无副作用、不影响 tree-shaking。
140
+ 代价是应用入口要显式引一行。
141
+
142
+ ### 通用的「视图设置」按钮
143
+
144
+ ```jsx
145
+ // 不要这样写
146
+ <Button>视图设置</Button>
147
+
148
+ // 要这样写 —— 按当前呈现方式命名
149
+ <Button>列设置</Button> {/* DataTable */}
150
+ <Button>看板设置</Button> {/* KanbanBoard */}
151
+ ```
152
+
153
+ 呈现设置是一个*概念*,不是一个按钮名。按钮必须按当前呈现方式命名:
154
+ `列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
155
+
156
+ ### 六种数据状态共用一句话
157
+
158
+ ```jsx
159
+ // 不要这样写
160
+ {items.length === 0 && <Empty title="暂无数据" />}
161
+
162
+ // 要这样写 —— 成因不同,用户的下一步动作也不同
163
+ <ApplicationDataDisplay
164
+ state={state}
165
+ empty={<Empty title="当前视角下无数据" description="切换业务视图或调整筛选条件" />}
166
+ noPermission={<Empty title="没有查看权限" description="请联系管理员申请" />}
167
+ error={<Empty title="加载失败" description="请稍后重试" />}
168
+ />
169
+ ```
170
+
171
+ Loading / Empty / Error / No Permission / Not Found / Partial Failure
172
+ **绝不能共用同一句话**。
173
+
174
+ ### 堆叠无界的垂直滚动容器
175
+
176
+ ```jsx
177
+ // 不要这样写
178
+ <ScrollArea><ScrollArea>…</ScrollArea></ScrollArea>
179
+ <ScrollArea>{/* 没给高度,等于没有「有界」前提 */}</ScrollArea>
180
+
181
+ // 要这样写 —— 显式给界,或改用水平方向
182
+ <ScrollArea maxHeight={320}>…</ScrollArea>
183
+ <ScrollArea horizontal>…</ScrollArea>
184
+ ```
185
+
186
+ Content Canvas 是页面唯一的主垂直滚动权持有者。
187
+ `ScrollArea` 与 `MessageScroller` 只用于正交方向或局部有界的溢出,且必须给出高度。
188
+
189
+ ### 用 Emoji 或系统字符代替图标
190
+
191
+ ```jsx
192
+ // 不要这样写
193
+ <span>✓ 已完成</span>
194
+ <span>★</span>
195
+ <svg viewBox="0 0 24 24"><path d="…" /></svg>
196
+
197
+ // 要这样写
198
+ <Icon name="check" size={16} />
199
+ ```
200
+
201
+ Shell 契约点名禁止四件事:用 Emoji、用系统字体符号(`✓ ★ ›`)、
202
+ 逐页手写内联 SVG、临时换用其他图标库。
203
+
204
+ 字形名必须先登记在 `src/icon/registry.json`,尺寸只取 14 / 16 / 18 / 20 / 24 五档。
205
+
206
+ ### 硬编码样式值(仅限库内)
207
+
208
+ ```css
209
+ /* 不要这样写 */
210
+ .mh-card { padding: 16px; border-radius: 16px; background: #f5f5f5; }
211
+
212
+ /* 要这样写 */
213
+ .mh-card { padding: var(--ds-space-4); border-radius: var(--ds-radius-16); background: var(--ds-color-surface); }
214
+ ```
215
+
216
+ 这三条规则 `scope` 是 `internal`,**只在组件库内部生效**,业务代码不受约束
217
+ (01 §7.3:用户业务代码里出现色值是完全正常的,全量禁止会吵到用户直接关掉整条规则)。
218
+
219
+ 库内写死 px 会让三档密度在该处失效 —— 响应式密度靠 `@media` 改写 `:root` 变量实现。
220
+
221
+ ### Application Module 组件脱离五层模型
222
+
223
+ ```jsx
224
+ // 不要这样写 —— 当成普通布局容器用
225
+ <ApplicationPageHeader title="标题" />
226
+
227
+ // 要这样写 —— 五层全部声明为状态字段
228
+ <ApplicationPageHeader
229
+ title="标题"
230
+ pageMode={pageMode}
231
+ pageModes={['LIST', 'CARD']}
232
+ onPageModeChange={setPageMode}
233
+ dataStatus="normal"
234
+ updatedAt={updatedAt}
235
+ />
236
+ ```
237
+
238
+ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `businessView` /
239
+ `dataControl` / `dataPresentation` 这套模型。装本库即意味着接受这套结构约定。
@@ -0,0 +1,98 @@
1
+ <!-- 手写文件。被 generate.mjs 嵌入 SKILL.md 的「五层 Canvas 模型」一节与 reference.md。
2
+ 内部标题必须从 ### 起,否则嵌入后会与宿主文档的层级冲突。 -->
3
+
4
+ Application Module 层的 26 个组件**强绑定**本模型。装本库即意味着接受这套结构约定
5
+ (01 §1.8 已明确声明这一代价)。Foundation 与 Application Atomic 两层不受本节约束。
6
+
7
+ ### 三层物理结构
8
+
9
+ ```
10
+ Application
11
+ ├─ Shell 跨页身份、应用、模块导航
12
+ ├─ Canvas 当前业务页面
13
+ └─ Overlay Dialog / Drawer / Popover / Menu / Toast
14
+ ```
15
+
16
+ ### Shell 四带
17
+
18
+ 固定骨架,**没有左侧全局栏**。三条导航带 `position: fixed`,永不滚动。
19
+
20
+ | 带 | 组件 | Standard | Compact |
21
+ |---|---|---:|---:|
22
+ | 顶部导航 `PLATFORM.TOP_USER_BAR` | `TopNavigationPrimaryBar` | 52px | 44px |
23
+ | 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 64px | 52px |
24
+ | 应用二级导航 `APPLICATION.SECONDARY_NAV` | `ApplicationSecondaryNavigation` | 48px | 40px |
25
+ | Content Canvas | `ApplicationPageLayoutContainer` | 剩余视口 | 剩余视口 |
26
+
27
+ **Content Canvas 是页面唯一的垂直滚动持有者。** 宿主 padding 为零 —— padding 属于页面内容根。
28
+ 表格、看板、标签页、日历可以拥有正交的水平滚动或局部有界滚动;
29
+ 不得堆叠无界的垂直滚动容器。
30
+
31
+ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑、通知铃铛、页面标题、卡片、阴影。
32
+
33
+ ### 五层认知模型
34
+
35
+ 新页面必须把五层**全部**声明为状态字段。缺一层即为结构不完整。
36
+
37
+ | 层 | 字段 | 取值 |
38
+ |---|---|---|
39
+ | L1 页面类型 | `pageType` | `WORKBENCH` / `MANAGEMENT` / `LEDGER` / `ANALYSIS` / `REPORT` / `DETAIL` |
40
+ | L2 页面模式 | `pageMode` | `LIST` / `CARD` / `SPLIT` / `BOARD` / `CALENDAR` |
41
+ | L3 业务视图 | `businessView` | 2–4 个稳定工作视角(全部 / 我的责任 / 最近处理) |
42
+ | L4 数据控制 | `dataControl` | search / filters / sort / pagination / appliedFilterTags |
43
+ | L5 数据呈现 | `dataPresentation` | `DataTable` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
44
+
45
+ `DETAIL` 与 `COMPOSITE` **不是**页面模式,是特殊物理结构资产。
46
+ `Embedded` 是 `integrationMode`,不是页面模式。
47
+
48
+ ### Canvas 标准区域顺序
49
+
50
+ 自上而下固定,不得重排:
51
+
52
+ ```
53
+ 上下文区 ApplicationPageHeader L1 / L2 / L3 的承载者
54
+ 指标区 ApplicationMetric*(可选) 不是每个页面都有
55
+ 数据控制 ApplicationQueryToolbar L4
56
+ ApplicationFilterList L4 的已应用筛选标签
57
+ 数据展示 ApplicationDataDisplay L5
58
+ ```
59
+
60
+ `SPLIT` 模式另有左栏 `ApplicationSplitListSidebar`(360px,Compact 300px)。
61
+ `DETAIL` 结构用 `ApplicationRecordDetailBody`。
62
+
63
+ ### 三个绝不能混为一谈的切换器
64
+
65
+ - **Page Mode Switch** —— 页面级,位于上下文区右侧、页面动作组之后。
66
+ 仅当页面真正开放 2 个以上模式时渲染,否则不占位。改 `pageMode`。
67
+ - **View Mode Switch** —— 仅 `SPLIT` 右栏。改 `dataPresentation`,**绝不改** `pageMode`。
68
+ - **Presentation Settings** —— 是一个*概念*,不是一个按钮名。
69
+ 按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
70
+ **禁止通用的「视图设置」按钮。** 呈现设置不得改变搜索、筛选、业务视图或页面模式,
71
+ 它只调整当前呈现方式的展示细节。
72
+
73
+ ### 六种数据状态
74
+
75
+ `ApplicationDataDisplay` 的 `state` 取六值:
76
+ `ready` / `loading` / `empty` / `error` / `no-permission` / `not-found`。
77
+
78
+ **六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「你没有权限」「请求失败」
79
+ 是三句不同的话,成因不同,用户的下一步动作也不同。
80
+ 另有 Partial Failure —— 部分数据加载失败,不等同于 `error`。
81
+
82
+ 页面头部的数据状态(`ApplicationPageHeader` 的 `dataStatus`)另有三值:
83
+ `normal`(附最后更新时间)/ `refreshing` / `failed`(附重试入口)。
84
+
85
+ ### 关键尺寸
86
+
87
+ 抽屉宽 680px(`--application-drawer-width: 1280px` 是宽/全屏变体);
88
+ 表单对话框 720px / 960px;`SPLIT` 左栏 360px(Compact 300px);
89
+ 卡片网格默认 ≥1440 五列、Condensed 四列、Compact 三列,卡片最小宽 220px。
90
+
91
+ ### Mock 数据
92
+
93
+ 真实数据缺失时使用已登记的占位符,逐字复用,不得即兴发挥:
94
+
95
+ `示例应用`(应用名)· `应用说明信息`(应用描述)· `模块名称`(当前模块)·
96
+ `模块 A` / `模块 B` / `模块 C`(模块菜单)· `Tab 1` / `Tab 2`(业务标签)· `企业名称`(品牌兜底)。
97
+
98
+ `模块1` / `模块2` 作为标签文案被明令禁止。