@moheng-design/ui-skill 3.1.0 → 3.2.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.
@@ -688,12 +688,13 @@
688
688
  "settings",
689
689
  "shield-check",
690
690
  "sliders-horizontal",
691
+ "table-properties",
691
692
  "trash-2",
692
693
  "triangle-alert",
693
694
  "upload",
694
695
  "x"
695
696
  ],
696
- "message": "<Icon> 的 name 取值须为 'activity' | 'arrow-down' | 'arrow-up' | 'calendar' | 'check' | 'chevron-down' | 'chevron-left' | 'chevron-right' | 'chevron-up' | 'chevrons-left' | 'chevrons-right' | 'circle-alert' | 'circle-check' | 'circle-check-big' | 'columns-2' | 'download' | 'ellipsis' | 'eye' | 'file-text' | 'funnel' | 'info' | 'kanban' | 'layout-grid' | 'list' | 'message-square' | 'minus' | 'paperclip' | 'pencil' | 'plus' | 'refresh-cw' | 'search' | 'settings' | 'shield-check' | 'sliders-horizontal' | 'trash-2' | 'triangle-alert' | 'upload' | 'x' 之一",
697
+ "message": "<Icon> 的 name 取值须为 'activity' | 'arrow-down' | 'arrow-up' | 'calendar' | 'check' | 'chevron-down' | 'chevron-left' | 'chevron-right' | 'chevron-up' | 'chevrons-left' | 'chevrons-right' | 'circle-alert' | 'circle-check' | 'circle-check-big' | 'columns-2' | 'download' | 'ellipsis' | 'eye' | 'file-text' | 'funnel' | 'info' | 'kanban' | 'layout-grid' | 'list' | 'message-square' | 'minus' | 'paperclip' | 'pencil' | 'plus' | 'refresh-cw' | 'search' | 'settings' | 'shield-check' | 'sliders-horizontal' | 'table-properties' | 'trash-2' | 'triangle-alert' | 'upload' | 'x' 之一",
697
698
  "rationale": "取值与顺序取自契约 contracts/foundation/icon/icon.ts,不得在别处另立一份。"
698
699
  },
699
700
  {
@@ -764,11 +765,12 @@
764
765
  "outline",
765
766
  "ghost",
766
767
  "ghost-accent",
768
+ "row-action",
767
769
  "destructive",
768
770
  "destructive-outline",
769
771
  "link"
770
772
  ],
771
- "message": "<Button> 的 variant 取值须为 'primary' | 'secondary' | 'outline' | 'ghost' | 'ghost-accent' | 'destructive' | 'destructive-outline' | 'link' 之一",
773
+ "message": "<Button> 的 variant 取值须为 'primary' | 'secondary' | 'outline' | 'ghost' | 'ghost-accent' | 'row-action' | 'destructive' | 'destructive-outline' | 'link' 之一",
772
774
  "rationale": "取值与顺序取自契约 contracts/foundation/actions/button.ts,不得在别处另立一份。"
773
775
  },
774
776
  {
@@ -1734,6 +1736,7 @@
1734
1736
  "component": "Badge"
1735
1737
  },
1736
1738
  "allowed": [
1739
+ "size",
1737
1740
  "tone",
1738
1741
  "variant",
1739
1742
  "children",
@@ -1742,9 +1745,30 @@
1742
1745
  "className",
1743
1746
  "style"
1744
1747
  ],
1745
- "message": "<Badge> 不接受该 prop。已声明的 props:tone、variant、children。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
1748
+ "message": "<Badge> 不接受该 prop。已声明的 props:size、tone、variant、children。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
1746
1749
  "rationale": "本条的 allowed 只列自有 props 与 React 保留项。继承自 HTMLAttributes<HTMLSpanElement> 的属性由 plugin-data.js 的 nativeBases 表按基类共享放行,直接消费 rules.json 的工具须同时读那张表。契约:contracts/foundation/data-content-layout/badge.ts"
1747
1750
  },
1751
+ {
1752
+ "id": "prop-enum-badge-size",
1753
+ "kind": "prop-enum",
1754
+ "generated": true,
1755
+ "scope": "both",
1756
+ "severity": "warn",
1757
+ "targets": [
1758
+ "js"
1759
+ ],
1760
+ "match": {
1761
+ "component": "Badge",
1762
+ "prop": "size"
1763
+ },
1764
+ "allowed": [
1765
+ "sm",
1766
+ "default",
1767
+ "lg"
1768
+ ],
1769
+ "message": "<Badge> 的 size 取值须为 'sm' | 'default' | 'lg' 之一",
1770
+ "rationale": "取值与顺序取自契约 contracts/foundation/data-content-layout/badge.ts,不得在别处另立一份。"
1771
+ },
1748
1772
  {
1749
1773
  "id": "prop-enum-badge-tone",
1750
1774
  "kind": "prop-enum",
@@ -2882,6 +2906,32 @@
2882
2906
  "message": "<ApplicationFilterMenu> 不接受该 prop。已声明的 props:label、options、value、defaultValue、onValueChange、multiple、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
2883
2907
  "rationale": "本条的 allowed 只列自有 props 与 React 保留项。继承自 HTMLAttributes<HTMLDivElement> 的属性由 plugin-data.js 的 nativeBases 表按基类共享放行,直接消费 rules.json 的工具须同时读那张表。契约:contracts/application-atomic/application-filter-menu.ts"
2884
2908
  },
2909
+ {
2910
+ "id": "props-whitelist-application-user-profile-card",
2911
+ "kind": "props-whitelist",
2912
+ "generated": true,
2913
+ "scope": "both",
2914
+ "severity": "warn",
2915
+ "targets": [
2916
+ "js"
2917
+ ],
2918
+ "match": {
2919
+ "component": "ApplicationUserProfileCard"
2920
+ },
2921
+ "allowed": [
2922
+ "name",
2923
+ "avatarSrc",
2924
+ "badge",
2925
+ "description",
2926
+ "children",
2927
+ "key",
2928
+ "ref",
2929
+ "className",
2930
+ "style"
2931
+ ],
2932
+ "message": "<ApplicationUserProfileCard> 不接受该 prop。已声明的 props:name、avatarSrc、badge、description、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
2933
+ "rationale": "本条的 allowed 只列自有 props 与 React 保留项。继承自 HTMLAttributes<HTMLDivElement> 的属性由 plugin-data.js 的 nativeBases 表按基类共享放行,直接消费 rules.json 的工具须同时读那张表。契约:contracts/application-atomic/application-user-profile-card.ts"
2934
+ },
2885
2935
  {
2886
2936
  "id": "props-whitelist-list-selection-checkbox",
2887
2937
  "kind": "props-whitelist",
@@ -3083,11 +3133,12 @@
3083
3133
  "secondary",
3084
3134
  "quiet",
3085
3135
  "quiet-accent",
3136
+ "row-action",
3086
3137
  "link",
3087
3138
  "destructive",
3088
3139
  "destructive-outline"
3089
3140
  ],
