@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.
@@ -36,8 +36,10 @@
36
36
  | `--application-*` / `--ui-*` | 公共接口,稳定契约 | 应用代码、页面布局 |
37
37
 
38
38
  业务代码只读 `--application-*` 与 `--ui-*`。下探 `--ds-*` 等于依赖内部实现,
39
- 小版本即可能失效。唯一的例外是换肤入口 `--ds-color-theme-primary`,
40
- 应用层可以且应当覆盖它。
39
+ 小版本即可能失效。例外只有两处:换肤入口 `--ds-color-theme-primary`,
40
+ 应用层可以且应当覆盖它;焦点环几何 `--ds-focus-ring-width` 与 `--ds-focus-ring-offset`,
41
+ 自定义可聚焦元素画焦点环时读取(不得覆盖)—— 焦点环的粗细与偏移全产品必须一致,
42
+ 本库不为它另开别名,组件内部读的也是这两个。
41
43
 
42
44
  **任何情况下都不得在业务代码中写字面色值、圆角与间距去对齐组件。**
43
45
  需要与组件对齐时读同一个 token。
@@ -73,7 +75,9 @@
73
75
 
74
76
  ### 滚动
75
77
 
76
- Content Canvas 是页面唯一的主垂直滚动权持有者。
78
+ 每个页面有且只有一个页面级纵向滚动持有者,按页型划分(06 · D-4):结果集页面由
79
+ `ApplicationDataDisplay` 的主体滚动,`WORKBENCH` / `DETAIL` / 多面板 `ANALYSIS` 等无结果集页面由
80
+ Content Canvas 滚动,见「五层 Canvas 模型」的「纵向滚动归属」。
77
81
  `ScrollArea` 与 `MessageScroller` 只用于**正交方向**(水平)或**局部有界**的溢出,
78
82
  且必须给出显式高度或最大高度。不得堆叠无界的垂直滚动容器。
79
83
 
@@ -90,11 +94,16 @@ Content Canvas 是页面唯一的主垂直滚动权持有者。
90
94
  Partial Failure 六种状态的文案各不相同,不得共用。
91
95
  Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
92
96
 
97
+ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`,不写 `你没有权限`。
98
+ 表单与说明文案(02 §8):校验错误写字段名与不满足的条件(`任务名称不能为空`);
99
+ 确认说明写后果(`删除后 3 条记录不可恢复`),不写请求;占位文字写示例或范围
100
+ (`例如:季度巡检记录`),不写指令;无权限的出路点明找谁(`联系本模块管理员开通`)。
101
+
93
102
  ## Icon
94
103
 
95
104
  **用途。** 已登记字形集中的单色图标,是内容图标在系统内出现的唯一渲染入口。
96
105
 
97
- **何时使用。** 凡界面上出现一个图标形状,该图标必须由本组件渲染。字形几何在构建时内联进包,运行时零外部依赖,SSR 直出完整 SVG,不存在首屏空盒子。`name` 接受 kebab 与 Pascal 两种书写形式(`chevron-down` 与 `ChevronDown` 等价)。承载图标槽位的组件(`Tabs` 的 `TabItem.icon`、`SidebarRailButton` 的 `icon`、`ToggleGroupItem` 的 `icon`)应当接收一个本组件的元素作为该槽位的值。
106
+ **何时使用。** 凡界面上出现一个图标形状,该图标必须由本组件渲染。字形几何在构建时内联进包,运行时零外部依赖,SSR 直出完整 SVG,不存在首屏空盒子。`name` 的类型是生成的 `IconName` 字面量联合,只收已登记字形的 kebab-case 名(`chevron-down`);Pascal 写法不再过类型检查,运行时仍归一处理。承载图标槽位的组件(`Tabs` 的 `TabItem.icon`、`SidebarRailButton` 的 `icon`、`ToggleGroupItem` 的 `icon`)应当接收一个本组件的元素作为该槽位的值。
98
107
 
99
108
  **何时改用其他组件。**
100
109
 
@@ -103,7 +112,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
103
112
  - 品牌标识不是图标。应用 logo 缺失时按登记的 mock 规则渲染纯色块,不得用本组件拼一个替代标识。
104
113
  - 系统内无其他相邻组件,内容图标的渲染由本组件独占。
105
114
 
106
- **组合约定。** `name` 必须已登记在 `src/icon/registry.json`;构建时的双向校验只覆盖库内 `src/`,业务代码里的未登记名字要到运行时才暴露 —— 渲染为等尺寸的隐藏占位盒,开发构建下 `console.warn`,生产构建静默。因此图标位会消失但布局不塌。`size` 取登记档 14 / 16 / 18 / 20 / 24:14 用于 chevron 类指示符,16 用于顶栏,18 用于全局动作与模块字形,20 用于工具与模块触发器,24 用于应用 logo mock 字形;12px 只登记给控件内的清除叉一处,业务代码不得取用。本组件恒为装饰件,渲染 `aria-hidden="true"` 与 `focusable="false"`,可访问名必须由承载它的控件提供 —— `Button` 与 `Toggle` 在 `iconOnly` 为 true 时必须给 `aria-label`。颜色继承 `currentColor`,由父级的 `color` 决定,`color` prop 通常不传。尺寸走 SVG 的 `width` / `height` 属性,图标容器宽度必须稳定,使 active 与 hover 的字重变化不会横向推移标签。图标与文字并排时的间隙由承载控件负责(`Button` 与 `Toggle` 的 4px gap),本组件不带外边距。二级导航的业务标签必须是图标加文字标签,窄屏下也不得丢弃图标。
115
+ **组合约定。** `name` 必须已登记在 `src/icon/registry.json`。业务代码里写错的字面量名在 tsc(`IconName` 联合)与 `prop-enum` 规则两处被拒;数据里存图标名时字段类型写 `IconName`(从 `@moheng-design/ui` 导入),不得写 `string` 再断言 —— 断言绕过类型后,未登记名字要到运行时才暴露:渲染为等尺寸的隐藏占位盒,开发构建下 `console.warn`,生产构建静默,图标位消失但布局不塌。`size` 取登记档 14 / 16 / 18 / 20 / 24:14 用于 chevron 类指示符,16 用于顶栏,18 用于全局动作与模块字形,20 用于工具与模块触发器,24 用于应用 logo mock 字形;12px 只登记给控件内的清除叉一处,业务代码不得取用。本组件恒为装饰件,渲染 `aria-hidden="true"` 与 `focusable="false"`,可访问名必须由承载它的控件提供 —— `SystemButton`、`Button` 与 `Toggle` 在 `iconOnly` 为 true 时必须给 `aria-label`。颜色继承 `currentColor`,由父级的 `color` 决定,`color` prop 通常不传。尺寸走 SVG 的 `width` / `height` 属性,图标容器宽度必须稳定,使 active 与 hover 的字重变化不会横向推移标签。图标与文字并排时的间隙由承载控件负责(`Button` 与 `Toggle` 的 4px gap),本组件不带外边距。二级导航的业务标签必须是图标加文字标签,窄屏下也不得丢弃图标。
107
116
 
108
117
  **禁止 / 使用边界。**
109
118
 
@@ -117,18 +126,18 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
117
126
 
118
127
  **用途。** Foundation 按钮,是按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。
119
128
 
120
- **何时使用。** 库内组件需要一个按钮时使用本组件。业务页面只在没有稳定应用语义可用时降级到本组件 —— 有稳定语义时一律用 `SystemButton`。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、16px 圆角、32px 默认高度;16px 圆角在 32px 高度下使等宽图标按钮自然成圆,系统内没有独立的 pill 或 circle token。
129
+ **何时使用。** 本组件只供库内组件使用。业务页面的按钮一律用 `SystemButton`,不存在降级到本组件的情形。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、16px 圆角、32px 默认高度;16px 圆角在 32px 高度下使等宽图标按钮自然成圆,系统内没有独立的 pill 或 circle token。
121
130
 
122
131
  **何时改用其他组件。**
123
132
 
124
- - 产品页面的常规动作按钮改用 `SystemButton`,它是整个产品的默认动作按钮,并承载 `loading` 与产品状态。
133
+ - 业务页面的任何按钮改用 `SystemButton`,它是整个产品的默认动作按钮,并承载 `loading` 与产品状态。
125
134
  - 跳转到另一个 URL 用原生 `<a>`;`variant="link"` 只用于行为是按钮、视觉为行内链接的动作。
126
135
  - 表达持续的两态状态改用 `Toggle`,一组互斥的显示选择改用 `ToggleGroup`。
127
136
  - 工作台菜单栏条目改用 `SidebarRailButton`,应用入口改用 `SidebarAppLinkButton`。
128
137
  - 页面区域内的内容分节切换改用 `Tabs`,不得用一排 ghost 按钮模拟。
129
138
  - 原生 `<button>` 一律改用本组件(`mappings.json` · `no-native-button`)。
130
139
 
131
- **组合约定。** `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` 确认,批量场景的标题中写明受影响对象的数量。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
140
+ **组合约定。** `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` 确认,批量场景的标题中写明受影响对象的数量。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`aria-disabled="true"` 与原生 `disabled` 同一套禁用外观但保持可聚焦,本组件不拦截事件,阻断动作由设置它的一方负责。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
132
141
 
133
142
  **禁止 / 使用边界。**
134
143
 
@@ -138,10 +147,11 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
138
147
  - 不得在同一个动作组内出现两个 `variant="primary"`。
139
148
  - 不得只禁用文字而保留图标可点,禁用作用于整个交互单元。
140
149
  - 禁止在业务页面自建第二套基础按钮视觉。
150
+ - 不得在业务页面直接使用本组件 —— 一律改用 `SystemButton`。
141
151
 
142
152
  ## ButtonGroup
143
153
 
144
- **用途。** 把一组相关 `Button` 合并为一个分段控件或间隔簇。
154
+ **用途。** 把一组相关按钮合并为一个分段控件或间隔簇。业务页面里组内一律是 `SystemButton`。
145
155
 
146
156
  **何时使用。** 动作对(`重置` 与 `应用`)与分离式控件(主动作加「更多」触发器)用本组件。该组只负责拼接与分隔,不管理任何选中态。默认 `attached` 为 true,子项拼接为一个整体;`attached` 为 false 时子项以 8px 分隔、各自保留完整圆角。
147
157
 
@@ -151,9 +161,9 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
151
161
  - 页面模式切换改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`。
152
162
  - 页面区域内的内容分节切换改用 `Tabs`,Shell 的二级导航改用 `ApplicationSecondaryNavigation`。
153
163
  - 翻页控件改用 `Pagination`,列表与表格的翻页改用 `ListTablePagination`。
154
- - 单个动作不成组,直接用 `Button` 或 `SystemButton`。
164
+ - 单个动作不成组,直接用 `SystemButton`。
155
165
 
156
- **组合约定。** `children` 是 slot 而非数据 prop,这与 `ToggleGroup` 的 `items` 形态相反,分工是实质性的(04 · A4):本组只做拼接、不管状态,因此接受任意子节点,包括 Fragment、数组与条件渲染,子组件也不必接受或转发 `style`。拼接态的圆角压平与 1px 边框重叠由 CSS 结构伪类完成,不做属性注入,子组件的 `className` 优先级不受影响。组内按钮的 `size` 必须一致,否则拼接边缘对不齐。拼接态要求子项都有可见边框才对得上,因此不得在拼接态里混入 `variant="ghost"` 与 `variant="link"`。组渲染 `role="group"`,若该组表达的是互斥选择,说明组件选错了。组自身不带外边距,与相邻元素的距离由容器负责。子项中至多一个 `variant="primary"`。
166
+ **组合约定。** `children` 是 slot 而非数据 prop,这与 `ToggleGroup` 的 `items` 形态相反,分工是实质性的(04 · A4):本组只做拼接、不管状态,因此接受任意子节点,包括 Fragment、数组与条件渲染,子组件也不必接受或转发 `style`。拼接态的圆角压平与 1px 边框重叠由 CSS 结构伪类完成,不做属性注入,子组件的 `className` 优先级不受影响。组内按钮的 `size` 必须一致,否则拼接边缘对不齐。拼接态要求子项都有可见边框才对得上,因此不得在拼接态里混入 `intent="quiet"` 与 `intent="link"`(库内为 `variant="ghost"` 与 `variant="link"`)。组渲染 `role="group"`,若该组表达的是互斥选择,说明组件选错了。组自身不带外边距,与相邻元素的距离由容器负责。子项中至多一个 primary。
157
167
 
158
168
  **禁止 / 使用边界。**
159
169
 
@@ -174,17 +184,17 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
174
184
  - 在多个选项中择一,或一组同族的分段开关,改用 `ToggleGroup`。
175
185
  - 立即生效的设置项(列可见性、通知开关、密度)改用 `Switch`。
176
186
  - 等待「应用」或「提交」的表单数据改用 `Checkbox`,列表与表格的行选择改用 `ListSelectionCheckbox`。
177
- - 触发一次性动作改用 `Button` 或 `SystemButton` —— 本组件表达的是持续状态,不是动作。
187
+ - 触发一次性动作改用 `SystemButton` —— 本组件表达的是持续状态,不是动作。
178
188
  - 页面模式切换改用 `ApplicationPageHeader`。
179
189
 
180
- **组合约定。** `pressed` 与 `defaultPressed` 互斥:受控用法传 `pressed` 并配 `onPressedChange`,非受控用法传 `defaultPressed`;`onPressedChange` 在两种用法下都会触发。`iconOnly` 为 true 时必须提供 `aria-label`。纯文字内容下选中不得仅靠颜色表达,须同时有图标或文案上的区分。尺寸轴比 `Button` 少一档 `xs`,只有 `sm` / `default` / `lg`,映射高度 28 / 32 / 40px(04 · A2)—— 需要 24px 高的可按下控件说明取错了组件族。本组件持有非受控状态,带 `"use client"`;受控用法下内部状态不参与,但指令按模块边界生效,客户端边界落在本组件上,父级无须整体转为客户端组件。多个 `Toggle` 并排时的间隔由容器的 gap 负责,本组件不带外边距。图标子节点用 `Icon`,与文字的 4px 间隙由控件的 gap 提供。
190
+ **组合约定。** `pressed` 与 `defaultPressed` 互斥:受控用法传 `pressed` 并配 `onPressedChange`,非受控用法传 `defaultPressed`;`onPressedChange` 在两种用法下都会触发。`iconOnly` 为 true 时必须提供 `aria-label`。选中态除色洗与强调前景外另有 1px 前景色描边,这是非颜色标识,纯文字内容下也不只靠颜色区分选中,调用方无须另补。尺寸轴比 `Button` 少一档 `xs`,只有 `sm` / `default` / `lg`,映射高度 28 / 32 / 40px(04 · A2)—— 需要 24px 高的可按下控件说明取错了组件族。本组件持有非受控状态,带 `"use client"`;受控用法下内部状态不参与,但指令按模块边界生效,客户端边界落在本组件上,父级无须整体转为客户端组件。多个 `Toggle` 并排时的间隔由容器的 gap 负责,本组件不带外边距。图标子节点用 `Icon`,与文字的 4px 间隙由控件的 gap 提供。
181
191
 
182
192
  **禁止 / 使用边界。**
183
193
 
184
194
  - 不得用一排 `Toggle` 模拟单选组,互斥语义一律交给 `ToggleGroup`。
185
195
  - 不得用本组件承载立即落库的设置项,那是 `Switch` 的职责。
186
196
  - 禁止用于 `pageMode` 切换。
187
- - 不得在纯文字内容上只用颜色表达选中。
197
+ - 不得覆盖掉选中态的描边 —— 它是纯文字内容下选中态唯一的非颜色标识。
188
198
  - 不得省略 `iconOnly` 形态的 `aria-label`。
189
199
  - 不得把选中态改写为抬升式白色表面 —— 抬升是分段控件的表达,独立开关用淡色洗(04 · A5)。
190
200
 
