Dify UI IconButton：带无障碍命名契约的纯图标命令按钮

在 Dify 的前端 UI 包 @langgenius/dify-ui 中，IconButton 是专门承接"只有一个图标、没有可见文字"的命令按钮的组件。阅读本文后，你将掌握它的无障碍命名契约（aria-label 与 aria-labelledby 二选一）、完整的外观/尺寸/色调变体体系，以及在与 Toggle、Menu、Popover 等拥有交互状态的原语组合时如何通过 render prop 保持状态归属的正确性。

适用边界：什么时候用 IconButton

IconButton 组件文档 开宗明义地划定了三个使用边界：

• 纯图标命令：动作只由一个图标表达、没有可见文字时，使用 IconButton；
• 带可见标签的动作：只要按钮有可见文字（包括带前导或尾部图标的按钮），应使用 Button，包括需要 type="submit" 提交表单或展示 loading 状态的场景；
• URL 导航：激活后跳转到 URL 的操作保留给原生链接，不要渲染成按钮。

实现上，Dify UI 的 IconButton 是一个"有主见的" Base UI Button 封装：它在上游按钮之上叠加了可访问名称的类型契约，以及图标按钮专属的外观、尺寸与色调变体，同时完整保留 Base UI 的键盘交互、焦点与组合行为。组件从包内以独立子路径导出（见 dify-ui 的 package.json 中 ./icon-button 的 exports 映射），消费方式为 @langgenius/dify-ui/icon-button。

无障碍命名契约：恰好一个名称来源

这是 IconButton 契约的核心：每个图标按钮必须且只能提供一个无障碍名称来源——aria-label 或 aria-labelledby，并且遵循 name、role、value 的计算规则。选择二者之一时，应遵循 Dify UI 跨组件的可访问名称与描述契约：优先复用 DOM 中已存在的可见文本（aria-labelledby），只有当角色允许命名且没有任何可见文本可作名称时才退回到 aria-label。需要特别强调的一点是：Tooltip 只是视觉增强，不是按钮的无障碍名称来源；跨组件文档明确建议，当图标按钮配 Tooltip 时，aria-label 内容应与 Tooltip 文本尽量一致。

这个契约不是纯文档约定，而是被 TypeScript 类型强制执行的。从 组件实现 可以看到互斥联合类型：

type AccessibleName =
  | {
      'aria-label': string
      'aria-labelledby'?: never
    }
  | {
      'aria-label'?: never
      'aria-labelledby': string
    }

两个分支各自把另一个属性标记为 never，意味着同时传 aria-label 和 aria-labelledby、或两个都不传，都会在类型检查阶段报错。IconButtonProps 在此基础上 Omit 了 Base Button 的 aria-label、aria-labelledby、children、className，再把 AccessibleName 与变体属性合并进来（index.tsx）。标准用法如下：

<IconButton aria-label="Close">
  <span aria-hidden="true" className="i-ri-close-line size-4" />
</IconButton>

字形规则：恰好一个装饰性 React 元素

子元素必须是恰好一个 React 元素，其中包含装饰性字形，并且要把该字形从无障碍树中隐藏（aria-hidden="true"）。这里的职责划分是清晰的：

• 子元素负责字形及其视觉尺寸——例如 size-4 决定图标光学的占位大小；
• IconButton 负责按钮的尺寸、圆角、颜色、hover、disabled 与 focus-visible 样式；
• className 仅用于外部布局，或由组合后的原语、业务状态属主驱动的样式选择器，不要用它重建已存在的外观变体。

字形本身不限定实现方式：Storybook 示例 中同时演示了 CSS 图标（Tailwind 图标工具类 i-ri-close-line）与内联 SVG 两种写法：

// CSS 图标
<IconButton aria-label="Close">
  <span aria-hidden="true" className="i-ri-close-line size-4" />
</IconButton>

// 内联 SVG（同样需要 aria-hidden）
<IconButton aria-label="Add">
  <svg aria-hidden="true" className="size-4" viewBox="0 0 16 16" fill="none" stroke="currentColor">
    <path d="M8 3v10M3 8h10" strokeLinecap="round" />
  </svg>
</IconButton>

无论哪种字形，children 类型被限定为 React.ReactElement（单个元素），从类型层面杜绝了传文字节点或多个图标的可能——这与"图标按钮的文字名称只能来自 ARIA 属性"的契约保持一致。

外观、尺寸与色调变体

变体系统由 variants.ts 中的 cva（class-variance-authority）定义，三个维度及默认值如下：

维度	取值	说明
variant	省略（默认 default）、primary、secondary、secondary-accent、tertiary、ghost、ghost-accent	省略 variant 得到 IconButton 专属的中性外观；其余命名与 Button 对齐
tone	default（默认）、destructive	破坏性操作用意，如删除
size	xs、sm、md（默认）、lg、xl	按钮盒尺寸与圆角

尺寸与圆角的具体映射（variants.ts）：