3090
- "message": "<SystemButton> 的 intent 取值须为 'primary' | 'secondary' | 'quiet' | 'quiet-accent' | 'link' | 'destructive' | 'destructive-outline' 之一",
3141
+ "message": "<SystemButton> 的 intent 取值须为 'primary' | 'secondary' | 'quiet' | 'quiet-accent' | 'row-action' | 'link' | 'destructive' | 'destructive-outline' 之一",
3091
3142
  "rationale": "取值与顺序取自契约 contracts/application-atomic/system-button.ts,不得在别处另立一份。"
3092
3143
  },
3093
3144
  {
@@ -3215,12 +3266,13 @@
3215
3266
  "settings",
3216
3267
  "shield-check",
3217
3268
  "sliders-horizontal",
3269
+ "table-properties",
3218
3270
  "trash-2",
3219
3271
  "triangle-alert",
3220
3272
  "upload",
3221
3273
  "x"
3222
3274
  ],
3223
- "message": "<ApplicationPrimaryNavigation> 的 appGlyph 取值须为 'activity' | 'arrow-down' | 'arrow-up' | 'calendar' | 'check' | 'chevron-down' | 'chevron-left' | 'chevron-right' | 'chevron-up' | 'chevrons-left' | 'chevrons-right' | 'circle-alert' | 'circle-check' | 'circle-check-big' | 'columns-2' | 'download' | 'ellipsis' | 'eye' | 'file-text' | 'funnel' | 'info' | 'kanban' | 'layout-grid' | 'list' | 'message-square' | 'minus' | 'paperclip' | 'pencil' | 'plus' | 'refresh-cw' | 'search' | 'settings' | 'shield-check' | 'sliders-horizontal' | 'trash-2' | 'triangle-alert' | 'upload' | 'x' 之一",
3275
+ "message": "<ApplicationPrimaryNavigation> 的 appGlyph 取值须为 'activity' | 'arrow-down' | 'arrow-up' | 'calendar' | 'check' | 'chevron-down' | 'chevron-left' | 'chevron-right' | 'chevron-up' | 'chevrons-left' | 'chevrons-right' | 'circle-alert' | 'circle-check' | 'circle-check-big' | 'columns-2' | 'download' | 'ellipsis' | 'eye' | 'file-text' | 'funnel' | 'info' | 'kanban' | 'layout-grid' | 'list' | 'message-square' | 'minus' | 'paperclip' | 'pencil' | 'plus' | 'refresh-cw' | 'search' | 'settings' | 'shield-check' | 'sliders-horizontal' | 'table-properties' | 'trash-2' | 'triangle-alert' | 'upload' | 'x' 之一",
3224
3276
  "rationale": "取值与顺序取自契约 contracts/application-module/navigation/application-primary-navigation.ts,不得在别处另立一份。"
3225
3277
  },
3226
3278
  {
@@ -3446,6 +3498,7 @@
3446
3498
  "component": "ApplicationMetricStrip"
3447
3499
  },
3448
3500
  "allowed": [
3501
+ "surface",
3449
3502
  "metrics",
3450
3503
  "columns",
3451
3504
  "children",
@@ -3456,9 +3509,29 @@
3456
3509
  "className",
3457
3510
  "style"
3458
3511
  ],
3459
- "message": "<ApplicationMetricStrip> 不接受该 prop。已声明的 props:metrics、columns、children、state、error。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
3512
+ "message": "<ApplicationMetricStrip> 不接受该 prop。已声明的 props:surface、metrics、columns、children、state、error。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
3460
3513
  "rationale": "本条的 allowed 只列自有 props 与 React 保留项。继承自 HTMLAttributes<HTMLDivElement> 的属性由 plugin-data.js 的 nativeBases 表按基类共享放行,直接消费 rules.json 的工具须同时读那张表。契约:contracts/application-module/statistics/metrics.ts"
3461
3514
  },
3515
+ {
3516
+ "id": "prop-enum-application-metric-strip-surface",
3517
+ "kind": "prop-enum",
3518
+ "generated": true,
3519
+ "scope": "both",
3520
+ "severity": "warn",
3521
+ "targets": [
3522
+ "js"
3523
+ ],
3524
+ "match": {
3525
+ "component": "ApplicationMetricStrip",
3526
+ "prop": "surface"
3527
+ },
3528
+ "allowed": [
3529
+ "plain",
3530
+ "card"
3531
+ ],
3532
+ "message": "<ApplicationMetricStrip> 的 surface 取值须为 'plain' | 'card' 之一",
3533
+ "rationale": "取值与顺序取自契约 contracts/application-module/statistics/metrics.ts,不得在别处另立一份。"
3534
+ },
3462
3535
  {
3463
3536
  "id": "prop-enum-application-metric-strip-state",
3464
3537
  "kind": "prop-enum",
@@ -3652,6 +3725,7 @@
3652
3725
  "component": "ApplicationPageHeader"
3653
3726
  },
3654
3727
  "allowed": [
3728
+ "layout",
3655
3729
  "title",
3656
3730
  "subtitle",
3657
3731
  "dataStatus",
@@ -3671,9 +3745,29 @@
3671
3745
  "style",
3672
3746
  "children"
3673
3747
  ],
3674
- "message": "<ApplicationPageHeader> 不接受该 prop。已声明的 props:title、subtitle、dataStatus、updatedAt、onRefresh、onBack、backLabel、taskStatus、actions、pageModes、pageMode、onPageModeChange、breadcrumb。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
3748
+ "message": "<ApplicationPageHeader> 不接受该 prop。已声明的 props:layout、title、subtitle、dataStatus、updatedAt、onRefresh、onBack、backLabel、taskStatus、actions、pageModes、pageMode、onPageModeChange、breadcrumb。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素",
3675
3749
  "rationale": "本条的 allowed 只列自有 props 与 React 保留项。继承自 HTMLAttributes<HTMLDivElement> 的属性由 plugin-data.js 的 nativeBases 表按基类共享放行,直接消费 rules.json 的工具须同时读那张表。契约:contracts/application-module/content/application-page-header.ts"