@@ -202,7 +212,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
202
212
  - 页面模式切换改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`;SPLIT 右栏的 View Mode Switch 改的是 `dataPresentation`,绝不改 `pageMode`。
203
213
  - 呈现设置的入口按钮按当前呈现方式命名(`列设置` / `卡片设置` / `看板设置`),由 `ApplicationQueryToolbar` 承载,不由本组件表达。
204
214
 
205
- **组合约定。** `items` 是数据 prop 而非 slot,与 `ButtonGroup` 的 `children` 形态相反,分工是实质性的(04 · A4):本组管理受控选中态,必须知道有哪些值。每个选项的 `label` 与 `icon` 至少提供其一,只有 `icon` 而无 `label` 时该项收敛为等宽方格。`type` 决定 `value` 的形态与无障碍语义:`single` 渲染 radio 语义、`value` 为 string,`multiple` 上报 `aria-pressed`、`value` 为 string[],两者必须匹配。受控用 `value` 配 `onValueChange`,非受控用 `defaultValue`;`single` 且未提供 `defaultValue` 时默认选中 `items[0].value`,因此单选组永远有一个选中项,不存在空态。整组禁用用 `disabled`,单个选项禁用用 `ToggleGroupItem.disabled`,两者可叠加。容器高度为 28 / 32 / 40px,选项高度是容器高度减去上下各 2px 的轨道内边距,得 24 / 28 / 36px;36px 是派生值而非标尺档位,不得为它新增 token。本组件持有非受控状态,带 `"use client"`。组自身不带外边距,与相邻控件的距离由容器负责。
215
+ **组合约定。** `items` 是数据 prop 而非 slot,与 `ButtonGroup` 的 `children` 形态相反,分工是实质性的(04 · A4):本组管理受控选中态,必须知道有哪些值。每个选项的 `label` 与 `icon` 至少提供其一,只有 `icon` 而无 `label` 时该项收敛为等宽方格。`type` 决定 `value` 的形态与无障碍语义:`single` 渲染 radio 语义、`value` 为 string,`multiple` 上报 `aria-pressed`、`value` 为 string[],两者必须匹配。`single` 组整组只占一个 Tab 停靠点,← / → 移动并同时选中、首尾相接,Home / End 跳到首末个可用项;`multiple` 组每项各是一个停靠点。受控用 `value` 配 `onValueChange`,非受控用 `defaultValue`;`single` 且未提供 `defaultValue` 时默认选中 `items[0].value`,因此单选组永远有一个选中项,不存在空态。整组禁用用 `disabled`,单个选项禁用用 `ToggleGroupItem.disabled`,两者可叠加。容器高度为 28 / 32 / 40px,选项高度是容器高度减去上下各 2px 的轨道内边距,得 24 / 28 / 36px;36px 是派生值而非标尺档位,不得为它新增 token。本组件持有非受控状态,带 `"use client"`。组自身不带外边距,与相邻控件的距离由容器负责。
206
216
 
207
217
  **禁止 / 使用边界。**
208
218
 
@@ -235,6 +245,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
235
245
  - 置于 `Field` 内时,`Field.htmlFor` 与该控件的 `id` 必须成对设置。`Field` 不生成 id,缺一则标签点击不聚焦控件。
236
246
  - `Field.error` 与该控件的 `invalid` 必须同时设置。两者不联动(04 · I5):只设 `error` 时错误文字出现而边框仍为常态色,且没有任何报错。
237
247
  - 无可见标签的位置(工具栏、表格单元格编辑器)必须给 `aria-label`。
248
+ - `ref` 落到原生 `<input>` 本身(React 19;React 18 不把 `ref` 交给函数组件),取 DOM 不必再按 id 查询。
238
249
  - 置于 `InputGroup` 内时必须是壳的直接子元素,一个壳只放一个控件。焦点只在最外层壳表达一次。
239
250
 
240
251
  **禁止 / 使用边界。**
@@ -265,11 +276,12 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
265
276
  - 附加物一律走 `leading` 与 `trailing`,不得混写进 `children`。
266
277
  - 附加物中的图标必须用 `Icon` 组件并取登记尺寸 14 / 16 / 18 / 20 / 24。
267
278
  - 该组件的 `disabled` 只改外壳视觉,不会禁用内部控件。整组禁用时该组件的 `disabled` 与内部控件的 `disabled` 必须同时设置,否则外壳呈禁用色而输入框仍可键入。
279
+ - `invalid` 同理只改外壳视觉:边框转为 danger 色,聚焦时焦点环也转为 danger 色,但不输出 `aria-invalid` —— 外壳是包装元素,失败语义属于内部控件。校验失败时该组件的 `invalid`、内部控件的 `invalid` 与 `Field.error` 三者必须同时设置。
268
280
  - 外边距由父容器负责,该组件不自带 margin。
269
281
 
270
282
  **禁止 / 使用边界。**
271
283
 
272
- - 不得依赖内部控件的 `invalid` 表达可见的校验失败态 —— 外壳已把内部控件的边框剥掉,该位置的 `invalid` 只保留 `aria-invalid` 语义。可见失败态由包裹该组件的 `Field` 的 `error` 承担。
284
+ - 不得只设内部控件的 `invalid` 表达校验失败 —— 外壳已把内部控件的边框剥掉,该位置的 `invalid` 只保留 `aria-invalid` 语义,边框仍是常态色。可见失败态由该组件自己的 `invalid` 承担。
273
285
  - 不得让内部控件再绘制第二圈焦点环。焦点由外壳的 `:focus-within` 表达一次。
274
286
  - 禁止把该组件的外壳样式复制进业务代码,用来自制搜索框、单位输入框或带按钮的输入框。
275
287
  - 不得在一个壳内放两个及以上录入控件。
@@ -292,6 +304,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
292
304
  - `value` 与 `onValueChange` 必须成对使用。只传 `value` 不传回调,该组件不可输入。非受控用 `defaultValue`,与 `value` 二者不得同时给。
293
305
  - 值以空格占位保持「第 i 个字符对应第 i 格」,尾部空格被裁掉。调用方在提交前必须同时判定「不含空格」与「长度等于 `length`」,只比长度会把跳格漏填的码判为已填完。
294
306
  - 粘贴由该组件接管:从当前格起依次填入,并把焦点移到最后一个填充位。调用方不得再自行绑定粘贴处理。
307
+ - `invalid` 把全部方框边框转为 danger 色并逐格输出 `aria-invalid`,与 `Field.error` 不联动,校验失败时两者必须同时设置。
295
308
  - 每个方框自带中文 `aria-label`(第 N 位),该文案不可覆盖 —— 单语言是既定裁决(04 · I16),不是遗漏。
296
309
  - 外边距与整体对齐由父容器负责,该组件不自带 margin。
297
310
 
@@ -322,7 +335,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
322
335
  - `Field.error` 与该控件的 `invalid` 必须同时设置(04 · I5),两者不联动。
323
336
  - 置于 `Field` 内时,`Field.htmlFor` 与该控件的 `id` 必须成对设置。
324
337
  - 无可见标签的位置必须给 `aria-label`。
325
- - 置于 `ApplicationFormDialog` 的字段网格中时,跨列由外层 `Field` 承担 —— 契约登记的写法是给 `Field` 传 `style={{ gridColumn: '1 / -1' }}`,该控件本身不参与网格定位。
338
+ - 置于 `ApplicationFormDialog` 的字段网格中时,跨列由外层 `Field` 承担 —— 给 `Field` 传 `span="full"`,该控件本身不参与网格定位。
326
339
  - 外边距由父容器负责,该控件不自带 margin。
327
340
 
328
341
  **禁止 / 使用边界。**
@@ -350,16 +363,17 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
350
363
 
351
364
  - `children` 只放一个控件。一行两个控件(如日期区间的起止)须拆成两个 Field,或由调用方容器自行排布。
352
365
  - 标签由 `Label` 渲染,`Label` 是标签视觉的 Foundation Owner。不得在 `children` 里另写一份标签实现(04 · I4)。
353
- - `htmlFor` 与控件的 `id` 必须成对设置。该组件不生成 id。
366
+ - `htmlFor` 与控件的 `id` 必须成对设置。该组件不生成 id。给了 `htmlFor` 时,说明与错误取 `<htmlFor>-description` / `<htmlFor>-error` 为 id 并并入该控件的 `aria-describedby`,控件包在 `InputGroup` 或 `Popover` 里同样生效;不给 `htmlFor` 则标签与说明都关联不到控件。错误带 `role="alert"`,出现即播报。
354
367
  - `error` 存在时取代 `description`,两者不同时显示。因此说明性信息不得成为错误文案的必要补充。
355
- - `error` 与内部控件的 `invalid` 必须同时设置。该组件不会把控件切到失败态(04 · I5),这是有意保留的不联动,漏写由阶段 5 的 lint 规则拦截。
368
+ - `error` 与内部控件的 `invalid` 必须同时设置。该组件不会把控件切到失败态视觉(04 · I5),这是有意保留的不联动;它只在控件没有 `aria-invalid` 时补上读屏语义。
356
369
  - `required` 只渲染标签后的星号,且该星号带 `aria-hidden`。必填语义必须由控件自身的 `required` 承担。
357
- - 字段之间的间距由 `ApplicationFormDialog` 的网格负责,该组件不自带外边距。跨列写法是给该组件传 `style={{ gridColumn: '1 / -1' }}`,这是 `ApplicationFormDialog` 契约登记的写法。
370
+ - 字段之间的间距由 `ApplicationFormDialog` 的网格负责,该组件不自带外边距。跨列写法是给该组件传 `span="full"`,规则由该组件自己的 CSS 承担,在任何网格父级内都生效。
358
371
 
359
372
  **禁止 / 使用边界。**
360
373
 
361
374
  - 不得用该组件改动内部控件的边框、高度或圆角 —— 控件视觉归控件自己所有。
362
375
  - 不得只设 `error` 而不设控件的 `invalid`:错误文字会出现,控件边框仍是常态色,且没有任何报错。
376
+ - 不得用内联 `style={{ gridColumn: … }}` 让本行跨列 —— 改传 `span="full"`;内联属性优先级最高,调用方的 `className` 覆盖随之失效(01 §1.7)。
363
377
  - 禁止在一个 Field 内放多个录入控件。
364
378
  - 不得用该组件包裹只读内容充当详情页布局。
365
379
  - 不得让 Loading / Empty / Error / No Permission / Not Found / Partial Failure 六种状态共用同一句 `error` 文案。
@@ -411,6 +425,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
411
425
 
412
426
  - `checked` 必须与 `onCheckedChange` 配对使用。非受控用 `defaultChecked`,与 `checked` 互斥。
413
427
  - `indeterminate` 优先级高于 `checked`,只用于「全选」这类父级行。
428
+ - `invalid` 把方框描边转为 danger 色并在内部 `<input>` 上输出 `aria-invalid`,与 `Field.error` 不联动,校验失败时两者必须同时设置。
414
429
  - `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<input>`(04 · I8)。因此 `id`、`name`、`value`、`aria-*` 会正确落在控件上,而布局类样式必须走 `className`。
415
430
  - 未传 `label` 时必须给 `aria-label` 或 `aria-labelledby`,否则该控件没有无障碍名称。
416
431
  - `label` 与方框同属一个 `<label>`,点击文字即可切换。放进 `Field` 时不得再用 `Field.label` 标注同一个控件。
@@ -439,7 +454,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
439
454
  - 条目是动作而非取值(编辑、删除、导出):`DropdownMenu`。
440
455
  - 该维度需要多选:`ApplicationFilterMenu` 或 `ToggleGroup`。该组件只承载单值。
441
456
 
442
- **组合约定。** 触发器宽度撑满父容器,浮层与触发器等宽,因此宽度必须由父级布局或 `Field` 决定,组件自身不设宽度、不带外边距。`SelectOption` 的 label 在触发器与选项内均以省略号截断,故标签必须在触发器宽度内读完。受控用法下 `value` 与 `onValueChange` 必须成对出现;只给 `value` 而不给 `onValueChange` 会得到一个永不改变的控件。`invalid` 与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。剩余属性落在根 `<div>` 上而非触发器,因此 `Field.htmlFor` 对该组件无效,可见标签必须由 `Field.label` 或 `Label` 给出。占位文字默认为「请选择」,本库单语言,不接受运行时本地化。
457
+ **组合约定。** 触发器宽度撑满父容器,浮层与触发器等宽,因此宽度必须由父级布局或 `Field` 决定,组件自身不设宽度、不带外边距。`SelectOption` 的 label 在触发器与选项内均以省略号截断,故标签必须在触发器宽度内读完。受控用法下 `value` 与 `onValueChange` 必须成对出现;只给 `value` 而不给 `onValueChange` 会得到一个永不改变的控件。`invalid` 与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。`id`、`aria-label`、`aria-labelledby`、`aria-describedby` 落在触发按钮上,其余属性落在根 `<div>`;因此 `Field.htmlFor` 配触发器的 `id` 即关联到按钮,无可见标签的场景(排序控件)用 `aria-label` 命名。按钮名称来自标签时,当前值经 `aria-describedby` 补报。占位文字默认为「未选择」,写状态而非指令,不得改回「请选择」一类祈使句(07 · C-4);本库单语言,不接受运行时本地化。
443
458
 
444
459
  **禁止 / 使用边界。**
445
460
  - 不得向 `value` 传数组充当多选。
@@ -481,7 +496,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
481
496
  - 查询工具栏中的常驻筛选维度:`ApplicationFilterMenu`。
482
497
  - 2–5 个选项且要求全部可见:`RadioGroup`。
483
498
 
484
- **组合约定。** `ComboboxOption.label` 为非字符串时必须提供 `searchText`,否则该项永远无法被筛选命中,且无任何报错。`searchText` 同时用于收起状态下输入框内的回显,因此必须是完整可读的文本,不得写成匹配用的关键词缩写。该组件不提供 `invalid`,校验失败一律由包裹它的 `Field` 的 `error` 表达。宽度由父容器决定,浮层与输入框外壳等宽。选中后浮层关闭且输入被清空,调用方不得依赖输入内容作为提交值。
499
+ **组合约定。** `ComboboxOption.label` 为非字符串时必须提供 `searchText`,否则该项永远无法被筛选命中,且无任何报错。`searchText` 同时用于收起状态下输入框内的回显,因此必须是完整可读的文本,不得写成匹配用的关键词缩写。`invalid` 把外壳边框转为 danger 色并在输入框上输出 `aria-invalid`,与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。`id`、`aria-label`、`aria-labelledby`、`aria-describedby` 落在输入框上,`Field htmlFor` 因此直接关联到输入框。聚焦不展开浮层,输入、↓ / ↑、Alt+↓ 或点击才展开,Tab 与失焦即收起。宽度由父容器决定,浮层与输入框外壳等宽。选中后浮层关闭且输入被清空,调用方不得依赖输入内容作为提交值。
485
500
 
486
501
  **禁止 / 使用边界。**
487
502
  - 不得把它当搜索框使用 —— 该组件没有提交回调,逐字实时搜索也被规范禁止。
@@ -502,7 +517,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
502
517
  - 立即生效的开关:`Switch`。
503
518
  - 该维度需要多选:`ApplicationFilterMenu` 或 `ToggleGroup`。
504
519
 
505
- **组合约定。** 组内间距由组件自身负责,垂直排列为 `--ds-space-2`、水平排列为 `--ds-space-4`,调用方不得再给选项加外边距。`name` 不传时自动生成且在 SSR 下稳定,仅当该组需参与原生 `<form>` 序列化时才显式设置。整组禁用用 `disabled`,单个选项的禁用用 `RadioGroupItem.disabled`,两者不得互相替代。剩余属性落在 `role="radiogroup"` 的根元素上,因此 `aria-label` 可用于给出组名。每个选项整行是一个 `<label>`,点击行内任意位置都会切换选中。
520
+ **组合约定。** 组内间距由组件自身负责,垂直排列为 `--ds-space-2`、水平排列为 `--ds-space-4`,调用方不得再给选项加外边距。`name` 不传时自动生成且在 SSR 下稳定,仅当该组需参与原生 `<form>` 序列化时才显式设置。整组禁用用 `disabled`,单个选项的禁用用 `RadioGroupItem.disabled`,两者不得互相替代。`invalid` 把全部圆点描边转为 danger 色,并在 `role="radiogroup"` 的根元素上输出 `aria-invalid`;与 `Field.error` 不联动,校验失败时两者必须同时设置。剩余属性落在 `role="radiogroup"` 的根元素上,因此 `aria-label` 可用于给出组名。每个选项整行是一个 `<label>`,点击行内任意位置都会切换选中。
506
521
 
507
522
  **禁止 / 使用边界。**
508
523
  - 不得逐个渲染单选项后手工拼组,那会丢掉分组的键盘导航与 `name` 绑定。
@@ -523,13 +538,14 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
523
538
  - 一组互斥的显示选项:`ToggleGroup`。
524
539
  - 列表与表格的行选择:`ListSelectionCheckbox`。
525
540
 
526
- **组合约定。** `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<button role="switch">`,这条分流是既定约定,调用方须按此预期传参。可见标签一律走 `label` prop,它与轨道同属一个 `<label>` 因而可点击;没有可见标签时必须提供 `aria-label`。`onCheckedChange` 应直接落库或落配置,回调内不得再排队等待外部提交。成组出现时的行距由容器负责,组件自身不带外边距。
541
+ **组合约定。** `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<button role="switch">`,这条分流是既定约定,调用方须按此预期传参。可见标签一律走 `label` prop,它与轨道同属一个 `<label>` 因而可点击;没有可见标签时必须提供 `aria-label`。`onCheckedChange` 应直接落库或落配置,回调内不得再排队等待外部提交。保存未返回期间设 `busy`:控件保持可聚焦并带 `aria-busy`,点击与空格不再切换,滑块内显示进行中指示。成组出现时的行距由容器负责,组件自身不带外边距。
527
542
 
528
543
  **禁止 / 使用边界。**
529
544
  - 不得把它放进 `ApplicationFormDialog` 的 `Field` 行充当表单字段 —— 表单行承载的是等待提交的数据,与立即生效语义相反。
530
545
  - 不得为它另配「应用」按钮。
531
546
  - 不得用它触发不可逆或破坏性操作,那类操作必须先经 `AlertDialog` 确认。
532
547
  - 禁止覆盖 36×20 轨道与 16px 滑块的已登记几何。
548
+ - 不得用 `disabled` 表达保存中的等待 —— 禁用会让按钮失焦,键盘焦点掉到 `body`;改用 `busy`。
533
549
 
534
550
  ## Slider
535
551
 
@@ -558,12 +574,12 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
558
574
  **何时使用。** 作为日期字段的取值面板使用,与 `Input` 一同放进 `Popover`。筛选区间由调用方持有起止两个值,各配一个该组件。**该组件是控件,不是承载面** —— `CALENDAR` 页面模式与它同名但不同层,不得混用。
559
575
 
560
576
  **何时改用其他组件。**
561
- - 整页的日历承载面(`pageMode` 为 `CALENDAR`):由 `ApplicationPageLayoutContainer` 承担。
577
+ - 整页的日历承载面(`pageMode` 为 `CALENDAR`):`ApplicationDataDisplay` 的 `presentation="Calendar"`,月格按 SKILL.md「呈现配方」的月历写法拼装。
562
578
  - 粒度切换加月格加当日议程栏的工作台面:`ScheduleCollaborationWorkspace`。
563
579
  - 查询工具栏中作为 `dataPresentation` 的日历呈现方式:由数据呈现区承担,不是本控件。
564
580
  - 日期已知且可直接键入:`Input`。
565
581
 
566
- **组合约定。** `onSelect` 收到的是本地零点的 `Date`;落库、比较与按日期匹配一律使用本地时区的 ISO 日期串。`month` 只作用于首次渲染的初始月份,翻月游标由组件内部持有,后续更改 `month` 不会重置视图,调用方不得把它当受控 prop 使用。`selected` 为单值,该组件不表达区间高亮。置于 `Popover` 内时面板宽度不得小于 252px,`Popover` 的默认 320px 已足够容纳。星期名、上一月与下一月的无障碍名称、以及「年」「月」标题为中文常量,本库单语言。
582
+ **组合约定。** `onSelect` 收到的是本地零点的 `Date`;落库、比较与按日期匹配一律使用本地时区的 ISO 日期串。翻月游标由组件内部持有;`month` 的年月变化时视图跟随,年月不变的重渲染不重置用户已翻到的月份。网格只占一个 Tab 停顿,方向键逐日 / 逐周、Home / End 到周首 / 周末、PageUp / PageDown 跨月(加 Shift 跨年),Enter / 空格选中;日格的无障碍名称为完整日期加星期。`selected` 为单值,该组件不表达区间高亮。「今天」默认取当前本地日期;以服务端时间为准、服务端渲染或测试需要固定日期时传 `today`(`Date`,只取本地年月日),它同时决定今日高亮、未传 `month` 时的初始月份与无选中日时的 Tab 停顿。置于 `Popover` 内时面板宽度不得小于 252px,`Popover` 的默认 320px 已足够容纳。星期名、上一月与下一月的无障碍名称、以及「年」「月」标题为中文常量,本库单语言。
567
583
 
568
584
  **禁止 / 使用边界。**
569
585
  - 不得用 `toISOString()` 生成或比较日期串 —— 该写法在 UTC+8 下必然错位一天,今日高亮与选中判断会整体错一格。
@@ -579,7 +595,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
579
595
 
580
596
  **何时改用其他组件。** 只有一个折叠区、且该区是「更多筛选」这类单一显隐入口时,改用 `Collapsible`。需要在页面区域内切换互斥内容、且切换后内容占满同一块区域时,改用 `Tabs`。业务详情的字段分节改用 `ApplicationRecordDetailBody` 的 `sections`,它已登记标题行、字段网格与分节级动作。原生 `<details>` / `<summary>` 一律不得出现,替换目标见 `mappings.json` 的 `no-native-details` 与 `no-native-summary`。
581
597
 
582
- **组合约定。** 该组件根节点自带上边线,每个折叠区自带下边线,因此两个 Accordion 直接相邻时接缝处会出现 2px 线;两者之间必须存在其他内容,或改为合并进同一个 `items`。组件不带任何外边距,与上下内容的间距由容器负责。`type` 为 `single` 时组件只在自身的展开动作中收敛为至多一项,外部通过 `open` 传入的数组原样渲染 —— 受控模式下调用方必须自行保证 `single` 时数组长度为 0 或 1。`open` 与 `onOpenChange` 必须成对提供,只传 `open` 会使全部触发行失效。`title` 已由组件负责渲染展开箭头,调用方不得在 `title` 内再放一个方向字形。
598
+ **组合约定。** 该组件根节点自带上边线,每个折叠区自带下边线,因此两个 Accordion 直接相邻时接缝处会出现 2px 线;两者之间必须存在其他内容,或改为合并进同一个 `items`。组件不带任何外边距,与上下内容的间距由容器负责。`type` 为 `single` 时组件只在自身的展开动作中收敛为至多一项,外部通过 `open` 传入的数组原样渲染 —— 受控模式下调用方必须自行保证 `single` 时数组长度为 0 或 1。`open` 与 `onOpenChange` 必须成对提供,只传 `open` 会使全部触发行失效。`title` 已由组件负责渲染展开箭头,调用方不得在 `title` 内再放一个方向字形。标题行以 `aria-controls` 指向展开的内容区,内容区是以标题行命名的 `region`;↑ / ↓ 在标题行间移动焦点、首尾相接,Home / End 跳到首末项,每个标题行仍是各自的 Tab 停靠点。
583
599
 
584
600
  **禁止 / 使用边界。**
585
601
  - 不得用于页面级或区域级的内容切换,那是 `Tabs` 的职责。
@@ -596,7 +612,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
596
612
 
597
613
  **何时改用其他组件。** 表达「当前处于哪个模块」以及模块间切换,改用 `ApplicationModuleSwitcher`。SPLIT 页面模式中表达「当前在目录的哪个位置」,改用 `ApplicationSplitListSidebar`。同层级之间的并列切换改用 `Tabs` 或 `NavigationMenu`。
598
614
 
599
- **组合约定。** 该组件只能作为 `ApplicationPageHeader` 的 `breadcrumb` 内容传入,间距与位置由上下文区负责,组件自身无外边距。中间层级按三态渲染:提供 `href` 渲染链接,仅提供 `onClick` 渲染按钮,两者都不提供渲染静态文本 —— 不可点击的层级必须走第三态,不得以空字符串或占位地址伪造链接。使用前端路由时必须同时提供 `href` 与 `onClick`,并在 `onClick` 内自行阻止默认跳转,组件不代为调用 `preventDefault`。末项无论是否提供 `href` 或 `onClick` 都渲染为当前页文本,两者在末项上均无效果。
615
+ **组合约定。** 该组件只能作为 `ApplicationPageHeader` 的 `breadcrumb` 内容传入,间距与位置由上下文区负责,组件自身无外边距。中间层级按三态渲染:提供 `href` 渲染链接,仅提供 `onClick` 渲染按钮,两者都不提供渲染静态文本 —— 不可点击的层级必须走第三态,不得以空字符串或占位地址伪造链接。使用前端路由时必须同时提供 `href` 与 `onClick`,并在 `onClick` 内自行阻止默认跳转,组件不代为调用 `preventDefault`。末项无论是否提供 `href` 或 `onClick` 都渲染为当前页文本,两者在末项上均无效果。组件输出 `nav > ol > li` 结构,分隔字形在 `li` 内且对读屏隐藏。
600
616
 
601
617
  **禁止 / 使用边界。**
602
618
  - 不得放进 Shell 的三条导航带 —— `TopNavigationPrimaryBar` 契约已明令禁止在其中添加面包屑。
@@ -609,14 +625,15 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
609
625
 
610
626
  **用途。** 键盘优先的命令面板,本地筛选并执行已登记命令。
611
627
 
612
- **何时使用。** 作为全局命令与跳转入口时使用该组件,命令按 `groups` 分组,筛选后为空的分组连标题一起消失。面板宽 420px、列表区最高 320px,自带 1px 边框、12px 圆角与浮层阴影。上下键在跨分组的扁平序列上移动,回车执行当前项。
628
+ **何时使用。** 作为全局命令与跳转入口时使用该组件,命令按 `groups` 分组,筛选后为空的分组连标题一起消失。面板宽 420px、列表区最高 320px,自带 1px 边框、12px 圆角与浮层阴影。上下键在跨分组的扁平序列上移动,回车执行当前项。有命中时首项自动高亮,打完字直接回车即执行。
613
629
 
614
630
  **何时改用其他组件。** 列表页的数据查询改用 `ApplicationQueryToolbar` 的搜索行,独立的纯文本搜索入口改用 `SearchField`(`mappings.json` 的 `no-native-search` 指向它)。表单内「输入即筛选」的单选控件改用 `Combobox`。上下文区或行尾收纳低频动作改用 `DropdownMenu`。
615
631
 
616
- **组合约定。** 该组件必须由 `Dialog` 承载,作为 `children` 传入;它自带边框、圆角与浮层阴影,不得再被 `Card`、`Popover` 或任何带边框的容器包裹。承载它的 `Dialog` 不得再传 `title`、`description` 或 `footer` —— 搜索行就是面板的头部。关闭由 `Dialog` 负责,该组件自身不处理关闭。`CommandGroup.label` 是组件的 React key,必须在整个面板内唯一。`CommandItem.label` 为非字符串时必须提供 `searchText`,否则该项永远不会被筛选命中,且不产生任何报错。`shortcut` 仅作展示,真实快捷键必须由应用层自行注册,两处文本必须一致。
632
+ **组合约定。** 作为全局命令入口时必须用 `dialog` 形态,以 `open` 与 `onOpenChange` 受控:面板自身就是模态框,与 `Dialog` 共用同一个模态基座(遮罩、Esc 与遮罩点击关闭、焦点陷阱、关闭后焦点恢复、背景滚动锁定),打开时焦点落在输入框,没有标题栏与关闭按钮 —— 搜索行就是面板的头部;宽度受视口边距约束;关闭时清空输入。选中命令后是否收起由调用方在 `onSelect` 里调用自己的关闭逻辑。它自带边框、圆角与浮层阴影,不得再放进 `Dialog`,也不得被 `Card`、`Popover` 或任何带边框的容器包裹。输入框是 `role="combobox"`,以 `aria-activedescendant` 指向高亮项;可访问名取传给本组件的 `aria-label` / `aria-labelledby`(落在输入框上,`dialog` 形态下同时落在模态框上),缺省时回落到 `placeholder`。`CommandGroup.label` 是组件的 React key,必须在整个面板内唯一。`CommandItem.label` 为非字符串时必须提供 `searchText`,否则该项永远不会被筛选命中,且不产生任何报错。`shortcut` 仅作展示,真实快捷键必须由应用层自行注册,两处文本必须一致。
617
633
 
618
634
  **禁止 / 使用边界。**
619
635
  - 不得把该组件直接放进页面内容流,它是浮层面板。
636
+ - 不得把该组件放进 `Dialog` 承载,模态用法一律用 `dialog` 形态。
620
637
  - 不得在 `label` 为非字符串时省略 `searchText`。
621
638
  - 禁止在 `shortcut` 中声明应用层并未注册的按键组合。
622
639
  - 禁止分组标题重名。
@@ -626,14 +643,15 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
626
643
 
627
644
  **用途。** 内容区域上的右键加速器 —— 列表行、卡片、看板块。
628
645
 
629
- **何时使用。** 已在别处可达的记录级动作需要一条更快的路径时使用该组件。条目支持图标、禁用、危险色与分隔线;键盘导航跳过禁用项与分隔线,回车确认,Esc 与外部点击关闭。菜单按点击坐标定位,并在打开后按实测尺寸收回视口内。
646
+ **何时使用。** 已在别处可达的记录级动作需要一条更快的路径时使用该组件。条目支持图标、禁用、危险色与分隔线;键盘导航跳过禁用项与分隔线,回车确认,Esc、Tab、外部点击、任一祖先滚动与窗口尺寸变化都会关闭。高亮项每次打开都清空,不沿用上一次停留的条目。Esc 关闭或选中后,焦点回到打开菜单前持有焦点的元素。菜单按点击坐标定位,并在绘制前按实测尺寸收回视口内。
630
647
 
631
648
  **何时改用其他组件。** 需要一个可见的触发器(上下文区或行尾的「更多」)改用 `DropdownMenu`,它另有 `heading` 字段可渲染分组标题。编辑器型工作面的常驻菜单条改用 `Menubar`。整行可点击的目录或选择器行改用 `Item`,业务记录行改用 `ApplicationRecordList`。
632
649
 
633
- **组合约定。** `children` 是右键触发区域,组件会在其外包一层 `position: relative` 的块级元素;在表格行或网格布局内使用时必须确认该额外层不破坏既有布局。任何动作都不得以右键菜单为唯一入口,记录级动作必须同时出现在行尾或详情中 —— 右键是加速器,不是可达性路径。可点击条目必须提供 `value`,缺少 `value` 的非分隔线条目会渲染出来却永不触发 `onSelect`。`destructive` 只把文字转为 danger 色,不改变确认流程,不可逆动作仍须由 `AlertDialog` 二次确认。`separator` 不得作为首项或末项。
650
+ **组合约定。** `children` 是右键触发区域,组件会在其外包一层 `position: relative` 的块级元素;在表格行或网格布局内使用时必须确认该额外层不破坏既有布局。任何动作都不得以右键菜单为唯一入口,记录级动作必须同时出现在行尾或详情中 —— 右键是加速器,不是可达性路径。可点击条目必须提供 `value`,缺少 `value` 的非分隔线条目会渲染出来却永不触发 `onSelect`。`destructive` 只把文字转为 danger 色,不改变确认流程,不可逆动作仍须由 `AlertDialog` 二次确认。`separator` 不得作为首项或末项。菜单内的点击、指针与键盘事件在菜单根截停,不冒泡到 `children` 及其祖先,因此该组件可以直接包在带 `onOpen` 的可点击记录行内 —— 选中条目不会连带触发行的点击或回车;外层若需要感知菜单动作,必须经 `onSelect` 获取,不得依赖事件冒泡。
634
651
 
635
652
  **禁止 / 使用边界。**
636
653
  - 不得把任何动作只放在右键菜单里。
654
+ - 不得依赖菜单内的点击或按键冒泡到外层元素,菜单动作一律经 `onSelect` 获取。
637
655
  - 禁止嵌套两层 ContextMenu —— 右键事件会冒泡,内外两个菜单将同时打开。
638
656
  - 不得省略可点击条目的 `value`。
639
657
  - 禁止用连续的 `separator` 模拟分组标题,需要标题的菜单改用 `DropdownMenu`。
@@ -643,11 +661,11 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
643
661
 
644
662
  **用途。** 桌面风格的水平菜单条,用于编辑器型工作面 —— 报表设计器、看板配置器。
645
663
 
646
- **何时使用。** 一个工作面同时拥有 2 个及以上顶级菜单、且每个菜单内含多条低频命令时使用该组件。菜单条高 32px、顶级菜单项高 24px、自带 1px 边框与 8px 圆角。菜单条已展开时,鼠标划过其他顶级菜单直接切换,这是桌面菜单的既定惯例。
664
+ **何时使用。** 一个工作面同时拥有 2 个及以上顶级菜单、且每个菜单内含多条低频命令时使用该组件。菜单条高 32px、顶级菜单项高 24px、自带 1px 边框与 8px 圆角。菜单条已展开时,鼠标划过其他顶级菜单直接切换,这是桌面菜单的既定惯例。键盘按 WAI-ARIA menubar 模式:菜单条只有一个 Tab 停靠点,← / → 在顶级菜单项间循环,Home / End 跳到首末项;Enter / 空格 / ↓ 打开并高亮首个可用项,↑ 打开并高亮末项;面板内 ↑ / ↓ / Home / End 移动并跳过禁用项,Enter / 空格选中并收起,← / → 切到相邻顶级菜单并打开;选中与 Esc 后焦点回到顶级菜单项,Tab 收起面板并离开菜单条。
647
665
 
648
666
  **何时改用其他组件。** 只有一个下拉时改用 `DropdownMenu`。页面或区域之间的导航改用 `NavigationMenu`、`Tabs` 或 `Sidebar`。应用二级导航改用 `ApplicationSecondaryNavigation`。右键加速器改用 `ContextMenu`。
649
667
 
650
- **组合约定。** 该组件只能位于 Content Canvas 内部,Shell 拥有自己的导航,不承载菜单条。`MenubarMenu.label` 同时是 React key 与展开态标识,必须在菜单条内唯一,重名会导致两个菜单同时展开。组件不接受子元素,顶级菜单只能来自 `menus` 数组 —— 不得在菜单项之间插入其他控件;工具按钮应放在菜单条之外的同一行容器内,间距由该容器负责。可点击条目必须提供 `value`。`shortcut` 仅作展示,真实按键绑定由承载它的工作面自行注册。
668
+ **组合约定。** 该组件只能位于 Content Canvas 内部,Shell 拥有自己的导航,不承载菜单条。`MenubarMenu.label` 是顶级菜单的 React key,必须在菜单条内唯一,重名会导致面板挂载错乱。组件不接受子元素,顶级菜单只能来自 `menus` 数组 —— 不得在菜单项之间插入其他控件;工具按钮应放在菜单条之外的同一行容器内,间距由该容器负责。可点击条目必须提供 `value`。`shortcut` 仅作展示,真实按键绑定由承载它的工作面自行注册。
651
669
 
652
670
  **禁止 / 使用边界。**
653
671
  - 不得用作页面导航,那是 Shell 的职责。
@@ -660,11 +678,11 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
660
678
 
661
679
  **用途。** 水平导航基元,条目可展开一个富内容浮层面板。
662
680
 
663
- **何时使用。** 页面区域之间的水平切换,且部分入口需要展开二级内容时使用该组件。激活态是 2px 强调色下划线加 medium 字重,条目高 32px、横向内边距 12px。面板在悬停或聚焦时展开,最小宽 320px,12px 圆角,带浮层阴影。
681
+ **何时使用。** 页面区域之间的水平切换,且部分入口需要展开二级内容时使用该组件。激活态是 2px 强调色下划线加 medium 字重,条目高 32px、横向内边距 12px。面板在悬停、聚焦或点击时展开,Esc 收起(焦点在面板内时回到条目),最小宽 320px,12px 圆角,带浮层阴影。
664
682
 
665
- **何时改用其他组件。** 应用二级导航一律改用 `ApplicationSecondaryNavigation` —— 那里每个业务标签强制「图标 + 文字」并由类型强制,本基元不施加该约束。同一页内切换内容区改用 `Tabs`,它另有 `count` 徽标与面板槽位。垂直排列的导航面改用 `Sidebar`。编辑器型工作面的命令菜单改用 `Menubar`。
683
+ **何时改用其他组件。** 应用二级导航一律改用 `ApplicationSecondaryNavigation` —— 那里每个业务标签强制「图标 + 文字」并由类型强制,本基元不施加该约束。同一页内切换内容区、且没有条目需要展开面板时改用 `Tabs`(它另有 `count` 徽标与面板槽位)或 `ToggleGroup`。垂直排列的导航面改用 `Sidebar`。编辑器型工作面的命令菜单改用 `Menubar`。
666
684
 
667
- **组合约定。** 面板从条目左边缘向右展开,组件不做视口碰撞翻转,因此带 `panel` 的条目不得放在导航行的最右端。面板的开合是组件内部状态,没有对应的 prop,调用方不得试图从外部控制。鼠标移出条目槽位即收起面板,与焦点无关,因此 `panel` 内不得放置需要多步操作的表单。`NavigationMenuItem` 没有禁用字段 —— 无权限的入口必须从 `items` 中移除,不得渲染成看似可点的项。受控使用时 `value` 与 `onValueChange` 必须成对提供。组件自身无外边距,与相邻内容的间距由容器负责。
685
+ **组合约定。** 面板从条目左边缘向右展开,组件不做视口碰撞翻转,因此带 `panel` 的条目不得放在导航行的最右端。面板的开合是组件内部状态,没有对应的 prop,调用方不得试图从外部控制。鼠标移出条目槽位 150ms 后收起面板(其间移入面板即取消),与焦点无关,因此 `panel` 内不得放置需要多步操作的表单。激活项标 `aria-current`,取值由 `current` 决定:条目各自对应一个页面时用默认的 `"page"`;条目只切换同一页面内的区域或主题时必须传 `current="true"`,否则读屏会把它报成「当前页面」。`NavigationMenuItem` 没有禁用字段 —— 无权限的入口必须从 `items` 中移除,不得渲染成看似可点的项。受控使用时 `value` 与 `onValueChange` 必须成对提供。组件自身无外边距,与相邻内容的间距由容器负责。
668
686
 
669
687
  **禁止 / 使用边界。**
670
688
  - 不得用作应用二级导航。
@@ -672,16 +690,17 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
672
690
  - 不得把带 `panel` 的条目放在行末。
673
691
  - 不得在 `panel` 内放置输入框、多步表单或分页控件。
674
692
  - 不得渲染无权限的条目。
693
+ - 不得在页内切换时沿用默认的 `current`(`"page"`)。
675
694
 
676
695
  ## Pagination
677
696
 
678
697
  **用途。** 裸分页步进器,只承担页码窗口与翻页。
679
698
 
680
- **何时使用。** 仅在确实不需要结果总数与每页条数时使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。当前页带 `aria-current="page"`、强调色描边与淡强调色底,不只靠颜色表达。按钮高 28px,页码使用等宽数字,翻页时按钮不左右跳动。
699
+ **何时使用。** 仅在确实不需要结果总数与每页条数时使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。当前页带 `aria-current="page"`、强调色描边与淡强调色底,不只靠颜色表达。页码按钮视觉上只显示数字,可访问名为「第 N 页」。按钮高 28px,页码使用等宽数字,翻页时按钮不左右跳动。
681
700
 
682
701
  **何时改用其他组件。** 数据展示区的列表与表格页脚一律改用 `ListTablePagination`,它额外承载结果区间、总数与每页条数选择器。两者是替代关系而非包含关系:`ListTablePagination` 的形态是「上一页 · 当前页/总页数 · 下一页」两键步进,不渲染页码窗口。系统内无限滚动不作为分页的替代方案。
683
702
 
684
- **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染两枚禁用的翻页按钮与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态必须跨 Page Mode 与 Business View 切换存活,从详情返回时也必须还原,该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
703
+ **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染两枚禁用的翻页按钮与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态在数据展示区内的规则与 `ListTablePagination` 相同(按业务视图各记一份,搜索、筛选、排序变化时复位到第 1 页,07 · C-13),该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
685
704
 
686
705
  **禁止 / 使用边界。**
687
706
  - 不得在列表或表格的标准页脚使用该组件。
@@ -692,13 +711,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
692
711
 
693
712
  ## Sidebar
694
713
 
695
- **用途。** Content Canvas 内部的垂直导航面 —— 设置导航、模块子导航。
714
+ **用途。** Content Canvas 内部的垂直导航面 —— 设置页目录。SPLIT 页面模式的左栏不用本组件,一律用 `ApplicationSplitListSidebar`(07 · C-15)。
696
715
 
697
716
  **何时使用。** 一个工作面需要按分组罗列 5 项及以上的垂直入口时使用该组件。展开宽默认 240px,折叠宽固定 56px,导航项高 36px,分组标题 12/16。选中态是淡强调色洗加强调色文字加 medium 字重,字重是颜色之外的第二信号。
698
717
 
699
718
  **何时改用其他组件。** 工作台左侧 72px 图标栏改用 `GlobalSidebar`,它由 `SidebarRailButton` 构成,是另一个组件,两者不可互相替代。SPLIT 页面模式的左栏改用 `ApplicationSplitListSidebar`,它已登记目录搜索、结果数与目录设置三件事。水平方向的导航改用 `NavigationMenu` 或 `Tabs`。
700
719
 
701
- **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏四带堆叠,不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态的悬浮提示不可用。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
720
+ **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏四带堆叠,不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态条目既无可访问名也无提示。折叠态条目以 `aria-label` 命名,并由内置 `Tooltip` 在悬停与聚焦时向右提示同一名称,调用方不得再包一层 `Tooltip`。有标题的分组输出以标题命名的 `role="group"`。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
702
721
 
703
722
  **禁止 / 使用边界。**
704
723
  - 不得把该组件当作应用外层 Shell 的全局左栏。
@@ -711,11 +730,11 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
711
730
 
712
731
  **用途。** 页面区域内的局部标签页 —— SPLIT 右栏内容标签、详情分节切换。
713
732
 
714
- **何时使用。** 同一块区域内需要在 2 个及以上互斥内容之间切换时使用该组件。标签高 32px、内边距 6/12、文字 14/20,激活态是 2px 强调色下划线加 medium 字重,明确不是 pill 背景。标签行下方有 1px 分隔线,`count` 徽标为 12px 等宽数字。左右方向键在标签之间移动焦点,选中须再按回车或空格。
733
+ **何时使用。** 同一块区域内需要在 2 个及以上互斥内容之间切换时使用该组件。标签高 32px、内边距 6/12、文字 14/20,激活态是 2px 强调色下划线加 medium 字重,明确不是 pill 背景。标签行下方有 1px 分隔线,`count` 徽标为 12px 等宽数字。标签行只占一个 Tab 停靠点,左右方向键在可用标签之间移动焦点、首尾相接,Home / End 跳到首末项,选中须再按回车或空格;焦点离开后停靠点回到选中标签。
715
734
 
716
735
  **何时改用其他组件。** Shell 第三带的业务标签改用 `ApplicationSecondaryNavigation`,那里的图标是必填。L3 业务视图标签由 `ApplicationQueryToolbar` 承担,其第一行内部已组合本组件,不得在工具栏之外另起一行 Tabs 表达业务视图。Page Mode Switch 属于 `ApplicationPageHeader`,不得用 Tabs 或 `ToggleGroup` 搭建。密度、对齐这类局部显示选择改用 `ToggleGroup`。带浮层面板的水平导航改用 `NavigationMenu`。
717
736
 
718
- **组合约定。** `children` 原样渲染,组件不做面板切换 —— 调用方必须自行依据当前 `value` 渲染对应内容。面板的 12px 上边距由组件负责,调用方不得再补上边距。`items` 为空数组时整个组件渲染 `null`,不渲染空标签行、不画分隔线、不保留高度,因此调用方不得为「暂无标签」另行渲染占位。未提供 `defaultValue` 时组件默认选中 `items[0].value` 且不检查其禁用状态,`items[0]` 为 `disabled` 时必须显式提供 `defaultValue`。受控使用时 `value` 与 `onValueChange` 必须成对提供。`count` 只接受数字。
737
+ **组合约定。** `children` 原样渲染,组件不做面板切换 —— 调用方必须自行依据当前 `value` 渲染对应内容。面板的 12px 上边距由组件负责,调用方不得再补上边距。根与面板都是列向 flex,面板吃掉根的剩余高度:要让面板内的 `ApplicationDataDisplay` 拿到有界高度、自己滚动,调用方只需让 Tabs 根在定高父级里拿到高度(给根加 `flex: 1; min-block-size: 0` 的类名),不得再在面板外另造一个 `role="tabpanel"` 容器;面板的直接子节点各成一个 flex 项,行内混排的文字须包一层块级元素。可访问名称以 `aria-label` 或 `aria-labelledby` 传入,组件把它落在 `role="tablist"` 上;渲染面板时激活标签与面板以 `aria-controls` / `aria-labelledby` 互相关联,调用方不必补。`items` 为空数组时整个组件渲染 `null`,不渲染空标签行、不画分隔线、不保留高度,因此调用方不得为「暂无标签」另行渲染占位。未提供 `defaultValue` 时组件默认选中 `items[0].value` 且不检查其禁用状态,`items[0]` 为 `disabled` 时必须显式提供 `defaultValue`。受控使用时 `value` 与 `onValueChange` 必须成对提供。`count` 只接受数字。
719
738
 
720
739
  **禁止 / 使用边界。**
721
740
  - 不得用作 Shell 的二级导航。
@@ -757,11 +776,11 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
757
776
  - 承载的是可折叠的分节 —— 改用 `Collapsible`;多个互斥折叠项改用 `Accordion`。
758
777
  - 承载的是一行可扫视的记录 —— 改用 `Item` 或 `ApplicationRecordList`。
759
778
 
760
- **组合约定。** 本组件不持有外边距,卡片之间的间距(Standard 12px、Condensed 10px、Compact 8px)由父级栅格或 `ApplicationPageLayoutContainer` 负责。`title` 与 `extra` 同处标题行,`extra` 只放一个状态 `Badge` 或一个安静的动作。`footer` 自带上边框与一段上内边距,不需要再在它上面放 `Separator`。`interactive` 只是把光标与边框反馈打开,跳转行为仍由调用方自己挂在卡片上 —— 因此 `interactive` 为 true 时必须同时给出真实的跳转处理,只设 `interactive` 而不跳转会得到一个骗人的指针。`interactive` 为 true 时卡内不得再放独立的可点控件,除非该控件自行阻止事件冒泡。
779
+ **组合约定。** 本组件不持有外边距,卡片之间的间距(Standard 12px、Condensed 10px、Compact 8px)由父级栅格或 `ApplicationPageLayoutContainer` 负责。`title` 与 `extra` 同处标题行,`extra` 只放一个状态 `Badge` 或一个安静的动作。内边距与内部间隙随视口密度档自动收紧:`default` 为 Standard 16px、Condensed 12px、Compact 10px,`sm` 为 12px、Compact 10px,由 token 层的 `@media` 驱动,调用方不得另写断点改卡片内边距。`footer` 自带上边框与一段上内边距,不需要再在它上面放 `Separator`。`interactive` 只是把光标与边框反馈打开,跳转行为仍由调用方自己挂在卡片上 —— 因此 `interactive` 为 true 时必须同时给出真实的跳转处理(`onClick`),只设 `interactive` 而不跳转会得到一个骗人的指针。`interactive` 且给了 `onClick` 时组件自带键盘入口:标题读作按钮、进 Tab 序列,Enter / 空格触发同一个 `onClick`,焦点环画在整张卡上;无标题时整卡可聚焦。调用方不得再自行补 `tabIndex` / `role` / `onKeyDown` —— 显式传入 `tabIndex` 或 `role` 即视为接管,组件不再加自己那一份。标题行最小高度 32px,有无 `extra` 都一样高。`interactive` 为 true 时卡内不得再放独立的可点控件,除非该控件自行阻止事件冒泡。
761
780
 
762
781
  **禁止 / 使用边界。**
763
782
  - 不得给卡片添加阴影 —— 已登记契约为 16px 圆角、1px 边框、无默认装饰阴影,边框负责分隔。
764
- - 禁止发明第三档密度:只有 `default`(16px 节奏)与 `sm`(12px)两档。
783
+ - 禁止发明第三档密度:只有 `default`(16px 节奏)与 `sm`(12px)两档,随视口收紧的是这两档的取值,不是新的档。
765
784
  - 不得在只读的指标卡语义上设置 `interactive` —— 指标卡必须保持 `cursor: default`,整卡绝不成为导航入口。
766
785
  - 不得在 Card 外面再包一层自带 padding 的容器,那会与页面内容根的内边距叠成双重外边距。
767
786
 
@@ -777,7 +796,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
777
796
  - 只是一条需要横向滚动的标签条或筛选条 —— 改用 `ScrollArea` 并设 `horizontal`。
778
797
  - 内容是消息流 —— 改用 `MessageScroller` 配 `Bubble` 或 `Message`。
779
798
 
780
- **组合约定。** `slides` 的每一项占满一页宽度,各项应当结构同构、高度一致,否则翻页会带来容器高度跳动。`index` 与 `defaultIndex` 二选一:给了 `index` 即进入受控模式,此时必须同时提供 `onIndexChange`,否则页索引永远停在初始值。本组件不持有外边距,与相邻区块的间隙由父级负责。左右导航按钮与页点绝对定位在内容之上,因此 `slides` 内容的四角区域不应放置必须可点的元素。页点带 `aria-hidden`,页序信息不由它传达。
799
+ **组合约定。** `slides` 的每一项占满一页宽度;各页高度由本组件取最高的一页统一撑开,翻页时容器高度不跳,调用方不必让各页等高,也不必为此把正文截成固定行数。`index` 与 `defaultIndex` 二选一:给了 `index` 即进入受控模式,此时必须同时提供 `onIndexChange`,否则页索引永远停在初始值。本组件不持有外边距,与相邻区块的间隙由父级负责。左右导航按钮与页点绝对定位在内容之上,因此 `slides` 内容的四角区域不应放置必须可点的元素。页点带 `aria-hidden`,页序信息由每页的名称「第 N 页,共 M 页」传达。根是 `aria-roledescription="carousel"` 的 `region`,名称应以 `aria-label` 或 `aria-labelledby` 传入,缺省为「轮播」。焦点在轮播内时 ← / → 翻页(文本框内除外),不在当前页的各页不可聚焦。
781
800
 
782
801
  **禁止 / 使用边界。**
783
802
  - 禁止用定时器驱动 `onIndexChange` 模拟自动播放 —— 系统动效只表达状态变化,无入场编排与自动轮转。
@@ -818,7 +837,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
818
837
  - 需要的是三栏工作台 —— 改用 `ContactsCollaborationWorkspace`、`FilesCollaborationWorkspace`、`ScheduleCollaborationWorkspace`,三栏外壳已在这三者中收敛。
819
838
  - 两栏宽度固定、用户无需调整 —— 不使用本组件,直接由页面布局承担。
820
839
 
821
- **组合约定。** 本组件不持有外边距,与相邻区块的间隙由父级负责。`size` 与 `defaultSize` 二选一:给了 `size` 即进入受控模式,此时必须同时提供 `onSizeChange`,否则分隔条拖不动。`min` 与 `max` 应成对给出,且必须落在调用方界面真实可用的范围内 —— 组件会把宽度钳制在这两个值之间。两个栏位均裁剪溢出,因此需要滚动的内容必须自带有界滚动容器(`ScrollArea` 或 `MessageScroller`),不得指望栏位自己滚。分隔条是 5px 宽的命中区并带焦点环,其两侧不得再叠加其他绝对定位元素。
840
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由父级负责。`size`、`defaultSize`、`min`、`max` 收数字或 CSS 长度字符串:数字按 px,字符串原样交给 CSS。左栏要跟随密度档(360 / 300)时传 `'var(--ui-sidebar-list-width)'`,不得在挂载时读出 token 的像素值再传数字 —— 那样换档后不跟随。拖拽与方向键调整后 `onSizeChange` 回传的恒为 px 数字(按调整那一刻的渲染宽度换算,已钳在 `min`–`max` 之间);受控方写回之后该栏不再跟随原字符串,要恢复跟随须把 `size` 写回原字符串。`min` 与 `max` 只约束拖拽与方向键,不钳制调用方写进 `size` 的值。`size` 与 `defaultSize` 二选一:给了 `size` 即进入受控模式,此时必须同时提供 `onSizeChange`,否则分隔条拖不动。`min` 与 `max` 应成对给出,且必须落在调用方界面真实可用的范围内 —— 组件会把宽度钳制在这两个值之间。两个栏位均裁剪溢出,因此需要滚动的内容必须自带有界滚动容器(`ScrollArea` 或 `MessageScroller`),不得指望栏位自己滚。分隔条是 5px 宽的命中区并带焦点环,其两侧不得再叠加其他绝对定位元素。分隔条的可访问名为「分栏宽度」,`aria-valuenow` 取整数像素。
822
841
 
823
842
  **禁止 / 使用边界。**
824
843
  - 不得让拖动分栏改变 `pageMode` —— 它只是布局调整,与页面模式无关。
@@ -836,12 +855,12 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
836
855
  - 滚动的是消息流 —— 改用 `MessageScroller`,它是消息流已登记的有界滚动容器并自带贴底行为。
837
856
  - 溢出的是表格的横向内容 —— 不使用本组件,`Table` 自身已持有横向滚动。
838
857
  - 需要的是固定比例的槽位而非滚动 —— 改用 `AspectRatio`。
839
- - 页面主体内容超出视口 —— 不使用本组件,Content Canvas 是页面唯一的垂直滚动持有者。
858
+ - 页面主体内容超出视口 —— 不使用本组件,页面级纵向滚动的归属按页型划分,见 SKILL.md「五层 Canvas 模型 · 纵向滚动归属」。
840
859
 
841
- **组合约定。** `height` 与 `maxHeight` 传数字时按 px 解释;两者可同时缺省,但缺省的垂直 ScrollArea 等于没有约束。`horizontal` 为 true 时垂直方向为 `hidden` —— 单个 ScrollArea 只承担一个方向,需要两个方向必须重新设计布局而不是嵌套两层。本组件不持有内边距与外边距,内容的留白由被包裹的内容自身负责。被包裹内容若自带外边距,滚动区末尾会出现视觉上的空白,应改由内容内部处理。
860
+ **组合约定。** `height` 与 `maxHeight` 传数字时按 px 解释;两者可同时缺省,但缺省的垂直 ScrollArea 等于没有约束。`horizontal` 为 true 时垂直方向为 `hidden` —— 单个 ScrollArea 只承担一个方向,需要两个方向必须重新设计布局而不是嵌套两层。唯一的登记例外是看板(07 · C-14):外层 `horizontal` 只管横向,列内各一个纵向 ScrollArea,写法见 SKILL.md「五层 Canvas 模型 · 呈现配方」。本组件不持有内边距与外边距,内容的留白由被包裹的内容自身负责。被包裹内容若自带外边距,滚动区末尾会出现视觉上的空白,应改由内容内部处理。`horizontal` 且内容确实溢出时,区域本身成为 Tab 停靠点并以 `region` 暴露,调用方应以 `aria-label` 写明区域内容(缺省为「横向滚动区域」);不溢出时不加停靠点。该组件为测量溢出带 `"use client"`。
842
861
 
843
862
  **禁止 / 使用边界。**
844
- - 禁止在 Content Canvas 内堆叠无界的垂直滚动容器 —— Content Canvas 是唯一的垂直滚动权持有者。
863
+ - 禁止在 Content Canvas 内堆叠无界的垂直滚动容器 —— 每个页面只有一个页面级纵向滚动持有者,按页型划分。
845
864
  - 不得用本组件包裹 `ApplicationPageLayoutContainer` 或 `ApplicationDataDisplay`,那会制造第二个页面级垂直滚动。
846
865
  - 不得在同一个 ScrollArea 上同时开启两个滚动方向。
847
866
  - 不得用本组件包裹 `Table` 以求横向滚动 —— 会得到两层横向滚动条。
@@ -858,7 +877,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
858
877
  - 需要的是菜单条目之间的分隔 —— 不使用本组件,`DropdownMenu` 的条目数据自带分隔线形态。
859
878
  - 需要的是表格行之间的分隔 —— 不使用本组件,`Table` 自带 1px 行分隔线。
860
879
 
861
- **组合约定。** 本组件自己持有两侧外边距,默认一档 12px,调用方通过 `spacing` 调整。`spacing` 必须传 token(如 `var(--ds-space-2)`)或数字,不得传字面 px 字符串。因为外边距归本组件所有,相邻元素不得再为分隔线补 margin —— 否则得到双份间距。`orientation` 为 `vertical` 时需要父容器有确定高度,实际做法是把它放进一个 `align-items: stretch` 的 flex 行;父容器高度不确定时垂直线不可见。带 `label` 的形态只用于分段标题,`label` 应是 2–4 字裸名词短语。
880
+ **组合约定。** 本组件自己持有两侧外边距,默认一档 12px,调用方通过 `spacing` 调整。`spacing` 必须传 token(如 `var(--application-space-2)`)或数字,不得传字面 px 字符串。因为外边距归本组件所有,相邻元素不得再为分隔线补 margin —— 否则得到双份间距。`orientation` 为 `vertical` 时需要父容器有确定高度,实际做法是把它放进一个 `align-items: stretch` 的 flex 行;父容器高度不确定时垂直线不可见。带 `label` 的形态只用于分段标题,`label` 应是 2–4 字裸名词短语。
862
881
 
863
882
  **禁止 / 使用边界。**
864
883
  - 不得用本组件替代 `Card` 的 `footer` 上边框 —— `footer` 已自带上边框与上内边距。
@@ -879,7 +898,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
879
898
  - 只是一组同构的目录行,无列对齐需求 —— 改用 `Item`。
880
899
  - 需要手写 `<table>` / `<tr>` / `<td>` —— 一律改用本组件,手写表格拿不到已登记的表头底色、行分隔线与列宽约定。
881
900
 
882
- **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。`rows` 为空时必须提供 `empty`,且应当传 `<Empty />`。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。
901
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `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`。
883
902
 
884
903
  **禁止 / 使用边界。**
885
904
  - 禁止手写 `<tr>` / `<td>` 作为子元素传入 —— 本组件不接受复合子组件,列与行只能来自 `columns` 与 `rows`。
@@ -897,13 +916,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
897
916
  **何时改用其他组件。**
898
917
  - 状态是 Loading —— 改用 `Skeleton`,且骨架必须贴近最终结构;短时的原地等待改用 `Spinner`。
899
918
  - 状态是 Error、No Permission 或 Not Found —— 仍可用本组件渲染节点,但文案必须各自独立;`ApplicationDataDisplay` 为这四种状态各留了独立槽位,不得共用同一个节点。
900
- - 状态是 Partial Failure —— 改用 `Alert`,它就地提示、提供重试,且不阻断主任务。
919
+ - 状态是 Partial Failure —— 改用 `Alert`,它就地提示、提供重试,且不阻断主任务;数据区里经 `ApplicationDataDisplay` 的 `notice` 槽位放置。
901
920
  - 需要的是不可逆动作的阻塞确认 —— 改用 `AlertDialog`。
902
921
 
903
922
  **组合约定。** `title` 没有默认值,调用方必须自己写出这一句 —— 组件刻意不提供泛化兜底。本组件自带内边距并居中排布,父容器不得再为它补内边距;说明文字限宽 320px,超出部分自动换行。`icon` 应传 `Icon` 组件并取已登记尺寸档,以弱化前景色显示。`action` 只在调用方确有权限创建缺失之物时提供,且按钮文案是 2–4 字裸名词短语(`新建`、`重置`)。用作 `Table` 的 `empty` 或 `ApplicationDataDisplay` 的 `empty` 槽位时,应设 `compact`。
904
923
 
905
924
  **禁止 / 使用边界。**
906
- - 禁止让 Empty 与 Error、No Permission、Not Found 共用同一句文案 ——「当前口径下无数据」「你没有权限」「未找到该记录」「请求失败」是四句不同的话。
925
+ - 禁止让 Empty 与 Error、No Permission、Not Found 共用同一句文案 ——「当前口径下无数据」「无权查看本模块」「未找到该记录」「请求失败」是四句不同的话。
907
926
  - 不得写「暂无数据」这类不带口径的泛化措辞。
908
927
  - 不得在数据仍在加载时渲染本组件,Loading 有它自己的节点。
909
928
  - 禁止在空态中出现 Emoji、插画或装饰图形。
@@ -913,7 +932,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
913
932
 
914
933
  **用途。** 人员或组织的身份标记,承载头像图片或其文字缩写回退。
915
934
 
916
- **何时使用。** 人员选择器、联系人列表、审计轨迹、记录负责人处必须使用该组件表达身份。已登记档位为 24 / 32 / 40px,与控件高度标尺同值,因此该组件与同行的按钮、输入框天然等高。无图片时该组件回退为文字缩写:中文名取首字,拉丁名按空格分词取各词首字母(最多两个)。人员用 `circle`,组织用 `rounded`。
935
+ **何时使用。** 人员选择器、联系人列表、审计轨迹、记录负责人处必须使用该组件表达身份。已登记档位为 24 / 32 / 40px,与控件高度标尺同值,因此该组件与同行的按钮、输入框天然等高。无图片时该组件回退为文字缩写:含中文的名字取末字(「张伟」→「伟」,占位符「成员 A」→「A」),拉丁名按空格分词取各词首字母(最多两个)。取末字而非首字,是因为同姓者与同一占位符前缀下的头像取首字时缩写全相同。人员用 `circle`,组织用 `rounded`。
917
936
 
918
937
  **何时改用其他组件。**
919
938
  - 应用身份与品牌区不属于本组件,由 `ApplicationPrimaryNavigation` 的 logo 瓦片承担,该瓦片是 8% 强调色混入表面色,绝不是饱和强调色块。
@@ -921,7 +940,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
921
940
  - 纯内容字形改用 `Icon`,字形必须取自已登记清单。
922
941
  - 身份加标题加描述构成的整行改用 `Item`,本组件放进它的 `leading` 槽位。
923
942
 
924
- **组合约定。** 传 `src` 时必须同时传 `name` —— `name` 同时充当图片替代文本与悬浮提示,缺失即该头像对读屏软件不可读。该组件已自带 `title`,调用方不得再包一层 `Tooltip`(`Tooltip` 的职责是为纯图标控件命名)。外边距由宿主槽位负责:`Item` 的 `leading`、`Message` 的 `avatar`、三栏工作台的成员行;本组件自身不带 margin,也不参与换行。`ContactsCollaborationWorkspace` 与 `PeoplePickerDialog` 的成员行已内置 24px 头像,调用方不再另行渲染。`size` 传任意数字会绕开标尺,仅当确实无法落到 24 / 32 / 40 时使用。同一列表内 `shape` 必须统一。
943
+ **组合约定。** 传 `src` 时必须同时传 `name` —— `name` 充当图片替代文本,缺失即该头像对读屏软件不可读。该组件不渲染原生 `title`(否则放进 `HoverCard` 触发区时会叠出两层提示),调用方也不得再包一层 `Tooltip`(`Tooltip` 的职责是为纯图标控件命名)。头像紧挨着可见姓名时应传 `aria-hidden`,免得读屏把缩写或姓名多读一遍。外边距由宿主槽位负责:`Item` 的 `leading`、`Message` 的 `avatar`、三栏工作台的成员行;本组件自身不带 margin,也不参与换行。`ContactsCollaborationWorkspace` 与 `PeoplePickerDialog` 的成员行已内置 24px 头像,调用方不再另行渲染。`size` 传任意数字会绕开标尺,仅当确实无法落到 24 / 32 / 40 时使用。同一列表内 `shape` 必须统一。
925
944
 
926
945
  **禁止 / 使用边界。**
927
946
  - 不得用 Emoji、系统字体符号或装饰性字形代替头像。
@@ -933,7 +952,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
933
952
 
934
953
  **用途。** 紧凑的状态或分类标签,20px 高、4px 圆角、12/16 字号。
935
954
 
936
- **何时使用。** 列表行、卡片、指标、详情头需要一个短状态词或分类词时,必须使用该组件。`RecordListItem` 与 `WorkspacePerson` 的 `status` 槽位、`Card` 的 `extra` 槽位、`Item` 的 `trailing` 槽位登记的默认内容即为本组件。`tone` 的六档全部来自功能状态色板,一个 tone 在整个产品内只能有一个含义。
955
+ **何时使用。** 列表行、卡片、指标、详情头需要一个短状态词或分类词时,必须使用该组件。`RecordListItem` 与 `WorkspacePerson` 的 `status` 槽位、`Card` 的 `extra` 槽位、`Item` 的 `trailing` 槽位登记的默认内容即为本组件。`tone` 的六档全部来自功能状态色板,一个 tone 在同一维度内只能有一个含义。
937
956
 
938
957
  **何时改用其他组件。**
939
958
  - 指标区里的「功能状态 + 计数」改用 `ApplicationMetricStatus`,该卡由圆点、文字、颜色三者共同承载状态。
@@ -942,12 +961,12 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
942
961
  - 一级导航上的未读提示改用 `ApplicationPrimaryNavigation` 的 `actionBadges` 圆点;消息条目的未读态改用 `Message` 的 `unread`。
943
962
  - 键盘按键提示改用 `Kbd`,二者同为 20px 高,语义不同,不得互换。
944
963
 
945
- **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`variant="outline"` 的边框取 tone 的语义色,而 `warning` 的前景为保证对比度取中性色,这是已裁决的刻意不同构(04 · D3),应用侧不得把前景「修正」回同色系。`children` 必须是 2–4 字裸名词短语。
964
+ **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。tone 只在同一维度内含义唯一:同屏出现两个状态维度(如处理状态与风险等级)时,用 `variant` 区分维度 —— 一个维度用 `soft`(淡色实底),另一个用 `outline`(描边),两个维度可以各用到同一个 tone(07 · C-9);同一维度内的不同取值不得共用 tone。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`variant="outline"` 的边框取 tone 的语义色,而 `warning` 的前景为保证对比度取中性色,这是已裁决的刻意不同构(04 · D3),应用侧不得把前景「修正」回同色系。`children` 必须是 2–4 字裸名词短语。
946
965
 
947
966
  **禁止 / 使用边界。**
948
967
  - 不得用图表分类色表达状态 —— 分类色只编码分类。
949
968
  - 禁止给本组件绑定点击或做成可移除标签。
950
- - 不得在不同页面给同一 tone 指派不同含义。
969
+ - 不得在不同页面给同一维度的同一 tone 指派不同含义。
951
970
  - 不得用本组件承载多行文字、长句或数值单位说明。
952
971
 
953
972
  ## Bubble
@@ -974,7 +993,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
974
993
 
975
994
  **用途。** 折线、面积、柱状三型的示意图基元,用于读趋势形状。
976
995
 
977
- **何时使用。** ANALYSIS 分析页、报表摘要,以及关注走势形状而非精确读数的位置,应使用该组件。系列配色按 `series` 的数组顺序取自共享的 20 色分类色板(`hsl(H, 24%, 53%)`,H 每 18 度一步),同亮度设计使整组图表读起来是一家人。该组件是示意图基元,不是精确图表。
996
+ **何时使用。** ANALYSIS 分析页、报表摘要,以及关注走势形状而非精确读数的位置,应使用该组件。系列配色取自共享的 20 色分类色板(`hsl(H, 24%, 53%)`,H 每 18 度一步),按系列数跳步取色:共 n 条系列时从 01 号色起每隔 ⌊20/n⌋ 号取一色,2 条相差 180 度、3 条相差 108 度,11 条起才逐号取。同亮度设计使整组图表读起来是一家人。该组件是示意图基元,不是精确图表。
978
997
 
979
998
  **何时改用其他组件。**
980
999
  - 指标卡内的迷你走势改用 `ApplicationMetricChart`。二者是两个组件:本组件是 Foundation 绘图基元,后者是 Application Module 的只读指标卡,自带卡片壳、指标名与主数值,不得互换。
@@ -982,11 +1001,11 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
982
1001
  - 需要逐值读数的明细改用 `Table`。
983
1002
  - 需要坐标轴刻度、交互取值、精确对齐的真实图表时,系统内无对应组件,必须按 02 §9 规则 9 记为规范缺口上报,不得把本基元调准来顶替。
984
1003
 
985
- **组合约定。** `series` 必填,各系列的 `data` 长度应一致;配色按数组顺序分配,因此跨页面比较同一组数据时系列顺序必须固定,否则同一业务口径会换色。该组件不渲染标题,可访问名称由调用方在根节点以 `aria-label` 给出。作为 Canvas 的 Data Presentation 使用时,图表由 `ApplicationDataDisplay` 承载,其呈现设置按钮属于 `ApplicationQueryToolbar` 且文案必须写作「图表设置」,通用的「视图设置」被明令禁止。Loading / Empty / Error / No Permission / Not Found 五种状态各有各的槽位,全部由 `ApplicationDataDisplay` 承担,本组件自身不渲染任何状态节点。外边距由宿主区域负责;`height` 只控制绘图区,标签行与图例在其下方另占高度。
1004
+ **组合约定。** `series` 必填,各系列的 `data` 长度应一致;配色由数组顺序与系列总数共同决定,因此跨页面比较同一组数据时系列顺序与条数都必须固定,否则同一业务口径会换色。该组件不渲染标题,根节点是 `role="figure"`,可访问名称由调用方在根节点以 `aria-label`(或 `aria-labelledby`)给出;绘图 svg 对读屏器隐藏,标签行与图例文字保持可读,因此名称应概括图表主题(如「近 6 月收入走势」),不必复述图例。作为 Canvas 的 Data Presentation 使用时,图表由 `ApplicationDataDisplay` 承载,其呈现设置按钮属于 `ApplicationQueryToolbar` 且文案必须写作「图表设置」,通用的「视图设置」被明令禁止。Loading / Empty / Error / No Permission / Not Found 五种状态各有各的槽位,全部由 `ApplicationDataDisplay` 承担,本组件自身不渲染任何状态节点。外边距由宿主区域负责;`height` 只控制绘图区,标签行与图例在其下方另占高度。
986
1005
 
987
1006
  **禁止 / 使用边界。**
988
1007
  - 不得用分类色表达状态 —— 红色系列不等于危险,状态一律交给 `Badge` 或 `ApplicationMetricStatus`。
989
- - 不得把 `labels` 当作与数据点一一对齐的刻度:标签沿轴均分排布,这是已裁决接受的限制(04 · D6)。
1008
+ - 不得把 `labels` 当作与数据点一一对齐的刻度:折线与面积图的标签沿轴均分排布,这是已裁决接受的限制(04 · D6);柱状图的标签按等宽列居中,只在标签数等于类目数时落在柱组中心。标签不折行,放不下时以省略号截断。
990
1009
  - 禁止依赖柱宽的视觉比例做判断,非等比拉伸会使柱宽随容器宽高比变形。
991
1010
  - 不得给图表添加图例之外的装饰、渐变或阴影。
992
1011
 
@@ -1005,7 +1024,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1005
1024
 
1006
1025
  **禁止 / 使用边界。**
1007
1026
  - 不得用本组件承载状态、计数、标签等非按键内容。
1008
- - 禁止在本组件上绑定点击 —— 它是提示,真实触发一律交给 `Button`。
1027
+ - 禁止在本组件上绑定点击 —— 它是提示,真实触发一律交给 `SystemButton`。
1009
1028
  - 不得在其中写「点击」「请按」一类引导语,按键名裸用。
1010
1029
  - 不得为本组件另行指定字族,等宽字族已由组件固定。
1011
1030
 
@@ -1021,7 +1040,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1021
1040
  - 业务记录行改用 `ApplicationRecordList`;表格行改用 `Table`。
1022
1041
  - 需要说明成因并提供重试出路的整段提示改用 `Alert`。
1023
1042
 
1024
- **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、运行总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
1043
+ **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、运行总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。整条可点开时直接给 `onClick`:组件随之给出指针与 hover 反馈,读作按钮、进 Tab 序列,Enter / 空格触发同一回调,调用方不得再自行补键盘处理。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
1025
1044
 
1026
1045
  **禁止 / 使用边界。**
1027
1046
  - 不得把本组件当作会话气泡使用。
@@ -1033,14 +1052,14 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1033
1052
 
1034
1053
  **用途。** 消息流的有界滚动容器,并按条件贴底。
1035
1054
 
1036
- **何时使用。** 需要在 Content Canvas 内部开一块有界的、正交的垂直滚动区域时使用该组件 —— 消息面板、评论流、办理讨论。这是 Content Canvas 单一垂直滚动权的合法局部例外,前提是高度有界。
1055
+ **何时使用。** 需要在 Content Canvas 内部开一块有界的、正交的垂直滚动区域时使用该组件 —— 消息面板、评论流、办理讨论。这是页面级纵向滚动持有者(结果集页面为 DataDisplay 主体,其余为 Content Canvas)之外的合法局部例外,前提是高度有界。
1037
1056
 
1038
1057
  **何时改用其他组件。**
1039
1058
  - 长筛选列表、宽表格、必须单行的标签条等通用溢出改用 `ScrollArea`,单个实例只承担一个滚动方向。
1040
- - 页面级垂直滚动不需要组件,Content Canvas 本身是唯一的主垂直滚动权持有者。
1059
+ - 页面级垂直滚动不需要组件:结果集页面由 `ApplicationDataDisplay` 主体滚动,其余页面由 Content Canvas 滚动(06 · D-4)。
1041
1060
  - 靠翻页而非滚动浏览的长列表改用 `ApplicationDataDisplay` 配 `ListTablePagination`。
1042
1061
 
1043
- **组合约定。** `height` 必须显式给出(数字按 px),否则失去「有界」前提;内置的 320px 只是兜底默认值,不是可依赖的版式。`children` 是一组 `Bubble` 或一组 `Message`,条目间距由本容器承担,条目自身不得再加外边距。`stickToBottom` 仅在用户当前已贴近底部(48px 阈值内)时生效(04 · D7),业务侧不得另写「新消息到达即拉到底」的逻辑把它覆盖回去。该组件持有交互状态并带 `"use client"`,在 Server Component 中只能作为子树引入。滚动监听(加载更多历史)挂在透传的 `onScroll` 上,不得另行注册事件监听器。
1062
+ **组合约定。** `height` 必须显式给出(数字按 px),否则失去「有界」前提;内置的 320px 只是兜底默认值,不是可依赖的版式。`children` 是一组 `Bubble` 或一组 `Message`,条目间距由本容器承担,条目自身不得再加外边距。`stickToBottom` 仅在用户当前已贴近底部(48px 阈值内)时生效(04 · D7),业务侧不得另写「新消息到达即拉到底」的逻辑把它覆盖回去。根节点是 `role="log"`,新增的条目由读屏以 polite 方式播报;静默加载历史时可传 `aria-live="off"` 覆盖。该组件持有交互状态并带 `"use client"`,在 Server Component 中只能作为子树引入。滚动监听(加载更多历史)挂在透传的 `onScroll` 上,不得另行注册事件监听器。
1044
1063
 
1045
1064
  **禁止 / 使用边界。**
1046
1065
  - 不得省略高度,也不得把它挂进本身高度不定的父容器再靠百分比撑开。
@@ -1060,7 +1079,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1060
1079
  - 可拖拽取值的输入改用 `Slider`,原生 `<input type="range">` 由 `no-native-range` 规则禁止。
1061
1080
  - 功能状态加计数改用 `ApplicationMetricStatus`;数值加环比改用 `ApplicationMetricTrend`。
1062
1081
 
1063
- **组合约定。** 百分比由 `value` 与 `max` 得出并钳制在 0–100,`max` 缺省为 100,因此直接传百分比时不必再给 `max`。指标区内使用时,该组件作为 `ApplicationMetricStrip` 的 `children` 之一传入,卡片壳由指标区提供,本组件自身不带卡片;指标卡默认只读,整卡不得成为导航入口。`label` 与 `showValue` 共处同一行左右分列,二者都不给时该行不渲染。`tone` 使用状态色时,其含义必须与该状态在全产品内的含义一致。外边距由宿主承担;`height` 只改轨道厚度,不影响说明行。填充过渡受 `prefers-reduced-motion` 约束,业务侧不得另加动画。
1082
+ **组合约定。** 百分比由 `value` 与 `max` 得出并钳制在 0–100,`max` 缺省为 100,因此直接传百分比时不必再给 `max`。指标区内使用时,该组件作为 `ApplicationMetricStrip` 的 `children` 之一传入,卡片壳由指标区提供,本组件自身不带卡片;指标卡默认只读,整卡不得成为导航入口。`label` 与 `showValue` 共处同一行左右分列,二者都不给时该行不渲染。`label` 同时是进度条的可访问名称(组件以 `aria-labelledby` 关联);不显示 `label` 时须传 `aria-label`,组件把它落在 `role="progressbar"` 上而不是根节点。`tone` 使用状态色时,其含义必须与该状态在全产品内的含义一致。外边距由宿主承担;`height` 只改轨道厚度,不影响说明行。填充过渡受 `prefers-reduced-motion` 约束,业务侧不得另加动画。
1064
1083
 
1065
1084
  **禁止 / 使用边界。**
1066
1085
  - 不得用本组件表达不确定的等待,禁止做成来回往复的假进度。
@@ -1101,7 +1120,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1101
1120
  - 整个区域或结果集无数据改用 `Empty`,其文案须区别于无权限与加载失败。
1102
1121
  - 结构性加载占位改用 `Skeleton`,短时原地等待改用 `Spinner`。
1103
1122
 
1104
- **组合约定。** 该组件无开合状态,由调用方条件渲染。`action` 槽位应传单个 `Button`,文案为 2–4 字裸名词短语(`重试`)。状态图标由 `tone` 推导,不接受外部传入的图标。`tone="danger"` 时该组件以 `role="alert"` 打断式播报,其余三个 tone 为 `role="status"`,调用方不得再手动覆盖 `role`。该组件不带外边距,与相邻内容的间距由父容器的 `gap` 负责。`ApplicationFormDialog` 的 `error` 槽位必须传 `<Alert tone="danger">`,渲染在表单主体顶部。
1123
+ **组合约定。** 该组件无开合状态,由调用方条件渲染。`action` 槽位应传单个 `SystemButton`,文案为 2–4 字裸名词短语(`重试`)。状态图标由 `tone` 推导,不接受外部传入的图标。`tone="danger"` 时该组件以 `role="alert"` 打断式播报,其余三个 tone 为 `role="status"`,调用方不得再手动覆盖 `role`。该组件不带外边距,与相邻内容的间距由父容器的 `gap` 负责。`ApplicationFormDialog` 的 `error` 槽位必须传 `<Alert tone="danger">`,渲染在表单主体顶部。数据区的 Partial Failure 传进 `ApplicationDataDisplay` 的 `notice` 槽位,不放进呈现组件之内。
1105
1124
 
1106
1125
  **禁止 / 使用边界。**
1107
1126
  - 不得用本组件承载必须阻断的确认,那是 `AlertDialog` 的职责。
@@ -1120,24 +1139,24 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1120
1139
  - 可撤销的已完成事实改用 `Sonner`,并把撤销放进它的 `action`。
1121
1140
  - 不阻断主任务的失败提示改用 `Alert`。
1122
1141
 
1123
- **组合约定。** 该组件宽度固定为 420px,不接受尺寸调整。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。`cancelText` 同时作为右上角关闭按钮的无障碍名称,因此必须是 2–4 字裸名词短语,不得写成句子。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
1142
+ **组合约定。** 该组件宽度固定为 420px,不接受尺寸调整。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。右上角关闭按钮的无障碍名称固定为「关闭」,与取消按钮可区分;打开时初始焦点落在取消按钮,误按 Enter 不会触发确认。`cancelText` 必须是 2–4 字裸名词短语,不得写成句子。面板以 `role="alertdialog"` 输出,`title` 与 `description` 分别作为它的可访问名与描述。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
1124
1143
 
1125
1144
  **禁止 / 使用边界。**
1126
1145
  - 不得在 `children` 中放置输入控件或表单字段。
1127
1146
  - 禁止把标题写成不含数量与后果的泛化问句。
1128
- - 不得在本组件之上再叠加第二层模态浮层。
1147
+ - 不得在本组件之上再叠加任何模态浮层 —— 它本身就是「模态之上放行的那一层」,再往上即超过一层(06 · D-3)。
1129
1148
  - 不得依赖点击遮罩关闭,该路径已按契约关闭。
1130
1149
 
1131
1150
  ## Collapsible
1132
1151
 
1133
- **用途。** 单个显隐区域,由一个触发器控制 —— 查询工具栏里的「更多筛选」模式。
1152
+ **用途。** 单个显隐区域,由一个触发器控制 —— 详情页的次要分节、表单里的高级选项。
1134
1153
 
1135
- **何时使用。** 当低频能力需要收进入口、但能力本身必须保留时,该组件是默认选择。查询工具栏内常驻 2–3 个高频筛选维度,其余维度一律收进本组件。触发器文字通过 `label` 传入,写作 2–4 字裸名词短语(`更多筛选`)。
1154
+ **何时使用。** 当低频能力需要收进入口、但能力本身必须保留时,该组件是默认选择。触发器文字通过 `label` 传入,写作 2–4 字裸名词短语(`版本记录`)。
1136
1155
 
1137
1156
  **何时改用其他组件。**
1138
1157
  - 多个并列或互斥的折叠区改用 `Accordion`。
1139
1158
  - 页面级的区域切换改用 `Tabs`。
1140
- - 需要锚定浮出而非就地展开的「更多筛选」改用 `Popover`,两者都可填入 `ApplicationQueryToolbar` 的 `moreFilters` 槽位。
1159
+ - 查询工具栏的「更多筛选」一律改用 `Popover`,填入 `ApplicationQueryToolbar` 的 `moreFilters` 槽位。本组件就地展开会把工具栏撑高(实测 99px → 452px),SPLIT 页的两栏随之被压扁(06 · D-4)。
1141
1160
  - 辅助性内容的侧滑面板改用 `Sheet`。
1142
1161
 
1143
1162
  **组合约定。** 折叠只改变入口,绝不移除能力 —— 被收起的筛选项仍然存在、仍可使用,调用方不得在收起时把它们从状态中移除。「更多筛选」通过「应用」提交,生效的条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。受控模式下 `open` 与 `onOpenChange` 必须成对出现,只传 `open` 会得到一个永不展开的区域。内容区的上边距由该组件自身声明,调用方不得再叠加外边距。触发器沿用 32px 高度与 16px 圆角的按钮几何,但它不是 `Button`,不接受 `variant` 一类的按钮属性。
@@ -1152,7 +1171,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1152
1171
 
1153
1172
  **用途。** 模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。
1154
1173
 
1155
- **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。命令面板(`Command`)作为全局搜索与执行入口时放进本组件。
1174
+ **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。
1156
1175
 
1157
1176
  **何时改用其他组件。**
1158
1177
  - 完整业务表单改用 `ApplicationFormDialog`,它拥有已登记的字段网格与提交语义。
@@ -1160,12 +1179,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1160
1179
  - 业务对象详情改用 `Drawer` 或独立详情页。
1161
1180
  - 辅助性内容(设置、帮助、附件预览)改用 `Sheet`。
1162
1181
  - 无需阻断背景的锚定面板改用 `Popover`。
1182
+ - 全局命令面板改用 `Command` 的 `dialog` 形态,不要把 `Command` 放进本组件。
1163
1183
 
1164
- **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `Button` 用 `variant="primary"`。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
1184
+ **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。打开时焦点默认落在面板内首个可聚焦元素,即标题栏的关闭按钮;主体以输入为主(新建、编辑)时应以 `initialFocus` 传入首个字段的 ref,焦点一次落定,不先经过关闭按钮。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `SystemButton` 用 `intent="primary"`。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
1165
1185
 
1166
1186
  **禁止 / 使用边界。**
1167
1187
  - 不得在本组件内改变 `pageType` 或 `pageMode` —— 浮层只是物理容器,绝不创造新的页面类型或页面模式。
1168
- - 禁止在本组件内嵌套第二个模态浮层。
1188
+ - 禁止在本组件内嵌套第二个对话框、抽屉或侧板。模态之上至多再叠一层确认框(`AlertDialog`)或选择器(`PeoplePickerDialog`),更深的嵌套一律禁止(06 · D-3):表单里的选人字段打开 `PeoplePickerDialog`、破坏性动作打开 `AlertDialog` 都属于放行的那一层,基座的 Esc 层级栈与焦点陷阱保证只有最上层响应。
1169
1189
  - 不得为完整业务表单手工拼装本组件的字段布局。
1170
1190
  - 不得传入使面板超出有效视口的宽度。
1171
1191
 
@@ -1186,7 +1206,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1186
1206
  **禁止 / 使用边界。**
1187
1207
  - 不得把深链接指向抽屉状态。
1188
1208
  - 禁止把关闭动作的文案写成「返回」。
1189
- - 不得在抽屉内再打开第二个抽屉或对话框。
1209
+ - 不得在抽屉内再打开第二个抽屉、对话框或侧板。模态之上至多再叠一层确认框(`AlertDialog`)或选择器(`PeoplePickerDialog`),更深的嵌套一律禁止(06 · D-3):抽屉里的删除必须经 `AlertDialog` 确认,确认框直接叠在抽屉之上,不得为此先关抽屉。
1190
1210
  - 不得承载帮助、附件预览一类辅助性面板 —— 那些走 `Sheet`;全局设置是唯一例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开。
1191
1211
 
1192
1212
  ## DropdownMenu
@@ -1202,7 +1222,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1202
1222
  - 查询工具栏中的筛选维度改用 `ApplicationFilterMenu`。
1203
1223
  - 面板内需要放置任意内容而非条目清单时改用 `Popover`。
1204
1224
 
1205
- **组合约定。** `trigger` 通常是 `iconOnly` 的 `Button`,此时必须同时提供 `aria-label`。该组件向 `trigger` 注入 `aria-expanded` 与 `aria-haspopup`,因此 `trigger` 必须是单个能接收这两个属性的 React 元素;传入纯字符串时属性不会注入,读屏用户无从得知此处有菜单。`separator` 与 `heading` 条目不需要 `value`,其余每个条目的 `value` 必填 —— 缺失时该条目不可选中且不触发 `onSelect`。面板与条目样式与 `ContextMenu`、`Menubar`、`Command` 共用同一套,最小宽度 168px。
1225
+ **组合约定。** `trigger` 通常是 `iconOnly` 的 `SystemButton`,此时必须同时提供 `aria-label`。该组件向 `trigger` 注入 `aria-expanded` 与 `aria-haspopup`,因此 `trigger` 必须是单个能接收这两个属性的 React 元素;传入纯字符串时属性不会注入,读屏用户无从得知此处有菜单。`separator` 与 `heading` 条目不需要 `value`,其余每个条目的 `value` 必填 —— 缺失时该条目不可选中且不触发 `onSelect`。面板与条目样式与 `ContextMenu`、`Menubar`、`Command` 共用同一套,最小宽度 168px。键盘打开(Enter / 空格 / ↓)高亮首个可用项,↑ 高亮末项,鼠标打开不预先高亮;Tab 收起菜单。Esc 关闭或选中后焦点回到 `trigger`,且选中时先归还焦点再调 `onSelect` —— 在 `onSelect` 里打开 `AlertDialog` 是既定用法,对话框关闭后焦点回到触发器,调用方不得再自行管理这段焦点。
1206
1226
 
1207
1227
  **禁止 / 使用边界。**
1208
1228
  - 不得把 Page Mode Switch 折叠进本组件 —— 它必须始终可见,这是 Shell 契约的硬性要求。
@@ -1221,7 +1241,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1221
1241
  - 需要在面板内执行动作或提交内容改用 `Popover`。
1222
1242
  - 完整的记录详情改用 `Drawer` 或独立详情页。
1223
1243
 
1224
- **组合约定。** 该组件永远只是补充。悬停对键盘用户与触屏用户不可用,因此同样的信息必须能通过点击或详情视图获得 —— 这条由调用方保证,组件本身无法约束。`content` 只放只读预览,动作入口留在行尾或详情中。`trigger` 应是行内元素,该组件的锚点包装为 `inline-flex`,不改变所在文本行的排版。宽度由 `width` 控制,超出高度时面板内部滚动。
1244
+ **组合约定。** 该组件永远只是补充。触发器获得键盘焦点时同样打开、焦点离开即关闭,Esc 随时可关且与库内其他浮层共用 Esc 层级栈;但面板与触发器没有可访问关联,读屏不播报,触屏上也无从悬停,因此同样的信息必须能通过点击或详情视图获得 —— 这条由调用方保证,组件本身无法约束。`content` 只放只读预览,动作入口留在行尾或详情中。`trigger` 应是行内元素,该组件的锚点包装为 `inline-flex`,不改变所在文本行的排版。宽度由 `width` 控制,超出高度时面板内部滚动。
1225
1245
 
1226
1246
  **禁止 / 使用边界。**
1227
1247
  - 不得让本组件成为某项信息的唯一入口。
@@ -1233,7 +1253,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1233
1253
 
1234
1254
  **用途。** 锚定式浮层面板 —— 筛选器、呈现设置、日期选择器。
1235
1255
 
1236
- **何时使用。** 当面板内容需要贴近触发器、且背景仍应保持可交互时,该组件是默认选择。默认宽度 320px,空间不足时自动翻转到对侧并限制高度,永不超出有效视口。呈现设置面板必须按当前呈现方式命名 —— 列设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置。
1256
+ **何时使用。** 当面板内容需要贴近触发器、且背景仍应保持可交互时,该组件是默认选择。默认宽度 320px,空间不足时自动翻转到对侧并限制高度,永不超出有效视口。呈现设置面板必须按当前呈现方式命名 —— 列设置 / 列表设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置。
1237
1257
 
1238
1258
  **何时改用其他组件。**
1239
1259
  - 条目清单式的低频动作改用 `DropdownMenu`。
@@ -1242,7 +1262,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1242
1262
  - 消息 / 待办 / 运行总览 / 风险预警四个全局动作共享的弹层改用 `ApplicationGlobalActionPanel`,其 720px 宽、20px 圆角、680px 最高的几何已登记。
1243
1263
  - 用户必须完成或放弃的任务改用 `Dialog`。
1244
1264
 
1245
- **组合约定。** 该组件是非模态浮层:不锁背景滚动、不陷阱焦点,Esc 与外部点击都会关闭并触发 `onOpenChange`。受控模式下 `open` 与 `onOpenChange` 必须成对出现。触发器包装元素已带 `aria-expanded`,调用方不得在 `trigger` 上再写一个。`radius` 应传 token 而非字面值。作为「更多筛选」入口时,生效条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。层级由已登记的浮层 z-index 承担,调用方不得自行设置。
1265
+ **组合约定。** 该组件是非模态浮层:不锁背景滚动、不陷阱焦点,Esc、外部点击与焦点离开(焦点从 `trigger` 或面板移到两者之外,如 Tab 出去)都会关闭并触发 `onOpenChange`;焦点离开引起的关闭不归还焦点。关闭时焦点若在面板内(Esc,或面板内的控件经 `onOpenChange(false)` 收起),焦点回到 `trigger`,因此在 `Dialog` 内使用时焦点不会逃出对话框。受控模式下 `open` 与 `onOpenChange` 必须成对出现。组件向 `trigger` 注入 `aria-expanded`,因此 `trigger` 必须是单个能接收该属性的 React 元素,调用方不得在 `trigger` 上再写一个;传入纯字符串时属性不会注入。触发器由别的组件渲染、只经回调交出元素时(`TopNavigationPrimaryBar` 的 `onAppSwitch` / `onAccount`),把该元素传给 `anchor` 并受控使用:面板贴它定位,点它不算外部点击,收起时焦点还给它,Tab 从它直接进入面板、从面板末项接着走它之后的元素;此时不渲染 `trigger`、组件根不占布局,`aria-expanded` 由渲染触发器的那个组件输出。`radius` 应传 token 而非字面值。作为「更多筛选」入口时,生效条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。层级由已登记的浮层 z-index 承担,调用方不得自行设置。
1246
1266
 
1247
1267
  **禁止 / 使用边界。**
1248
1268
  - 不得用本组件手工拼装四个全局动作的共享弹层。
@@ -1261,6 +1281,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1261
1281
  - 已登记的业务详情结构改用 `ApplicationDetailDrawer`。
1262
1282
  - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
1263
1283
  - 消息 / 待办 / 运行总览 / 风险预警四个全局动作改用 `ApplicationGlobalActionPanel`;设置不走该面板,走本组件或 `Drawer`。
1284
+ - 工具栏的呈现设置面板(列设置、看板设置等)改用 `Popover`,与更多筛选同一承载 —— 本组件的「设置」指全局设置(07 · C-7)。
1264
1285
 
1265
1286
  **组合约定。** 该组件与 `Dialog`、`AlertDialog`、`Drawer` 共用同一个模态基座,因此自带 Esc 关闭、焦点陷阱、焦点恢复与背景滚动锁定。该组件没有固定底部动作区 —— 需要提交按钮常驻底部的载体改用 `Drawer`。主体区域内部滚动,标题栏高度对齐内容区标题栏。全局设置在整个产品中只能有一个入口,该入口打开本组件或 `Drawer`,不得同时存在第二处。
1266
1287
 
@@ -1281,8 +1302,9 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1281
1302
  - 需要用户确认的不可逆动作改用 `AlertDialog`。
1282
1303
  - 需要用户填写或选择的内容改用 `Dialog`。
1283
1304
  - 结果集为空改用 `Empty`。
1305
+ - 只是要在页面里弹一条提示、不需要自己持有提示集合时,改用 `SonnerProvider` 挂在应用根、页面里调 `useToast()`,不必再自建一层 context。
1284
1306
 
1285
- **组合约定。** 整个应用只挂一个本组件,位置固定在应用根,`position` 决定四个角中的一个,默认 `bottom-right`。`toasts` 由调用方持有并维护;`onDismiss` 必须真的把该 `id` 从数组中移除,否则计时到期后提示不会消失。`action` 只放可选的加速器(`撤销`),错过它不得造成损失。`SonnerToast.id` 必须稳定唯一,复用同一个 id 会使计时错乱。四个 `tone` 决定左侧色条,单条宽度约束在 280–420px。
1307
+ **组合约定。** 整个应用只挂一个本组件(`SonnerProvider` 内部渲染的那一个也算),位置固定在应用根,`position` 决定四个角中的一个,默认 `top-right` —— 右下角会在提示停留的 5 秒里盖住批量栏、弹窗页脚一类底部动作条,因此不作默认。`toasts` 由调用方持有并维护;`onDismiss` 必须真的把该 `id` 从数组中移除,否则计时到期后提示不会消失。`action` 只放可选的加速器(`撤销`),错过它不得造成损失。`SonnerToast.id` 必须稳定唯一,复用同一个 id 会使计时错乱。四个 `tone` 决定左侧色条,单条宽度约束在 280–420px。
1286
1308
 
1287
1309
  **禁止 / 使用边界。**
1288
1310
  - 不得用 toast 承载提交失败或任何用户必须处理的信息。
@@ -1290,6 +1312,25 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1290
1312
  - 不得把 `duration` 设为 0 使提示常驻 —— 不会自己消失的提示不是 toast。
1291
1313
  - 不得在单条提示内放置表单、多步动作或需要滚动的内容。
1292
1314
 
1315
+ ## SonnerProvider
1316
+
1317
+ **用途。** `Sonner` 的调用入口:挂在应用根,内部持有提示集合并渲染唯一的 `Sonner`,子树里任何位置用 `useToast()` 取到 `toast()` 即可弹出一条提示。
1318
+
1319
+ **何时使用。** 应用需要在页面里弹出 toast 时,该组件是默认选择,必须挂在应用根、包住全部页面。页面里写 `const toast = useToast()`,再调 `toast({ title: '已保存', tone: 'success' })`;返回值是该条提示的 id,`toast.dismiss(id)` 可提前消除它。入参与 `SonnerToast` 相同,只是不带 `id` —— id 由本组件生成。`position` 原样传给内部的 `Sonner`,默认 `top-right`。
1320
+
1321
+ **何时改用其他组件。**
1322
+ - 需要自己持有提示集合(如从服务端推送恢复、跨标签页同步)时改用受控的 `Sonner`,二者不得同时挂载。
1323
+ - 用户必须读到并处理的失败改用 `Alert`,就地呈现在受影响区域顶部。
1324
+ - 需要用户确认的不可逆动作改用 `AlertDialog`。
1325
+
1326
+ **组合约定。** 整个应用只挂一个本组件;它渲染的 `Sonner` 即全应用唯一的提示堆栈,因此不得再另挂 `Sonner`。`useToast()` 必须在本组件的子树内调用,否则直接抛错 —— 静默吞掉的提示比报错更难查。`toast()` 函数引用在本组件存活期间保持稳定,可放进 effect 或 `useCallback` 的依赖。提示内容的约束与 `Sonner` 完全相同:`title` 是已完成事实的陈述,`action` 只放可选的加速器(`撤销`),点了加速器之后应调 `toast.dismiss(id)` 收起该条。
1327
+
1328
+ **禁止 / 使用边界。**
1329
+ - 不得嵌套挂载本组件,也不得与受控的 `Sonner` 同时挂载 —— 两个堆栈会叠在同一个角上。
1330
+ - 不得用 `toast()` 承载提交失败或任何用户必须处理的信息。
1331
+ - 禁止在本组件之外调用 `useToast()`,也不得为绕开报错自建一层同名 context。
1332
+ - 不得在渲染过程中调用 `toast()`,只在事件处理或 effect 中调用。
1333
+
1293
1334
  ## Spinner
1294
1335
 
1295
1336
  **用途。** 不确定时长的原地等待 —— 刷新中的按钮、提交中的对话框。
@@ -1313,14 +1354,14 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1313
1354
 
1314
1355
  **用途。** 悬停或聚焦时出现的短标签,用于为纯图标控件命名 —— 五个全局动作触发器、工具栏图标按钮。
1315
1356
 
1316
- **何时使用。** 当控件没有可见文字、需要一个名称时,该组件是默认选择。28px 高、8px 圆角、背景为 92% 文字色。显示延迟 220ms,避免在密集工具栏上划过时连闪一串;悬停与聚焦两种方式都会触发。
1357
+ **何时使用。** 当控件没有可见文字、需要一个名称时,该组件是默认选择。28px 高、8px 圆角、背景为 92% 文字色。显示延迟 220ms,避免在密集工具栏上划过时连闪一串;悬停与聚焦两种方式都会触发,Esc 关闭提示且不移动焦点,与库内其他浮层共用 Esc 层级栈(上层先响应)。
1317
1358
 
1318
1359
  **何时改用其他组件。**
1319
1360
  - 富预览内容改用 `HoverCard`。
1320
1361
  - 需要在面板内执行动作改用 `Popover`。
1321
1362
  - 需要长期可见的说明改用 `Field` 的说明文字或 `Alert`。
1322
1363
 
1323
- **组合约定。** 工具提示不是可访问名称 —— 被提示的控件必须同时带真实的 `aria-label`,纯图标 `Button`(`iconOnly` 为 true)尤其如此,且两者文案应一致。`content` 是控件的名称而非操作说明,写作 2–4 字裸名词短语(`列设置`、`关闭`)。`children` 应是单个可聚焦控件;该组件的锚点包装为 `inline-flex`,不改变所在行的排版。提示面板不接收指针事件,因此它绝不会挡住刚刚触发它的按钮,但也意味着其中的任何内容都不可点击。
1364
+ **组合约定。** 工具提示不是可访问名称 —— 被提示的控件必须同时带真实的 `aria-label`,纯图标 `SystemButton`(`iconOnly` 为 true)尤其如此,且两者文案应一致。`content` 是控件的名称而非操作说明,写作 2–4 字裸名词短语(`列设置`、`关闭`)。`children` 应是单个可聚焦控件;该组件的锚点包装为 `inline-flex`,不改变所在行的排版。提示面板不接收指针事件,因此它绝不会挡住刚刚触发它的按钮,但也意味着其中的任何内容都不可点击。
1324
1365
 
1325
1366
  **禁止 / 使用边界。**
1326
1367
  - 不得用本组件替代控件自身的 `aria-label`。
@@ -1340,7 +1381,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1340
1381
  - 选项极多、或密集的表格行内编辑器:改用 `NativeSelect`。
1341
1382
  - 需要输入即筛选:改用 `Combobox`。
1342
1383
  - 局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`。
