@moheng-design/ui-skill 1.0.0 → 2.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.
@@ -7,7 +7,7 @@ description: 评估一个存量项目离 @moheng-design/ui 规范有多远、该
7
7
 
8
8
  # 存量项目合规审计
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
12
  ## 数字由工具算,本技能只解释
13
13
 
@@ -36,23 +36,34 @@ npx @moheng-design/ui-skill audit
36
36
  | 三、结构性 | 平行 UI 依赖、未引样式表、Application Module 组件缺五层模型声明 | 单独立项,不与前两桶混在一个 PR |
37
37
  | 四、lint 看不见 | 下面这张清单 | 只能人看,抽样核对后写进报告的「未量化风险」 |
38
38
 
39
- - [ ] **`iconOnly` 为真则 `aria-label` 必填**(Button 契约)—— 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动
39
+ 与 `moheng-audit.json` 的字段对应:`buckets.autofix` 即第一桶,`buckets.manual` 即第二桶;
40
+ `buckets.generated`(`props-whitelist` / `prop-enum` 的命中)不进四桶 —— 它们与 tsc 报的
41
+ 是同一类问题,只用于下面「升档门槛」的第二条。第三桶读 `structural` 的 `parallelUi`、
42
+ `parallelImports`、`stylesImported` 与 `deepImports`;其中「缺五层模型声明」命令算不出来,
43
+ 须逐个打开用到 Application Module 组件的文件核对,并在报告里写明这一项是人工计数。
44
+ `suppressed` 是被 `eslint-disable` 压掉的命中,不计入总数,但必须在「现状」一节单列 ——
45
+ 关掉的规则正是最该看见的欠账。
46
+
47
+ - [ ] **`iconOnly` 为真则 `aria-label` 必填**(Button / SystemButton 契约)—— 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动
40
48
  - [ ] **不得用 `onMouseEnter` / `onMouseLeave` 驱动样式**(§1.7、反例「用 JS state 模拟 hover」)—— 五类 kind 里没有「组件上不得出现某个 prop」这一形态。这两个是基类提供的合法原生属性,由 `nativeBases` 表放行,props 白名单只判「不认识的 prop」
41
49
  - [ ] **不得用 `模块1` / `模块2` 之类未登记的 mock 占位符**(02 §8)—— 唯一能判字符串字面量的 `forbid-value`,其 `scope` 被 schema 锁死为 `internal`(§7.3),而这条要管的正是消费方写的 mock
42
50
  - [ ] **六种数据状态不得共用一句话**(反例「六种数据状态共用一句话」)—— 判定是六个 `ReactNode` 槽位之间的文案比对,跨 prop 的内容比较,五类 kind 无一作用于此
43
51
  - [ ] **必须引一次 `@moheng-design/ui/styles.css`**(反例「忘记引样式表」)—— `forbid-import` 只有「不得从某处导入」,没有反向的「必须导入」;且样式引在应用入口、组件用在别处,判定跨文件
44
52
  - [ ] **换肤与 `.dark` 必须挂在 `<html>` 上**(反例「换肤改错了变量」)—— 挂载点在 JSX 里是任意元素的 `className` / `style`,真正的判定落在运行时的 DOM 层级上
45
53
  - [ ] **呈现设置按钮不得取名「视图设置」**(反例「通用的视图设置按钮」)—— 文案约束,同 mock 占位符那条
46
- - [ ] **`ScrollArea` 必须给高度、不得嵌套**(反例「堆叠无界的垂直滚动容器」)—— 前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链
47
- - [ ] **Application Module 组件必须声明五层模型字段**(§1.8、canvas-model.md)—— 契约里五个字段都是可选的 —— 缺了 tsc 不说,而「用了本层组件就必须一并声明」同样是条件式必填
54
+ - [ ] **`ScrollArea` 必须给高度、不得嵌套(看板外层横向、列内纵向是登记例外,07 · C-14)**(反例「堆叠无界的垂直滚动容器」)—— 前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链
55
+ - [ ] **结果集页面必须声明五层模型字段,无结果集页面只声明 `pageType`**(§1.8、canvas-model.md(06 · D-1))—— `pageType` 已收进类型(`ApplicationPageLayoutContainer` 必填,缺了 tsc 报错);其余四个字段在契约里仍是可选的,「用了本层组件就必须一并声明」同样是条件式必填
56
+ - [ ] **业务页面不得直接使用 Foundation `Button`**(Button / SystemButton 契约、反例「业务页面用 Foundation Button」)—— `forbid-element` 的 `match.element` 被 schema 限定为小写原生标签名,「不得使用本库自己的某个导出」是另一种形态,schema 阶段 3 已定稿。原生 `<button>` 的 autofix 已改写为 `SystemButton`
48
57
  - [ ] **产品 UI 文案里不得出现 Emoji**(02 §8)—— 文案约束,同 mock 占位符那条。生成器对本包 `handwritten/*.md` 与 `@moheng-design/ui` 的契约 JSDoc 查 Emoji,管不到消费方代码
