AtomUI/docs/controls/desktop/general/button/token.md

Button Token 设计

本文档定义 AtomUI.Desktop.Controls.ButtonToken 的 Button 专属语义、分类、使用范围和兼容边界。控件 Token 的通用分层、命名、计算、Theme Variables 边界和预设色规则见 AtomUI 控件 Token 设计规范。Button 整体架构见 Button 桌面版架构设计，内部实现原理见 Button 桌面版实现原理，设计和契约变化记录见 Button Changelog。

1. 定位

ButtonToken 是 Button 的组件级设计变量层。它把全局设计体系中的颜色、尺寸、间距、字体和阴影转换为 Button 可消费的语义值。

ButtonToken 服务以下主题和控件：

• ButtonTheme.axaml
• DropdownButtonTheme.axaml
• SplitButtonTheme.axaml
• HyperLinkButtonTheme.axaml
• Button 家族控件中的 icon、额外内容、下拉间距和状态视觉

ButtonToken 不承载 IsPressed、IsPointerOver、IsLoading、EffectiveColor、EffectiveVariant 等实例状态。这些状态由 Button 状态模型和主题变量处理。

2. Token 分类

ButtonToken 当前按 Button 语义分为七类。

2.1 排版 Token

• FontWeight
• ContentFontSize
• ContentFontSizeLG
• ContentFontSizeSM
• ContentLineHeight
• ContentLineHeightLG
• ContentLineHeightSM

用于控制 Button 内容文本的字体大小、行高和字重。字体大小默认来自 SharedToken；行高在 CalculateTokenValues 中根据字体大小计算。

2.2 尺寸与间距 Token

• Padding
• PaddingLG
• PaddingSM
• CirclePadding
• IconOnyPadding
• IconOnyPaddingLG
• IconOnyPaddingSM
• IconMargin
• ExtraContentItemSpacing
• ExtraContentMargin
• ExtraContentMarginLG
• ExtraContentMarginSM
• GutterToFlyout

用于 Button 的尺寸密度、icon-only 内边距、圆形按钮内边距、DropdownButton 额外内容和下拉菜单间距。

SizeType=Custom 不新增 ButtonToken。Custom 尺寸的默认值复用 Middle 档 Token；实例级定制通过 Button 现有布局、排版以及 IconWidth、IconHeight 属性完成，Token 仍只表达预设尺寸语义。

2.3 Icon Token 与 SharedToken 依赖

ButtonToken 提供：

• OnlyIconSize
• OnlyIconSizeLG
• OnlyIconSizeSM

SharedToken 依赖：

• IconSize
• IconSizeLG
• IconSizeSM

IconSizeLG、IconSize、IconSizeSM 是用户 icon 与普通 loading icon 的默认尺寸，也用于非 loading 的 icon-only 用户图标。OnlyIconSizeLG、OnlyIconSize、OnlyIconSizeSM 只用于 :icononly:loading 状态下的 loading icon 默认尺寸，不改变普通 icon-only 用户图标的既有视觉。

Theme 把上述 ButtonToken 或 SharedToken 资源设置到 Button 自身的 IconWidth、IconHeight，模板中的用户 icon 与 loading icon 再通过 TemplateBinding 消费。Token 只提供默认值；Button 实例上的本地 IconWidth、IconHeight 具有更高优先级，并同时覆盖两个图标节点。宽高属性相互独立，Token 默认值为正方形不限制用户设置非正方形尺寸。

2.4 默认按钮颜色 Token

• DefaultColor
• DefaultBg
• DefaultBorderColor
• DefaultBorderColorDisabled
• DefaultHoverBg
• DefaultHoverColor
• DefaultHoverBorderColor
• DefaultActiveBg
• DefaultActiveColor
• DefaultActiveBorderColor
• BorderColorDisabled

用于普通动作的文本、背景、边框及 hover / active / disabled 状态。该组 Token 服务 ButtonType=Default、ButtonType=Dashed 和 Color=Default 的基础视觉。

2.5 主色与危险 Token

• PrimaryColor
• DangerColor
• PrimaryShadow
• DangerShadow

用于主动作和危险动作的前景与阴影。危险语义优先级高，不应通过普通样式覆盖隐式消失。

2.6 Ghost、Text、Link Token