1343
- - 键盘优先的全局搜索与执行:改用 `Command`,且必须放进 `Dialog`。
1384
+ - 键盘优先的全局搜索与执行:改用 `Command` 的 `dialog` 形态。
1344
1385
 
1345
1386
  **组合约定。** 该组件必须作为 `ApplicationQueryToolbar` 的 `commonFilters` 内容出现,传 2–3 个;不得独立散落在页面其他位置。该组件只持有本维度的取值,已生效条件必须由调用方回写到 `ApplicationQueryToolbar` 的 `appliedTags`,并实现 `onRemoveTag` 与 `onResetTags`;筛选状态只存在于菜单内部是不合规的。`ApplicationFilterOption.label` 传入非字符串时,必须同时提供 `labelText`,否则触发器回显退化为 `[object Object]`。`multiple` 为 true 时 `value` 与 `defaultValue` 必须是数组,为 false 时必须是字符串;单选状态下再次点选当前值会清空该维度,`onValueChange` 必须能接收空字符串。面板自带定位、碰撞翻转与外点击关闭,调用方不得再包一层 `Popover` 或 `DropdownMenu`。`count` 必须与数据展示区当前口径下的结果数一致。该组件不自带外边距,横向间距由工具栏的 `--ui-control-gap` 负责。
1346
1387
 