3676
3750
  },
3751
+ {
3752
+ "id": "prop-enum-application-page-header-layout",
3753
+ "kind": "prop-enum",
3754
+ "generated": true,
3755
+ "scope": "both",
3756
+ "severity": "warn",
3757
+ "targets": [
3758
+ "js"
3759
+ ],
3760
+ "match": {
3761
+ "component": "ApplicationPageHeader",
3762
+ "prop": "layout"
3763
+ },
3764
+ "allowed": [
3765
+ "horizontal",
3766
+ "stacked"
3767
+ ],
3768
+ "message": "<ApplicationPageHeader> 的 layout 取值须为 'horizontal' | 'stacked' 之一",
3769
+ "rationale": "取值与顺序取自契约 contracts/application-module/content/application-page-header.ts,不得在别处另立一份。"
3770
+ },
3677
3771
  {
3678
3772
  "id": "prop-enum-application-page-header-data-status",
3679
3773
  "kind": "prop-enum",
@@ -7,7 +7,7 @@ description: 评估一个存量项目离 @moheng-design/ui 规范有多远、该
7
7
 
8
8
  # 存量项目合规审计
9
9
 
10
- 适用版本:v3.1.0
10
+ 适用版本:v3.2.0
11
11
 
12
12
  ## 数字由工具算,本技能只解释
13
13
 
@@ -7,7 +7,7 @@ description: 新项目启动、要基于 @moheng-design/ui 定技术栈与搭建
7
7
 
8
8
  # 新项目技术路径
9
9
 
10
- 适用版本:v3.1.0
10
+ 适用版本:v3.2.0
11
11
 
12
12
  ## 先读项目规范,不替项目选型
13
13
 
@@ -91,7 +91,7 @@ Next.js App Router 是本库实测过的环境:只有持有交互状态的组
91
91
  7. **搭第一个页面。** 转 `moheng-ui-page`:先判定有没有结果集、定下五层 Canvas 模型里该写的字段,再选组件。
92
92
  验证:页面通过第 5 步的 lint,且零报错。
93
93
 
94
- 当前 165 条规则中,带 autofix 的有:`no-native-button`、`no-native-input`、`no-native-textarea`、`no-native-label`、`no-native-hr`、`no-native-progress`、`no-native-kbd`。
94
+ 当前 169 条规则中,带 autofix 的有:`no-native-button`、`no-native-input`、`no-native-textarea`、`no-native-label`、`no-native-hr`、`no-native-progress`、`no-native-kbd`。
95
95
  新项目不应依赖 autofix —— 一次写对是主技能 `moheng-ui` 的职责,autofix 是存量迁移的工具。
96
96
 
97
97
  ## 产出:写进项目的 agent 指导文件
@@ -7,7 +7,7 @@ description: 用 @moheng-design/ui 搭系统的过程中撞到组件缺失、pro
7
7
 
8
8
  # 问题收集与回流
9
9
 
10
- 适用版本:v3.1.0
10
+ 适用版本:v3.2.0
11
11
 
12
12
  ## 为什么要结构化
13
13
 
@@ -57,7 +57,7 @@ npx @moheng-design/ui-skill feedback
57
57
  ```markdown
58
58
  ### <反馈类型> · <组件或 token 名>
59
59
 
60
- - 版本:@moheng-design/ui v3.1.0
60
+ - 版本:@moheng-design/ui v3.2.0
61
61
  - 位置:<文件:行>
62
62
  - 复现:<最小代码>
63
63
  - 期望:<一句话>
@@ -7,7 +7,7 @@ description: 用 @moheng-design/ui 的 Application Module 层搭一个完整页
7
7
 
8
8
  # 页面骨架
9
9
 
10
- 适用版本:v3.1.0
10
+ 适用版本:v3.2.0
11
11
 
12
12
  ## 先定字段,再碰组件
13
13
 
@@ -7,7 +7,7 @@ description: 审查一段用 @moheng-design/ui 写的改动(PR、diff、单个
7
7
 
8
8
  # @moheng-design/ui 审查清单
9
9
 
10
- 适用版本:v3.1.0
10
+ 适用版本:v3.2.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
- 零报错不等于合规。165 条规则覆盖的是「用错组件库」与「发明不存在的 prop」,
20
+ 零报错不等于合规。169 条规则覆盖的是「用错组件库」与「发明不存在的 prop」,
21
21
  下面这些它一条都看不见。
22
22
 
23
23
  ## 逐条人工核对
@@ -7,7 +7,7 @@ description: 升级项目里的 @moheng-design/ui 版本时加载。先看契约
7
7
 
8
8
  # 版本升级
9
9
 
10
- 适用版本:v3.1.0
10
+ 适用版本:v3.2.0
11
11
 
12
12
  ## 差异由契约算
13
13
 
@@ -127,7 +127,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
127
127
 
128
128
  **用途。** Foundation 按钮,是按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。
129
129
 
130
- **何时使用。** 本组件只供库内组件使用。业务页面的按钮一律用 `SystemButton`,不存在降级到本组件的情形。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、12px 圆角、32px 默认高度;等宽图标按钮为 12 圆角方形,系统内没有独立的 pill 或 circle token。
130
+ **何时使用。** 本组件只供库内组件使用。业务页面的按钮一律用 `SystemButton`,不存在降级到本组件的情形。已登记契约为 14/20 字号、10px 行内内边距、2px 图标间隙、12px 圆角、32px 默认高度;等宽图标按钮为 12 圆角方形,系统内没有独立的 pill 或 circle token。
131
131
 
132
132
  **何时改用其他组件。**
133
133
 
@@ -138,7 +138,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
138
138
  - 页面区域内的内容分节切换改用 `Tabs`,不得用一排 ghost 按钮模拟。
139
139
  - 原生 `<button>` 一律改用本组件(`mappings.json` · `no-native-button`)。
140
140
 
141
- **组合约定。** `size` 与 `iconOnly` 是两根正交的轴(04 · A1):`size` 映射高度 24 / 28 / 32 / 40px,`iconOnly` 把宽度收敛为与高度相等并把行内内边距归零,两者可任意组合。`iconOnly` 为 true 时必须提供 `aria-label`,因为按钮没有可见文字。`children` 是必填的 —— 等宽图标按钮的 `children` 就是那个 `Icon` 元素。一个动作组内至多一个 `variant="primary"`;上下文区的页面动作组由 `ApplicationPageHeader` 的 `actions` 承载,同样至多一个。外边距一律由容器负责:动作对交给 `ButtonGroup`(未拼接态以 8px 分隔),页面动作组交给 `ApplicationPageHeader`,批量动作交给 `ListBatchActionBar` 的 `actions`,按钮自身不得带 margin。图标与文字的 4px 间隙由按钮的 gap 提供,不得再包一层带间距的容器。破坏性动作用 `variant="destructive"`,且必须经 `AlertDialog` 确认,批量场景的标题中写明受影响对象的数量。各变体的默认、移入、按下、禁用四态逐个对齐 GAP Design kit 按钮组件集 24:2110:`primary` 移入变浅、按下变深、禁用为浅主色底白字,三档从换肤主色 `--ds-color-theme-primary` 派生,换肤时随之变化;`secondary` 移入只把文字变为主色,按下为主色 15% 底、主色描边与主色字,禁用只把文字退为文字3;`ghost` 移入中性 6% 底、按下中性 25% 底;`ghost-accent` 透明底、主色字,移入主色 6% 底、按下主色 15% 底,用于行内动作(kit「类型=幽灵主要」)。`outline`、`destructive`、`link` 在 kit 里没有对应类型。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`aria-disabled="true"` 与原生 `disabled` 同一套禁用外观但保持可聚焦,本组件不拦截事件,阻断动作由设置它的一方负责。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
141
+ **组合约定。** `size` 与 `iconOnly` 是两根正交的轴(04 · A1):`size` 映射高度 24 / 28 / 32 / 40px,`iconOnly` 把宽度收敛为与高度相等并把行内内边距归零,两者可任意组合。`iconOnly` 为 true 时必须提供 `aria-label`,因为按钮没有可见文字。`children` 是必填的 —— 等宽图标按钮的 `children` 就是那个 `Icon` 元素。一个动作组内至多一个 `variant="primary"`;上下文区的页面动作组由 `ApplicationPageHeader` 的 `actions` 承载,同样至多一个。外边距一律由容器负责:动作对交给 `ButtonGroup`(未拼接态以 8px 分隔),页面动作组交给 `ApplicationPageHeader`,批量动作交给 `ListBatchActionBar` 的 `actions`,按钮自身不得带 margin。图标与文字的 4px 间隙由按钮的 gap 提供,不得再包一层带间距的容器。破坏性动作用 `variant="destructive"`,且必须经 `AlertDialog` 确认,批量场景的标题中写明受影响对象的数量。各变体的默认、移入、按下、禁用四态逐个对齐 GAP Design kit 按钮组件集 24:2110:`primary` 移入变浅、按下变深、禁用为浅主色底白字,三档从换肤主色 `--ds-color-theme-primary` 派生,换肤时随之变化;`secondary` 移入只把文字变为主色,按下为主色 15% 底、主色描边与主色字,禁用只把文字退为文字3;`ghost` 移入中性 6% 底、按下中性 25% 底;`ghost-accent` 透明底、主色字,移入主色 6% 底、按下主色 15% 底,用于轻强调按钮;记录行动作使用 `row-action`。`outline`、`destructive`、`link` 在 kit 里没有对应类型。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`aria-disabled="true"` 与原生 `disabled` 同一套禁用外观但保持可聚焦,本组件不拦截事件,阻断动作由设置它的一方负责。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
142
142
 
143
143
  **禁止 / 使用边界。**
144
144
 
@@ -922,7 +922,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
922
922
  - 只是一组同构的目录行,无列对齐需求 —— 改用 `Item`。
923
923
  - 需要手写 `<table>` / `<tr>` / `<td>` —— 一律改用本组件,手写表格拿不到已登记的表头底色、行分隔线与列宽约定。
924
924
 
925
- **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`;它的可访问名是「选择」加标题列(首个 `priority: 'primary'` 的列,未声明取首列)单元格的内容。给了 `onRowClick` 的行可聚焦,Enter / 空格触发同一回调,行保留表格行语义、不改作按钮。行点击与按键忽略来自行内可交互元素(按钮、链接、勾选框、菜单等)的事件,`render` 里放这类控件时调用方不必再手动阻止冒泡。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。放进 `ApplicationDataDisplay` 时,表头排序是工具栏 `sort` 槽位(`Select`)的第二入口,`sort` 必须与工具栏取自同一份排序状态(07 · C-2)。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。单独使用时 `rows` 为空必须提供 `empty`,且应当传 `<Empty />`;放进 `ApplicationDataDisplay` 时不另设 `empty`,空结果由数据展示区的 `state="empty"` 与 `empty` 槽位承担(07 · C-6)。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。有设计稿时,每一列的 `width` 取设计稿的列宽:固定宽的列写数字,弹性列不写 `width`,由表格均分剩余宽度(固定表格布局,GAP Design kit「列表」的弹性列等分)—— 不得全部留空交给浏览器按内容分配。弹性列最窄 88px,容器不够分时表格转为在自身内部横向滚动。表头文字 14/20 medium 文字2。行内动作(「编辑 / 删除」)用 `SystemButton intent="quiet-accent"`(kit「类型=幽灵主要」,列表操作单元 123:5796)。单元格里放了按钮时,该单元格上下内边距自动收为 12,32 高的按钮落进 56 的行,不撑高行(kit「列表」类型=操作);调用方不得为此改用 `size="sm"` 或自写单元格样式。列数多、需要横向滚动时,末列「操作」写 `fixed: 'right'` 贴住右缘,首列标题列可写 `fixed: 'left'`;只允许首列声明 `left`、末列声明 `right`,每侧至多一列。附着在列表末尾的进行中状态(「识别中…」「正在加载更多」)经 `trailingRow` 渲染为一条横跨全部列的通栏行,与表体行同为最小高 56;`busy` 为 true 时文字取强调色并带扫光动效;`rows` 为空时它不渲染。
925
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`;它的可访问名是「选择」加标题列(首个 `priority: 'primary'` 的列,未声明取首列)单元格的内容。给了 `onRowClick` 的行可聚焦,Enter / 空格触发同一回调,行保留表格行语义、不改作按钮。行点击与按键忽略来自行内可交互元素(按钮、链接、勾选框、菜单等)的事件,`render` 里放这类控件时调用方不必再手动阻止冒泡。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。放进 `ApplicationDataDisplay` 时,表头排序是工具栏 `sort` 槽位(`Select`)的第二入口,`sort` 必须与工具栏取自同一份排序状态(07 · C-2)。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。单独使用时 `rows` 为空必须提供 `empty`,且应当传 `<Empty />`;放进 `ApplicationDataDisplay` 时不另设 `empty`,空结果由数据展示区的 `state="empty"` 与 `empty` 槽位承担(07 · C-6)。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。有设计稿时,每一列的 `width` 取设计稿的列宽:固定宽的列写数字,弹性列不写 `width`,由表格均分剩余宽度(固定表格布局,GAP Design kit「列表」的弹性列等分)—— 不得全部留空交给浏览器按内容分配。弹性列最窄 88px,容器不够分时表格转为在自身内部横向滚动。表头文字 14/20 medium 文字2。行内动作(「编辑 / 删除」)用 `SystemButton intent="row-action"`(kit「列表操作」303:2664)。文字操作与同一行的表体文字对齐,常规单行仍高 56;调用方不得为此改用 `size="sm"` 或自写单元格样式。列数多、需要横向滚动时,末列「操作」写 `fixed: 'right'` 贴住右缘,首列标题列可写 `fixed: 'left'`;只允许首列声明 `left`、末列声明 `right`,每侧至多一列。附着在列表末尾的进行中状态(「识别中…」「正在加载更多」)经 `trailingRow` 渲染为一条横跨全部列的通栏行,与表体行同为最小高 56;`busy` 为 true 时文字取强调色并带扫光动效;`rows` 为空时它不渲染。
926
926
 
927
927
  **禁止 / 使用边界。**
928
928
  - 禁止手写 `<tr>` / `<td>` 作为子元素传入 —— 本组件不接受复合子组件,列与行只能来自 `columns` 与 `rows`。
@@ -987,7 +987,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
987
987
  - 一级导航上的未读提示改用 `ApplicationPrimaryNavigation` 的 `actionBadges` 圆点;消息条目的未读态改用 `Message` 的 `unread`。
988
988
  - 键盘按键提示改用 `Kbd`,二者语义不同,不得互换。
989
989
 
990
- **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。tone 只在同一维度内含义唯一:同屏出现两个状态维度(如处理状态与风险等级)时,用 `variant` 区分维度 —— 一个维度用 `soft`(淡色实底),另一个用 `outline`(描边),两个维度可以各用到同一个 tone(07 · C-9);同一维度内的不同取值不得共用 tone。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`soft` 档的底色一律是 tone 语义色的 10% 透明(`neutral` 为文字色 6%),前景与描边取 tone 的语义色,`warning` 也不例外(GAP Design kit;此前 `warning` 前景取中性灰,已随警示色调深为 #ff7b00 改回同色系)。`children` 必须是 2–4 字裸名词短语。
990
+ **组合约定。** `size` 为 sm / default / lg(20 / 24 / 32 高),与 tone、variant 独立。`tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。tone 只在同一维度内含义唯一:同屏出现两个状态维度(如处理状态与风险等级)时,用 `variant` 区分维度 —— 一个维度用 `soft`(淡色实底),另一个用 `outline`(描边),两个维度可以各用到同一个 tone(07 · C-9);同一维度内的不同取值不得共用 tone。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`soft` 档的底色一律是 tone 语义色的 10% 透明(`neutral` 为文字色 6%),前景与描边取 tone 的语义色,`warning` 也不例外(GAP Design kit;此前 `warning` 前景取中性灰,已随警示色调深为 #ff7b00 改回同色系)。`children` 必须是 2–4 字裸名词短语。
991
991
 
992
992
  **禁止 / 使用边界。**
993
993
  - 不得用图表分类色表达状态 —— 分类色只编码分类。
@@ -1324,7 +1324,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1324
1324
 
1325
1325
  **用途。** 转瞬即逝的提示堆栈,用于确认某件事已经发生 —— 已保存、已导出、3 条已办结。
1326
1326
 
1327
- **何时使用。** 当结果是已完成的事实、用户无需据此采取任何行动时,该组件是默认选择。判据是单一的:如果用户错过了这条提示会有损失,它就不该是 toast。`title` 应是已完成事实的陈述。未指定 `duration` 时单条停留 5000ms,指针停在堆栈上时暂停计时。
1327
+ **何时使用。** 当结果是已完成的事实、用户无需据此采取任何行动时,该组件是默认选择。判据是单一的:如果用户错过了这条提示会有损失,它就不该是 toast。`title` 应是已完成事实的陈述。未指定 `duration` 时单条停留 5000ms,指针停在堆栈上或键盘焦点在提示内时暂停;两者都离开后按剩余时间继续计时。
1328
1328
 
1329
1329
  **何时改用其他组件。**
1330
1330
  - 用户必须读到并处理的失败改用 `Alert`,就地呈现在受影响区域顶部。
@@ -1545,7 +1545,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1545
1545
 
1546
1546
  **用途。** 整个产品的默认动作按钮,是 Foundation `Button` 之上只承载应用意图、loading 与产品状态的薄适配层。
1547
1547
 
1548
- **何时使用。** 业务页面中的每一个按钮都必须使用本组件,没有例外;Foundation `Button` 只供库内组件使用。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、12px 圆角全部来自 Foundation `Button`。删除类动作分两档:`intent="destructive-outline"`(白底、线条色描边、危险色文字;移入时描边变为危险色,按下时再加危险色 10% 底(GAP Design kit「按钮 / 类型=危险」三态))用于与次要按钮并排的删除,如表单里「删除此附件」;`intent="destructive"`(实心危险色)只用于 `AlertDialog` 里那个不可逆的最终确认,同一动作组内不得同时出现两档。记录级的行内动作(`Table` 操作列、`ApplicationRecordList` 行尾的「编辑 / 删除」)用 `intent="quiet-accent"`:透明底、主色字,移入主色 6% 底、按下主色 15% 底(GAP Design kit「按钮 / 类型=幽灵主要」,列表操作单元 123:5796);行内删除同样用它,危险提示交给删除前的 `AlertDialog`,kit 的行内没有红色删除。`intent="link"`(无内边距、带下划线)只留给句中或卡片页脚那种链接式动作。各意图的移入、按下、禁用态随 Foundation `Button` 对齐 kit 按钮组件集 24:2110,`primary` 的三态从换肤主色派生。
1548
+ **何时使用。** 业务页面中的每一个按钮都必须使用本组件,没有例外;Foundation `Button` 只供库内组件使用。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、12px 圆角全部来自 Foundation `Button`。删除类动作分两档:`intent="destructive-outline"`(白底、线条色描边、危险色文字;移入时描边变为危险色,按下时再加危险色 10% 底(GAP Design kit「按钮 / 类型=危险」三态))用于与次要按钮并排的删除,如表单里「删除此附件」;`intent="destructive"`(实心危险色)只用于 `AlertDialog` 里那个不可逆的最终确认,同一动作组内不得同时出现两档。记录级的行内动作(`Table` 操作列、`ApplicationRecordList` 行尾的「编辑 / 删除」)用 `intent="row-action"`:16/20 纯文字,移入、按下变色,无按钮底;行内删除同样用它,危险提示交给删除前的 `AlertDialog`,kit 的行内没有红色删除。`intent="link"`(无内边距、带下划线)只留给句中或卡片页脚那种链接式动作。各意图的移入、按下、禁用态随 Foundation `Button` 对齐 kit 按钮组件集 24:2110,`primary` 的三态从换肤主色派生。
1549
1549
 
1550
1550
  **何时改用其他组件。**
1551
1551
  - 一组相关按钮需要拼接为分段控件或间隔簇:外层用 `ButtonGroup`,组内仍是 `SystemButton`。
@@ -1645,7 +1645,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1645
1645
  - 跨应用(而非跨模块)跳转:改用 `TopNavigationPrimaryBar` 的 `onAppSwitch`,条目用 `SidebarAppLinkButton`。
1646
1646
  - 工作台的图标菜单栏:改用 `GlobalSidebar`;Content Canvas 内的通用垂直导航:改用 `Sidebar`。
1647
1647
 
1648
- **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。几何按 GAP Design kit「应用二级模块切换」:触发器 168×48(Compact 148×40)、内边距 4/12、没有图标块,模块名 16/20 medium,20px chevron 右对齐,右侧 0.5px 分隔线,悬停与展开时 6% 淡底;面板挂在触发器正下方,与触发器同宽 168(最窄 128),内边距 4、条目间隔 2,限高到视口底、自身滚动;条目 40 高、内边距 8/12、圆角 12,悬停取导航背景,当前模块为强调色 semibold 加 14px 对勾。几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 可选,kit 的模块条目不带图标,需要时走 `Icon`。键盘按 menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),↑ / ↓ / Home / End 在模块间移动;Esc、外部点击与 Tab 都经 `onOpenChange(false)` 收起,Esc 后焦点回到触发器 —— 调用方不得再自行监听 Esc 或外部点击。
1648
+ **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。几何按 GAP Design kit「应用二级模块切换」:触发器 168×48(Compact 148×40)、内边距 4/12、左侧 16px 模块图标,模块名 14/20 medium,16px chevron 右对齐,右侧 0.5px 分隔线,悬停与展开时 6% 淡底;面板挂在触发器正下方,与触发器同宽 168(最窄 128),内边距 4、条目间隔 2,限高到视口底、自身滚动;条目 40 高、内边距 8/12、圆角 12,悬停取导航背景,当前模块为强调色 semibold 加 14px 对勾。几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 可选,kit 的模块条目不带图标,需要时走 `Icon`。键盘按 menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),↑ / ↓ / Home / End 在模块间移动;Esc、外部点击与 Tab 都经 `onOpenChange(false)` 收起,Esc 后焦点回到触发器 —— 调用方不得再自行监听 Esc 或外部点击。
1649
1649
 