• DefaultGhostColor
• GhostBg
• DefaultGhostBorderColor
• SolidTextColor
• TextTextColor
• TextTextHoverColor
• TextTextActiveColor
• TextHoverBg
• LinkHoverBg

用于 ghost 背景策略、文本按钮、链接按钮和实心按钮前景策略。Ghost 是背景呈现策略，Text / Link 是低强调动作表达。

Text Token 必须保持以下语义：

• ButtonType=Text 等价于 Color=Default + Variant=Text，文字使用 TextTextColor、 TextTextHoverColor 和 TextTextActiveColor，默认都来自 ColorText，不隐式跟随品牌主色。
• TextHoverBg 默认来自 ColorFillTertiary；pressed 背景使用 ColorFill。
• Color=Primary + Variant=Text 的 normal、hover、pressed 文字分别来自 ColorPrimary、 ColorPrimaryHover、ColorPrimaryActive，背景分别为透明、ColorPrimaryBg、ColorPrimaryBorder。
• Danger Text 的 hover 背景使用 ColorErrorBg，pressed 背景使用 ColorErrorBgActive。

2.7 结构协同 Token

• DefaultShadow
• GroupBorderColor

用于默认按钮阴影和按钮组边框协调。该组 Token 影响 Button 与 Button 家族或周边控件的视觉关系。

3. Button 多彩模型中的 Token 使用

Button 多彩模型不在 ButtonToken 中展开所有颜色与 variant 组合。

ButtonToken 保留 Button 组件常用语义值，例如 default、primary、danger、text、link、shadow、padding。Preset color 的 base / hover / active / light / shadow 来源于全局 palette 或通用 preset palette resource。

Button 颜色状态按以下职责使用 Token：

ButtonToken
  提供 default / primary / danger / text / link 等组件语义值

Palette
  提供 preset color 色阶

Effective color resolver
  根据 EffectiveColor 选择 ButtonToken、SharedToken 或 Palette 值

Variant resolver
  将颜色变量映射到文字、背景、边框和阴影变量

ControlTheme
  只把最终主题变量投影到 normal、hover、pressed 和 disabled 视觉

ButtonToken 不定义 BlueSolidHoverBg、PurpleFilledActiveBg 这类组合 Token。

4. Button 家族影响

ButtonToken 当前被 Button 家族主题共同引用。Token 变更必须评估：

• 默认 Button
• DropdownButton
• SplitButton
• HyperLinkButton
• IconButton 相关主题

如果某个值只服务特定家族控件，应确认它是否仍属于 Button 体系共享语义。只有共享语义值才应进入 ButtonToken。

Button 家族控件支持 Custom 尺寸时，应沿用同一原则：未设置本地尺寸属性时使用 Middle 默认值；设置本地属性时由本地值覆盖。DropdownButton 继承 Button 的 IconWidth、IconHeight 语义，但其 OpenIndicator 保持独立尺寸职责。不得为家族控件私自复制一组 Custom 专属 Token，除非该值已经证明是稳定的家族级语义。

5. 兼容性要求

ButtonToken 属于 Button 主题契约。即使 ButtonToken 是 internal 类型，生成的 ButtonTokenKind 和 AXAML resource 使用点已经形成稳定依赖。

ButtonToken 变更要求：

• 不擅自重命名既有 Token。
• 不擅自删除既有 Token。
• 不改变既有 Token 的语义含义。
• 不把实例状态迁移到 Token。
• 不在 ButtonToken 中硬编码 Button 私有 preset 色表。
• 需要破坏性变更时，必须先说明影响范围并获得授权。

6. 验证策略

改动类型	验证要求
新增 ButtonToken	检查生成的 ButtonTokenKind、AXAML 引用和默认值计算。
修改 ButtonToken 计算	覆盖 light / dark 主题，检查 Button 与 Button 家族视觉。
删除或重命名 ButtonToken	默认不允许；如获授权，需同步所有 AXAML 引用和生成文件。
多彩按钮 Token 调整	验证 default、primary、danger、preset color 与各 variant 的状态映射。
Icon Token 投影调整	覆盖 Large / Middle / Small / Custom、普通 icon-only、icon-only loading、本地 IconWidth / IconHeight 覆盖，以及桌面 / Browser / DropdownButton 模板。