@@ -1374,13 +1415,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1374
1415
 
1375
1416
  **用途。** 数据展示区的标准页脚 —— 结果区间、结果总数、每页条数与翻页步进。
1376
1417
 
1377
- **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态固定为「第 X–Y 条 / 共 Z 条」加每页条数选择器加上一页 / 位置 / 下一页三件。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
1418
+ **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态固定为「第 X–Y 条 / 共 Z 条」加每页条数选择器加上一页 / 位置 / 下一页三件;位置视觉上是「3 / 10」,读屏读作「第 3 页,共 10 页」。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
1378
1419
 
1379
1420
  **何时改用其他组件。**
1380
1421
  - 既无总数也无每页条数需求:改用 `Pagination`,它是裸页码步进器,带首页 + 当前页 ±1 + 末页的页码窗口。
1381
1422
  - 两者是替代关系而非包含关系:同一个数据展示区内只能出现其中一个。
1382
1423
 
1383
- **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页语义必须跨 `pageMode` 与 `businessView` 切换存活,从详情返回时也必须还原 —— 该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`,调用方不得在旁边再挂一个 `Select`。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
1424
+ **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页状态按业务视图各记一份:切换 `businessView` 时回到该视图上次所在的页,切换 `pageMode` 与从详情返回时保持当前页;搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`,调用方不得在旁边再挂一个 `Select`。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
1384
1425
 