49
58
  - [ ] **`SearchField` 不得逐字实时搜索**(反例「逐字实时搜索」)—— 判定是 `onChange` 回调体内有没有发起搜索,跨函数体的语义判定。规则只拦得住原生 `<input type="search">`
59
+ - [ ] **消费方代码不得读 `--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` 档因此为空
60
+ - [ ] **条件式必填: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 本轮不改
50
61
 
51
62
  ## 产出:MIGRATION.md
52
63
 
53
64
  报告固定五节,数字全部来自 `moheng-audit.json`,写明取值时间与 `@moheng-design/ui` 版本:
54
65
 
55
- 1. **现状** —— 文件数、命中总数、按规则的前十条。
66
+ 1. **现状** —— 文件数、命中总数、按规则的前十条、被 `eslint-disable` 压掉的条数。
56
67
  2. **四桶** —— 每桶的条数与涉及文件数。
57
68
  3. **升档门槛** —— 进入 `recommended` 的条件是第一、二桶归零;进入 `strict` 的条件是
58
69
  `props-whitelist` / `prop-enum` 也归零。写成可勾选的清单。
@@ -7,7 +7,7 @@ description: 新项目启动、要基于 @moheng-design/ui 定技术栈与搭建
7
7
 
8
8
  # 新项目技术路径
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
12
  ## 先读项目规范,不替项目选型
13
13
 
@@ -56,7 +56,8 @@ description: 新项目启动、要基于 @moheng-design/ui 定技术栈与搭建
56
56
  - `shadcn`
57
57
 
58
58
  项目自有样式用什么写由项目规范定,但与组件对齐时必须读 `--application-*` 与 `--ui-*`
59
- 两层 token,不得读 `--ds-*`,唯一例外是换肤入口 `--ds-color-theme-primary`。
59
+ 两层 token,不得读 `--ds-*`,例外是换肤入口 `--ds-color-theme-primary` 与焦点环几何
60
+ `--ds-focus-ring-width` / `--ds-focus-ring-offset`(只读)。
60
61
 
61
62
  Next.js App Router 是本库实测过的环境:只有持有交互状态的组件带 `"use client"`,
62
63
  其余可直接在 server component 中渲染。其他 React 环境按上表「模块格式」与「浏览器」两条自检。
@@ -70,9 +71,12 @@ Next.js App Router 是本库实测过的环境:只有持有交互状态的组
70
71
  验证:安装输出无 peer 依赖告警。
71
72
  2. **引样式。** 在应用入口(Next.js 为 `app/layout.tsx`)依次引入
72
73
  `@moheng-design/ui/tokens.css` 与 `@moheng-design/ui/styles.css`,token 在前,顺序不得调换。
73
- 验证:渲染一个 `<Button>`,外观与文档站一致。
74
+ 项目若还引入其他带 `@layer` 的样式表(如 Tailwind),这两份必须排在它们之后:
75
+ `moheng` 层组的位置由两份里先引入的那一份决定,排在前面会被对方的 preflight 压掉。
76
+ 验证:渲染一个 `<SystemButton>`,外观与文档站一致。
74
77
  3. **定挂载点。** 换肤只覆盖 `--ds-color-theme-primary`,暗色只切 `.dark` 类,
75
- 两者都必须挂在 `<html>` 上,挂在 `<body>` 或容器上一律无效。
78
+ 两者都必须挂在 `<html>` 上。挂在 `<body>` 或容器上是半生效,比无效更糟:
79
+ 直接读 `--ds-*` 的部件变了,读 `--application-*` 的部件不变,看上去像是生效了。
76
80
  验证:在 `<html>` 上改主色,主按钮与焦点环同时变色。
77
81
  4. **拷技能。** `npx @moheng-design/ui-skill install`。升级 `@moheng-design/ui` 后必须重跑。
78
82
  验证:`.claude/skills/` 下出现 `moheng-ui` 及各附属技能目录。