size	按钮盒	圆角	内边距	建议图标大小（story 参考）
xs	size-4（16px）	rounded-sm	p-0	size-3.5
sm	size-5（20px）	rounded-md	—	size-4
md（默认）	size-6（24px）	rounded-md	p-0.5	size-4
lg	size-8（32px）	rounded-lg	p-1.5	size-4
xl	size-9（36px）	rounded-lg	p-2	size-5

破坏性色调的实现方式

tone 维度本身不直接挂样式类（tone 的两个取值在 variants 里都是空字符串），而是通过 compoundVariants 与 variant 组合生效（variants.ts）：default、primary、secondary、tertiary、ghost 五个变体各自定义了 destructive 的覆盖样式。以默认变体为例：

// variant=default + tone=destructive 的复合样式
class: [
  'text-text-tertiary hover:bg-state-destructive-hover hover:text-text-destructive',
  'data-disabled:text-text-disabled data-disabled:hover:bg-transparent data-disabled:hover:text-text-disabled',
]

这个设计的交互含义很具体：静止时保持中性外观，悬停时才呈现破坏性意图——Storybook 的 DestructiveIntent 示例 的描述正是 "Destructive intent appears on hover while the resting action remains neutral"。而 primary 的 destructive 复合样式则换成完整的危险色背景（bg-components-button-destructive-primary-bg 等）。所有状态样式都挂在 data-disabled: 等数据属性选择器上，与 Base UI 的 data-* 状态契约对齐。

所有变体共享的基础类还包括 focus-visible:ring-2 焦点环与 data-disabled:cursor-not-allowed 禁用光标（variants.ts）。

与状态属主原语的组合：render prop 模式

文档给出了组合原则：当 Toggle、Menu、Popover、Tooltip 或 Collapsible 拥有交互状态（pressed、open、expanded 等）时，把这些原语保留在外层，通过其 render prop 来组合 IconButton，而不是把状态镜像到图标按钮上——这样能保住属主原语的 pressed/open/expanded 状态、事件与 ref 行为。

组件实现上这很自然：IconButtonProps 直接继承了 Base Button 的全部 props（Omit 掉的四个之外），因此 render 原样透传给了底层的 BaseButton（index.tsx）：

function IconButton({
  className,
  variant,
  tone,
  size,
  type = 'button',
  children,
  ...props
}: IconButtonProps) {
  return (
    <BaseButton
      type={type}
      className={cn(iconButtonVariants({ variant, tone, size }), className)}
      {...props}
    >
      {children}
    </BaseButton>
  )
}

组件测试 专门验证了这条组合路径：把 IconButton 通过 render 挂到一个带 data-trigger="menu" 的 <button> 上后，点击会同时触发 IconButton 上的 onClick 和 rendered 元素上的 onClick，两个 ref 都指向同一个 DOM 节点——确认事件与 ref 没有被中间层截断。

默认行为与测试证据

单元测试 用 vitest 浏览器模式（真实 DOM 交互）锁定了三条契约：

1. 渲染具名的原生按钮：默认渲染 <button type="button">，且能通过 getByRole('button', { name: 'Close' }) 按无障碍名称检索到——即 aria-label 确实参与了可访问名称计算，而 aria-hidden 的字形没有污染名称。这也解释了实现中 type = 'button' 的默认值：图标按钮几乎从不用于表单提交，显式 type="submit" 需要调用方主动声明。
2. 保留 Base UI 的 render prop 组合：见上一节，事件与 ref 双通道验证。
3. 保留 Base UI 的 disabled 行为：disabled 的按钮可被 toBeDisabled() 判定，且原生 click() 不会触发 onClick 回调。

测试文件顶部只导入 render、userEvent 与组件本身，全部断言基于 ARIA 角色与可访问名称，这正是 Dify UI 跨组件文档所要求的验证方式——在每次改动边界上检查可观察的名称、描述与键盘行为。

与 Button 的关系及延伸阅读

IconButton 与 Button 是同一设计体系下的两个分工明确的成员：Button 面向带可见文字标签的动作，额外提供 loading 状态、内容间距管理与 type="submit" 语义；IconButton 面向图标命令，把命名责任收拢到单一的 ARIA 属性上。二者的 variant 命名刻意保持一致，便于同一动作在"有文字/无文字"两种呈现间切换时保持视觉一致。

与本文相关的仓库入口：

• IconButton 组件文档：原始契约定义；
• 组件实现：AccessibleName 联合类型与 Base Button 封装；
• 变体定义：外观、尺寸与破坏性复合样式；
• 单元测试：命名、render 组合与 disabled 行为的浏览器级验证；
• Storybook 故事：全部变体、尺寸对照与破坏性意图的可视化示例；
• 可访问名称与描述契约：跨组件的名称/描述来源选择规则，包括 aria-labelledby 计算优先级、Tooltip 定位与隐藏文本安全移除等内容。