1385
1426
  **禁止 / 使用边界。**
1386
1427
  - 不得在同一数据展示区内出现两处分页控件。
@@ -1398,9 +1439,9 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1398
1439
  - 普通单行文本录入:改用 `Input`。
1399
1440
  - 带前后缀或附加按钮的组合输入:改用 `InputGroup`;它是本组件适配的 Foundation 基座,页面不得把它的外壳复制一份充当搜索框。
1400
1441
  - 在已知选项集合内做本地筛选、且不构成一次数据查询:改用 `Combobox`。
1401
- - 键盘优先的全局搜索与命令执行:改用 `Command`,放进 `Dialog`。
1442
+ - 键盘优先的全局搜索与命令执行:改用 `Command` 的 `dialog` 形态。
1402
1443
 
1403
- **组合约定。** `ariaLabel` 是必填项,且必须写明搜索范围(如「搜索监管对象」),不得写成泛泛的「搜索」。`onSubmit` 仅在 Enter 时触发,调用方不得在 `onChange` 里发起查询 —— `onChange` 只用于受控回显。清除按钮同样触发 `onChange`,其事件对象只保证 `target.value` 一个字段,处理函数不得访问其他事件属性。`ApplicationQueryToolbar` 内部已经渲染了一个 `SearchField`,工具栏场景必须走 `searchValue` / `onSearchChange` / `onSearchSubmit` / `searchPlaceholder`,不得再往 `commonFilters` 或 `moreFilters` 里塞第二个;`PeoplePickerDialog` 同理,其搜索由组件自身持有。`ApplicationFilterList` 的 `search` 槽位应当传入本组件。需要提示提交方式时,配一个 `Kbd` 写「Enter」。调用方拥有搜索范围、提交时机与查询数据;布局宽度可以设,颜色、边框、圆角、背景与焦点视觉不得覆盖。该组件不自带外边距。
1444
+ **组合约定。** `ariaLabel` 是必填项,且必须写明搜索范围(如「搜索监管对象」),不得写成泛泛的「搜索」。`onSubmit` 仅在 Enter 时触发,调用方不得在 `onChange` 里发起查询 —— `onChange` 只用于受控回显。清除按钮同样触发 `onChange`,其事件对象只保证 `target.value` 一个字段,处理函数不得访问其他事件属性。`ApplicationQueryToolbar` 内部已经渲染了一个 `SearchField`,工具栏场景必须走 `searchValue` / `onSearchChange` / `onSearchSubmit` / `searchPlaceholder` / `searchAriaLabel`,不得再往 `commonFilters` 或 `moreFilters` 里塞第二个;`PeoplePickerDialog` 同理,其搜索由组件自身持有。`ApplicationFilterList` 的 `search` 槽位应当传入本组件。需要提示提交方式时,配一个 `Kbd` 写「Enter」。调用方拥有搜索范围、提交时机与查询数据;布局宽度可以设,颜色、边框、圆角、背景与焦点视觉不得覆盖。该组件不自带外边距。
1404
1445
 
