@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
|
@@ -34,13 +34,21 @@ npx @moheng-design/ui-skill audit
|
|
|
34
34
|
| 三、结构性 | 平行 UI 依赖、未引样式表、Application Module 组件缺五层模型声明 | 单独立项,不与前两桶混在一个 PR |
|
|
35
35
|
| 四、lint 看不见 | 下面这张清单 | 只能人看,抽样核对后写进报告的「未量化风险」 |
|
|
36
36
|
|
|
37
|
+
与 `moheng-audit.json` 的字段对应:`buckets.autofix` 即第一桶,`buckets.manual` 即第二桶;
|
|
38
|
+
`buckets.generated`(`props-whitelist` / `prop-enum` 的命中)不进四桶 —— 它们与 tsc 报的
|
|
39
|
+
是同一类问题,只用于下面「升档门槛」的第二条。第三桶读 `structural` 的 `parallelUi`、
|
|
40
|
+
`parallelImports`、`stylesImported` 与 `deepImports`;其中「缺五层模型声明」命令算不出来,
|
|
41
|
+
须逐个打开用到 Application Module 组件的文件核对,并在报告里写明这一项是人工计数。
|
|
42
|
+
`suppressed` 是被 `eslint-disable` 压掉的命中,不计入总数,但必须在「现状」一节单列 ——
|
|
43
|
+
关掉的规则正是最该看见的欠账。
|
|
44
|
+
|
|
37
45
|
<!-- @generated: unenforced-checklist -->
|
|
38
46
|
|
|
39
47
|
## 产出:MIGRATION.md
|
|
40
48
|
|
|
41
49
|
报告固定五节,数字全部来自 `moheng-audit.json`,写明取值时间与 `@moheng-design/ui` 版本:
|
|
42
50
|
|
|
43
|
-
1. **现状** ——
|
|
51
|
+
1. **现状** —— 文件数、命中总数、按规则的前十条、被 `eslint-disable` 压掉的条数。
|
|
44
52
|
2. **四桶** —— 每桶的条数与涉及文件数。
|
|
45
53
|
3. **升档门槛** —— 进入 `recommended` 的条件是第一、二桶归零;进入 `strict` 的条件是
|
|
46
54
|
`props-whitelist` / `prop-enum` 也归零。写成可勾选的清单。
|
|
@@ -46,7 +46,8 @@ description: 新项目启动、要基于 @moheng-design/ui 定技术栈与搭建
|
|
|
46
46
|
<!-- @generated: parallel-ui -->
|
|
47
47
|
|
|
48
48
|
项目自有样式用什么写由项目规范定,但与组件对齐时必须读 `--application-*` 与 `--ui-*`
|
|
49
|
-
两层 token,不得读 `--ds
|
|
49
|
+
两层 token,不得读 `--ds-*`,例外是换肤入口 `--ds-color-theme-primary` 与焦点环几何
|
|
50
|
+
`--ds-focus-ring-width` / `--ds-focus-ring-offset`(只读)。
|
|
50
51
|
|
|
51
52
|
Next.js App Router 是本库实测过的环境:只有持有交互状态的组件带 `"use client"`,
|
|
52
53
|
其余可直接在 server component 中渲染。其他 React 环境按上表「模块格式」与「浏览器」两条自检。
|
|
@@ -60,9 +61,12 @@ Next.js App Router 是本库实测过的环境:只有持有交互状态的组
|
|
|
60
61
|
验证:安装输出无 peer 依赖告警。
|
|
61
62
|
2. **引样式。** 在应用入口(Next.js 为 `app/layout.tsx`)依次引入
|
|
62
63
|
`@moheng-design/ui/tokens.css` 与 `@moheng-design/ui/styles.css`,token 在前,顺序不得调换。
|
|
63
|
-
|
|
64
|
+
项目若还引入其他带 `@layer` 的样式表(如 Tailwind),这两份必须排在它们之后:
|
|
65
|
+
`moheng` 层组的位置由两份里先引入的那一份决定,排在前面会被对方的 preflight 压掉。
|
|
66
|
+
验证:渲染一个 `<SystemButton>`,外观与文档站一致。
|
|
64
67
|
3. **定挂载点。** 换肤只覆盖 `--ds-color-theme-primary`,暗色只切 `.dark` 类,
|
|
65
|
-
两者都必须挂在 `<html>`
|
|
68
|
+
两者都必须挂在 `<html>` 上。挂在 `<body>` 或容器上是半生效,比无效更糟:
|
|
69
|
+
直接读 `--ds-*` 的部件变了,读 `--application-*` 的部件不变,看上去像是生效了。
|
|
66
70
|
验证:在 `<html>` 上改主色,主按钮与焦点环同时变色。
|
|
67
71
|
4. **拷技能。** `npx @moheng-design/ui-skill install`。升级 `@moheng-design/ui` 后必须重跑。
|
|
68
72
|
验证:`.claude/skills/` 下出现 `moheng-ui` 及各附属技能目录。
|
|
@@ -74,7 +78,7 @@ Next.js App Router 是本库实测过的环境:只有持有交互状态的组
|
|
|
74
78
|
6. **进 CI。** 把 lint 与类型检查接进项目的 CI,两者缺一不可:lint 管「用错组件库」,
|
|
75
79
|
类型检查管「传错 prop」。只接在本地等于没接。
|
|
76
80
|
验证:带一处原生 `<button>` 的提交在 CI 上变红。
|
|
77
|
-
7. **搭第一个页面。** 转 `moheng-ui-page
|
|
81
|
+
7. **搭第一个页面。** 转 `moheng-ui-page`:先判定有没有结果集、定下五层 Canvas 模型里该写的字段,再选组件。
|
|
78
82
|
验证:页面通过第 5 步的 lint,且零报错。
|
|
79
83
|
|
|
80
84
|
当前 <!-- @generated: rule-count --> 条规则中,带 autofix 的有:<!-- @generated: autofix-rules -->。
|
|
@@ -29,7 +29,12 @@ description: 用 @moheng-design/ui 搭系统的过程中撞到组件缺失、pro
|
|
|
29
29
|
// eslint-disable-next-line moheng/no-native-button -- moheng: <反馈类型> <一句话>
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
没有 `-- moheng:` 说明的 disable
|
|
32
|
+
没有 `-- moheng:` 说明的 disable,收集命令会单独列出来要求补齐。没禁用规则、只是记一笔的地方
|
|
33
|
+
用 `TODO(moheng)` 标记,首词同样写反馈类型,收集命令据此归类:
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
// TODO(moheng): missing-component 看板呈现没有对应组件
|
|
37
|
+
```绕过而不记录,
|
|
33
38
|
问题就永远留在项目里,组件库永远不知道。
|
|
34
39
|
|
|
35
40
|
## 收集
|
|
@@ -1,21 +1,28 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: moheng-ui-page
|
|
3
|
-
description: 用 @moheng-design/ui 的 Application Module
|
|
3
|
+
description: 用 @moheng-design/ui 的 Application Module 层搭一个完整页面(列表页、详情页、工作台、设置页)时加载。先判定页面有没有结果集、定下五层 Canvas 模型里该写的字段,再选组件组合,最后出骨架。凡是「新建一个页面 / 搭页面骨架 / 这页该用哪些 Module 组件」,均适用。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 页面骨架
|
|
7
7
|
|
|
8
8
|
适用版本:v<!-- @generated: version -->
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## 先定字段,再碰组件
|
|
11
11
|
|
|
12
12
|
Application Module 层的组件不能脱离五层 Canvas 模型使用。写第一行 JSX 之前,
|
|
13
|
-
|
|
13
|
+
先判定这一页有没有**结果集** —— 一份由 `ApplicationQueryToolbar` 驱动、由
|
|
14
|
+
`ApplicationDataDisplay` 展示的记录集合:
|
|
15
|
+
|
|
16
|
+
- **有结果集**(列表、台账、报表、以查询结果为主体的分析页):下面五个字段必须逐个定下来
|
|
17
|
+
并写进代码,不得含糊、不得留空。
|
|
18
|
+
- **没有结果集**(工作台、详情页、配置页、协作工作台、编辑器):只声明 `pageType`,其余
|
|
19
|
+
四个字段不写,也不得为凑字段塞一个数据展示区或空工具栏。结构按 SKILL.md「无结果集页面
|
|
20
|
+
的结构」一节搭。
|
|
14
21
|
|
|
15
22
|
<!-- @generated: canvas-fields -->
|
|
16
23
|
|
|
17
|
-
|
|
18
|
-
|
|
24
|
+
字段的取值与含义、两类页面的判据与 `pageType` 取法以 SKILL.md 的「五层 Canvas 模型」
|
|
25
|
+
一节为准。定不下来的字段先问,不要猜一个「默认值」。
|
|
19
26
|
|
|
20
27
|
## 再选组件组合
|
|
21
28
|
|
|
@@ -23,22 +30,39 @@ Application Module 层的组件不能脱离五层 Canvas 模型使用。写第
|
|
|
23
30
|
|
|
24
31
|
<!-- @generated: module-components -->
|
|
25
32
|
|
|
26
|
-
选定后按 SKILL.md「Canvas
|
|
33
|
+
选定后按 SKILL.md「Canvas 标准区域顺序」排布,顺序不得调换;`SPLIT` 页按「SPLIT 的标准
|
|
34
|
+
组件树」,看板、月历、时间轴三种呈现按「呈现配方」拼装。
|
|
27
35
|
|
|
28
36
|
## 最后出骨架
|
|
29
37
|
|
|
30
38
|
骨架的硬要求:
|
|
31
39
|
|
|
32
|
-
-
|
|
40
|
+
- 该写的字段显式写进组件 props,不写在注释里。落点是:
|
|
41
|
+
`pageType` → `ApplicationPageLayoutContainer`(必填);
|
|
42
|
+
`pageMode` → `ApplicationPageHeader`;
|
|
43
|
+
`businessView` → `ApplicationQueryToolbar`;
|
|
44
|
+
`dataControl` → `ApplicationQueryToolbar` 实际给出的 search / filters / sort / pagination 等 props,
|
|
45
|
+
整个工具栏传进 `ApplicationPageLayoutContainer` 的 `dataControl` 槽位;
|
|
46
|
+
`dataPresentation` → `ApplicationQueryToolbar` 与 `ApplicationDataDisplay` 的 `presentation`(prop 名与字段名不同)。
|
|
33
47
|
- 六种数据状态(Loading / Empty / Error / No Permission / Not Found / Partial Failure)
|
|
34
48
|
各给各的文案,不得共用一句。
|
|
49
|
+
- 页头的更新时间(`ApplicationPageHeader` 的 `updatedAt`)写完整日期时间 `YYYY-MM-DD HH:mm`(如 `2026-07-28 10:00`,
|
|
50
|
+
GAP Design kit「数据更新」,取代 07 · C-12 的 `HH:mm`),组件原样显示、不加前缀;
|
|
51
|
+
由服务端随数据返回的时间戳格式化而来,与数据同源;不得在客户端用 `useState(Date.now())` 一类写法自造一个时刻 —— 服务端渲染与客户端
|
|
52
|
+
水合各取一次当前时间,落在分钟边界两侧时文本不一致,且这个时刻与数据的实际更新时间无关。
|
|
53
|
+
- 查询参数(业务视图、搜索词、筛选、页码)与地址栏同步时,Next.js 下用 `useRouter()` 的
|
|
54
|
+
`router.replace`,不得直接调 `history.replaceState` —— 后者绕开 Next 的路由状态,浏览器后退
|
|
55
|
+
再回到本页时参数丢失。
|
|
56
|
+
- 有设计稿时,表格列宽照稿写进 `TableColumn.width`:稿上固定宽的列写数字(px),稿上均分剩余宽度的弹性列不写 `width`;
|
|
57
|
+
不得全部留空交给浏览器按内容分配 —— 那样每次数据不同列宽都不同,且与稿对不上。横向放不下时末列「操作」写 `fixed: 'right'`。
|
|
35
58
|
- Mock 数据只用登记过的占位符(`示例应用` / `模块 A` / `Tab 1`)。
|
|
36
59
|
- 骨架内不出现原生 `<button>` / `<input>` / `<table>`,替换表里有的一律用组件。
|
|
37
60
|
|
|
38
|
-
写完跑一遍 lint
|
|
61
|
+
写完跑一遍 lint,再按 moheng-ui-review 的「逐条人工核对」清单逐条过一遍 —— lint 零报错不等于合规,那张清单列的正是 lint 看不见的约束。
|
|
39
62
|
|
|
40
63
|
## 边界
|
|
41
64
|
|
|
42
65
|
- 不得用 Foundation 组件手拼一个 Module 层已有的区域(页头、工具栏、分页)。
|
|
43
66
|
- 不得在页面里写「视图设置」这类通用命名的按钮。
|
|
44
|
-
-
|
|
67
|
+
- 结果集页面不得为了「先跑起来」省掉五个字段中的任何一个;无结果集页面不得为了凑满五个字段
|
|
68
|
+
虚构工具栏或数据展示区。
|
|
@@ -20,10 +20,12 @@ npx @moheng-design/ui-skill upgrade --from <旧版 contracts.json 的路径>
|
|
|
20
20
|
|
|
21
21
|
旧版 `contracts.json` 在升级前的 `node_modules/@moheng-design/ui-skill/generated/` 里,
|
|
22
22
|
升级前先拷一份出来。命令比对新旧两份,产出 `moheng-upgrade.md`:
|
|
23
|
-
组件的增删、prop
|
|
23
|
+
组件的增删、prop 的增删与必填变化、枚举值的增删、类型的收窄与变化、新标为弃用的 prop。
|
|
24
24
|
|
|
25
|
-
3.
|
|
26
|
-
|
|
25
|
+
3. 按报告改代码,从破坏性的几节改起(报告按此排序,「新增」两节排在最后)。删掉的 prop
|
|
26
|
+
与枚举值、收窄为固定取值的 prop 对应的是 `props-whitelist` / `prop-enum` 会报的那些
|
|
27
|
+
位置,先跑一遍 lint 再动手。「类型变化」一节 tsc 未必报(放宽的类型照样编译通过),
|
|
28
|
+
逐条核对引用处是否该改用新写法;「标为弃用」一节本次可不改,下一次升级前必须迁走。
|
|
27
29
|
4. 重跑安装命令,让项目里的 SKILL.md 跟上:
|
|
28
30
|
|
|
29
31
|
```bash
|
|
@@ -14,14 +14,17 @@
|
|
|
14
14
|
|
|
15
15
|
| 约束 | 出处 | 为什么没有规则 |
|
|
16
16
|
|---|---|---|
|
|
17
|
-
| `iconOnly` 为真则 `aria-label` 必填 | Button 契约 | 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动 |
|
|
17
|
+
| `iconOnly` 为真则 `aria-label` 必填 | Button / SystemButton 契约 | 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动 |
|
|
18
18
|
| 不得用 `onMouseEnter` / `onMouseLeave` 驱动样式 | §1.7、反例「用 JS state 模拟 hover」 | 五类 kind 里没有「组件上不得出现某个 prop」这一形态。这两个是基类提供的合法原生属性,由 `nativeBases` 表放行,props 白名单只判「不认识的 prop」 |
|
|
19
19
|
| 不得用 `模块1` / `模块2` 之类未登记的 mock 占位符 | 02 §8 | 唯一能判字符串字面量的 `forbid-value`,其 `scope` 被 schema 锁死为 `internal`(§7.3),而这条要管的正是消费方写的 mock |
|
|
20
20
|
| 六种数据状态不得共用一句话 | 反例「六种数据状态共用一句话」 | 判定是六个 `ReactNode` 槽位之间的文案比对,跨 prop 的内容比较,五类 kind 无一作用于此 |
|
|
21
21
|
| 必须引一次 `@moheng-design/ui/styles.css` | 反例「忘记引样式表」 | `forbid-import` 只有「不得从某处导入」,没有反向的「必须导入」;且样式引在应用入口、组件用在别处,判定跨文件 |
|
|
22
22
|
| 换肤与 `.dark` 必须挂在 `<html>` 上 | 反例「换肤改错了变量」 | 挂载点在 JSX 里是任意元素的 `className` / `style`,真正的判定落在运行时的 DOM 层级上 |
|
|
23
23
|
| 呈现设置按钮不得取名「视图设置」 | 反例「通用的视图设置按钮」 | 文案约束,同 mock 占位符那条 |
|
|
24
|
-
| `ScrollArea`
|
|
25
|
-
|
|
|
24
|
+
| `ScrollArea` 必须给高度、不得嵌套(看板外层横向、列内纵向是登记例外,07 · C-14) | 反例「堆叠无界的垂直滚动容器」 | 前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链 |
|
|
25
|
+
| 结果集页面必须声明五层模型字段,无结果集页面只声明 `pageType` | §1.8、canvas-model.md(06 · D-1) | `pageType` 已收进类型(`ApplicationPageLayoutContainer` 必填,缺了 tsc 报错);其余四个字段在契约里仍是可选的,「用了本层组件就必须一并声明」同样是条件式必填 |
|
|
26
|
+
| 业务页面不得直接使用 Foundation `Button` | Button / SystemButton 契约、反例「业务页面用 Foundation Button」 | `forbid-element` 的 `match.element` 被 schema 限定为小写原生标签名,「不得使用本库自己的某个导出」是另一种形态,schema 阶段 3 已定稿。原生 `<button>` 的 autofix 已改写为 `SystemButton` |
|
|
26
27
|
| 产品 UI 文案里不得出现 Emoji | 02 §8 | 文案约束,同 mock 占位符那条。生成器对本包 `handwritten/*.md` 与 `@moheng-design/ui` 的契约 JSDoc 查 Emoji,管不到消费方代码 |
|
|
27
28
|
| `SearchField` 不得逐字实时搜索 | 反例「逐字实时搜索」 | 判定是 `onChange` 回调体内有没有发起搜索,跨函数体的语义判定。规则只拦得住原生 `<input type="search">` |
|
|
29
|
+
| 消费方代码不得读 `--ds-*`;例外只有换肤入口 `--ds-color-theme-primary`(覆盖)与焦点环几何 `--ds-focus-ring-width` / `--ds-focus-ring-offset`(只读,这两个是唯一可跨层读取的 `--ds-*`) | 通则「token 的两层边界」、07 · C-1(06 · D-5) | 断言 6 只扫 `@moheng-design/ui` 自身的 `src/`;能作用于消费方 CSS 的只有 `forbid-value`,其 `scope` 被 schema 锁死为 `internal`(§7.3),stylelint 的 `consumer` 档因此为空 |
|
|
30
|
+
| 条件式必填:prop A 出现(或取某值)则 prop B 必填。例:`appliedTags` 的 `label` 传 JSX 时必须给 `labelText`;`<ApplicationDataDisplay state="empty">` 必须给 `empty`;`businessView` 与 `onBusinessViewChange` 必须成对提供。各组件约定里「必须成对提供」「必须同时提供」一类写法均属此类 | 05 §3、07 · C-3 | 五类 kind 一类都表达不了。schema 加 `requires-with`(prop A 出现则 prop B 必填)留到第二个真实项目再评估,阶段 3 已定稿的 schema 本轮不改 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@moheng-design/ui-skill",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.0",
|
|
4
4
|
"description": "@moheng-design/ui 的 AI agent 支持包 —— SKILL.md 引导 + ESLint / stylelint 强制规则",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -54,13 +54,13 @@
|
|
|
54
54
|
"eslint": "^9.39.0",
|
|
55
55
|
"stylelint": "^16.26.0",
|
|
56
56
|
"typescript": "^5.9.3",
|
|
57
|
-
"@moheng-design/ui": "
|
|
57
|
+
"@moheng-design/ui": "3.0.0"
|
|
58
58
|
},
|
|
59
59
|
"scripts": {
|
|
60
60
|
"generate": "node scripts/generate.mjs",
|
|
61
61
|
"check:generate": "node scripts/generate.mjs --check",
|
|
62
62
|
"extract": "node scripts/extract-contracts.mjs",
|
|
63
63
|
"build": "node scripts/generate.mjs",
|
|
64
|
-
"test": "node test/generate.negative.mjs && node test/eslint-rules.test.mjs && node test/stylelint-rules.test.mjs"
|
|
64
|
+
"test": "node test/generate.negative.mjs && node test/eslint-rules.test.mjs && node test/stylelint-rules.test.mjs && node test/commands.test.mjs"
|
|
65
65
|
}
|
|
66
66
|
}
|