x-next 1.16.1 → 1.18.0

package/AI_USAGE/catalog.md

@@ -1,9 +1,9 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # 公开组件与服务导航
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
-从当前构建的根公共声明生成，包含 105 个具名组件/服务导出（含子组件和别名，不等于组件族数量），每项均有包内用法与 API 导航。运行时仅从 `x-next` 导入；未列出的 hooks、指令和类型继续查 [公共入口声明](../dist/index.d.ts)。
+从当前构建的根公共声明生成，包含 106 个具名组件/服务导出（含子组件和别名，不等于组件族数量），每项均有包内用法与 API 导航。运行时仅从 `x-next` 导入；未列出的 hooks、指令和类型继续查 [公共入口声明](../dist/index.d.ts)。
 
 | 导出 | 形式 | 本地用法 | 本地 API | 类型导航 | 样式入口 |
 | --- | --- | --- | --- | --- | --- |
@@ -104,6 +104,7 @@
 | TimeRangeSelector | 组件 | [用法](./components/time-range-selector.md) | [API](./components/time-range-selector-api.md#timerangeselector-api) | [公开声明](../dist/components/time-range-selector/index.d.ts) | x-next/style/time-range-selector |
 | Tooltip | 组件 | [用法](./components/tooltip.md) | [API](./components/tooltip-api.md#tooltip-api) | [公开声明](../dist/components/tooltip/index.d.ts) | x-next/style/tooltip |
 | Tr | 组件 | [用法](./components/table.md) | [API](./components/table-api.md#tr-api) | [公开声明](../dist/components/table/table-tr.d.ts) | x-next/style/table |
+| Transfer | 组件 | [用法](./components/transfer.md) | [API](./components/transfer-api.md#transfer-api) | [公开声明](../dist/components/transfer/index.d.ts) | x-next/style/transfer |
 | TreeSelect | 组件 | [用法](./components/tree-select.md) | [API](./components/tree-select-api.md#treeselect-api) | [公开声明](../dist/components/tree-select/index.d.ts) | x-next/style/tree-select |
 | TreeSelectDropdown | 组件 | [用法](./components/tree-select.md) | [API](./components/tree-select-api.md#treeselectdropdown-api) | [公开声明](../dist/components/tree-select/index.d.ts) | x-next/style/tree-select |
 | TrendChart | 组件 | [用法](./components/trend-chart.md) | [API](./components/trend-chart-api.md#trendchart-api) | [公开声明](../dist/components/trend-chart/index.d.ts) | x-next/style/base.css |

package/AI_USAGE/components/alert-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Alert 完整公开 API
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/alert.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Alert AI 使用
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。公开导出：`Alert`；主要模型：v-model:visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./alert-api.md)，包含本组件族全部子组件和别名。
 
@@ -80,6 +80,38 @@ import { Alert } from 'x-next';
 </template>
 ```
 
+### 暗色主题
+
+暗色提示与 Button 状态按钮、Link 悬浮背景及反馈图标底使用同组状态配色，正文保持浅色，图标保留类型辨识度。`normal` 继续使用中性弱提示背景。下面通过 ConfigProvider 展示局部暗色，页面主题切换时也会应用相同配色。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert as XAlert, ConfigProvider as XConfigProvider } from 'x-next';
+import 'x-next/style/base.css';
+import 'x-next/style/alert.css';
+</script>
+<template>
+<XConfigProvider :dark="true" class="alert-dark-example">
+    <XAlert type="info">用于普通信息提示。</XAlert>
+    <XAlert type="success">用于成功状态反馈。</XAlert>
+    <XAlert type="warning">用于需要关注的警告信息。</XAlert>
+    <XAlert type="strong">用于需要强调的提醒信息。</XAlert>
+    <XAlert type="error">用于错误或失败信息。</XAlert>
+    <XAlert type="normal">用于弱提示或中性说明。</XAlert>
+  </XConfigProvider>
+</template>
+<style scoped>
+.alert-dark-example {
+  display: grid;
+  gap: 12px;
+  padding: 20px;
+  border-radius: 8px;
+  background: var(--x-color-bg-surface);
+}
+</style>
+```
+
 ### 标题
 
 ```vue

package/AI_USAGE/components/bar-chart-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # BarChart 完整公开 API
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/bar-chart.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # BarChart AI 使用
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。公开导出：`BarChart`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./bar-chart-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/boxicons.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Boxicons AI 用法
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。本地组件文档导入的选型和配套资源用法。
 

package/AI_USAGE/components/button-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Button 完整公开 API
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 
@@ -19,13 +19,12 @@
 | loadingFill | 加载时居中覆盖内容并保持尺寸；结束后恢复文字和插槽 | undefined &#124; false &#124; true | 否 | false |
 | debounce | 点击后保持 loading 态的时间，单位 ms，用于防重复点击 | undefined &#124; number | 否 | 0 |
 | shape | 胶囊形、圆形或直角；未设置时使用默认圆角 | undefined &#124; "round" &#124; "circle" &#124; "square" | 否 | undefined |
-| link | 是否展示为链接按钮样式 | undefined &#124; false &#124; true | 否 | false |
-| type | 按钮类型 | undefined &#124; "default" &#124; "primary" &#124; "dashed" &#124; "outline" &#124; "text" | 否 | "default" |
+| type | 按钮形态；primary 是实心形态的快捷类型，默认使用品牌色 | undefined &#124; "default" &#124; "primary" &#124; "solid" &#124; "subtle" &#124; "dashed" &#124; "outline" &#124; "text" | 否 | "default" |
 | htmlType | 原生按钮类型；模板中使用 html-type | undefined &#124; "button" &#124; "submit" &#124; "reset" | 否 | "button" |
-| status | 按钮状态 | undefined &#124; "default" &#124; "success" &#124; "warning" &#124; "strong" &#124; "info" &#124; "danger" | 否 | "default" |
-| plain | 是否朴素样式 | undefined &#124; false &#124; true | 否 | false |
+| status | 按钮颜色 | undefined &#124; "default" &#124; "success" &#124; "warning" &#124; "strong" &#124; "info" &#124; "primary" &#124; "danger" | 否 | "default" |
+| plain | 将 default / solid / primary 改为弱底，保留颜色 | undefined &#124; false &#124; true | 否 | false |
 | size | 按钮尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" &#124; "huge" | 否 | undefined |
-| border | 是否显示边框 | undefined &#124; false &#124; true | 否 | true |
+| border | 是否允许形态的边框；false 只隐藏边框 | undefined &#124; false &#124; true | 否 | true |
 | narrow | 是否使用窄按钮，无内边距 | undefined &#124; false &#124; true | 否 | false |
 
 ### Events
@@ -41,7 +40,7 @@
 | default | 按钮内容 | () => any |
 | prefix | 前置内容 | () => any |
 | suffix | 后置内容 | () => any |
-| icon | 图标内容，会渲染在文字前；仅有此插槽时按钮等宽高，请设置 aria-label | any |
+| icon | 图标内容，会渲染在文字前；仅有此插槽时通常等宽高，block 时撑满父宽；请设置 aria-label | any |
 
 ### 实例方法
 
@@ -54,9 +53,9 @@
 ```typescript-reference
 type ButtonSize = 'mini' | 'small' | 'medium' | 'large' | 'huge';
 
-type ButtonStatus = 'default' | 'success' | 'warning' | 'strong' | 'danger' | 'info';
+type ButtonStatus = 'default' | 'primary' | 'success' | 'warning' | 'strong' | 'danger' | 'info';
 
-type ButtonTypes = 'primary' | 'default' | 'dashed' | 'outline' | 'text';
+type ButtonTypes = 'primary' | 'default' | 'solid' | 'subtle' | 'dashed' | 'outline' | 'text';
 
 type ButtonHtmlType = 'button' | 'submit' | 'reset';
 
@@ -69,7 +68,6 @@ type ButtonProps = {
     loadingFill?: boolean;
     debounce?: number;
     shape?: ButtonShape;
-    link?: boolean;
     type?: ButtonTypes;
     htmlType?: ButtonHtmlType;
     status?: ButtonStatus;
@@ -89,11 +87,11 @@ type ButtonProps = {
 
 | 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
 | --- | --- | --- | --- | --- |
-| type | 子按钮默认类型 | undefined &#124; "default" &#124; "primary" &#124; "dashed" &#124; "outline" &#124; "text" | 否 | 未声明 |
-| status | 子按钮默认状态 | undefined &#124; "default" &#124; "success" &#124; "warning" &#124; "strong" &#124; "info" &#124; "danger" | 否 | 未声明 |
+| type | 子按钮默认类型 | undefined &#124; "default" &#124; "primary" &#124; "solid" &#124; "subtle" &#124; "dashed" &#124; "outline" &#124; "text" | 否 | 未声明 |
+| status | 子按钮默认状态 | undefined &#124; "default" &#124; "success" &#124; "warning" &#124; "strong" &#124; "info" &#124; "primary" &#124; "danger" | 否 | 未声明 |
 | shape | 子按钮默认形状 | undefined &#124; "round" &#124; "circle" &#124; "square" | 否 | 未声明 |
 | size | 子按钮默认尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" &#124; "huge" | 否 | 未声明 |
-| disabled | 是否禁用所有子按钮 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| disabled | 子按钮默认禁用值；子按钮显式值优先 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
 
 ### Events
 
@@ -114,9 +112,9 @@ type ButtonProps = {
 ```typescript-reference
 type ButtonSize = 'mini' | 'small' | 'medium' | 'large' | 'huge';
 
-type ButtonStatus = 'default' | 'success' | 'warning' | 'strong' | 'danger' | 'info';
+type ButtonStatus = 'default' | 'primary' | 'success' | 'warning' | 'strong' | 'danger' | 'info';
 
-type ButtonTypes = 'primary' | 'default' | 'dashed' | 'outline' | 'text';
+type ButtonTypes = 'primary' | 'default' | 'solid' | 'subtle' | 'dashed' | 'outline' | 'text';
 
 type ButtonHtmlType = 'button' | 'submit' | 'reset';
 
@@ -129,7 +127,6 @@ type ButtonProps = {
     loadingFill?: boolean;
     debounce?: number;
     shape?: ButtonShape;
-    link?: boolean;
     type?: ButtonTypes;
     htmlType?: ButtonHtmlType;
     status?: ButtonStatus;

package/AI_USAGE/components/button.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Button AI 使用
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。公开导出：`Button, ButtonGroup`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./button-api.md)，包含本组件族全部子组件和别名。
 
@@ -9,7 +9,7 @@
 
 ## 已核验行为与示例
 
-[组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。尺寸优先级为显式 `size` → ButtonGroup → ConfigProvider → `'medium'`；Button 不通过 FormItem 继承尺寸。`disabled` / `loading` 默认关闭。
+[组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 管形态，默认 `'default'`；实心用 `'solid'`、弱底用 `'subtle'`、透明用 `'outline'/'dashed'/'text'`。`status` 管颜色，默认中性 `'default'`，品牌色显式 `'primary'`。默认与中性 outline 是同一普通操作层级的弱底 / 透明表面差异；品牌描边显式使用 status=primary。兼容 `type='primary'` 解析品牌实心，其他语义 status 优先；`plain` 仅把填充形态转为 subtle，`border=false` 只隐藏边框；语义弱底不额外描边，中性默认保留细边，outline/dashed 需要边框。波纹颜色跟随状态；text、disabled/loading 无外部波纹。深灰实心是独立纯灰的高权重进阶组合，不代表次要或禁用。text 保留按钮点击区域，`type="text" narrow` 去掉水平内边距且保持按钮高度；URL 导航用 Link 的 href 或项目路由方案。Button 不提供 link 类型或布尔 link 属性。`htmlType` 默认 `'button'`，原生提交用 `'submit'`。尺寸优先级为显式 `size` → ButtonGroup → ConfigProvider → `'medium'`；Button 不通过 FormItem 继承尺寸。`disabled` / `loading` 默认关闭。
 
 `click` 载荷为 `MouseEvent`，禁用或加载中不会触发。`default`、`prefix`、`suffix`、`icon` 插槽可组合内容；异步业务自行维护 `loading`。
 
@@ -61,14 +61,141 @@ import { Button } from 'x-next';
 <template>
 <Button>默认按钮</Button>
   <Button type="primary">主要按钮</Button>
-  <Button type="outline">描边按钮</Button>
+  <Button type="outline" status="primary">品牌描边</Button>
   <Button type="text">文本按钮</Button>
 </template>
 ```
 
+### 形态与颜色
+
+通过 `type` 设置形态，通过 `status` 设置颜色。品牌色使用 `status="primary"`。
+
+| 形态 | 表现 |
+| --- | --- |
+| default | 浅色背景；中性按钮有细边框，状态色按钮无边框 |
+| solid | 实心底、白字 |
+| subtle | 弱填充、无可见边框 |
+| outline / dashed | 透明底、实线 / 虚线边框 |
+| text | 透明文字，保留按钮尺寸与内边距 |
+
+### 文本动作与跳转链接
+
+`type="text"` 适合表格或工具栏操作，加上 `narrow` 可去掉水平内边距。跳转页面使用 `x-link` 的 `href`。
+
+### 进阶组合：深灰实心
+
+深灰实心适合黑白品牌或强调操作；次要操作可使用默认或文本按钮。
+
+### 组合预览
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button type="solid" status="primary">品牌实心</Button>
+  <Button type="subtle" status="primary">品牌弱底</Button>
+  <Button type="outline" status="primary">品牌描边</Button>
+  <Button type="text" status="primary">品牌文本</Button>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button as XButton, Link as XLink } from 'x-next';
+import 'x-next/style/button';
+import 'x-next/style/link';
+const textCount = ref(0);
+const compactCount = ref(0);
+</script>
+<template>
+<XButton type="text" status="primary" @click="textCount++">文本操作</XButton>
+  <span>行内动作：<XButton type="text" narrow status="primary" @click="compactCount++">紧凑文本操作</XButton></span>
+  <XLink href="/components/link" :hoverable="false">查看 Link 文档</XLink>
+  <span role="status">文本操作 {{ textCount }} 次，紧凑操作 {{ compactCount }} 次</span>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button type="solid">深灰实心</Button>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button as XButton, ButtonGroup as XButtonGroup, Select as XSelect, Checkbox as XCheckbox } from 'x-next';
+import type { ButtonTypes, ButtonStatus } from 'x-next';
+import 'x-next/style/button';
+import 'x-next/style/form-select';
+import 'x-next/style/form-checkbox';
+const types = ['default', 'solid', 'subtle', 'outline', 'dashed', 'text', 'primary'] as const;
+const statuses = ['default', 'primary', 'success', 'warning', 'strong', 'danger', 'info'] as const;
+const typeOptions = types.map(value => ({ label: value, value }));
+const statusOptions = statuses.map(value => ({ label: value, value }));
+const typeAttrs = { 'aria-label': '按钮形态' };
+const statusAttrs = { 'aria-label': '按钮颜色' };
+const type = ref<ButtonTypes>('outline');
+const status = ref<ButtonStatus>('default');
+const plain = ref(false), border = ref(true), count = ref(0);
+</script>
+<template>
+<div class="button-controls">
+    <div class="button-field">
+      <span>形态</span>
+      <XSelect v-model="type" :options="typeOptions" v-bind="typeAttrs" class="button-select" />
+    </div>
+    <div class="button-field">
+      <span>颜色</span>
+      <XSelect v-model="status" :options="statusOptions" v-bind="statusAttrs" class="button-select" />
+    </div>
+    <XCheckbox v-model="plain">plain</XCheckbox>
+    <XCheckbox v-model="border">border</XCheckbox>
+  </div>
+  <XButton :type="type" :status="status" :plain="plain" :border="border" @click="count++">组合按钮</XButton>
+  <span role="status">已触发 {{ count }} 次</span>
+  <XButtonGroup type="outline">
+    <XButton :border="false">组内无边框一</XButton>
+    <XButton :border="false">组内无边框二</XButton>
+  </XButtonGroup>
+</template>
+<style scoped>
+.button-controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+}
+.button-field {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: none;
+}
+.button-field > span {
+  white-space: nowrap;
+}
+.button-field :deep(.button-select) {
+  width: 136px;
+  flex: none;
+}
+</style>
+```
+
 ### 外部水波纹
 
-Button 默认开启类似 Ant Design Vue 的外部轮廓水波纹。`disabled`、`loading`、`link` 和 `type="text"` 状态不会展示外部水波纹。
+点击按钮查看反馈。禁用、加载或文本按钮不显示水波纹。
 
 ```vue
 <script setup lang="ts">
@@ -80,6 +207,7 @@ import { Button } from 'x-next';
 <Button>默认水波纹</Button>
   <Button type="primary">主要水波纹</Button>
   <Button status="danger">危险水波纹</Button>
+  <Button type="outline" status="danger">危险描边水波纹</Button>
   <Button loading>加载不触发</Button>
   <Button disabled>禁用不触发</Button>
 </template>
@@ -87,6 +215,8 @@ import { Button } from 'x-next';
 
 ### 状态
 
+通过 `status` 表达成功、警告、危险等状态。
+
 ```vue
 <script setup lang="ts">
 import 'x-next/style.css';
@@ -104,15 +234,45 @@ import { Button } from 'x-next';
 </template>
 ```
 
-### 状态色实心按钮
+### 暗色状态按钮
 
-五种状态色都提供实心（高亮）形态，**统一使用白字**与主题惯例一致。实心底色即主题种子色：主要 `#1c61ff`、成功 `#00a809`、警告 `#ffb800`、强调 `#ff8200`、危险 `#e02225`。
+通过 `ConfigProvider` 的 `dark` 属性设置局部暗色。
 
-危险色种子 `#e02225` 的白字对比为 4.75:1，实心底直接使用种子本身，不再需要压暗变体。
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button as XButton, ConfigProvider as XConfigProvider } from 'x-next';
+import 'x-next/style/base.css';
+import 'x-next/style/button.css';
+</script>
+<template>
+<XConfigProvider :dark="true" class="button-dark-example">
+    <XButton>默认</XButton>
+    <XButton status="success">成功</XButton>
+    <XButton status="warning">警告</XButton>
+    <XButton status="strong">强调</XButton>
+    <XButton status="danger">危险</XButton>
+    <XButton status="info">信息</XButton>
+    <XButton disabled>禁用</XButton>
+  </XConfigProvider>
+</template>
+<style scoped>
+.button-dark-example {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  padding: 20px;
+  border-radius: 8px;
+  background: var(--x-color-bg-surface);
+}
+</style>
+```
+
+### 状态色实心按钮
 
-实心底与白字在明暗主题下都恒定不翻转，因此暗色下仍是同一块强调色。更换主题种子色（`base.scss` 的 `--x-color-<name>`）后实心按钮整体联动。
+实心按钮适合强调操作，搭配 `status` 设置颜色。
 
-亮黄色、亮橙色实底上的白字属于主题惯例内的折中：这类底亮度过高，强行让白字达到正文级 4.5:1 只能压深到底色失去品牌识别。参考 Arco 的橙色实底白字为 2.57:1、Ant Design 的 `warning` 为 1.90:1，本库 `warning` / `strong` 与二者处于同一水平。需要更高可读性时，可改用 `type="outline"`、`plain` 或 `type="text"` 形态，或把种子色选得更深。各状态实测值与回归下限由 `script/check-contrast.js` 守护。
+黄色、橙色实心按钮的文字对比较弱，需要更高可读性时可选用描边或弱底形态。
 
 ```vue
 <script setup lang="ts">
@@ -131,25 +291,11 @@ import { Button } from 'x-next';
 
 ### 类型与边框
 
-`border="false"` 使用弱背景状态色，不会切换成实心危险按钮。需要实心危险按钮时使用 `type="primary" status="danger"`。
-
-`link` 保持透明背景和对应状态文字色，非圆形链接按钮的高度随文字行高变化、没有水平内边距。禁用和加载期间不会响应悬浮或按下颜色。
-
-彩色文字按钮（`plain`、`outline`、`text`、`link`）在亮色主题中沿用品牌主色，暗色主题中使用同色系的亮色档，与 Link、Tag 同源。对比度下限对齐 Arco 同级角色，由 `script/check-contrast.js` 的 `ARCO_BASELINE` 守护。
-
-### 交互三态
+`:border="false"` 只隐藏边框。需要弱底危险按钮时使用 `type="subtle" status="danger"`，实心危险按钮使用 `type="solid" status="danger"`。
 
-按钮的常态、悬浮、按下按**渐深梯度**设计，每一级都可感知且保持轻盈（明度差 ≥ 0.025，由门禁守护）：
+### 交互状态
 
-| 形态 | 常态 | 悬浮 | 按下 |
-| --- | --- | --- | --- |
-| 默认 / 信息（灰色系） | `fill-2` | `neutral-3` | `neutral-4` |
-| 彩色弱底 / 描边 / 文本（除 warning） | 无色或同色浅底 | 同色浅底混入按钮文字色 10% | 同色浅底混入按钮文字色 16% |
-| warning 弱底 / 描边 / 文本 | 无色或同色浅底 | 同色浅底混入按钮文字色 25% | 同色浅底混入按钮文字色 40% |
-| 链接 | 透明背景、状态文字色 | 保持常态 | 保持常态 |
-| 实色 | 种子实底 | 混白 8%（更亮） | 混恒定深 10%（更深） |
-
-默认按钮不用 `fill-2/3/4` 递进：全局 fill 灰阶在浅端被压缩，`fill-2` 与 `fill-3` 只差 3 个通道，悬浮态几乎看不出变化；改用 `neutral-3/4` 后与 Arco 的步进一致。
+悬浮或按住按钮查看状态变化，也可用 Tab 聚焦后按 Space / Enter 操作。第二组展示局部暗色。
 
 ```vue
 <script setup lang="ts">
@@ -163,15 +309,52 @@ import { Button } from 'x-next';
   <Button type="text">文本按钮</Button>
   <Button plain status="success">朴素成功</Button>
   <Button :border="false" status="danger">无边框危险</Button>
-  <Button link>链接按钮</Button>
-  <Button link status="danger">危险链接</Button>
-  <Button link disabled>禁用链接</Button>
+  <Button type="text" narrow>紧凑文本</Button>
+  <Button type="text" narrow status="danger">危险文本</Button>
+  <Button type="text" narrow disabled>禁用文本</Button>
 </template>
 ```
 
-### 状态矩阵
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button as XButton, ConfigProvider as XConfigProvider } from 'x-next';
+import 'x-next/style/base.css';
+import 'x-next/style/button.css';
 
-Button 的状态色基于组件 alias token 组织，例如 `--x-button-color-bg-danger-subtle`、`--x-button-color-bg-danger-solid`、`--x-button-color-text-danger`。后续自定义主题可以优先覆盖这些组件级 token。
+const count = ref(0);
+const statuses = ['default', 'primary', 'success', 'warning', 'strong', 'danger', 'info'] as const;
+</script>
+<template>
+<div v-for="status in statuses" :key="status">
+    <XButton type="outline" :status="status" @click="count++">描边</XButton>
+    <XButton type="dashed" :status="status" @click="count++">虚线</XButton>
+    <XButton type="text" :status="status" @click="count++">文本</XButton>
+    <XButton type="text" narrow :status="status" @click="count++">紧凑文本</XButton>
+  </div>
+  <XConfigProvider :dark="true" class="button-dark-example">
+    <XButton type="outline" @click="count++">暗色描边</XButton>
+    <XButton type="dashed" @click="count++">暗色虚线</XButton>
+    <XButton type="text" @click="count++">暗色文本</XButton>
+    <XButton type="text" narrow @click="count++">暗色紧凑文本</XButton>
+    <XButton type="outline" disabled>禁用</XButton>
+    <XButton type="text" loading>加载</XButton>
+  </XConfigProvider>
+  <span role="status">已触发 {{ count }} 次</span>
+</template>
+<style scoped>
+.button-dark-example {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  padding: 20px;
+  background: var(--x-color-bg-surface);
+}
+</style>
+```
+
+### 状态矩阵
 
 ```vue
 <script setup lang="ts">
@@ -283,6 +466,15 @@ const pushLog = (label: string) => {
 
 `type` 控制视觉样式，`html-type` 控制原生按钮行为。默认 `html-type="button"`，不会因为放进表单而意外提交。
 
+### 原生动作与防重复点击
+
+<form class="example-box example-box-column" data-demo="button-native-debounce" @submit.prevent="nativeCount++" @reset="formStatus = '防重复示例已重置'">
+  <label>必填内容 <input name="message" required value="初始内容" /></label>
+  <span role="status">已提交 {{ nativeCount }} 次；{{ formStatus }}</span>
+</form>
+
+`debounce` 用于防止重复点击，提交结果在表单的 submit 事件中处理。
+
 ```vue
 <script setup lang="ts">
 import 'x-next/style.css';
@@ -300,6 +492,23 @@ const handleSubmit = () => {
 </template>
 ```
 
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+import { ref } from 'vue';
+const count = ref(0), message = ref('尚未重置');
+</script>
+<template>
+<form @submit.prevent="count++" @reset="message = '已重置'">
+    <label>必填内容 <input name="message" required value="初始内容" /></label>
+    <Button type="solid" status="primary" html-type="submit" :debounce="800">防重复提交</Button>
+    <Button html-type="reset" :debounce="800">防重复重置</Button>
+    <span role="status">已提交 {{ count }} 次；{{ message }}</span>
+  </form>
+</template>
+```
+
 ### 文字与图标
 
 按钮支持中英文混排，可以通过 `prefix`、`suffix` 插槽添加图标或附加文字。下面展示不同尺寸的组合，切换加载状态可查看加载图标与内容的排列。
@@ -433,6 +642,8 @@ const nativeAttrs1 = { "aria-label": "切换填充加载" } satisfies ButtonHTML
 
 按钮组只连接相邻边缘，保留两端的形状；只有一个按钮时仍保留完整圆角。
 
+circle 与 block 同用时保持圆形等宽高；普通纯图标与 block 同用时撑满父宽。按钮组中无边框、subtle 和 text 形态不自动补左侧分隔边框。
+
 ```vue
 <script setup lang="ts">
 import 'x-next/style.css';

package/AI_USAGE/components/charts.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Charts AI 用法
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。本地组件文档导入的选型和配套资源用法。
 

package/AI_USAGE/components/checkbox-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Checkbox 完整公开 API
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/checkbox.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Checkbox AI 使用
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。公开导出：`Checkbox, CheckboxGroup`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./checkbox-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/color-picker-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # ColorPicker 完整公开 API
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/color-picker.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # ColorPicker AI 使用
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。公开导出：`ColorPicker`；主要模型：v-model、v-model:show。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./color-picker-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/config-provider-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # ConfigProvider 完整公开 API
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/config-provider.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # ConfigProvider AI 使用
 
-适用版本：x-next@1.16.1；来源指纹：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+适用版本：x-next@1.18.0；来源指纹：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
 
 先读 [通用接入](../core.md)。公开导出：`ConfigProvider`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./config-provider-api.md)，包含本组件族全部子组件和别名。