1405
1446
  **禁止 / 使用边界。**
1406
1447
  - 不得把逐字输入直接接到查询上,实时搜索禁止作为默认行为。
@@ -1418,7 +1459,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1418
1459
  **何时改用其他组件。**
1419
1460
  - 同一应用内的模块切换:改用 `ApplicationModuleSwitcher`,它是应用二级导航的左半部分。
1420
1461
  - 工作台菜单栏的图标条目:改用 `SidebarRailButton`。
1421
- - Content Canvas 内部的垂直导航面(SPLIT 左侧目录、设置导航、模块子导航):改用 `Sidebar`。
1462
+ - Content Canvas 内部的垂直导航面(设置页目录):改用 `Sidebar`;SPLIT 左栏改用 `ApplicationSplitListSidebar`。
1422
1463
  - 通用的「前置槽位 · 标题 + 描述 · 尾部槽位」列表行:改用 `Item`。
1423
1464
  - 触发的是动作而非跳转:改用 `SystemButton`。
1424
1465
 
@@ -1437,39 +1478,39 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1437
1478
  **何时使用。** 工作台左侧图标栏的导航条目必须使用本组件。图标登记尺寸 20px,标签 12/16 且限宽 52px、超长省略,激活态是淡强调色洗并渲染 `aria-current="page"`。
1438
1479
 
1439
1480
  **何时改用其他组件。**
1440
- - 该栏整体由 `GlobalSidebar` 渲染:改为向 `GlobalSidebar` 的 `items` 传数据(`icon` / `label` / `badge` / `separator`),本组件由它在内部渲染。
1481
+ - 该栏整体由 `GlobalSidebar` 渲染:改为向 `GlobalSidebar` 的 `items` 传数据(`icon` / `label` / `badge` / `separator`),本组件由它在内部渲染。栏底入口例外:`GlobalSidebar` 的 `footer` 直接放本组件(07 · C-15)。
1441
1482
  - 跨应用的快捷入口:改用 `SidebarAppLinkButton`。
1442
1483
  - Content Canvas 内部的通用垂直导航:改用 `Sidebar`,其折叠态即是 56px 图标栏。
1443
1484
  - Shell 的四带导航:改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`、`ApplicationModuleSwitcher`。
1444
1485
 
1445
- **组合约定。** `label` 不可省略 —— 规范禁止纯图标导航项。图标与标签是一个交互单元,禁用或淡化必须作用于整个条目。同一栏内至多一个条目设 `active`。`badge` 只承载未读计数或极短文本,长文案会溢出 14px 高的药丸。标签必须是 2–4 字裸名词短语,超出即被截断。分隔线通过 `GlobalSidebarEntry.separator` 表达,调用方不得在 `items` 之间手工插入 `Separator`。直接使用本组件时(即不经 `GlobalSidebar`),必须放进 56px 宽的列容器,条目之间的纵向间距由该容器负责,该组件不自带外边距。
1486
+ **组合约定。** `label` 不可省略 —— 规范禁止纯图标导航项。图标与标签是一个交互单元,禁用或淡化必须作用于整个条目。同一栏内至多一个条目设 `active`。`badge` 只承载未读计数或极短文本,长文案会溢出 14px 高的药丸;数字或文本徽标的视觉部分对读屏隐藏,条目名读作「标签,N 条」,调用方不得再把计数拼进 `label`。标签必须是 2–4 字裸名词短语,超出即被截断。分隔线通过 `GlobalSidebarEntry.separator` 表达,调用方不得在 `items` 之间手工插入 `Separator`。直接使用本组件时(即不经 `GlobalSidebar`),必须放进 56px 宽的列容器,条目之间的纵向间距由该容器负责,该组件不自带外边距。
1446
1487
 
1447
1488
  **禁止 / 使用边界。**
1448
1489
  - 不得省略 `label`,纯图标导航项被规范禁止。
1449
1490
  - 不得只禁用图标或只淡化标签,二者必须整体一致。
1450
- - 禁止在 `GlobalSidebar` 的 `items` 之外再向该栏手工插入条目。
1491
+ - 禁止在 `GlobalSidebar` 的 `items` 与 `footer` 之外再向该栏手工插入条目。
1451
1492
  - 不得把它挪进应用外层 Shell —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
1452
1493
 
1453
1494
  ## SystemButton
1454
1495
 
1455
1496
  **用途。** 整个产品的默认动作按钮,是 Foundation `Button` 之上只承载应用意图、loading 与产品状态的薄适配层。
1456
1497
 
1457
- **何时使用。** 应用层与业务页面中的每一个动作按钮都必须优先使用本组件 —— 应用层存在稳定语义适配器时应优先使用 `SystemButton` 而非 `Button`。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、16px 圆角全部来自 Foundation `Button`。
1498
+ **何时使用。** 业务页面中的每一个按钮都必须使用本组件,没有例外;Foundation `Button` 只供库内组件使用。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、16px 圆角全部来自 Foundation `Button`。
1458
1499
 
1459
1500
  **何时改用其他组件。**
1460
- - 确无稳定应用语义可用时才降级到 `Button`,这是唯一的降级条件。
1461
1501
  - 一组相关按钮需要拼接为分段控件或间隔簇:外层用 `ButtonGroup`,组内仍是 `SystemButton`。
1462
1502
  - 一个局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`;单个独立开关改用 `Toggle`。
1463
1503
  - 立即生效的设置:改用 `Switch`。