1650
1650
  **禁止 / 使用边界。**
1651
1651
  - 不得把触发器简化成一个小图标,也不得在窄屏下移除它。
@@ -1689,7 +1689,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1689
1689
  - 行内或表格单元中的状态标签:改用 `Badge`。
1690
1690
  - 承载业务内容而非数字的卡片:改用 `Card`。
1691
1691
 
1692
- **组合约定。** 本组件必须放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取卡片总数(`metrics` 条目数加 `children` 中的卡片数,条件渲染为 `null` / `false` 的不计入)、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。`Metric.description` 是数值下方一行 12/16 的口径说明(「2026 年 · 不含已冲红」),只写统计口径,不写趋势或操作提示;有设计稿时照稿给出,同一区内要么都写要么都不写,否则等高的卡片里文字基线不齐。指标壳不是卡片:无边框、无底色、无内边距,直接落在页面底色上,高 76px;标签 12/16、数值 32/32 semibold、说明 12/16 三行之间各 6(GAP Design kit「字段/竖/统计」)。指标数据在途或失败时用 `state` 表达,取值只有 `ready` / `loading` / `error` 三种:`loading` 由组件渲染与指标卡同壳同高的骨架(张数同 `columns` 的缺省算法,无卡片时为 4),调用方不得自拼骨架卡;`error` 渲染一张横跨整行的失败卡,内容经 `error` 传入,应说明失败原因并提供「重试」,不传时显示内置的「指标加载失败」。两种状态下 `metrics` 与 `children` 都不渲染;读屏经组件内置的状态播报获知「指标加载中」/「指标加载失败」。
1692
+ **组合约定。** 所有页面与抽屉均可使用;在标准页面布局中放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取卡片总数(`metrics` 条目数加 `children` 中的卡片数,条件渲染为 `null` / `false` 的不计入)、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。`Metric.description` 是数值下方一行 12/16 的口径说明(「2026 年 · 不含已冲红」),只写统计口径,不写趋势或操作提示;有设计稿时照稿给出,同一区内要么都写要么都不写,否则等高的卡片里文字基线不齐。`surface="card"` 为每项添加卡片表面、12px 内边距和圆角;默认 `plain`:无边框、无底色、无内边距,直接落在页面底色上,高 76px;标签 12/16、数值 32/32 semibold、说明 12/16 三行之间各 6(GAP Design kit「字段/竖/统计」)。指标数据在途或失败时用 `state` 表达,取值只有 `ready` / `loading` / `error` 三种:`loading` 由组件渲染与指标卡同壳同高的骨架(张数同 `columns` 的缺省算法,无卡片时为 4),调用方不得自拼骨架卡;`error` 渲染一张横跨整行的失败卡,内容经 `error` 传入,应说明失败原因并提供「重试」,不传时显示内置的「指标加载失败」。两种状态下 `metrics` 与 `children` 都不渲染;读屏经组件内置的状态播报获知「指标加载中」/「指标加载失败」。
1693
1693
 