@@ -84,10 +88,10 @@ Next.js App Router 是本库实测过的环境:只有持有交互状态的组
84
88
  6. **进 CI。** 把 lint 与类型检查接进项目的 CI,两者缺一不可:lint 管「用错组件库」,
85
89
  类型检查管「传错 prop」。只接在本地等于没接。
86
90
  验证:带一处原生 `<button>` 的提交在 CI 上变红。
87
- 7. **搭第一个页面。** 转 `moheng-ui-page`:先定五层 Canvas 模型的五个字段,再选组件。
91
+ 7. **搭第一个页面。** 转 `moheng-ui-page`:先判定有没有结果集、定下五层 Canvas 模型里该写的字段,再选组件。
88
92
  验证:页面通过第 5 步的 lint,且零报错。
89
93
 
90
- 当前 150 条规则中,带 autofix 的有:`no-native-button`、`no-native-input`、`no-native-textarea`、`no-native-label`、`no-native-hr`、`no-native-progress`、`no-native-kbd`。
94
+ 当前 163 条规则中,带 autofix 的有:`no-native-button`、`no-native-input`、`no-native-textarea`、`no-native-label`、`no-native-hr`、`no-native-progress`、`no-native-kbd`。
91
95
  新项目不应依赖 autofix —— 一次写对是主技能 `moheng-ui` 的职责,autofix 是存量迁移的工具。
92
96
 
93
97
  ## 产出:写进项目的 agent 指导文件
@@ -7,7 +7,7 @@ description: 用 @moheng-design/ui 搭系统的过程中撞到组件缺失、pro
7
7
 
8
8
  # 问题收集与回流
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
12
  ## 为什么要结构化
13
13
 
@@ -31,7 +31,12 @@ description: 用 @moheng-design/ui 搭系统的过程中撞到组件缺失、pro
31
31
  // eslint-disable-next-line moheng/no-native-button -- moheng: <反馈类型> <一句话>
32
32
  ```
33
33
 
34
- 没有 `-- moheng:` 说明的 disable,收集命令会单独列出来要求补齐。绕过而不记录,
34
+ 没有 `-- moheng:` 说明的 disable,收集命令会单独列出来要求补齐。没禁用规则、只是记一笔的地方
35
+ 用 `TODO(moheng)` 标记,首词同样写反馈类型,收集命令据此归类:
36
+
37
+ ```tsx
38
+ // TODO(moheng): missing-component 看板呈现没有对应组件
39
+ ```绕过而不记录,
35
40
  问题就永远留在项目里,组件库永远不知道。
36
41
 
37
42
  ## 收集
@@ -51,7 +56,7 @@ npx @moheng-design/ui-skill feedback
51
56
  ```markdown
52
57
  ### <反馈类型> · <组件或 token 名>
53
58
 
54
- - 版本:@moheng-design/ui v1.0.0
59
+ - 版本:@moheng-design/ui v3.0.0
55
60
  - 位置:<文件:行>
56
61
  - 复现:<最小代码>
57
62
  - 期望:<一句话>
@@ -1,18 +1,25 @@
1
1
  ---
2
2
  name: moheng-ui-page
3
- description: 用 @moheng-design/ui 的 Application Module 层搭一个完整页面(列表页、详情页、工作台、设置页)时加载。先定五层 Canvas 模型的五个字段,再选组件组合,最后出骨架。凡是「新建一个页面 / 搭页面骨架 / 这页该用哪些 Module 组件」,均适用。
3
+ description: 用 @moheng-design/ui 的 Application Module 层搭一个完整页面(列表页、详情页、工作台、设置页)时加载。先判定页面有没有结果集、定下五层 Canvas 模型里该写的字段,再选组件组合,最后出骨架。凡是「新建一个页面 / 搭页面骨架 / 这页该用哪些 Module 组件」,均适用。
4
4
  ---
5
5
 
6
6
  <!-- 生成文件 —— 请勿手改。源:handwritten/skills/ 与 @moheng-design/ui 的契约、mappings.json,生成器:scripts/generate.mjs -->
7
7
 
8
8
  # 页面骨架
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
- ## 先定五个字段,再碰组件
12
+ ## 先定字段,再碰组件
13
13
 
14
14
  Application Module 层的组件不能脱离五层 Canvas 模型使用。写第一行 JSX 之前,