1464
1504
  - 页面模式切换:改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`,不得用按钮自造 Page Mode Switch。
1465
1505
 
1466
- **组合约定。** `intent="icon"` 或 `size="icon"` 时必须提供 `aria-label`,该组件此时映射到 Foundation `Button` 的 `iconOnly`,按钮上没有可见文字。一个动作组内至多一个 `intent="primary"`。`loading` 与 `disabled` 都阻断动作但语义不同:loading 是暂时的且设置 `aria-busy`,等待中的动作必须用 `loading` 表达,不得用 `disabled` 冒充;loading 期间 `children` 必须保持不变,否则按钮宽度会跳动。`intent="destructive"` 只表达外观,破坏性动作仍必须经 `AlertDialog` 确认,批量场景下标题须写明受影响对象的数量。页面级动作放进 `ApplicationPageHeader` 的 `actions`,批量动作放进 `ListBatchActionBar` 的 `actions`,记录级动作放在行尾且必须阻止事件冒泡。该组件不自带外边距,动作之间的间距由 `ButtonGroup` 或容器的 gap 负责。`size="compact"` 当前与 `default` 同为 32px,该值为密度分档预留,不得用它做视觉压缩。换肤只有一个入口 `--ds-color-theme-primary`,覆盖 `--application-accent` 只会改到引用它的那一部分组件。
1506
+ **组合约定。** `iconOnly` 为 true 时必须提供 `aria-label`,按钮上没有可见文字;它直接映射到 Foundation `Button` 的 `iconOnly`,与 `intent`、`size` 正交,常规图标按钮写 `intent="quiet" iconOnly`。一个动作组内至多一个 `intent="primary"`。`loading` 与 `disabled` 都阻断动作但语义不同:loading 是暂时的且设置 `aria-busy`,等待中的动作必须用 `loading` 表达,不得用 `disabled` 冒充;loading 期间按钮渲染 `aria-disabled="true"` 而非原生 `disabled`,保持可聚焦(点击后焦点不会掉到页首),点击与 `type="submit"` 的表单提交由组件拦截,调用方不必在 `onClick` 里自行判断 loading;loading 期间 `children` 必须保持不变,否则按钮宽度会跳动;`iconOnly` 时转圈替换原图标的位置,按钮尺寸与可访问名不变。`intent="destructive"` 只表达外观,破坏性动作仍必须经 `AlertDialog` 确认,批量场景下标题须写明受影响对象的数量。页面级动作放进 `ApplicationPageHeader` 的 `actions`,批量动作放进 `ListBatchActionBar` 的 `actions`,记录级动作放在行尾:放进 `Table` 的单元格或 `ApplicationRecordList` 的行内时,行已忽略来自行内按钮的点击与按键,不必再阻止事件冒泡;放进自建的可点击容器(自己挂 `onClick` 的卡片、条目)时必须自行阻止冒泡。该组件不自带外边距,动作之间的间距由 `ButtonGroup` 或容器的 gap 负责。`size="compact"` 当前与 `default` 同为 32px,该值为密度分档预留,不得用它做视觉压缩。`size="sm"` 为 28px,只用于嵌进 32px 控件内部的动作(`InputGroup` 的尾部按钮)。换肤只有一个入口 `--ds-color-theme-primary`,覆盖 `--application-accent` 只会改到引用它的那一部分组件。
1467
1507
 
1468
1508
  **禁止 / 使用边界。**
1469
1509
  - 不得自建平台级或业务级的按钮变体,逐页 fork 会摧毁统一换肤这个性质。
1470
1510
  - 不得使用原生 `<button>` 承担动作。
1471
1511
  - 禁止用 `disabled` 表达加载中,等待状态必须用 `loading`。
1472
1512
  - 不得省略纯图标按钮的 `aria-label`。
1513
+ - 不得写 `intent="icon"` 或 `size="icon"` —— 两者已移除,等宽图标按钮一律走 `iconOnly`。
1473
1514
  - 不得在同一个动作组内出现两个 `intent="primary"`。
1474
1515
 
1475
1516
  ## TopNavigationPrimaryBar
@@ -1485,7 +1526,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1485
1526
  - 层级回溯路径:改用 `Breadcrumb`,且只能出现在上下文区。
1486
1527
  - 跨应用跳转的条目:改用 `SidebarAppLinkButton` 渲染在 `onAppSwitch` 打开的面板内。
1487
1528
 
1488
- **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 52px / Compact 44px),只有这两档;调用方不得用 `className` 或行内样式改高。三条导航带的 `position: fixed` 与层级由宿主布局承担,组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位。本带自持左右内边距与底部分隔线,宿主不得再加外边距。`brandLogoSrc` 缺省时自动回退到已登记 mock:28×28 纯色块 + 8px 间隙 + `brandName`;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像首字均取自它。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。
1529
+ **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 52px / Compact 44px),只有这两档;调用方不得用 `className` 或行内样式改高。三条导航带的 `position: fixed` 与层级由宿主布局承担(标准宿主 CSS 见 SKILL.md「五层 Canvas 模型 · 宿主布局」),组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位。本带自持左右内边距与底部分隔线,宿主不得再加外边距。`brandLogoSrc` 缺省时自动回退到已登记 mock:28×28 纯色块 + 8px 间隙 + `brandName`;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像缩写均取自它,缩写规则与 `Avatar` 相同(中文取末字,「成员 A」→「A」;拉丁名取首字母)。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。 应用切换与账户两个面板用 `Popover` 承载:`onAppSwitch` / `onAccount` 的参数是被点的触发器,必须传给 `Popover` 的 `anchor` 锚定,不得另放空锚点凑位置;开合由调用方受控,回调里切换开合(再点触发器即收起),并把同一份状态回写到 `appSwitchOpen` / `accountOpen`,触发器据此输出 `aria-haspopup="dialog"` 与 `aria-expanded`,面板内容根相应声明 `role="dialog"` 与可访问名。
1489
1530
 
1490
1531
  **禁止 / 使用边界。**
1491
1532
  - 不得在本带内加入搜索框、面包屑、通知铃铛、页面标题、卡片或阴影 —— Shell 契约禁止添加未登记元素。
@@ -1505,7 +1546,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1505
1546
  - 模块切换与业务标签:改用 `ApplicationSecondaryNavigation`。
1506
1547
  - 前四个动作打开的浮层内容:改用 `ApplicationGlobalActionPanel`;设置打开的浮层:改用 `Drawer` 或 `Sheet`。
1507
1548
 
1508
- **组合约定。** 五个动作及其顺序(消息 → 待办 → 运行总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind` 指明该动作应接哪一类浮层:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;`drawer` 动作接抽屉。`activeAction` 与 `onAction` 必须成对使用,`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名。`compact` 为 true 时仅隐藏 `appDescription`,logo、`appName` 与全部五个动作入口必须保留。本带自持内边距与底部分隔线,宿主不得再加外边距。
1549
+ **组合约定。** 五个动作及其顺序(消息 → 待办 → 运行总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind` 指明该动作应接哪一类浮层:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;`drawer` 动作接抽屉。`activeAction` 与 `onAction` 必须成对使用,`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名,类型与 `<Icon name>` 同为 `IconName`。Compact 档(视口宽 ≤1180px 或高 ≤720px,与 Shell 三带高度切换同一断点)由 `@media` 自动隐藏 `appDescription`,logo、`appName` 与全部五个动作入口必须保留;宿主不得再读断点自行判定。`compact` 已弃用、下一个 minor 删除,新代码不得再传,传 `true` 仍强制紧凑。五个动作内置 `Tooltip`,悬停与聚焦时提示动作名,外观读 `--ui-shell-global-action-tooltip-*`,对应面板展开期间不提示;调用方不得再为它们包一层 `Tooltip`。本带自持内边距与底部分隔线,宿主不得再加外边距。
1509
1550
 
1510
1551
  **禁止 / 使用边界。**
1511
1552
  - 禁止渲染第二个设置入口,无论它出现在本带、账户菜单还是页面内。
@@ -1548,7 +1589,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1548
1589
  - 跨应用(而非跨模块)跳转:改用 `TopNavigationPrimaryBar` 的 `onAppSwitch`,条目用 `SidebarAppLinkButton`。
1549
1590
  - 工作台的图标菜单栏:改用 `GlobalSidebar`;Content Canvas 内的通用垂直导航:改用 `Sidebar`。
1550
1591
 
1551
- **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。面板是 `position: fixed`,顶边贴 `--ui-shell-application-total-height`,底边贴视口底,宽 392px 并受视口宽度限制;因此本组件的任何祖先元素都不得设置 `transform`、`filter` 或 `contain`,否则固定定位会改以该祖先为包含块而错位。触发器最小宽 168px、高 40px(Compact 148 / 32),几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 与触发器的 `glyph` 均走 `Icon`,`glyph` 的登记尺寸是 18px。
1592
+ **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。面板是 `position: fixed`,顶边贴 `--ui-shell-application-total-height`,底边贴视口底,宽读 `--ui-shell-module-switch-panel-width`(320px)并受视口宽度限制;因此本组件的任何祖先元素都不得设置 `transform`、`filter` 或 `contain`,否则固定定位会改以该祖先为包含块而错位。触发器最小宽 168px、高 40px(Compact 148 / 32),几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 与触发器的 `glyph` 均走 `Icon`,`glyph` 的登记尺寸是 18px。键盘按 menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),↑ / ↓ / Home / End 在模块间移动;Esc、外部点击与 Tab 都经 `onOpenChange(false)` 收起,Esc 后焦点回到触发器 —— 调用方不得再自行监听 Esc 或外部点击。
1552
1593
 
1553
1594
  **禁止 / 使用边界。**
1554
1595
  - 不得把触发器简化成一个小图标,也不得在窄屏下移除它。
@@ -1564,13 +1605,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1564
1605
  **何时使用。** `pageType` 为 `WORKBENCH` 的工作台面需要一列固定的图标入口时使用本组件。它是工作台这一种页面的构件,其存在与否由页面决定,不由应用外壳决定。
1565
1606
 
1566
1607
  **何时改用其他组件。**
1567
- - Content Canvas 内的通用垂直导航(SPLIT 左栏目录、设置导航、模块子导航):改用 `Sidebar`。
1608
+ - Content Canvas 内的通用垂直导航(设置页目录):改用 `Sidebar`。
1568
1609
  - SPLIT 左栏的记录列表:改用 `ApplicationSplitListSidebar`。
1569
1610
  - 模块级导航:改用 `ApplicationSecondaryNavigation`。
1570
1611
  - 编辑器型工作面的水平菜单条:改用 `Menubar`。
1571
1612
  - 单个图标入口按钮:改用 `SidebarRailButton`;跨应用入口:改用 `SidebarAppLinkButton`。
1572
1613
 
1573
- **组合约定。** `items` 是数据而非元素 —— 组件内部渲染 `SidebarRailButton` 并自行控制 `active` 与点击,调用方不得先构造好按钮元素再传入。`GlobalSidebarEntry.label` 在类型上可选,在规范上必填:规范禁止纯图标导航项,只给 `icon` 不给 `label` 能通过类型检查但不合规。`icon` 的登记尺寸是 20px,走 `Icon`。`separator` 为 true 时其余字段被忽略,但该条目的 `key` 仍必须在栏内唯一。`value` 与 `onValueChange` 成对使用。`footer` 被推到栏底,与条目之间不需要额外间隔元素。本组件自持内边距与右侧 1px 边线,宿主用 flex 把它与内容区并排即可,不得再加外边距。
1614
+ **组合约定。** `items` 是数据而非元素 —— 组件内部渲染 `SidebarRailButton` 并自行控制 `active` 与点击,调用方不得先构造好按钮元素再传入。`GlobalSidebarEntry.label` 在类型上可选,在规范上必填:规范禁止纯图标导航项,只给 `icon` 不给 `label` 能通过类型检查但不合规。`icon` 的登记尺寸是 20px,走 `Icon`。`separator` 为 true 时其余字段被忽略,但该条目的 `key` 仍必须在栏内唯一。`value` 与 `onValueChange` 成对使用。`footer` 被推到栏底,与条目之间不需要额外间隔元素;栏底的入口(如「设置」)直接放 `SidebarRailButton`(07 · C-15)。本组件自持内边距与右侧 1px 边线,宿主用 flex 把它与内容区并排即可(写法见 SKILL.md「五层 Canvas 模型 · 宿主布局」),不得再加外边距。
1574
1615
 
1575
1616
  **禁止 / 使用边界。**
1576
1617
  - 不得把本组件当作应用外壳的全局左栏 —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
@@ -1591,9 +1632,10 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1591
1632
  - 行内或表格单元中的状态标签:改用 `Badge`。
1592
1633
  - 承载业务内容而非数字的卡片:改用 `Card`。
1593
1634
 
1594
- **组合约定。** 本组件必须放进 `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` 缺省取指标数量、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。
1635
+ **组合约定。** 本组件必须放进 `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`。指标数据在途或失败时用 `state` 表达,取值只有 `ready` / `loading` / `error` 三种:`loading` 由组件渲染与指标卡同壳同高的骨架(张数同 `columns` 的缺省算法,无卡片时为 4),调用方不得自拼骨架卡;`error` 渲染一张横跨整行的失败卡,内容经 `error` 传入,应说明失败原因并提供「重试」,不传时显示内置的「指标加载失败」。两种状态下 `metrics` 与 `children` 都不渲染;读屏经组件内置的状态播报获知「指标加载中」/「指标加载失败」。
1595
1636
 
1596
1637
  **禁止 / 使用边界。**
1638
+ - 不得用 `state="loading"` 长期占位来顶替「无真实指标」—— 无指标时整个区域不渲染。
1597
1639
  - 不得用占位卡凑数:页面没有真实指标时整个区域不渲染,向 `ApplicationPageLayoutContainer` 传 `metrics={undefined}`。
1598
1640
  - 不得给指标卡挂点击跳转,整卡默认只读,`cursor: default` 是已登记行为。
1599
1641
  - 不得一行超过 6 张,也不得让同一区内的卡片高度不一致。
@@ -1652,7 +1694,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1652
1694
  - 表达占比或完成度:改用 `Progress`。
1653
1695
  - 无形状信息、只有一个数:改用 `ApplicationMetricStrip` 的 `metrics`。
1654
1696
 
1655
- **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。走势图形是 `aria-hidden` 的装饰性 SVG,指标的可读信息必须完整地由 `label` 与 `value` 表达;`data` 与 `value` 必须成对提供。`data` 为空数组时不渲染走势图形,卡片仍保留数值并参与等高。`colorIndex` 索引的是 20 色图表分类色板 `--application-categorical-01…20`,仅编码分类,与好坏无关。绘图区是 88×28px 的版式常量,调用方不得改写。
1697
+ **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。走势图形是 `aria-hidden` 的装饰性 SVG,指标的可读信息必须完整地由 `label` 与 `value` 表达;`data` 与 `value` 必须成对提供。`data` 为空数组时不渲染走势图形,卡片仍保留数值并参与等高。走势线纵轴按 `data` 自身的最小值–最大值归一化、不从 0 起算,因此只表达形状、不表达绝对量级与幅度;`data` 全部相等时画成中线。`colorIndex` 索引的是 20 色图表分类色板 `--application-categorical-01…20`,仅编码分类,与好坏无关。绘图区是 88×28px 的版式常量,调用方不得改写。
1656
1698
 
1657
1699
  **禁止 / 使用边界。**
1658
1700
  - 不得用本卡替代 `Chart` 承担分析职责,它没有坐标轴、图例与数值刻度。
@@ -1693,7 +1735,8 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1693
1735
  - SPLIT 的两栏切分改用 `Resizable`,它落在该组件的数据展示区之内,不替代该组件。
1694
1736
 
1695
1737
  **组合约定。**
1696
- - 四个槽位与 Canvas 五层模型逐一对应:`header` 承载上下文区,`metrics` 承载指标区,`dataControl` 承载 L3 业务视图与 L4 数据控制,`children` 承载 L5 数据呈现。
1738
+ - `pageType` 必填,取值 `WORKBENCH` / `MANAGEMENT` / `LEDGER` / `ANALYSIS` / `REPORT` / `DETAIL`,输出为根节点的 `data-page-type`。它是 L1 页面类型唯一的 prop 落点,不改变区域顺序与留白;唯一受它影响的是纵向尺寸 —— `DETAIL` 页的容器随内容增高、由 Content Canvas 滚动,其余页型的容器收缩到 Canvas 高度、由数据展示区内的 `ApplicationDataDisplay` 内部滚动。
1739
+ - 四个槽位与 Canvas 五层模型逐一对应:`header` 承载上下文区,`metrics` 承载指标区,`dataControl` 承载 L3 业务视图与 L4 数据控制,`children` 承载 L5 数据呈现。无结果集页面(工作台、详情、配置、协作、编辑器)只传 `pageType`,`dataControl` 不传(编辑器例外:`Menubar` 放这里),`children` 承载面板网格、详情分节或工作面,由 Content Canvas 整页滚动(06 · D-1、D-4)。
1697
1740
  - `header` 应传 `ApplicationPageHeader`,`metrics` 应传 `ApplicationMetricStrip`,`dataControl` 应传 `ApplicationQueryToolbar`,`children` 应传 `ApplicationDataDisplay`。
1698
1741
  - 区域顺序由槽位固定,不由调用方书写次序决定:把上下文区传进 `metrics` 不会让它落到指标区的位置上。
1699
1742
  - 外边距归属唯一:Content Canvas 宿主内边距为零,页面内边距与区域间隙(Standard 12px / Condensed 10px / Compact 8px)全部由该组件持有。四个区域自身不得再带外边距。
@@ -1706,7 +1749,8 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1706
1749
  - 不得在该组件外层再包一层带内边距的容器 —— 页面留白只有一个持有者,两边都加会得到双倍留白。
1707
1750
  - 禁止用占位指标卡凑满 `metrics`,无真实指标时该区域整体不渲染。
1708
1751
  - 不得在该组件内部再嵌套一个 `ApplicationPageLayoutContainer`。
1709
- - 禁止在页面内堆叠第二个无界垂直滚动容器 —— Content Canvas 是唯一的垂直滚动持有者。
1752
+ - 不得把 `pageType` 写成常量、注释或自造的 `data-*` 属性来代替该 prop。
1753
+ - 禁止在页面内堆叠第二个无界垂直滚动容器 —— 页面级纵向滚动只有一个持有者:结果集页面是 `ApplicationDataDisplay` 的主体,其余页面是 Content Canvas。
1710
1754
 
1711
1755
  ## ApplicationPageHeader
1712
1756
 
@@ -1722,10 +1766,10 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1722
1766
  - 面包屑本体用 `Breadcrumb`,经 `breadcrumb` 槽位传入。
1723
1767
 
1724
1768
  **组合约定。**
1725
- - `actions` 承载页面级动作组,元素应为 `Button` 或 `SystemButton`,至多一个 primary。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
1726
- - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。
1769
+ - `actions` 承载页面级动作组,元素应为 `SystemButton`,至多一个 primary。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
1770
+ - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。它按 radiogroup 模式只占一个 Tab 停靠点,← / → 切换模式并首尾相接,Home / End 跳到首末项 —— 方向键同样触发 `onPageModeChange`。
1727
1771
  - `pageModes` 只列该页面真正开放的模式。少于 2 个时开关完全不渲染且不占位。
1728
- - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则状态区只剩一个刷新按钮,数据新鲜度无从判断。
1772
+ - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则状态区只剩一个刷新按钮,数据新鲜度无从判断。`updatedAt` 只登记 `HH:mm` 一种写法(24 小时制、两位补零,如 `09:12`),组件渲染为「更新于 09:12」;不得传日期、秒或「刚刚」「5 分钟前」一类相对时间(07 · C-12)。
1729
1773
  - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时刻,`refreshing` 显示刷新中且刷新按钮禁用,`failed` 显示刷新失败且按钮读作 `重试`。
1730
1774
  - `title` 为字符串时才会得到悬浮提示。需要悬浮提示又需要补充信息时,标题主体传 `title`,补充信息走 `subtitle`。
1731
1775
  - 该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 的区域间隙负责。
@@ -1747,7 +1791,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1747
1791
  **何时改用其他组件。**
1748
1792
  - Page Mode Switch 属于 `ApplicationPageHeader`,不得在此重建。
1749
1793
  - 单个高频筛选维度的触发器改用 `ApplicationFilterMenu`,经 `commonFilters` 传入。
1750
- - 完整的筛选维度面板改用 `ApplicationFilterList`,装进 `Collapsible` 或 `Popover` 后经 `moreFilters` 传入。
1794
+ - 完整的筛选维度面板改用 `ApplicationFilterList`,装进 `Popover` 后经 `moreFilters` 传入;不得装进 `Collapsible` 就地展开(06 · D-4)。
1751
1795
  - 纯文本搜索输入已由该组件内置的 `SearchField` 承担,不得在工具栏内另置搜索控件。
1752
1796
  - 分页改用 `ListTablePagination`,它属于 `ApplicationDataDisplay` 的底部。
1753
1797
  - 批量动作改用 `ListBatchActionBar`。
@@ -1756,26 +1800,33 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1756
1800
  - 三行的渲染条件固定:第一行业务视图仅当确有视图时渲染,第二行恒在,第三行仅当有筛选生效时渲染。
1757
1801
  - `businessViews` 传 2–4 个稳定工作视角,`businessView` 与 `onBusinessViewChange` 必须成对提供。
1758
1802
  - 搜索经 `searchValue` 与 `onSearchChange` 受控,提交只经 `onSearchSubmit`,由 Enter 触发。
1759
- - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu`,其余维度一律收进 `moreFilters`。折叠只改变入口,不移除能力。
1803
+ - 搜索框的可访问名优先取 `searchAriaLabel`,其次取 `searchPlaceholder`,二者至少给一个且必须写明搜索范围;占位文字写示例、可访问名写范围时分开传,同文时只传 `searchPlaceholder`。`searchPlaceholder` 没有默认值,缺省时占位文字取 `searchAriaLabel`;二者都缺省时可访问名回落为「搜索当前结果」并在开发构建下告警一次。
1804
+ - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu`,其余维度一律收进 `moreFilters`;常用筛选里出现的维度不再进更多筛选(07 · C-11)。折叠只改变入口,不移除能力。
1805
+ - `sort` 传 `Select`(无可见标签,用 `aria-label` 命名)。DataTable 呈现下表头排序是第二入口:`Table` 的 `sort` 与这里的 `Select` 读写同一份排序状态,任一处改动另一处同步回显(07 · C-2)。
1760
1806
  - 生效条件必须回写 `appliedTags`,并同时提供 `onRemoveTag` 与 `onResetTags`。`AppliedFilterTag.label` 为非字符串时必须提供 `labelText`,否则移除按钮的无障碍名称为空。
1761
1807
  - `presentation` 决定呈现设置按钮的文案,必须与 `ApplicationDataDisplay` 的同名 prop 取自同一处状态。
1762
- - 无真实可配置项时传 `hasPresentationSettings={false}`,按钮不渲染且不占位;提供设置时 `onPresentationSettings` 必须一并给出。
1808
+ - `hasPresentationSettings` 缺省时按是否提供 `onPresentationSettings` 推断:给了回调即渲染设置按钮,不给即不渲染且不占位;显式传入优先。无真实可配置项时不传回调即可,或显式传 `hasPresentationSettings={false}`。
1809
+ - `onPresentationSettings` 收到设置按钮的点击事件,`event.currentTarget` 即按钮元素,可作面板锚点或关闭后的焦点归还目标;不读参数的无参回调照旧可用。面板由调用方持有,其开合状态经 `presentationSettingsOpen` 回传,按钮据此输出 `aria-expanded` —— 二者应当成对提供,不传则按钮不报开合。
1810
+ - 呈现设置面板一律用 `Popover` 承载、锚定在呈现设置按钮上,与 `moreFilters` 同一承载;不得改用 `Sheet`、`Dialog` 或 `Drawer`(07 · C-7)。
1763
1811
  - 每种呈现方式各自独立存储其设置,切换呈现方式不得沿用上一种的设置。
1764
1812
  - `viewModeSwitch` 仅允许出现在服务 SPLIT 右栏的那一份工具栏上,且只改 `dataPresentation`。
1765
- - 搜索框固定 240px,该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
1813
+ - 搜索框宽 240–320px 弹性:行内有余量时长到 320px,筛选多时退回 240px,以容下写明搜索范围的占位文字。该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
1814
+ - 数据展示区的 `state` 为 `no-permission` 或 `not-found` 时不渲染本组件;处于 `error` 时保留,条件改动后重新查询(07 · C-6)。
1766
1815
 
1767
1816
  **禁止 / 使用边界。**
1768
1817
  - 禁止逐字实时搜索,不得在 `onSearchChange` 中直接发起查询。
1769
- - 禁止出现通用的「视图设置」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
1818
+ - 不得同时省略 `searchAriaLabel` 与 `searchPlaceholder`,也不得把任一写成不含范围的「搜索」。
1819
+ - 不得显式传 `hasPresentationSettings` 为 true 而不给 `onPresentationSettings` —— 那是一个点了没反应的按钮。
1820
+ - 禁止出现通用的「视图设置」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
1770
1821
  - 不得在该组件内渲染 Page Mode Switch,也不得用 `viewModeSwitch` 改动 `pageMode`。
1771
1822
  - 不得让筛选状态只存在于菜单或面板内部而不回写 `appliedTags`。
1772
- - 禁止为同一个结果集放置两份工具栏,也不得把搜索、筛选、排序下沉进 `ApplicationDataDisplay`。
1823
+ - 禁止为同一个结果集放置两份工具栏,也不得把搜索、筛选、排序下沉进 `ApplicationDataDisplay`。表头排序不算下沉,但不得另持一份与工具栏 `sort` 分离的排序状态。
1773
1824
 
1774
1825
  ## ApplicationFilterList
1775
1826
 
1776
1827
  **用途。** 「更多筛选」的面板主体 —— 全量筛选维度列表,持有草稿并由「应用」提交。
1777
1828
 
1778
- **何时使用。** 页面的可筛选维度多于工具栏能常驻的 2–3 个时使用。它是筛选能力的全集入口,而非常用筛选的补充。每个提供筛选的页面至多一份。
1829
+ **何时使用。** 页面的可筛选维度多于工具栏能常驻的 2–3 个时使用。它承载常用筛选之外的全部维度,常用筛选里出现的维度不再进本面板(07 · C-11)。每个提供筛选的页面至多一份。
1779
1830
 
1780
1831
  **何时改用其他组件。**
1781
1832
  - 常驻在工具栏主控制行的单个高频维度改用 `ApplicationFilterMenu`。
@@ -1796,7 +1847,8 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1796
1847
  **禁止 / 使用边界。**
1797
1848
  - 不得在 `onChange` 中直接提交查询 —— 草稿只有经「应用」才生效。
1798
1849
  - 禁止把生效的筛选条件只保留在面板内部而不回写筛选标签行。
1799
- - 不得只放部分维度 —— 该面板必须覆盖每一个可筛选维度,否则它不能被称作「更多筛选」。
1850
+ - 不得只放部分维度 —— 该面板必须覆盖常用筛选之外的每一个可筛选维度,否则它不能被称作「更多筛选」。
1851
+ - 不得重复放入常用筛选里已有的维度 —— 同一维度两处入口生效语义不同(常用筛选点即生效,本面板经「应用」才生效),先后改动时无从判定以谁为准。
1800
1852
  - 不得用该组件替代工具栏内常驻的 2–3 个常用筛选。
1801
1853
  - 禁止在该组件内放置排序、呈现设置或页面模式相关的控件。
1802
1854
 
@@ -1807,7 +1859,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1807
1859
  **何时使用。** 页面需要展示结果集时使用。LIST 页面模式与 SPLIT 右栏共用同一个该组件与同一个呈现组件。该区域只负责展示与选择,不负责查询。
1808
1860
 
1809
1861
  **何时改用其他组件。**
1810
- - 具体的呈现形态由被承载的组件决定:结构化记录列表用 `ApplicationRecordList`,表格用 `Table`,图表用 `Chart`,日历用 `Calendar`。
1862
+ - 具体的呈现形态由被承载的组件决定:结构化记录列表用 `ApplicationRecordList`(`presentation="RecordList"`),表格用 `Table`,卡片网格用 `Card`,图表用 `Chart`。看板、月历、时间轴三种暂无专属组件,一律按 SKILL.md「五层 Canvas 模型 · 呈现配方」的标准拼装写法承载(06 · D-2);月历不得用 Foundation `Calendar` 控件充当。
1811
1863
  - 单条记录的详情主体改用 `ApplicationRecordDetailBody`。
1812
1864
  - 指标概览属于指标区,改用 `ApplicationMetricStrip` 与四个语义指标卡。
1813
1865
  - 只需要一个带边框的静态面板时改用 `Card`。
@@ -1816,14 +1868,20 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1816
1868
  **组合约定。**
1817
1869
  - `state` 为 `ready` 时渲染 `children`,其余五种状态各自渲染对应槽位。使用某个状态前必须提供该状态的节点,否则该区域为空白。
1818
1870
  - 六种状态的文案必须区分成因:`loading` 传贴近最终结构的 `Skeleton`,`empty` 传 `Empty` 且点明当前口径,`error` 说明失败原因并提供重试,`noPermission` 与 `notFound` 各写各的措辞。
1871
+ - 第六种 Partial Failure 不替换呈现:`state` 保持 `ready`,把 `Alert` 传进 `notice`,说明哪部分没取到并给出重试;受影响的字段在呈现里以「—」或「暂不可用」占位。`notice` 固定在批量条之下、呈现之上,位于滚动区之外,不随内容滚走;非 `ready` 态不渲染。不得把这条 `Alert` 放进 `children` 顶部 —— 那样它与呈现共用滚动区,一滚就看不到。
1872
+ - `empty` 按成因分两句(07 · C-6):有搜索或筛选生效时写「没有符合当前筛选条件的记录」,出路是 `清除筛选`;当前视图下本就没有数据时写「当前视图下还没有记录」,出路是 `新建`(仅当有创建权限)。
1873
+ - 被承载的 `Table` 不再另设 `empty`:结果为空时把 `state` 置为 `empty`,空态只由本组件的 `empty` 槽位承担。
1874
+ - `state` 为 `no-permission` 或 `not-found` 时页面不渲染 `ApplicationQueryToolbar`(`dataControl` 不传);`error` 时保留工具栏,改条件即可重新查询。
1819
1875
  - `presentation` 必须与 `ApplicationQueryToolbar` 的同名 prop 取自同一处状态,否则呈现设置按钮会命名错误。
1820
1876
  - `batchBar` 应传 `ListBatchActionBar`,仅在有记录被选中时才出现;`pagination` 应传 `ListTablePagination`,固定在区域底部。
1877
+ - 分页状态按业务视图各记一份:切换 `businessView` 时回到该视图上次所在的页,切换 `pageMode` 与从详情返回时保持当前页;搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。
1821
1878
  - 展示区自身滚动,批量条与分页固定在上下两端。调用方不得在 `children` 外再包一层滚动容器。
1879
+ - 还原滚动位置:主体滚动容器经 `bodyRef` 暴露,跨状态切换不重建。从列表进入详情前读 `bodyRef.current.scrollTop`,与查询条件一起存进跨路由存活的状态(layout 级 context 或 URL);回到列表后在 `state` 首次变为 `ready` 时于 `useLayoutEffect` 中写回,只写一次。存下的位置只对原来那一份结果集有意义,离开期间查询条件变了就不还原。
1822
1880
  - 该组件在列向 flex 中吃掉剩余高度,必须作为 `ApplicationPageLayoutContainer` 的 `children` 使用,否则拿不到剩余高度,内部滚动失效。
1823
1881
  - 边框、圆角与背景由该组件持有,被承载的呈现组件不得再画一层外框。
1824
1882
 
1825
1883
  **禁止 / 使用边界。**
1826
- - 不得在该区域内持有第二套查询状态 —— 搜索、筛选、排序全部属于 `ApplicationQueryToolbar`。
1884
+ - 不得在该区域内持有第二套查询状态 —— 搜索、筛选、排序全部属于 `ApplicationQueryToolbar`;`Table` 表头排序只是同一份排序状态的第二入口。
1827
1885
  - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案。
1828
1886
  - 不得为 LIST 页面模式与 SPLIT 右栏各写一份近乎相同的呈现实现。
1829
1887
  - 不得在一个展示区内同时渲染两种 Data Presentation。
@@ -1844,13 +1902,15 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1844
1902
 
1845
1903
  **组合约定。**
1846
1904
  - 该组件受控:`value` 与 `onValueChange` 必须成对提供。
1847
- - 当前对象的合法取值只有两种:空,或当前结果集中一个有权限的对象。
1905
+ - 当前对象的合法取值只有两种:空,或当前结果集中一个有权限的对象。空写作 `value={null}`(或不传),不得用空串或某个哨兵值冒充。
1906
+ - 取消定位的出口是 `onClear`:提供后再次选择当前项(点击或 Enter / 空格)即回调 `onClear`,调用方在此把 `value` 写回 `null`;`onValueChange` 只回传条目值,从不回传 `null`。这个操作没有可见提示(读屏经当前项的描述「再次选择取消定位」获知),因此可见的出口仍应放在 `footer`,例如「清除定位」按钮,与 `onClear` 写回同一处状态。
1848
1907
  - `SplitSidebarItem.depth` 从 0 起,每级缩进一档。树形目录必须逐项给出 `depth`,否则全部平铺。
1849
1908
  - `SplitSidebarItem.icon` 应传 `Icon`,字形须在 `src/icon/registry.json` 中登记。
1850
- - `width` 只在需要覆盖已登记宽度时传;不传则取 `--ui-sidebar-list-width`,三档密度自动生效。
1851
- - 该组件自身滚动,右侧分隔边框由它持有。调用方不得再加外边距或第二条分隔线。
1909
+ - `width` 只在需要覆盖已登记宽度时传;不传则取 `--ui-sidebar-list-width`,三档密度自动生效。放进 `Resizable` 的左栏时宽度自动交给栏位(填满栏宽、随拖拽变化),调用方不必再传 `width="100%"`;栏宽由 `Resizable` 的 `size` 决定,要跟随密度档就给它传 `'var(--ui-sidebar-list-width)'`。
1910
+ - 该组件自身滚动,右侧分隔边框由它持有。调用方不得再加外边距或第二条分隔线。放进 `Resizable` 的左栏等高度确定的父级时,它在父级内填满高度,目录区滚动、`footer` 贴底,调用方不必再补 `block-size`。
1911
+ - 目录项按 `depth` 渲染为嵌套列表,读屏可报出层级;它不是 `role="tree"`,没有展开 / 收起。
1852
1912
  - `settings` 是目录设置,与右栏的呈现设置是两回事,两者不得互相顶替。
1853
- - 目录项的计数经 `count` 传入,不得拼进 `label`。
1913
+ - 目录项的计数经 `count` 传入,不得拼进 `label`;条目名读作「标签,N 条」。
1854
1914
 
1855
1915
  **禁止 / 使用边界。**
1856
1916
  - 禁止在左栏放置第二个 Page Mode Switch。
@@ -1902,13 +1962,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1902
1962
  - 消息流与活动流的条目改用 `Message`,会话气泡改用 `Bubble`。
1903
1963
  - 六种系统状态的承载、批量动作条与分页的挂载,由宿主 `ApplicationDataDisplay` 负责,不在本组件内解决。
1904
1964
 
1905
- **组合约定。** 本组件必须放进 `ApplicationDataDisplay` 的 `children`,仅在 `state="ready"` 时渲染。外边距由 `ApplicationPageLayoutContainer` 持有(`--ui-page-gutter` 与 `--ui-section-gap`),本组件与其行一律不自带 margin。`selectable` 为 true 时行首由组件自动渲染 `ListSelectionCheckbox`,调用方不得再自行插一个;`selected` 与 `onSelectedChange` 必须成对提供,本组件的选择是受控的。选择集合非空时,调用方必须把 `ListBatchActionBar` 交给 `ApplicationDataDisplay` 的 `batchBar`。`activeId` 与选择集合是两回事:前者是 SPLIT 右栏或抽屉流程中的当前对象,只有一个,视觉上是选中底色;后者是勾选集合,视觉上是 4% 淡洗。`RecordListItem.actions` 由组件包一层并阻止点击冒泡;一旦改用 `renderRow` 接管行主体,阻止冒泡的责任转移给调用方。行高 56px,容得下标题与元信息两行。呈现设置按钮读作「列设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
1965
+ **组合约定。** 本组件必须放进 `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` 另由组件包一层阻止冒泡,连同动作区的留白一起不开行。改用 `renderRow` 接管行主体时同样成立,调用方不必再手动阻止冒泡。给了 `onOpen` 的行可聚焦、Enter / 空格打开,行保留列表项语义;`activeId` 那一行输出 `aria-current="true"`。行首勾选框的可访问名为「选择」加记录标题(`renderRow` 接管且 `title` 不是纯文本时回落为「选择此行」)。行高 56px,容得下标题与元信息两行。`presentation` 取 `RecordList`,不得谎报为 `DataTable`;呈现设置按钮读作「列表设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
1906
1966
 
1907
1967
  **禁止 / 使用边界。**
1908
1968
  - 不得在本组件内持有搜索、筛选、排序状态 —— 那些全部属于 `ApplicationQueryToolbar`,数据展示区绝不持有第二套查询状态。
1909
1969
  - 不得把右键菜单作为某个记录级动作的唯一入口,该动作必须同时出现在行尾或详情中。
1910
1970
  - 不得为业务记录另写一套行结构,需要改写行主体时使用 `renderRow`。
1911
- - 禁止在 `renderRow` 返回的行主体里省略阻止冒泡 —— 点动作绝不能顺带打开详情。
1971
+ - 禁止在 `renderRow` 返回的行主体上另挂点击或按键处理来打开详情 —— 打开记录只走 `onOpen`,键盘入口与行内控件的排除由组件统一承担。
1912
1972
  - 不得把分页塞进本组件,分页固定在 `ApplicationDataDisplay` 区域底部。
1913
1973
 
1914
1974
  ## ListBatchActionBar
@@ -1923,7 +1983,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1923
1983
  - 破坏性批量动作的确认改用 `AlertDialog`,标题中必须写明受影响对象的数量。
1924
1984
  - 「已办结 3 条」这类事后确认改用 `Sonner`;需要用户处理的局部失败改用 `Alert`。
1925
1985
 
1926
- **组合约定。** 本组件与 `ListSelectionCheckbox` 成对出现 —— 页面提供了行选择能力就必须提供本组件,反之没有选择能力就不得渲染本组件。挂载位置固定为 `ApplicationDataDisplay` 的 `batchBar` 槽位,外边距由该宿主与 `ApplicationPageLayoutContainer` 负责。`count` 必须由选择集合的长度驱动,不得另设计数状态。`onClear` 必须真正清空选择集合,而不仅仅隐藏动作条。`actions` 内一律传 `Button`,右对齐由组件负责。区带高度 44px,比 32px 的工具栏行高一档 —— 这是区带尺度,不在控件高度标尺(24 / 28 / 32 / 40)上。
1986
+ **组合约定。** 本组件与 `ListSelectionCheckbox` 成对出现 —— 页面提供了行选择能力就必须提供本组件,反之没有选择能力就不得渲染本组件。挂载位置固定为 `ApplicationDataDisplay` 的 `batchBar` 槽位,外边距由该宿主与 `ApplicationPageLayoutContainer` 负责。`count` 必须由选择集合的长度驱动,不得另设计数状态。`onClear` 必须真正清空选择集合,而不仅仅隐藏动作条。`actions` 内一律传 `SystemButton`,右对齐由组件负责。区带高度 44px,比 32px 的工具栏行高一档 —— 这是区带尺度,不在控件高度标尺(24 / 28 / 32 / 40)上。
1927
1987
 
1928
1988
  **禁止 / 使用边界。**
1929
1989
  - 不得把批量动作条放进 Shell 的任何一带 —— 批量动作作用于当前选中的那些行,放远了读者看不出它作用于什么。
@@ -1945,7 +2005,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1945
2005
  - 设置、帮助、附件预览这类辅助性面板改用 `Sheet`。
1946
2006
  - 字段规模超出两档宽度可承载的范围时,改用独立编辑页承载。
1947
2007
 
1948
- **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段传 `style={{ gridColumn: '1 / -1' }}`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。`submitting` 为 true 时组件禁用主按钮并置忙态,调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发,因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
2008
+ **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段给 `Field` 传 `span="full"`,不得用内联 `style` 写 `gridColumn`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。主体与底部动作区包在一个 `<form>` 里,主按钮是提交按钮,字段内按 Enter 即提交并调用 `onSubmit`;浏览器自带校验已关闭,字段校验一律走 `Field`。`submitting` 为 true 时组件禁用主按钮并置忙态,同时屏蔽 Esc 与遮罩点击两条关闭路径,取消按钮仍可用;调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发(提交中只剩取消按钮),因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
1949
2009
 
1950
2010
  **禁止 / 使用边界。**
1951
2011
  - 不得把提交失败呈现为 `Sonner` —— 用户必须处理的失败绝不能放进转瞬即逝的提示里。
@@ -1967,7 +2027,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1967
2027
  - 分节超过 3 个、字段超过 15 个、动作流程有实质差异或性能要求不同时,改用独立详情页承载完整内容;抽屉侧只保留核心内容。
1968
2028
  - 编辑与新建改用 `ApplicationFormDialog`;不可逆动作的确认改用 `AlertDialog`。
1969
2029
 
1970
- **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`primaryAction` 是唯一的主对象动作,固定在右下角,其余一律进 `secondaryActions`。关闭按钮由组件渲染并写作「关闭」,独立详情页写「返回」—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
2030
+ **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`side` 默认 `right`;来源在页面右侧(SPLIT 右栏的条目、月格的周末日格)时传 `left`,不得让抽屉盖住刚打开它的那一处。`primaryAction` 是唯一的主对象动作,固定在右下角,其余一律进 `secondaryActions`。关闭按钮由组件渲染并写作「关闭」,独立详情页写「返回」—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
1971
2031
 
1972
2032
  **禁止 / 使用边界。**
1973
2033
  - 不得让深链接指向抽屉 —— 深链接只指向独立详情页。
@@ -1980,7 +2040,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1980
2040
 
1981
2041
  **用途。** 消息、待办、运行总览、风险预警这四个 popover 型全局动作共享的同一个面板。
1982
2042
 
1983
- **何时使用。** 该面板由 `ApplicationPrimaryNavigation` 的右侧动作簇触发,`onAction` 回调的 `kind` 为 `'popover'` 时打开本组件。四个动作复用同一个实例,切换的只是 `title`、`tabs` 与 `children`。它不是模态:背景仍可交互,因此不锁滚动、不陷阱焦点。
2043
+ **何时使用。** 该面板由 `ApplicationPrimaryNavigation` 的右侧动作簇触发,`onAction` 回调的 `kind` 为 `'popover'` 时打开本组件。四个动作复用同一个实例,切换的只是 `title`、`tabs` 与 `children`。它不是模态:背景仍可交互,因此不锁滚动、不陷阱焦点;但打开时焦点移入面板的首个可聚焦元素,Esc 关闭由本组件承担,并与库内其他浮层共用同一个 Esc 层级栈(上层浮层先响应),关闭后焦点归还给打开它的全局动作按钮。由于不陷阱焦点,面板在 DOM 中的挂载位置决定从它 Tab 出去之后的顺序,建议紧跟触发它的全局动作挂载。
1984
2044
 
1985
2045
  **何时改用其他组件。**
1986
2046
  - 设置改用 `Drawer` 或 `Sheet` —— `onAction` 对它给出的 `kind` 是 `'drawer'`,它不走本面板。
@@ -1988,13 +2048,13 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
1988
2048
  - 必须完成或放弃的聚焦任务改用 `Dialog` 或 `ApplicationFormDialog`。
1989
2049
  - 业务页面内容一律留在 Canvas,不进入 Shell 层的任何浮层。
1990
2050
 
1991
- **组合约定。** `open` 与 `title` 必须与 `ApplicationPrimaryNavigation` 的 `activeAction` 同步,四个动作绝不各造一个弹层。`tabs` 传 `GlobalActionTab`(`value` / `label` / `count`),当前项由 `activeTab` 受控、`onTabChange` 回写。`children` 通常是一组 `Message`;条目多到需要独立滚动时用 `MessageScroller` 并给它显式 `height` —— 那是有界的正交滚动区,不得堆叠无界的垂直滚动容器。无条目时传 `emptyState`,内容应是 `Empty`,其文案必须区别于无权限与加载失败。整体性动作(例如「全部标记为已读」)放 `footer`。几何全部由 `--ui-shell-global-action-*` 登记:720px 宽、20px 圆角、680px 最高、16px 视口边距、位于整个 Shell 堆叠之下,调用方不得覆盖。由于本面板非模态,外点击关闭由调用方触发 `onClose`。
2051
+ **组合约定。** `open` 与 `title` 必须与 `ApplicationPrimaryNavigation` 的 `activeAction` 同步,四个动作绝不各造一个弹层。`tabs` 传 `GlobalActionTab`(`value` / `label` / `count`),当前项由 `activeTab` 受控、`onTabChange` 回写。`children` 通常是一组 `Message`;条目多到需要独立滚动时用 `MessageScroller` —— 面板主体是列向 flex,`MessageScroller` 的 `height` 在这里是上限而非定值:视口不够时它自动收缩到面板剩余高度、由它独自滚动,面板主体不再出现第二层纵向滚动;不得在它外面再包一层带高度或滚动的容器。面板主体的系统状态由 `state` 选择槽位,命名照 `ApplicationDataDisplay`:`ready` 渲染 `children`,`loading` 渲染 `loading`(贴近条目结构的 `Skeleton`,主体随之标 `aria-busy`),`empty` 渲染 `emptyState`(`Empty`,点明当前标签的口径),`error` 渲染 `error`(说明失败原因并提供重试),`no-permission` 渲染 `noPermission`;使用某个状态前必须提供该状态的节点,否则主体为空白。不传 `state` 时保持旧行为:有 `children` 渲染它,否则渲染 `emptyState`。非 `ready` 状态下 `footer` 里的整体性动作必须禁用。整体性动作(例如「全部标记为已读」)放 `footer`。几何全部由 `--ui-shell-global-action-*` 登记:720px 宽、20px 圆角、680px 最高、16px 视口边距、位于整个 Shell 堆叠之下,调用方不得覆盖。由于本面板非模态,外点击关闭由调用方触发 `onClose`(点另一个全局动作是切换而非关闭,这份判据只有调用方知道);Esc 已由本组件处理,调用方不得再自挂 keydown 监听处理 Esc —— 那份监听进不了 Esc 层级栈,会与上层浮层同时响应。
1992
2052
 
1993
2053
  **禁止 / 使用边界。**
1994
2054
  - 不得为四个全局动作分别造弹层 —— 一个面板,四套内容。
1995
2055
  - 不得在本面板内渲染设置,也不得在产品内存在第二个设置入口。
1996
2056
  - 不得把业务页面内容搬进本面板,Shell 不承载业务内容。
1997
- - 禁止让 Loading、Empty、No Permission、Error 共用 `emptyState` 一句文案。
2057
+ - 禁止让 Loading、Empty、No Permission、Error 共用一句文案,也不得把加载、失败或无权限的节点塞进 `emptyState` 或 `children`。
1998
2058
  - 不得覆盖已登记的宽度、圆角与最大高度。
1999
2059
 
2000
2060
  ## PeoplePickerDialog
@@ -2010,7 +2070,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
2010
2070
  - 把人员作为筛选维度使用时改用 `ApplicationFilterMenu`,本组件不承担筛选。
2011
2071
  - 非人员的通用选择任务改用 `Dialog`。
2012
2072
 
2013
- **组合约定。** `Person.name` 必须是纯文本 —— 它参与搜索匹配,也用于已选项的移除按钮无障碍名称;`org` 同样参与匹配。`selected` 与 `onSelectedChange` 成对提供,选择受控。搜索框由组件内部以 `SearchField` 渲染,调用方不得再传一个;对应地,本组件没有搜索槽位。已选栏宽 240px,对话框宽度取 720px 一档、高度固定 520px,目录与已选清单各自滚动,人数增减不改变对话框尺寸。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发。作为表单字段的值选择器使用时,触发器与回显由调用方在 `Field` 内提供,本组件只负责选择过程。视口边距、焦点与滚动锁定由 Overlay 基座负责。
2073
+ **组合约定。** `Person.name` 必须是纯文本 —— 它参与搜索匹配,也用于已选项的移除按钮无障碍名称;`org` 同样参与匹配。`selected` 与 `onSelectedChange` 成对提供,选择受控。搜索框由组件内部以 `SearchField` 渲染,调用方不得再传一个;对应地,本组件没有搜索槽位。与 `SearchField` 的约定一致,检索只在 Enter 时生效,清空输入框即恢复全量目录。已选栏宽 240px,对话框宽度取 720px 一档、高度固定 520px,目录与已选清单各自滚动,人数增减不改变对话框尺寸。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发。作为表单字段的值选择器使用时,触发器与回显由调用方在 `Field` 内提供,本组件只负责选择过程;表单本身在 `Dialog` / `Drawer` 里时,本组件就是模态之上放行的那一层(06 · D-3),本组件之上不得再开任何模态。视口边距、焦点与滚动锁定由 Overlay 基座负责。
2014
2074
 
2015
2075
  **禁止 / 使用边界。**
2016
2076
  - 不得把 `Person.name` 传成 JSX —— 那会让该条目搜索不到,也会让移除按钮的无障碍名称失效。
@@ -2031,7 +2091,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
2031
2091
  - 只需要详情主体本身改用 `ApplicationRecordDetailBody`。
2032
2092
  - 文件与日程各有自己的工作台:`FilesCollaborationWorkspace`、`ScheduleCollaborationWorkspace`。
2033
2093
 
2034
- **组合约定。** 本组件是受控的整体结构,整体复用,不得拆开抄进页面。`search` 应传 `SearchField`,其 `ariaLabel` 必填且应写明搜索范围。`orgTree` 复用 `SplitSidebarItem` 的条目结构(`value` / `label` / `icon` / `count` / `depth`),树形缩进走 `depth`,不要另造一套树数据。`detail` 应传 `ApplicationRecordDetailBody`。`activePerson` 为空是完全合法的状态,不得为了填满详情栏而自动选中第一个成员。成员行的头像、姓名、岗位、状态由 `WorkspacePerson` 的四个字段驱动,行本身复用 Foundation `Item`。本组件不设工具栏槽位 —— 页面级动作留在 `ApplicationPageHeader`。外壳的边框、16px 圆角与分栏滚动规则由三个 collaboration 组件共用同一份 CSS,`--mh-contacts-*` 是本组件的局部尺度而非公共接口。
2094
+ **组合约定。** 本组件是受控的整体结构,整体复用,不得拆开抄进页面。`search` 应传 `SearchField`,其 `ariaLabel` 必填且应写明搜索范围。`orgTree` 复用 `SplitSidebarItem` 的条目结构(`value` / `label` / `icon` / `count` / `depth`),树形缩进走 `depth`,不要另造一套树数据;组织树渲染为按 `depth` 嵌套的列表,恒为展开,不声明 `role="tree"`。`detail` 应传 `ApplicationRecordDetailBody`。`activePerson` 为空是完全合法的状态,不得为了填满详情栏而自动选中第一个成员;此时不传 `detail`,详情栏显示 `detailEmpty`(缺省为内置的「未选择成员」)。当前机构下没有成员时成员栏显示 `peopleEmpty`(缺省为内置的「此机构下无成员」)。系统状态经 `state` 与 `loading` / `empty` / `error` / `noPermission` / `notFound` 五个槽位表达,取值与命名同 `ApplicationDataDisplay`:非 `ready` 时槽位顶替成员栏与详情栏两栏,组织树保留,读者仍能换一个机构;`loading` 应传贴近「成员列表 · 详情」两栏的 `Skeleton`,五个槽位各写各的措辞。本组件不得放进 `ApplicationDataDisplay`,也不得在非 `ready` 时整块换成它 —— 那会画出双层外框并让分栏滚动失效。成员行的头像、姓名、岗位、状态由 `WorkspacePerson` 的四个字段驱动,行本身复用 Foundation `Item`。本组件不设工具栏槽位 —— 页面级动作留在 `ApplicationPageHeader`。外壳的边框、16px 圆角与分栏滚动规则由三个 collaboration 组件共用同一份 CSS,`--mh-contacts-*` 是本组件的局部尺度而非公共接口。
2035
2095
 
2036
2096
  **禁止 / 使用边界。**
2037
2097
  - 不得在每个页面重新搭一遍三栏布局 —— 复制出去的外壳会让下一次调整要改多处。
@@ -2039,6 +2099,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
2039
2099
  - 不得为了填满详情栏自动选中第一个成员。
2040
2100
  - 禁止把本组件的外壳类名挪作其他三栏布局使用。
2041
2101
  - 不得在本组件外再包一层自己的 padding,页面内容根的内边距由 `ApplicationPageLayoutContainer` 持有。
2102
+ - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案,成员栏与详情栏的空态也不得借用 `empty` 的措辞。
2042
2103
 
2043
2104
  ## FilesCollaborationWorkspace
2044
2105
 
@@ -2052,7 +2113,7 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
2052
2113
  - 附件预览若属于业务详情的一部分,改由 `ApplicationRecordDetailBody` 的分节 `content` 承载。
2053
2114
  - 人员与日程各有自己的工作台:`ContactsCollaborationWorkspace`、`ScheduleCollaborationWorkspace`。
2054
2115
 
2055
- **组合约定。** 本组件是整装件,整体复用。`search` 应传 `SearchField`,`folders` 复用 `SplitSidebarItem` 的条目结构。`preview` 仅在确有选中项时传 —— 无选中项时整体省略该槽位,与「无真实指标时不渲染指标区」是同一条原则。`empty` 应传 `Empty`,文案须点明是「此目录下」无文件,且不得与无权限、未找到、加载失败共用措辞。上传、新建文件夹这类目录级动作放 `toolbar`。本组件不设 `batchBar` 槽位,选中文件后的批量动作同样由调用方放进 `toolbar`。行选择由内部 `Table` 承载,`selected` 与 `onSelectedChange` 成对提供;打开文件走 `onOpen`。文件夹树 280px、预览栏 320px,文件表占剩余宽度并独立滚动。
2116
+ **组合约定。** 本组件是整装件,整体复用。`search` 应传 `SearchField`,`folders` 复用 `SplitSidebarItem` 的条目结构。`preview` 仅在确有选中项时传 —— 无选中项时整体省略该槽位,与「无真实指标时不渲染指标区」是同一条原则。`empty` 应传 `Empty`,文案须点明是「此目录下」无文件,且不得与无权限、未找到、加载失败共用措辞;它在 `ready` 而目录为空时由文件表显示,`state="empty"` 时顶替文件表显示。系统状态经 `state` 与 `loading` / `empty` / `error` / `noPermission` / `notFound` 槽位表达,取值与命名同 `ApplicationDataDisplay`:非 `ready` 时槽位顶替文件表、预览栏不渲染,文件夹树与工具栏保留;本组件不得放进 `ApplicationDataDisplay`,也不得在非 `ready` 时整块换成它。上传、新建文件夹这类目录级动作放 `toolbar`,槽位内的多件横向排列并自带控件间距,调用方不得再包一层 flex 容器。本组件不设 `batchBar` 槽位,选中文件后的批量动作同样由调用方放进 `toolbar`。行选择由内部 `Table` 承载,`selected` 与 `onSelectedChange` 成对提供;打开文件走 `onOpen`。文件夹树 280px、预览栏 320px,文件表占剩余宽度并独立滚动,表头吸顶。
2056
2117
 
2057
2118
  **禁止 / 使用边界。**
2058
2119
  - 不得在没有选中项时传 `preview` —— 空的预览栏会白占一栏宽度。
@@ -2065,14 +2126,14 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
2065
2126
 
2066
2127
  **用途。** 「日程」工作台的整装模块件 —— 粒度切换、月格、当日议程栏。
2067
2128
 
2068
- **何时使用。** 需要在一个工作台面里同时看到月度分布与当日明细时使用本组件。周一为一周起始。日格最多平铺 2 条事件,其余折成「+N」;格高 76px,议程栏宽 280px。粒度在日、周、月三档之间切换,由 `grain` 与 `onGrainChange` 受控。
2129
+ **何时使用。** 需要在一个工作台面里同时看到月度分布与当日明细时使用本组件。周一为一周起始。日格最多平铺 2 条事件,其余折成「+N」;格高 76px,议程栏宽 280px。粒度在日、周、月三档之间切换,由 `grain` 与 `onGrainChange` 受控。周档显示焦点日所在的那一周(周一至周日,可跨月),日档只显示焦点日;焦点日取 `selectedDate`(须落在 `month` 当月内),否则取当月 1 日。周、日两档的事件全部平铺,不折叠。
2069
2130
 
2070
2131
  **何时改用其他组件。**
2071
2132
  - 表单里的日期字段与筛选区间,改用 Foundation `Calendar` 与 `Input` 一起放进 `Popover` —— 那是控件,本组件是工作台面。
2072
2133
  - 整页的日历承载面改用 `CALENDAR` 页面模式,即 `ApplicationPageHeader` 的 `pageMode` 与 `ApplicationDataDisplay` 的 `presentation="Calendar"` 组合。
2073
2134
  - 人员与文件各有自己的工作台:`ContactsCollaborationWorkspace`、`FilesCollaborationWorkspace`。
2074
2135
 
2075
- **组合约定。** 本组件是整装件,整体复用。`month` 是 `Date`,只取年月;`selectedDate` 与 `ScheduleEvent.date` 是 ISO `yyyy-mm-dd` 字符串 —— 它们是标识而非时间点,两者语义不同,不强行统一为同一种类型。事件日期串必须按本地时区生成,与组件内部的日期比较口径一致。`onGrainChange` 回传的是 `ScheduleGrain` 字面量,调用方不得回写其他值。`toolbar` 排在粒度切换之后,属于日程范围内的动作。外壳的边框、16px 圆角与分栏滚动规则与另外两个 collaboration 组件共用同一份 CSS;三者栏数并不相同:本组件是月格与议程栏两栏,`ContactsCollaborationWorkspace` 是三栏,`FilesCollaborationWorkspace` 视 `preview` 有无为两栏或三栏。选用任何日历型承载面之前,调用方必须先命名日期字段与真实的观察粒度。
2136
+ **组合约定。** 本组件是整装件,整体复用。`month` 是 `Date`,只取年月;`selectedDate` 与 `ScheduleEvent.date` 是 ISO `yyyy-mm-dd` 字符串 —— 它们是标识而非时间点,两者语义不同,不强行统一为同一种类型。事件日期串必须按本地时区生成,与组件内部的日期比较口径一致。`onGrainChange` 回传的是 `ScheduleGrain` 字面量,调用方不得回写其他值。`toolbar` 排在粒度切换之后,属于日程范围内的动作。翻页由组件内置:提供 `onMonthChange` 时标题行出现「上一页 · 今天 · 下一页」三个按钮,文案随粒度为「上月 / 下月」「上周 / 下周」「前一天 / 后一天」;月档翻一个月,周档、日档把焦点日前后移 7 天 / 1 天并经 `onSelectDate` 回传,跨月时同时回调 `onMonthChange`(周档、日档未提供 `onSelectDate` 时按月翻);「今天」回调今天所在月份并选中今天。`onMonthChange` 回传目标月份的 1 日。提供了 `onMonthChange` 就不得再往 `toolbar` 里塞一套翻月按钮;不提供时组件不渲染翻页控件。选中日期当天没有事件时议程栏显示 `agendaEmpty`(缺省为内置的「当日无日程」)。系统状态经 `state` 与 `loading` / `empty` / `error` / `noPermission` / `notFound` 槽位表达,取值与命名同 `ApplicationDataDisplay`:非 `ready` 时槽位顶替月格、议程栏不渲染,标题行保留;本组件不得放进 `ApplicationDataDisplay`,也不得在非 `ready` 时整块换成它。外壳的边框、16px 圆角与分栏滚动规则与另外两个 collaboration 组件共用同一份 CSS;三者栏数并不相同:本组件是月格与议程栏两栏,`ContactsCollaborationWorkspace` 是三栏,`FilesCollaborationWorkspace` 视 `preview` 有无为两栏或三栏。选用任何日历型承载面之前,调用方必须先命名日期字段与真实的观察粒度。
2076
2137
 
2077
2138
  **禁止 / 使用边界。**
2078
2139
  - 不得用本组件替代 `CALENDAR` 页面模式,两者同名不同层。
@@ -2080,3 +2141,4 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
2080
2141
  - 不得把周日作为一周起始。
2081
2142
  - 禁止绕开「+N」折叠机制在单个日格内堆入超过 2 条事件。
2082
2143
  - 不得在缺少日期字段或未确定观察粒度的情况下选用本组件。
2144
+ - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案。