1694
1694
  **禁止 / 使用边界。**
1695
1695
  - 不得用 `state="loading"` 长期占位来顶替「无真实指标」—— 无指标时整个区域不渲染。
@@ -1697,7 +1697,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1697
1697
  - 不得给指标卡挂点击跳转,整卡默认只读,`cursor: default` 是已登记行为。
1698
1698
  - 不得一行超过 6 张,也不得让同一区内的卡片高度不一致。
1699
1699
  - 不得在指标区放置页面动作按钮、搜索框或筛选控件。
1700
- - 禁止给指标卡加阴影、边框或白底 —— 指标直接落在页面底色上。
1700
+ - 禁止自行给指标加阴影、边框或白底;需要卡片表面时统一使用 `surface="card"`。
1701
1701
 
1702
1702
  ## ApplicationMetricTrend
1703
1703
 
@@ -1826,13 +1826,13 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1826
1826
  - `actions` 承载页面级动作组,元素应为 `SystemButton`,至多一个 primary,直接并列传入、不包 `ButtonGroup`。动作之间的 4px 间隔由组件给出(GAP Design kit「数据更新、操作」的页面操作插槽)。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
1827
1827
  - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。它按 radiogroup 模式只占一个 Tab 停靠点,← / → 切换模式并首尾相接,Home / End 跳到首末项 —— 方向键同样触发 `onPageModeChange`。