15
- 五个字段必须逐个定下来并写进代码,不得含糊、不得留空:
15
+ 先判定这一页有没有**结果集** —— 一份由 `ApplicationQueryToolbar` 驱动、由
16
+ `ApplicationDataDisplay` 展示的记录集合:
17
+
18
+ - **有结果集**(列表、台账、报表、以查询结果为主体的分析页):下面五个字段必须逐个定下来
19
+ 并写进代码,不得含糊、不得留空。
20
+ - **没有结果集**(工作台、详情页、配置页、协作工作台、编辑器):只声明 `pageType`,其余
21
+ 四个字段不写,也不得为凑字段塞一个数据展示区或空工具栏。结构按 SKILL.md「无结果集页面
22
+ 的结构」一节搭。
16
23
 
17
24
  - `pageType`
18
25
  - `pageMode`
@@ -20,8 +27,8 @@ Application Module 层的组件不能脱离五层 Canvas 模型使用。写第
20
27
  - `dataControl`
21
28
  - `dataPresentation`
22
29
 
23
- 字段的取值与含义以 SKILL.md 的「五层 Canvas 模型」一节为准。定不下来的字段
24
- 先问,不要猜一个「默认值」。
30
+ 字段的取值与含义、两类页面的判据与 `pageType` 取法以 SKILL.md 的「五层 Canvas 模型」
31
+ 一节为准。定不下来的字段先问,不要猜一个「默认值」。
25
32
 
26
33
  ## 再选组件组合
27
34
 
@@ -54,22 +61,36 @@ Application Module 层的组件不能脱离五层 Canvas 模型使用。写第
54
61
  - `FilesCollaborationWorkspace` —— 「文件」工作台 —— 左侧文件夹定位器 · 中间文件表 · 右侧可选预览栏。
55
62
  - `ScheduleCollaborationWorkspace` —— 「日程」工作台 —— 粒度切换 · 月格 · 当日议程栏。周一为一周起始。
56
63
 
57
- 选定后按 SKILL.md「Canvas 标准区域顺序」排布,顺序不得调换。
64
+ 选定后按 SKILL.md「Canvas 标准区域顺序」排布,顺序不得调换;`SPLIT` 页按「SPLIT 的标准
65
+ 组件树」,看板、月历、时间轴三种呈现按「呈现配方」拼装。
58
66
 
59
67
  ## 最后出骨架
60
68
 
61
69
  骨架的硬要求:
62
70
 
63
- - 五个字段以 prop 形式显式传给 Module 组件,不写在注释里。
71
+ - 该写的字段显式写进组件 props,不写在注释里。落点是:
72
+ `pageType` → `ApplicationPageLayoutContainer`(必填);
73
+ `pageMode` → `ApplicationPageHeader`;
74
+ `businessView` → `ApplicationQueryToolbar`;
75
+ `dataControl` → `ApplicationQueryToolbar` 实际给出的 search / filters / sort / pagination 等 props,
76
+ 整个工具栏传进 `ApplicationPageLayoutContainer` 的 `dataControl` 槽位;
77
+ `dataPresentation` → `ApplicationQueryToolbar` 与 `ApplicationDataDisplay` 的 `presentation`(prop 名与字段名不同)。
64
78
  - 六种数据状态(Loading / Empty / Error / No Permission / Not Found / Partial Failure)
65
79
  各给各的文案,不得共用一句。
80
+ - 页头的「更新于 …」(`ApplicationPageHeader` 的 `updatedAt`)只写 `HH:mm` 一种格式(如 `09:12`,07 · C-12),
81
+ 由服务端随数据返回的时间戳格式化而来,与数据同源;不得在客户端用 `useState(Date.now())` 一类写法自造一个时刻 —— 服务端渲染与客户端
82
+ 水合各取一次当前时间,落在分钟边界两侧时文本不一致,且这个时刻与数据的实际更新时间无关。
83
+ - 查询参数(业务视图、搜索词、筛选、页码)与地址栏同步时,Next.js 下用 `useRouter()` 的
84
+ `router.replace`,不得直接调 `history.replaceState` —— 后者绕开 Next 的路由状态,浏览器后退
85
+ 再回到本页时参数丢失。
66
86
  - Mock 数据只用登记过的占位符(`示例应用` / `模块 A` / `Tab 1`)。
67
87
  - 骨架内不出现原生 `<button>` / `<input>` / `<table>`,替换表里有的一律用组件。
68
88
 
69
- 写完跑一遍 lint,再对照 moheng-ui-review 的清单过一遍第四桶。
89
+ 写完跑一遍 lint,再按 moheng-ui-review 的「逐条人工核对」清单逐条过一遍 —— lint 零报错不等于合规,那张清单列的正是 lint 看不见的约束。
70
90
 
