@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,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui-audit
|
|
3
|
+
description: 评估一个存量项目离 @moheng-design/ui 规范有多远、该按什么顺序迁移时加载。产出一份带数字的迁移报告,而不是逐个文件改代码。凡是「这个老项目能不能接入 / 差多少 / 先改什么」,均适用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 存量项目合规审计
|
|
7
|
+
|
|
8
|
+
适用版本:v<!-- @generated: version -->
|
|
9
|
+
|
|
10
|
+
## 数字由工具算,本技能只解释
|
|
11
|
+
|
|
12
|
+
先跑审计命令,它会在项目根写出 `moheng-audit.json`:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npx @moheng-design/ui-skill audit
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
命令用 `migration` 档(全部 warn)跑一遍 ESLint,按规则、文件、组件聚合命中数;
|
|
19
|
+
另扫 `package.json` 里的平行 UI 依赖、样式表是否引入、深引位置。装了 stylelint 时
|
|
20
|
+
再以只读模式统计 CSS 里的字面色值与 px —— 那三条规则不作为消费方 lint 配置发出
|
|
21
|
+
(§7.3),但只读统计不是 lint,借来量一下硬编码有多严重是允许的。
|
|
22
|
+
|
|
23
|
+
**不得在没有 `moheng-audit.json` 的情况下写报告。** 凭印象写「大概几十处」是本技能
|
|
24
|
+
明令禁止的形态。
|
|
25
|
+
|
|
26
|
+
## 把命中分成四桶
|
|
27
|
+
|
|
28
|
+
读 `moheng-audit.json`,按下面的顺序分桶。桶的顺序就是迁移的顺序。
|
|
29
|
+
|
|
30
|
+
| 桶 | 判据 | 处理 |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| 一、机械可修 | 命中的规则带 autofix:<!-- @generated: autofix-rules --> | `npx eslint --fix`,改完人工过一遍 import |
|
|
33
|
+
| 二、人工替换 | 其余 `forbid-element` / `forbid-import` | 逐处替换,报错文案即替换指令 |
|
|
34
|
+
| 三、结构性 | 平行 UI 依赖、未引样式表、Application Module 组件缺五层模型声明 | 单独立项,不与前两桶混在一个 PR |
|
|
35
|
+
| 四、lint 看不见 | 下面这张清单 | 只能人看,抽样核对后写进报告的「未量化风险」 |
|
|
36
|
+
|
|
37
|
+
<!-- @generated: unenforced-checklist -->
|
|
38
|
+
|
|
39
|
+
## 产出:MIGRATION.md
|
|
40
|
+
|
|
41
|
+
报告固定五节,数字全部来自 `moheng-audit.json`,写明取值时间与 `@moheng-design/ui` 版本:
|
|
42
|
+
|
|
43
|
+
1. **现状** —— 文件数、命中总数、按规则的前十条。
|
|
44
|
+
2. **四桶** —— 每桶的条数与涉及文件数。
|
|
45
|
+
3. **升档门槛** —— 进入 `recommended` 的条件是第一、二桶归零;进入 `strict` 的条件是
|
|
46
|
+
`props-whitelist` / `prop-enum` 也归零。写成可勾选的清单。
|
|
47
|
+
4. **结构性问题** —— 第三桶逐项说明,每项一段。
|
|
48
|
+
5. **未量化风险** —— 第四桶抽样结果。
|
|
49
|
+
|
|
50
|
+
## 边界
|
|
51
|
+
|
|
52
|
+
- 本技能不改代码。改代码是接下来的事,且必须在 `migration` 档接入之后进行。
|
|
53
|
+
- 不得建议存量项目直接上 `strict`(§7.4)。
|
|
54
|
+
- 报告里不出现 Emoji。
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui-bootstrap
|
|
3
|
+
description: 新项目启动、要基于 @moheng-design/ui 定技术栈与搭建顺序时加载。先读项目自己的规范与技术栈,逐项对照本库的硬约束,再给出一条顺序固定、每步可验证的技术路径。凡是「起一个新项目 / 技术选型 / 脚手架怎么搭 / 这套技术栈能不能用本库」,均适用。存量项目接入走 moheng-ui-audit,不走本技能。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 新项目技术路径
|
|
7
|
+
|
|
8
|
+
适用版本:v<!-- @generated: version -->
|
|
9
|
+
|
|
10
|
+
## 先读项目规范,不替项目选型
|
|
11
|
+
|
|
12
|
+
技术栈由项目规范决定,本技能只判断它与本库是否相容,并排出搭建顺序。开工前先把下面
|
|
13
|
+
六项从项目规范里逐项读出来 —— 来源依次是项目根的 `AGENTS.md` / `CLAUDE.md`、团队规范文档、
|
|
14
|
+
已有的 `package.json`:
|
|
15
|
+
|
|
16
|
+
| 项 | 要读到的事实 |
|
|
17
|
+
|---|---|
|
|
18
|
+
| 框架 | Next.js App Router / Vite + React / 其他 |
|
|
19
|
+
| 语言 | TypeScript 还是 JavaScript,`moduleResolution` 取值 |
|
|
20
|
+
| 包管理器 | pnpm / npm / yarn,是否 monorepo |
|
|
21
|
+
| 浏览器基线 | `browserslist` 或规范里写明的最低版本 |
|
|
22
|
+
| 样式方案 | 项目自有样式用什么写 |
|
|
23
|
+
| 终端与语言 | 桌面端还是移动端,是否多语言 |
|
|
24
|
+
|
|
25
|
+
**规范里没写的项先问,不得猜一个「常见选择」填上。** 路由、数据获取、状态管理、表单校验
|
|
26
|
+
不在本库范围内(本库为纯展示层),一律按项目规范定,本技能不给建议。
|
|
27
|
+
|
|
28
|
+
## 逐项对照硬约束
|
|
29
|
+
|
|
30
|
+
下表每一条都是本库的既定事实,不是偏好。项目规范与其中任何一条冲突时,
|
|
31
|
+
**停下来把冲突报给人**,不得自行绕过,也不得替项目改规范。
|
|
32
|
+
|
|
33
|
+
| 约束 | 取值 | 冲突时的表现 |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| React | <!-- @generated: react-range -->,`react-dom` 同 | 装包即报 peer 依赖不满足 |
|
|
36
|
+
| 模块格式 | 只发 ESM | `require('@moheng-design/ui')` 直接失败;打包器须能消费 ESM 包 |
|
|
37
|
+
| 类型解析 | `moduleResolution` 取 `bundler` / `node16` / `nodenext` | 取 `node`(node10)时类型入口解析不到 |
|
|
38
|
+
| 浏览器 | Chrome 111 / Safari 16.2 / Firefox 113 及以上 | `color-mix()` 与 `@layer` 不做降级编译,低于此线样式整体失效 |
|
|
39
|
+
| 终端 | 桌面端,中文单语言 | 无移动端密度档,无 RTL,组件内置文案为中文 |
|
|
40
|
+
| 样式 | 纯 CSS,两份样式表直接引入,零构建配置 | 不需要 Tailwind、PostCSS 插件或 CSS-in-JS 运行时 |
|
|
41
|
+
| 平行 UI 依赖 | 不得并存 | 见下 |
|
|
42
|
+
|
|
43
|
+
下列依赖出现在 `package.json` 即被 `npx @moheng-design/ui-skill audit` 记为结构性问题 ——
|
|
44
|
+
两套组件库必然分岔,新项目从第一天起就不装:
|
|
45
|
+
|
|
46
|
+
<!-- @generated: parallel-ui -->
|
|
47
|
+
|
|
48
|
+
项目自有样式用什么写由项目规范定,但与组件对齐时必须读 `--application-*` 与 `--ui-*`
|
|
49
|
+
两层 token,不得读 `--ds-*`,唯一例外是换肤入口 `--ds-color-theme-primary`。
|
|
50
|
+
|
|
51
|
+
Next.js App Router 是本库实测过的环境:只有持有交互状态的组件带 `"use client"`,
|
|
52
|
+
其余可直接在 server component 中渲染。其他 React 环境按上表「模块格式」与「浏览器」两条自检。
|
|
53
|
+
|
|
54
|
+
## 技术路径:七步,顺序固定
|
|
55
|
+
|
|
56
|
+
每一步做完即验证,验证不过不进下一步。
|
|
57
|
+
|
|
58
|
+
1. **装包。** 用项目规范指定的包管理器装 `@moheng-design/ui` 与开发依赖 `@moheng-design/ui-skill`,
|
|
59
|
+
两者版本号必须相同 —— 版本号相同即为配套,不存在兼容矩阵。
|
|
60
|
+
验证:安装输出无 peer 依赖告警。
|
|
61
|
+
2. **引样式。** 在应用入口(Next.js 为 `app/layout.tsx`)依次引入
|
|
62
|
+
`@moheng-design/ui/tokens.css` 与 `@moheng-design/ui/styles.css`,token 在前,顺序不得调换。
|
|
63
|
+
验证:渲染一个 `<Button>`,外观与文档站一致。
|
|
64
|
+
3. **定挂载点。** 换肤只覆盖 `--ds-color-theme-primary`,暗色只切 `.dark` 类,
|
|
65
|
+
两者都必须挂在 `<html>` 上,挂在 `<body>` 或容器上一律无效。
|
|
66
|
+
验证:在 `<html>` 上改主色,主按钮与焦点环同时变色。
|
|
67
|
+
4. **拷技能。** `npx @moheng-design/ui-skill install`。升级 `@moheng-design/ui` 后必须重跑。
|
|
68
|
+
验证:`.claude/skills/` 下出现 `moheng-ui` 及各附属技能目录。
|
|
69
|
+
5. **接 ESLint。** 需要 ESLint <!-- @generated: eslint-range --> 与 flat config。
|
|
70
|
+
**新项目直接用 `strict` 档** —— 没有存量代码,不需要 `migration` → `recommended`
|
|
71
|
+
的渐进路径;TypeScript 项目另须配置 `@typescript-eslint/parser`,否则 `.tsx` 一条都扫不到。
|
|
72
|
+
stylelint 当前无需接入,面向消费方的 CSS 规则集为空。
|
|
73
|
+
验证:写一个原生 `<button>`,lint 必须报 `moheng/no-native-button`;报不出来即配置未生效。
|
|
74
|
+
6. **进 CI。** 把 lint 与类型检查接进项目的 CI,两者缺一不可:lint 管「用错组件库」,
|
|
75
|
+
类型检查管「传错 prop」。只接在本地等于没接。
|
|
76
|
+
验证:带一处原生 `<button>` 的提交在 CI 上变红。
|
|
77
|
+
7. **搭第一个页面。** 转 `moheng-ui-page`:先定五层 Canvas 模型的五个字段,再选组件。
|
|
78
|
+
验证:页面通过第 5 步的 lint,且零报错。
|
|
79
|
+
|
|
80
|
+
当前 <!-- @generated: rule-count --> 条规则中,带 autofix 的有:<!-- @generated: autofix-rules -->。
|
|
81
|
+
新项目不应依赖 autofix —— 一次写对是主技能 `moheng-ui` 的职责,autofix 是存量迁移的工具。
|
|
82
|
+
|
|
83
|
+
## 产出:写进项目的 agent 指导文件
|
|
84
|
+
|
|
85
|
+
把结论写进项目根的 `AGENTS.md`(或 `CLAUDE.md`)的「技术路径」一节,固定四段:
|
|
86
|
+
|
|
87
|
+
1. **技术栈** —— 上面六项的取值,逐项注明出处(项目规范的哪一节,或人的答复)。
|
|
88
|
+
2. **硬约束对照** —— 七条逐条写「相容」或「冲突:原因」。有冲突即在此停住。
|
|
89
|
+
3. **七步进度** —— 可勾选清单,每步附验证结果。
|
|
90
|
+
4. **不在本库范围** —— 路由、数据获取、状态管理、表单校验各自按项目规范的哪一条执行。
|
|
91
|
+
|
|
92
|
+
## 边界
|
|
93
|
+
|
|
94
|
+
- 不得替项目选型:规范没写的项必须问人,不得按「业界常见做法」填。
|
|
95
|
+
- 不得为了让本库跑起来而下调项目的浏览器基线要求,或为低版本浏览器加降级编译。
|
|
96
|
+
- 不得在新项目里装平行 UI 依赖,也不得用 `npx shadcn add` 往项目里拷组件源码。
|
|
97
|
+
- 不得跳过第 5 步先写页面 —— 没有 lint 兜底时写出的页面,返工量与存量迁移相同。
|
|
98
|
+
- 不得把本技能用于存量项目,那是 `moheng-ui-audit` 的范围。
|
|
99
|
+
- 产出中不出现 Emoji。
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui-feedback
|
|
3
|
+
description: 用 @moheng-design/ui 搭系统的过程中撞到组件缺失、prop 不够、token 没有、规则误报、约定不清时加载。把问题按回流目标结构化记录下来,供组件库维护方消化。凡是「这个库少了 X / 这条规则不对 / 记一下这个问题」,均适用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 问题收集与回流
|
|
7
|
+
|
|
8
|
+
适用版本:v<!-- @generated: version -->
|
|
9
|
+
|
|
10
|
+
## 为什么要结构化
|
|
11
|
+
|
|
12
|
+
用本库时撞到的每一类问题,在组件库仓库里都有一个固定的落点。反馈按落点分类,
|
|
13
|
+
维护方拿到就能改;自由文本要先猜是哪一类,猜错就改错地方。
|
|
14
|
+
|
|
15
|
+
| 反馈类型 | 回流到 | 判据 |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `missing-component` | 新契约 + `conventions.md` | 系统里没有能承担这个场景的组件,且替换表也没指向任何组件 |
|
|
18
|
+
| `missing-prop` | 契约 | 组件在,但缺一个 prop 或枚举值;`props-whitelist` / `prop-enum` 因此报错 |
|
|
19
|
+
| `missing-token` | `application-extend.css` / `foundation-extend.css` | 需要一个尺度或颜色,`--application-*` 与 `--ui-*` 两层都找不到 |
|
|
20
|
+
| `rule-false-positive` | `mappings.json` | 规则报了不该报的,或报错文案照做后仍然报错 |
|
|
21
|
+
| `unclear-convention` | `conventions.md` | 两个组件的边界说不清该用哪个 |
|
|
22
|
+
| `doc-mismatch` | 契约 JSDoc | 文档与实际行为不一致 |
|
|
23
|
+
|
|
24
|
+
## 每一次绕过都是一条反馈
|
|
25
|
+
|
|
26
|
+
禁用本库规则时**必须**附原因,格式固定:
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
// eslint-disable-next-line moheng/no-native-button -- moheng: <反馈类型> <一句话>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
没有 `-- moheng:` 说明的 disable,收集命令会单独列出来要求补齐。绕过而不记录,
|
|
33
|
+
问题就永远留在项目里,组件库永远不知道。
|
|
34
|
+
|
|
35
|
+
## 收集
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npx @moheng-design/ui-skill feedback
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
命令扫描项目里所有对本库规则的 `eslint-disable`、`TODO(moheng)` / `FIXME(moheng)`
|
|
42
|
+
标记与深引位置,连同 `@moheng-design/ui` 版本号写成 `moheng-feedback.md` 草稿。
|
|
43
|
+
**草稿由人看过再提交**,本技能不自动发 issue。
|
|
44
|
+
|
|
45
|
+
## 记录格式
|
|
46
|
+
|
|
47
|
+
每条反馈一个条目,字段缺一不可:
|
|
48
|
+
|
|
49
|
+
```markdown
|
|
50
|
+
### <反馈类型> · <组件或 token 名>
|
|
51
|
+
|
|
52
|
+
- 版本:@moheng-design/ui v<!-- @generated: version -->
|
|
53
|
+
- 位置:<文件:行>
|
|
54
|
+
- 复现:<最小代码>
|
|
55
|
+
- 期望:<一句话>
|
|
56
|
+
- 当前绕法:<disable / 平行实现 / 手写原生元素>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## 边界
|
|
60
|
+
|
|
61
|
+
- 不得把业务需求写成组件库反馈。「我们的表格要三层表头」先判断是不是 Table 的职责。
|
|
62
|
+
- 不得因为一条规则误报就整条关掉;记一条 `rule-false-positive`,局部 disable 并附原因。
|
|
63
|
+
- 反馈里不出现 Emoji,mock 内容用登记过的占位符。
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui-page
|
|
3
|
+
description: 用 @moheng-design/ui 的 Application Module 层搭一个完整页面(列表页、详情页、工作台、设置页)时加载。先定五层 Canvas 模型的五个字段,再选组件组合,最后出骨架。凡是「新建一个页面 / 搭页面骨架 / 这页该用哪些 Module 组件」,均适用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 页面骨架
|
|
7
|
+
|
|
8
|
+
适用版本:v<!-- @generated: version -->
|
|
9
|
+
|
|
10
|
+
## 先定五个字段,再碰组件
|
|
11
|
+
|
|
12
|
+
Application Module 层的组件不能脱离五层 Canvas 模型使用。写第一行 JSX 之前,
|
|
13
|
+
五个字段必须逐个定下来并写进代码,不得含糊、不得留空:
|
|
14
|
+
|
|
15
|
+
<!-- @generated: canvas-fields -->
|
|
16
|
+
|
|
17
|
+
字段的取值与含义以 SKILL.md 的「五层 Canvas 模型」一节为准。定不下来的字段
|
|
18
|
+
先问,不要猜一个「默认值」。
|
|
19
|
+
|
|
20
|
+
## 再选组件组合
|
|
21
|
+
|
|
22
|
+
按字段取值从下面这批组件里选,每个组件的适用场景以其约定章节的「何时使用」为准:
|
|
23
|
+
|
|
24
|
+
<!-- @generated: module-components -->
|
|
25
|
+
|
|
26
|
+
选定后按 SKILL.md「Canvas 标准区域顺序」排布,顺序不得调换。
|
|
27
|
+
|
|
28
|
+
## 最后出骨架
|
|
29
|
+
|
|
30
|
+
骨架的硬要求:
|
|
31
|
+
|
|
32
|
+
- 五个字段以 prop 形式显式传给 Module 组件,不写在注释里。
|
|
33
|
+
- 六种数据状态(Loading / Empty / Error / No Permission / Not Found / Partial Failure)
|
|
34
|
+
各给各的文案,不得共用一句。
|
|
35
|
+
- Mock 数据只用登记过的占位符(`示例应用` / `模块 A` / `Tab 1`)。
|
|
36
|
+
- 骨架内不出现原生 `<button>` / `<input>` / `<table>`,替换表里有的一律用组件。
|
|
37
|
+
|
|
38
|
+
写完跑一遍 lint,再对照 moheng-ui-review 的清单过一遍第四桶。
|
|
39
|
+
|
|
40
|
+
## 边界
|
|
41
|
+
|
|
42
|
+
- 不得用 Foundation 组件手拼一个 Module 层已有的区域(页头、工具栏、分页)。
|
|
43
|
+
- 不得在页面里写「视图设置」这类通用命名的按钮。
|
|
44
|
+
- 不得为了「先跑起来」省掉五个字段中的任何一个。
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui-review
|
|
3
|
+
description: 审查一段用 @moheng-design/ui 写的改动(PR、diff、单个文件)时加载。ESLint 已经拦住的不用再看,本技能只覆盖 lint 看不见的那批约束:条件式必填、文案、挂载点、跨文件的引用。凡是「帮我 review 这个页面 / 组件 / PR」,均适用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @moheng-design/ui 审查清单
|
|
7
|
+
|
|
8
|
+
适用版本:v<!-- @generated: version -->
|
|
9
|
+
|
|
10
|
+
## 先跑工具,再看清单
|
|
11
|
+
|
|
12
|
+
先让 lint 说话。下面的清单只管 lint 管不了的东西,重复看 lint 已报的项是浪费。
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npx eslint --config eslint.config.js <改动的文件>
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
零报错不等于合规。<!-- @generated: rule-count --> 条规则覆盖的是「用错组件库」与「发明不存在的 prop」,
|
|
19
|
+
下面这些它一条都看不见。
|
|
20
|
+
|
|
21
|
+
## 逐条人工核对
|
|
22
|
+
|
|
23
|
+
对 diff 里每个用到本库组件的文件,按下表逐条过。每一条要么明确写「不涉及」,
|
|
24
|
+
要么给出文件与行号 —— 不得整体写「已检查」。
|
|
25
|
+
|
|
26
|
+
<!-- @generated: unenforced-checklist -->
|
|
27
|
+
|
|
28
|
+
## 产出格式
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
### <文件路径>
|
|
32
|
+
- [ ] <约束>:不涉及 / 通过 / 违反(第 N 行,原因)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
只列有结论的条目。「违反」必须附替换写法,写法从 SKILL.md 的替换表与反例里取,
|
|
36
|
+
不得自创。
|
|
37
|
+
|
|
38
|
+
## 边界
|
|
39
|
+
|
|
40
|
+
- 本清单不替代类型检查与 lint,三者各管一段。
|
|
41
|
+
- 本清单不判断业务逻辑对错,只判断组件库用法。
|
|
42
|
+
- 清单会随规则增补缩短:一条约束一旦收进 mappings.json 或契约,就从这里消失。
|
|
43
|
+
以本文件头部版本对应的那一份为准。
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: moheng-ui-upgrade
|
|
3
|
+
description: 升级项目里的 @moheng-design/ui 版本时加载。先看契约差异再改代码,不靠 tsc 报错一处一处试。凡是「升级组件库 / 换了版本编译不过 / SKILL.md 版本对不上」,均适用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 版本升级
|
|
7
|
+
|
|
8
|
+
适用版本:v<!-- @generated: version -->
|
|
9
|
+
|
|
10
|
+
## 差异由契约算
|
|
11
|
+
|
|
12
|
+
两包 fixed versioning,版本号相同即为配套。升级只有一种正确顺序:
|
|
13
|
+
|
|
14
|
+
1. 升级两个包到同一版本。
|
|
15
|
+
2. 跑差异命令,拿到契约层面的变化:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx @moheng-design/ui-skill upgrade --from <旧版 contracts.json 的路径>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
旧版 `contracts.json` 在升级前的 `node_modules/@moheng-design/ui-skill/generated/` 里,
|
|
22
|
+
升级前先拷一份出来。命令比对新旧两份,产出 `moheng-upgrade.md`:
|
|
23
|
+
组件的增删、prop 的增删与必填变化、枚举值的增删。
|
|
24
|
+
|
|
25
|
+
3. 按报告改代码。删掉的 prop 与枚举值对应的是 `props-whitelist` / `prop-enum` 会报的
|
|
26
|
+
那些位置,先跑一遍 lint 再动手。
|
|
27
|
+
4. 重跑安装命令,让项目里的 SKILL.md 跟上:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npx @moheng-design/ui-skill install --force
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## 边界
|
|
34
|
+
|
|
35
|
+
- 不得跳过第 2 步直接按 tsc 报错修。tsc 只报类型不匹配,不报「这个枚举值改名了」。
|
|
36
|
+
- 不得只升一个包。版本不同的两包之间不存在兼容矩阵。
|
|
37
|
+
- 项目里的 SKILL.md 头部版本号与 `package.json` 不一致时,一律以
|
|
38
|
+
`node_modules/@moheng-design/ui-skill/generated/reference.md` 为准,直到第 4 步完成。
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
只有引导、没有强制的约束清单。
|
|
3
|
+
|
|
4
|
+
这份表原先写在 README 里,现在挪到这儿成为一份手写事实来源:README 的同名章节、
|
|
5
|
+
moheng-ui-review 技能的审查清单,都从这里生成。理由与 §1.5 相同 —— 一张表两处
|
|
6
|
+
维护,缩短时必漏一处,而漏掉不报错。
|
|
7
|
+
|
|
8
|
+
每一行三列:约束 | 出处 | 为什么没有规则。第三列不可省 —— §1.4 的危害不在
|
|
9
|
+
「少一条规则」,而在「以为约束住了、实际没有」。读到这张表的人要知道它为什么
|
|
10
|
+
只能靠人看。
|
|
11
|
+
|
|
12
|
+
这张表是会缩短的。凡是能收进类型或收进 mappings 的,就不该留在这里。
|
|
13
|
+
-->
|
|
14
|
+
|
|
15
|
+
| 约束 | 出处 | 为什么没有规则 |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `iconOnly` 为真则 `aria-label` 必填 | Button 契约 | 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动 |
|
|
18
|
+
| 不得用 `onMouseEnter` / `onMouseLeave` 驱动样式 | §1.7、反例「用 JS state 模拟 hover」 | 五类 kind 里没有「组件上不得出现某个 prop」这一形态。这两个是基类提供的合法原生属性,由 `nativeBases` 表放行,props 白名单只判「不认识的 prop」 |
|
|
19
|
+
| 不得用 `模块1` / `模块2` 之类未登记的 mock 占位符 | 02 §8 | 唯一能判字符串字面量的 `forbid-value`,其 `scope` 被 schema 锁死为 `internal`(§7.3),而这条要管的正是消费方写的 mock |
|
|
20
|
+
| 六种数据状态不得共用一句话 | 反例「六种数据状态共用一句话」 | 判定是六个 `ReactNode` 槽位之间的文案比对,跨 prop 的内容比较,五类 kind 无一作用于此 |
|
|
21
|
+
| 必须引一次 `@moheng-design/ui/styles.css` | 反例「忘记引样式表」 | `forbid-import` 只有「不得从某处导入」,没有反向的「必须导入」;且样式引在应用入口、组件用在别处,判定跨文件 |
|
|
22
|
+
| 换肤与 `.dark` 必须挂在 `<html>` 上 | 反例「换肤改错了变量」 | 挂载点在 JSX 里是任意元素的 `className` / `style`,真正的判定落在运行时的 DOM 层级上 |
|
|
23
|
+
| 呈现设置按钮不得取名「视图设置」 | 反例「通用的视图设置按钮」 | 文案约束,同 mock 占位符那条 |
|
|
24
|
+
| `ScrollArea` 必须给高度、不得嵌套 | 反例「堆叠无界的垂直滚动容器」 | 前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链 |
|
|
25
|
+
| Application Module 组件必须声明五层模型字段 | §1.8、canvas-model.md | 契约里五个字段都是可选的 —— 缺了 tsc 不说,而「用了本层组件就必须一并声明」同样是条件式必填 |
|
|
26
|
+
| 产品 UI 文案里不得出现 Emoji | 02 §8 | 文案约束,同 mock 占位符那条。生成器对本包 `handwritten/*.md` 与 `@moheng-design/ui` 的契约 JSDoc 查 Emoji,管不到消费方代码 |
|
|
27
|
+
| `SearchField` 不得逐字实时搜索 | 反例「逐字实时搜索」 | 判定是 `onChange` 回调体内有没有发起搜索,跨函数体的语义判定。规则只拦得住原生 `<input type="search">` |
|
package/package.json
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@moheng-design/ui-skill",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "@moheng-design/ui 的 AI agent 支持包 —— SKILL.md 引导 + ESLint / stylelint 强制规则",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"agent",
|
|
7
|
+
"skill",
|
|
8
|
+
"eslint",
|
|
9
|
+
"stylelint",
|
|
10
|
+
"design-system",
|
|
11
|
+
"moheng"
|
|
12
|
+
],
|
|
13
|
+
"license": "UNLICENSED",
|
|
14
|
+
"type": "module",
|
|
15
|
+
"sideEffects": false,
|
|
16
|
+
"publishConfig": {
|
|
17
|
+
"access": "public",
|
|
18
|
+
"registry": "https://registry.npmjs.org/"
|
|
19
|
+
},
|
|
20
|
+
"bin": {
|
|
21
|
+
"moheng-ui-skill": "./bin/cli.js"
|
|
22
|
+
},
|
|
23
|
+
"exports": {
|
|
24
|
+
".": "./eslint/index.js",
|
|
25
|
+
"./eslint": "./eslint/index.js",
|
|
26
|
+
"./stylelint": "./stylelint/index.js",
|
|
27
|
+
"./rules.json": "./generated/rules.json",
|
|
28
|
+
"./SKILL.md": "./generated/SKILL.md",
|
|
29
|
+
"./reference.md": "./generated/reference.md",
|
|
30
|
+
"./package.json": "./package.json"
|
|
31
|
+
},
|
|
32
|
+
"files": [
|
|
33
|
+
"bin",
|
|
34
|
+
"eslint",
|
|
35
|
+
"stylelint",
|
|
36
|
+
"generated",
|
|
37
|
+
"handwritten",
|
|
38
|
+
"README.md"
|
|
39
|
+
],
|
|
40
|
+
"peerDependencies": {
|
|
41
|
+
"eslint": "^9.0.0",
|
|
42
|
+
"stylelint": "^16.0.0"
|
|
43
|
+
},
|
|
44
|
+
"peerDependenciesMeta": {
|
|
45
|
+
"eslint": {
|
|
46
|
+
"optional": true
|
|
47
|
+
},
|
|
48
|
+
"stylelint": {
|
|
49
|
+
"optional": true
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"@types/react": "^19.2.2",
|
|
54
|
+
"eslint": "^9.39.0",
|
|
55
|
+
"stylelint": "^16.26.0",
|
|
56
|
+
"typescript": "^5.9.3",
|
|
57
|
+
"@moheng-design/ui": "1.0.0"
|
|
58
|
+
},
|
|
59
|
+
"scripts": {
|
|
60
|
+
"generate": "node scripts/generate.mjs",
|
|
61
|
+
"check:generate": "node scripts/generate.mjs --check",
|
|
62
|
+
"extract": "node scripts/extract-contracts.mjs",
|
|
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"
|
|
65
|
+
}
|
|
66
|
+
}
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @moheng-design/ui-skill 的 stylelint 插件(01 §7.2.1)。
|
|
3
|
+
*
|
|
4
|
+
* **两个工具,一个来源。** ESLint 管 JS / JSX / TS / TSX,stylelint 管 CSS,
|
|
5
|
+
* 两者的规则都从 mappings.json 生成。
|
|
6
|
+
*
|
|
7
|
+
* 为什么非有它不可:组件样式全部写在外部 CSS(§1.7),而 ESLint 读不了 .css。
|
|
8
|
+
* 若只做 ESLint,「组件 CSS 不得出现硬编码值」(§4.1)就只是一句文档 ——
|
|
9
|
+
* 即 §1.4 定义的反模式:以为约束住了,实际没有。
|
|
10
|
+
*
|
|
11
|
+
* 不允许为 stylelint 单独维护一份配置 —— 那等于制造第三处事实来源,
|
|
12
|
+
* §1.5 的死循环会从「Skill vs ESLint」变成三方僵持。
|
|
13
|
+
*
|
|
14
|
+
* 用法:
|
|
15
|
+
*
|
|
16
|
+
* // stylelint.config.js
|
|
17
|
+
* import moheng from '@moheng-design/ui-skill/stylelint'
|
|
18
|
+
* export default { plugins: moheng.plugins, rules: moheng.internal }
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import stylelint from 'stylelint'
|
|
22
|
+
|
|
23
|
+
import data from '../generated/plugin-data.js'
|
|
24
|
+
import { compileValuePattern, matchesFile } from '../eslint/lib/match.js'
|
|
25
|
+
import { inScope } from '../eslint/lib/tiers.js'
|
|
26
|
+
|
|
27
|
+
const { createPlugin, utils } = stylelint
|
|
28
|
+
|
|
29
|
+
export const NAMESPACE = 'moheng'
|
|
30
|
+
|
|
31
|
+
/** 只有声明了 css 目标的规则才进 stylelint。 */
|
|
32
|
+
const cssRules = data.rules.filter((rule) => rule.targets.includes('css'))
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* 由一条 forbid-value 规则数据造出一个具名 stylelint 插件。
|
|
36
|
+
*
|
|
37
|
+
* 导出是为测试留的口子:`cssProperties` 省略时插件检查**全部声明**,而当前三条
|
|
38
|
+
* 规则都带 `cssProperties`,这条分支没有任何真实规则覆盖得到 —— 连带
|
|
39
|
+
* 「自定义属性声明处不得报错」那道守卫也测不出来(属性表先返回了)。
|
|
40
|
+
* 唯一能覆盖它的办法是拿一条合成规则单独造插件,故此处开放。
|
|
41
|
+
* 消费方不需要它,`stylelint.config.js` 一律用 `plugins` 与档位导出。
|
|
42
|
+
*/
|
|
43
|
+
export function makePlugin(rule) {
|
|
44
|
+
const ruleName = `${NAMESPACE}/${rule.id}`
|
|
45
|
+
/* 报错文案直接用 rule.message,不加工 —— 与 ESLint 侧、SKILL.md 逐字一致。 */
|
|
46
|
+
const messages = utils.ruleMessages(ruleName, { rejected: () => rule.message })
|
|
47
|
+
const properties = rule.cssProperties ? new Set(rule.cssProperties) : null
|
|
48
|
+
|
|
49
|
+
const ruleFunction = (primary) => (root, result) => {
|
|
50
|
+
if (!utils.validateOptions(result, ruleName, { actual: primary, possible: [true, false] })) return
|
|
51
|
+
if (primary === false) return
|
|
52
|
+
|
|
53
|
+
const from = root.source?.input?.from ?? ''
|
|
54
|
+
if (matchesFile(from, rule.exceptFiles)) return
|
|
55
|
+
|
|
56
|
+
/* 编译走 compileValuePattern —— 与 ESLint 侧同一份实现(§7.2.1 一个来源),
|
|
57
|
+
* 它剥掉 g / y,否则 test() 会跨声明保留 lastIndex,同一文件里的违规每隔一个漏报。 */
|
|
58
|
+
const re = compileValuePattern(rule)
|
|
59
|
+
|
|
60
|
+
root.walkDecls((decl) => {
|
|
61
|
+
/* cssProperties 省略时检查全部声明;给出时只查列表内的属性。
|
|
62
|
+
* 例如 no-raw-px-value 不查 border —— 1px 边框一律走 --ui-border-default,
|
|
63
|
+
* 把 border 列进去只会得到一片必然的误报。 */
|
|
64
|
+
if (properties && !properties.has(decl.prop.toLowerCase())) return
|
|
65
|
+
/* 自定义属性的声明处必须能写字面值,那是 token 被定义的地方 */
|
|
66
|
+
if (decl.prop.startsWith('--')) return
|
|
67
|
+
/* 正则跑在「属性: 值」整串上,不是只跑值。
|
|
68
|
+
* 同一条 valuePattern 必须同时供 ESLint 与 stylelint 使用(§7.2.1 一个来源),
|
|
69
|
+
* 而 JS 侧看到的字面量是 `font-family: Menlo, monospace` 这样的整串,
|
|
70
|
+
* 因此 no-unregistered-font 的模式以属性名起头。只拿 decl.value 去比,
|
|
71
|
+
* 该模式永远匹配不上 —— 规则会在它唯一存在意义的那一侧(CSS)静默失效。 */
|
|
72
|
+
if (!re.test(`${decl.prop}: ${decl.value}`)) return
|
|
73
|
+
|
|
74
|
+
utils.report({
|
|
75
|
+
result,
|
|
76
|
+
ruleName,
|
|
77
|
+
message: messages.rejected(),
|
|
78
|
+
node: decl,
|
|
79
|
+
word: decl.value,
|
|
80
|
+
})
|
|
81
|
+
})
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
ruleFunction.ruleName = ruleName
|
|
85
|
+
ruleFunction.messages = messages
|
|
86
|
+
ruleFunction.meta = { url: `https://moheng.dev/rules/${rule.id}` }
|
|
87
|
+
|
|
88
|
+
return createPlugin(ruleName, ruleFunction)
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
export const plugins = cssRules.map(makePlugin)
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* 档位条目一律写成 `[true, { severity }]`,severity 取自 mappings.json 的声明。
|
|
95
|
+
*
|
|
96
|
+
* 只写 `true` 时插件从不读 `rule.severity`,实际严重度落到 stylelint 的
|
|
97
|
+
* defaultSeverity 上,恰好是 error 才没出事。消费方在自己的 stylelint.config.js
|
|
98
|
+
* 里写一句 `defaultSeverity: 'warning'`,三条规则整体降级为告警,含硬编码色值与
|
|
99
|
+
* px 的 CSS 退出码变 0 —— 闸门不再拦任何东西,且不报错、不告警,正是 §1.4 点名的
|
|
100
|
+
* 「以为约束住了,实际没有」。
|
|
101
|
+
*
|
|
102
|
+
* 显式带出后本档不受 defaultSeverity 影响,而消费方仍可逐条覆盖(自己的规则设置
|
|
103
|
+
* 排在本档展开之后即生效),§7.4 的渐进启用不受影响。
|
|
104
|
+
*/
|
|
105
|
+
const rulesFor = (scope) => Object.fromEntries(
|
|
106
|
+
cssRules
|
|
107
|
+
.filter(inScope(scope))
|
|
108
|
+
.map((rule) => [`${NAMESPACE}/${rule.id}`, [true, { severity: rule.severity }]]),
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* 库内自用档。三条 forbid-value 的 scope 都是 internal(schema 强制),
|
|
113
|
+
* 所以 consumer 档实际为空 —— 这不是遗漏,是 §7.3 的直接结果:
|
|
114
|
+
* 用户业务代码里出现色值与 px 是完全正常的。
|
|
115
|
+
*/
|
|
116
|
+
export const internal = rulesFor('internal')
|
|
117
|
+
|
|
118
|
+
/** 消费方档。当前为空;将来若有 scope 为 consumer / both 的 css 规则会自动出现在这里。 */
|
|
119
|
+
export const consumer = rulesFor('consumer')
|
|
120
|
+
|
|
121
|
+
export default { plugins, internal, consumer, NAMESPACE }
|