1828
1828
  - `pageModes` 只列该页面真正开放的模式。少于 2 个时开关完全不渲染且不占位。
1829
- - 左侧按 GAP Design kit「数据更新」排布:可选的「返回」→ 标题 → 12px 竖线 → 更新时间。传 `onBack` 时标题前渲染「返回」幽灵按钮(16px chevron + 文字,32 高、圆角 12),文案经 `backLabel` 可改,组件不跳转、回到哪里由调用方决定;二级页面用它回到来源页。`onBack` 与 `breadcrumb` 不得同时传。
1830
- - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则数据新鲜度无从判断。`updatedAt` 写完整日期时间 `YYYY-MM-DD HH:mm`(24 小时制、两位补零,如 `2026-07-28 10:00`),组件原样显示为 14/20 正文色,不加「更新于」前缀;不得传秒或「刚刚」「5 分钟前」一类相对时间。此条取代 07 · C-12 的「只写 HH:mm」(业财平台 round-01 按 kit 裁决)。
1831
- - 传了 `onRefresh` 时,更新时间与其后的 16px 刷新字形合成一枚幽灵按钮,点它即刷新,可访问名为「刷新,2026-07-28 10:00」;没有刷新能力的页面(草稿、向导、一次性结果)不传,时间按纯文字显示,不出现刷新字形。
1829
+ - 默认 `layout="horizontal"`,亦可显式选择 `stacked`(时间在标题下,左侧有标记),不按视口自动切换。左右布局按 GAP Design kit「数据更新」排布:可选的「返回」→ 标题 → 12px 竖线 → 更新时间。传 `onBack` 时标题前渲染「返回」幽灵按钮(16px chevron + 文字,32 高、圆角 12),文案经 `backLabel` 可改,组件不跳转、回到哪里由调用方决定;二级页面用它回到来源页。`onBack` 与 `breadcrumb` 不得同时传。
1830
+ - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则数据新鲜度无从判断。`updatedAt` 写完整日期时间 `YYYY-MM-DD HH:mm`(24 小时制、两位补零,如 `2026-07-28 10:00`),组件原样显示为 12/16 次要文字色,不加「更新于」前缀;不得传秒或「刚刚」「5 分钟前」一类相对时间。此条取代 07 · C-12 的「只写 HH:mm」(业财平台 round-01 按 kit 裁决)。
1831
+ - 传了 `onRefresh` 时,更新时间与其后的 12px 刷新字形合成一枚文字按钮,点它即刷新,可访问名为「刷新,2026-07-28 10:00」;没有刷新能力的页面(草稿、向导、一次性结果)不传,时间按纯文字显示,不出现刷新字形。
1832
1832
  - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时间,`refreshing` 显示刷新中、字形转圈且按钮不可点,`failed` 显示刷新失败(危险色)且按钮读作 `重试`。