71
91
  ## 边界
72
92
 
73
93
  - 不得用 Foundation 组件手拼一个 Module 层已有的区域(页头、工具栏、分页)。
74
94
  - 不得在页面里写「视图设置」这类通用命名的按钮。
75
- - 不得为了「先跑起来」省掉五个字段中的任何一个。
95
+ - 结果集页面不得为了「先跑起来」省掉五个字段中的任何一个;无结果集页面不得为了凑满五个字段
96
+ 虚构工具栏或数据展示区。
@@ -7,7 +7,7 @@ description: 审查一段用 @moheng-design/ui 写的改动(PR、diff、单个
7
7
 
8
8
  # @moheng-design/ui 审查清单
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
12
  ## 先跑工具,再看清单
13
13
 
@@ -17,7 +17,7 @@ description: 审查一段用 @moheng-design/ui 写的改动(PR、diff、单个
17
17
  npx eslint --config eslint.config.js <改动的文件>
18
18
  ```
19
19
 
20
- 零报错不等于合规。150 条规则覆盖的是「用错组件库」与「发明不存在的 prop」,
20
+ 零报错不等于合规。163 条规则覆盖的是「用错组件库」与「发明不存在的 prop」,
21
21
  下面这些它一条都看不见。
22
22
 
23
23
  ## 逐条人工核对
@@ -25,17 +25,20 @@ npx eslint --config eslint.config.js <改动的文件>
25
25
  对 diff 里每个用到本库组件的文件,按下表逐条过。每一条要么明确写「不涉及」,
26
26
  要么给出文件与行号 —— 不得整体写「已检查」。
27
27
 
28
- - [ ] **`iconOnly` 为真则 `aria-label` 必填**(Button 契约)—— 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动
28
+ - [ ] **`iconOnly` 为真则 `aria-label` 必填**(Button / SystemButton 契约)—— 「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动
29
29
  - [ ] **不得用 `onMouseEnter` / `onMouseLeave` 驱动样式**(§1.7、反例「用 JS state 模拟 hover」)—— 五类 kind 里没有「组件上不得出现某个 prop」这一形态。这两个是基类提供的合法原生属性,由 `nativeBases` 表放行,props 白名单只判「不认识的 prop」
30
30
  - [ ] **不得用 `模块1` / `模块2` 之类未登记的 mock 占位符**(02 §8)—— 唯一能判字符串字面量的 `forbid-value`,其 `scope` 被 schema 锁死为 `internal`(§7.3),而这条要管的正是消费方写的 mock
31
31
  - [ ] **六种数据状态不得共用一句话**(反例「六种数据状态共用一句话」)—— 判定是六个 `ReactNode` 槽位之间的文案比对,跨 prop 的内容比较,五类 kind 无一作用于此
32
32
  - [ ] **必须引一次 `@moheng-design/ui/styles.css`**(反例「忘记引样式表」)—— `forbid-import` 只有「不得从某处导入」,没有反向的「必须导入」;且样式引在应用入口、组件用在别处,判定跨文件
33
33
  - [ ] **换肤与 `.dark` 必须挂在 `<html>` 上**(反例「换肤改错了变量」)—— 挂载点在 JSX 里是任意元素的 `className` / `style`,真正的判定落在运行时的 DOM 层级上
34
34
  - [ ] **呈现设置按钮不得取名「视图设置」**(反例「通用的视图设置按钮」)—— 文案约束,同 mock 占位符那条
35
- - [ ] **`ScrollArea` 必须给高度、不得嵌套**(反例「堆叠无界的垂直滚动容器」)—— 前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链
36
- - [ ] **Application Module 组件必须声明五层模型字段**(§1.8、canvas-model.md)—— 契约里五个字段都是可选的 —— 缺了 tsc 不说,而「用了本层组件就必须一并声明」同样是条件式必填
35
+ - [ ] **`ScrollArea` 必须给高度、不得嵌套(看板外层横向、列内纵向是登记例外,07 · C-14)**(反例「堆叠无界的垂直滚动容器」)—— 前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链
36
+ - [ ] **结果集页面必须声明五层模型字段,无结果集页面只声明 `pageType`**(§1.8、canvas-model.md(06 · D-1))—— `pageType` 已收进类型(`ApplicationPageLayoutContainer` 必填,缺了 tsc 报错);其余四个字段在契约里仍是可选的,「用了本层组件就必须一并声明」同样是条件式必填
37
+ - [ ] **业务页面不得直接使用 Foundation `Button`**(Button / SystemButton 契约、反例「业务页面用 Foundation Button」)—— `forbid-element` 的 `match.element` 被 schema 限定为小写原生标签名,「不得使用本库自己的某个导出」是另一种形态,schema 阶段 3 已定稿。原生 `<button>` 的 autofix 已改写为 `SystemButton`
37
38
  - [ ] **产品 UI 文案里不得出现 Emoji**(02 §8)—— 文案约束,同 mock 占位符那条。生成器对本包 `handwritten/*.md` 与 `@moheng-design/ui` 的契约 JSDoc 查 Emoji,管不到消费方代码
38
39
  - [ ] **`SearchField` 不得逐字实时搜索**(反例「逐字实时搜索」)—— 判定是 `onChange` 回调体内有没有发起搜索,跨函数体的语义判定。规则只拦得住原生 `<input type="search">`
40
+ - [ ] **消费方代码不得读 `--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` 档因此为空
41
+ - [ ] **条件式必填: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 本轮不改
39
42
 
40
43
  ## 产出格式
41
44
 
@@ -7,7 +7,7 @@ description: 升级项目里的 @moheng-design/ui 版本时加载。先看契约
7
7
 
8
8
  # 版本升级
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
12
  ## 差异由契约算
13
13
 
@@ -1,7 +1,7 @@
1
1
  [
2
2
  {
3
3
  "constraint": "`iconOnly` 为真则 `aria-label` 必填",
4
- "source": "Button 契约",
4
+ "source": "Button / SystemButton 契约",
5
5
  "why": "「prop A 为真则 prop B 必填」五类 kind 一类都表达不了,而 schema 阶段 3 已定稿,不得为一条规则改动"
6
6
  },
7
7
  {
@@ -35,14 +35,19 @@
35
35
  "why": "文案约束,同 mock 占位符那条"
36
36
  },
37
37
  {
38
- "constraint": "`ScrollArea` 必须给高度、不得嵌套",
38
+ "constraint": "`ScrollArea` 必须给高度、不得嵌套(看板外层横向、列内纵向是登记例外,07 · C-14)",
39
39
  "source": "反例「堆叠无界的垂直滚动容器」",
40
40
  "why": "前半是条件式必填(同 `iconOnly` 那条),后半要看祖先链"
41
41
  },
42
42
  {
43
- "constraint": "Application Module 组件必须声明五层模型字段",
44
- "source": "§1.8、canvas-model.md",
45
- "why": "契约里五个字段都是可选的 —— 缺了 tsc 不说,而「用了本层组件就必须一并声明」同样是条件式必填"
43
+ "constraint": "结果集页面必须声明五层模型字段,无结果集页面只声明 `pageType`",
44
+ "source": "§1.8、canvas-model.md(06 · D-1)",
45
+ "why": "`pageType` 已收进类型(`ApplicationPageLayoutContainer` 必填,缺了 tsc 报错);其余四个字段在契约里仍是可选的,「用了本层组件就必须一并声明」同样是条件式必填"
46
+ },
47
+ {
48
+ "constraint": "业务页面不得直接使用 Foundation `Button`",
49
+ "source": "Button / SystemButton 契约、反例「业务页面用 Foundation Button」",
50
+ "why": "`forbid-element` 的 `match.element` 被 schema 限定为小写原生标签名,「不得使用本库自己的某个导出」是另一种形态,schema 阶段 3 已定稿。原生 `<button>` 的 autofix 已改写为 `SystemButton`"
46
51
  },
47
52
  {
48
53
  "constraint": "产品 UI 文案里不得出现 Emoji",
@@ -53,5 +58,15 @@
53
58
  "constraint": "`SearchField` 不得逐字实时搜索",
54
59
  "source": "反例「逐字实时搜索」",
55
60
  "why": "判定是 `onChange` 回调体内有没有发起搜索,跨函数体的语义判定。规则只拦得住原生 `<input type=\"search\">`"
61
+ },
62
+ {
63
+ "constraint": "消费方代码不得读 `--ds-*`;例外只有换肤入口 `--ds-color-theme-primary`(覆盖)与焦点环几何 `--ds-focus-ring-width` / `--ds-focus-ring-offset`(只读,这两个是唯一可跨层读取的 `--ds-*`)",
64
+ "source": "通则「token 的两层边界」、07 · C-1(06 · D-5)",
65
+ "why": "断言 6 只扫 `@moheng-design/ui` 自身的 `src/`;能作用于消费方 CSS 的只有 `forbid-value`,其 `scope` 被 schema 锁死为 `internal`(§7.3),stylelint 的 `consumer` 档因此为空"
66
+ },
67
+ {
68
+ "constraint": "条件式必填:prop A 出现(或取某值)则 prop B 必填。例:`appliedTags` 的 `label` 传 JSX 时必须给 `labelText`;`<ApplicationDataDisplay state=\"empty\">` 必须给 `empty`;`businessView` 与 `onBusinessViewChange` 必须成对提供。各组件约定里「必须成对提供」「必须同时提供」一类写法均属此类",
69
+ "source": "05 §3、07 · C-3",
70
+ "why": "五类 kind 一类都表达不了。schema 加 `requires-with`(prop A 出现则 prop B 必填)留到第二个真实项目再评估,阶段 3 已定稿的 schema 本轮不改"
56
71
  }
57
72
  ]
@@ -13,18 +13,33 @@
13
13
 
14
14
  ```jsx
15
15
  // 不要这样写
16
- <Button variant="icon"><Icon name="rotate-cw" size={16} /></Button>
17
- <Button size="icon"><Icon name="rotate-cw" size={16} /></Button>
16
+ <SystemButton intent="icon"><Icon name="refresh-cw" size={16} /></SystemButton>
17
+ <SystemButton size="icon"><Icon name="refresh-cw" size={16} /></SystemButton>
18
18
 
19
- // 要这样写 —— 尺寸与形状是两根轴,iconOnly 控制形状
20
- <Button iconOnly aria-label="刷新"><Icon name="rotate-cw" size={16} /></Button>
19
+ // 要这样写 —— 意图与形状是两根轴,iconOnly 控制形状
20
+ <SystemButton intent="quiet" iconOnly aria-label="刷新"><Icon name="refresh-cw" size={16} /></SystemButton>
21
21
  ```
22
22
 
23
- `variant` 只有 `primary` / `secondary` / `outline` / `ghost` / `destructive` / `link`;
24
- `size` 只有 `xs` / `sm` / `default` / `lg`。**shadcn 习惯的 `size="icon"` 在本库不存在。**
23
+ `SystemButton` 的 `intent` 只有 `primary` / `secondary` / `quiet` / `link` / `destructive`;
24
+ `size` 只有 `default` / `compact` / `sm`。**shadcn 习惯的 `size="icon"` 在本库不存在**,
25
+ Foundation `Button` 同样只用 `iconOnly` 表达等宽图标按钮。
25
26
 
26
27
  `iconOnly` 为 true 时按钮没有可见文字,**必须**另给 `aria-label`。
27
28
 
29
+ ### 业务页面用 Foundation Button
30
+
31
+ ```jsx
32
+ // 不要这样写 —— Button 只供库内组件使用
33
+ <Button variant="primary" onClick={create}>新建</Button>
34
+
35
+ // 要这样写 —— 业务页面的按钮一律用 SystemButton
36
+ <SystemButton intent="primary" onClick={create}>新建</SystemButton>
37
+ ```
38
+
39
+ `SystemButton` 是整个产品的默认动作按钮,承载应用意图、`loading` 与产品状态;
40
+ 改一次应用强调色,全部 `SystemButton` 同时换肤。lint 的 `no-native-button` 把原生
41
+ `<button>` 改写成的也是它。
42
+
28
43
  ### 内联 style
29
44
 
30
45
  ```jsx
@@ -45,10 +60,10 @@
45
60
  ```jsx
46
61
  // 不要这样写
47
62
  const [hover, setHover] = useState(false)
48
- <Button onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
63
+ <SystemButton onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
49
64
 
50
65
  // 要这样写 —— 什么都不写,hover 已由 CSS 伪类实现
51
- <Button>提交</Button>
66
+ <SystemButton>提交</SystemButton>
52
67
  ```
53
68
 
54
69
  `useState` 会让组件强制成为 client component。状态一律用 CSS 伪类
@@ -60,7 +75,7 @@ const [hover, setHover] = useState(false)
60
75
  /* 不要这样写 —— 只会改到引用它的那部分组件 */
61
76
  :root { --application-accent: #16a34a; }
62
77
 
63
- /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上一律无效 */
78
+ /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上半生效 */
64
79
  <div className="dark">…</div>
65
80
 
66
81
  /* 要这样写 */
@@ -69,7 +84,8 @@ const [hover, setHover] = useState(false)
69
84
 
70
85
  `--ds-color-theme-primary` 是换肤契约的唯一入口。
71
86
  换肤与 `.dark` **必须挂在 `<html>` 上** —— `var()` 代换在声明所在元素就完成了,
72
- 挂在 `<body>` 或容器 div 上无效(已实测)。系统内不存在「局部暗色区块」这种用法。
87
+ 挂在 `<body>` 或容器 div 上是半生效(已实测):直接读 `--ds-*` 的部件变了,读 `--application-*`
88
+ 的部件不变。半生效比无效更糟 —— 看上去像是生效了。系统内不存在「局部暗色区块」这种用法。
73
89
 
74
90
  ### 手写表格结构
75
91
 
@@ -113,10 +129,10 @@ const [hover, setHover] = useState(false)
113
129
  ```jsx
114
130
  // 不要这样写
115
131
  import { Button } from '@/components/ui/button'
116
- import { Button } from '@moheng-design/ui/dist/components/foundation/actions/Button.js'
132
+ import { SystemButton } from '@moheng-design/ui/dist/components/application-atomic/SystemButton.js'
117
133
 
118
134
  // 要这样写
119
- import { Button } from '@moheng-design/ui'
135
+ import { SystemButton } from '@moheng-design/ui'
120
136
  ```
121
137
 
122
138
  `@/components/ui/` 目录通常是 `npx shadcn add` 生成的第二套组件源码,
@@ -129,10 +145,10 @@ import { Button } from '@moheng-design/ui'
129
145
 
130
146
  ```jsx
131
147
  // 不要这样写 —— 组件渲染出来是无样式的裸结构
132
- import { Button } from '@moheng-design/ui'
148
+ import { SystemButton } from '@moheng-design/ui'
133
149
 
134
150
  // 要这样写 —— 应用入口引一次即可
135
- import { Button } from '@moheng-design/ui'
151
+ import { SystemButton } from '@moheng-design/ui'
136
152
  import '@moheng-design/ui/styles.css'
137
153
  ```
138
154
 
@@ -143,15 +159,15 @@ import '@moheng-design/ui/styles.css'
143
159
 
144
160
  ```jsx
145
161
  // 不要这样写
146
- <Button>视图设置</Button>
162
+ <SystemButton>视图设置</SystemButton>
147
163
 
148
164
  // 要这样写 —— 按当前呈现方式命名
149
- <Button>列设置</Button> {/* DataTable */}
150
- <Button>看板设置</Button> {/* KanbanBoard */}
165
+ <SystemButton>列设置</SystemButton> {/* DataTable */}
166
+ <SystemButton>看板设置</SystemButton> {/* KanbanBoard */}
151
167
  ```
152
168
 
153
169
  呈现设置是一个*概念*,不是一个按钮名。按钮必须按当前呈现方式命名:
154
- `列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
170
+ `列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
155
171
 
156
172
  ### 六种数据状态共用一句话
157
173
 
@@ -162,9 +178,11 @@ import '@moheng-design/ui/styles.css'
162
178
  // 要这样写 —— 成因不同,用户的下一步动作也不同
163
179
  <ApplicationDataDisplay
164
180
  state={state}
165
- empty={<Empty title="当前视角下无数据" description="切换业务视图或调整筛选条件" />}
166
- noPermission={<Empty title="没有查看权限" description="请联系管理员申请" />}
167
- error={<Empty title="加载失败" description="请稍后重试" />}
181
+ empty={filtered
182
+ ? <Empty title="没有符合当前筛选条件的记录" action={<SystemButton onClick={resetFilters}>清除筛选</SystemButton>} />
183
+ : <Empty title="当前视图下还没有记录" action={<SystemButton onClick={create}>新建</SystemButton>} />}
184
+ noPermission={<Empty title="无权查看本模块" description="联系本模块管理员开通" />}
185
+ error={<Empty title="加载失败" description="服务暂时不可用,可重试" />}
168
186
  />
169
187
  ```
170
188
 
@@ -183,7 +201,7 @@ Loading / Empty / Error / No Permission / Not Found / Partial Failure
183
201
  <ScrollArea horizontal>…</ScrollArea>
184
202
  ```
185
203
 
186
- Content Canvas 是页面唯一的主垂直滚动权持有者。
204
+ 页面级纵向滚动持有者每页只有一个:结果集页面是 `ApplicationDataDisplay` 的主体,其余页面是 Content Canvas。
187
205
  `ScrollArea` 与 `MessageScroller` 只用于正交方向或局部有界的溢出,且必须给出高度。
188
206
 
189
207
  ### 用 Emoji 或系统字符代替图标