1833
1833
  - `title` 为字符串时才会得到悬浮提示。需要悬浮提示又需要补充信息时,标题主体传 `title`,补充信息走 `subtitle`。
1834
1834
  - 页面级进行中任务(批量识别、批量导入)的进度经 `taskStatus` 渲染为页头正中的胶囊,`label` 写「正在识别 14/100」,`busy` 为 true 时带强调色转圈;胶囊 32 高、内边距 6/10、主色 6% 底,文字为文字1。任务结束后移除 `taskStatus`,结果写进 `Sonner` 或页面内容。进度不得写进 `subtitle`。
1835
- - 外观是 48px 通栏:落在页面底色上、只有一条 0.5px 下边线,不是卡片;放在 `ApplicationPageLayoutContainer` 的 `header` 槽位时自动吃掉顶部与两侧留白。
1835
+ - 外观是最小高 52px 的通栏:落在页面底色上、只有一条 0.5px 下边线,不是卡片;放在 `ApplicationPageLayoutContainer` 的 `header` 槽位时自动吃掉顶部与两侧留白。
1836
1836
  - 该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 的区域间隙负责。
1837
1837
  - Page Mode Switch 的选中态与 `ToggleGroup` 同为分段控件表达(选中项抬升为表面色),不得改为淡色洗 —— 淡色洗属于独立开关 `Toggle`。
1838
1838
 
@@ -2034,7 +2034,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
2034
2034
  - 消息流与活动流的条目改用 `Message`,会话气泡改用 `Bubble`。
2035
2035
  - 六种系统状态的承载、批量动作条与分页的挂载,由宿主 `ApplicationDataDisplay` 负责,不在本组件内解决。
2036
2036
 
2037
- **组合约定。** 本组件必须放进 `ApplicationDataDisplay` 的 `children`,仅在 `state="ready"` 时渲染。外边距由 `ApplicationPageLayoutContainer` 持有(`--ui-page-gutter` 与 `--ui-section-gap`),本组件与其行一律不自带 margin。`selectable` 为 true 时行首由组件自动渲染 `ListSelectionCheckbox`,列表顶部另有一行吸顶的全选框(`scope="all"`,半选态按本次 `records` 里已选的条数派生),调用方不得再自行插一个行勾选框或全选行;全选 / 全不选只增删本次 `records` 的 id,`selected` 里其他页的选择原样保留,因此 `onSelectedChange` 的结果可以直接写回,不必再与别页的选择合并。可选时根节点是 `role="group"`、条目在内层的 list 里,`aria-label` 照旧传给本组件,即为该组与列表的名字。`selected` 与 `onSelectedChange` 必须成对提供,本组件的选择是受控的。选择集合非空时,调用方必须把 `ListBatchActionBar` 交给 `ApplicationDataDisplay` 的 `batchBar`。`activeId` 与选择集合是两回事:前者是 SPLIT 右栏或抽屉流程中的当前对象,只有一个,视觉上是选中底色;后者是勾选集合,视觉上是 4% 淡洗。行点击与 Enter / 空格忽略来自行内可交互元素的事件 —— 按钮、链接、表单控件、勾选框、菜单与菜单项(含经 portal 渲染的菜单面板)都不会顺带触发 `onOpen`;`RecordListItem.actions` 另由组件包一层阻止冒泡,连同动作区的留白一起不开行;放进去的动作用 `SystemButton intent="quiet-accent"`,与 `Table` 操作列一致。改用 `renderRow` 接管行主体时同样成立,调用方不必再手动阻止冒泡。给了 `onOpen` 的行可聚焦、Enter / 空格打开,行保留列表项语义;`activeId` 那一行输出 `aria-current="true"`。行首勾选框的可访问名为「选择」加记录标题(`renderRow` 接管且 `title` 不是纯文本时回落为「选择此行」)。行高 56px,容得下标题与元信息两行。`presentation` 取 `RecordList`,不得谎报为 `DataTable`;呈现设置按钮读作「列表设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
2037
+ **组合约定。** 本组件必须放进 `ApplicationDataDisplay` 的 `children`,仅在 `state="ready"` 时渲染。外边距由 `ApplicationPageLayoutContainer` 持有(`--ui-page-gutter` 与 `--ui-section-gap`),本组件与其行一律不自带 margin。`selectable` 为 true 时行首由组件自动渲染 `ListSelectionCheckbox`,列表顶部另有一行吸顶的全选框(`scope="all"`,半选态按本次 `records` 里已选的条数派生),调用方不得再自行插一个行勾选框或全选行;全选 / 全不选只增删本次 `records` 的 id,`selected` 里其他页的选择原样保留,因此 `onSelectedChange` 的结果可以直接写回,不必再与别页的选择合并。可选时根节点是 `role="group"`、条目在内层的 list 里,`aria-label` 照旧传给本组件,即为该组与列表的名字。`selected` 与 `onSelectedChange` 必须成对提供,本组件的选择是受控的。选择集合非空时,调用方必须把 `ListBatchActionBar` 交给 `ApplicationDataDisplay` 的 `batchBar`。`activeId` 与选择集合是两回事:前者是 SPLIT 右栏或抽屉流程中的当前对象,只有一个,视觉上是选中底色;后者是勾选集合,视觉上是 4% 淡洗。行点击与 Enter / 空格忽略来自行内可交互元素的事件 —— 按钮、链接、表单控件、勾选框、菜单与菜单项(含经 portal 渲染的菜单面板)都不会顺带触发 `onOpen`;`RecordListItem.actions` 另由组件包一层阻止冒泡,连同动作区的留白一起不开行;放进去的动作用 `SystemButton intent="row-action"`,与 `Table` 操作列一致。改用 `renderRow` 接管行主体时同样成立,调用方不必再手动阻止冒泡。给了 `onOpen` 的行可聚焦、Enter / 空格打开,行保留列表项语义;`activeId` 那一行输出 `aria-current="true"`。行首勾选框的可访问名为「选择」加记录标题(`renderRow` 接管且 `title` 不是纯文本时回落为「选择此行」)。行高 56px,容得下标题与元信息两行。`presentation` 取 `RecordList`,不得谎报为 `DataTable`;呈现设置按钮读作「列表设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
2038
2038
 
2039
2039
  **禁止 / 使用边界。**
2040
2040
  - 不得在本组件内持有搜索、筛选、排序状态 —— 那些全部属于 `ApplicationQueryToolbar`,数据展示区绝不持有第二套查询状态。
@@ -2219,3 +2219,19 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
2219
2219
  - 禁止绕开「+N」折叠机制在单个日格内堆入超过 2 条事件。
2220
2220
  - 不得在缺少日期字段或未确定观察粒度的情况下选用本组件。
2221
2221
  - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案。
2222
+
2223
+ ## ApplicationUserProfileCard
2224
+
2225
+ **用途。** 展示当前账户的身份摘要和可选账户操作,供顶栏、侧栏及账户页复用。
2226
+
2227
+ **何时使用。** 需要在同一处展示头像、姓名、身份或辅助说明时使用。
2228
+
2229
+ **何时改用其他组件。** 仅展示头像用 `Avatar`;选择其他人员用 `PeoplePickerDialog`。
2230
+
2231
+ **组合约定。** `name` 必填。`badge` 可放小档 `Badge`;`description` 可放组织或脱敏的联系方式。账户动作作为 `children` 传入。需要浮层时放进 `Popover`,显隐与焦点仍由浮层负责。
2232
+
2233
+ **禁止 / 使用边界。**
2234
+
2235
+ - 不得在组件内查询账户、权限或执行登录退出。
2236
+ - 不得为了占位编造私人联系方式,或在无权限时显示敏感信息。
2237
+ - 不得在账户卡里重复放置全局导航已有的设置入口。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@moheng-design/ui-skill",
3
- "version": "3.1.0",
3
+ "version": "3.2.0",
4
4
  "description": "@moheng-design/ui 的 AI agent 支持包 —— SKILL.md 引导 + ESLint / stylelint 强制规则",
5
5
  "keywords": [
6
6
  "agent",
@@ -54,7 +54,7 @@
54
54
  "eslint": "^9.39.0",
55
55
  "stylelint": "^16.26.0",
56
56
  "typescript": "^5.9.3",
57
- "@moheng-design/ui": "3.1.0"
57
+ "@moheng-design/ui": "3.2.0"
58
58
  },
59
59
  "scripts": {
60
60
  "generate": "node scripts/generate.mjs",