# 按钮与行动层级 / Buttons & action hierarchy

ID: buttons
Version: 1.2.1

按钮执行动作，链接进入目标。视觉层级应帮助读者找到当前最重要的下一步。

Buttons perform actions and links navigate. Visual hierarchy should reveal the most useful next step.

## Anatomy
- 文字标签：动词加对象，例如“浏览工具”“复制规则”。
  Label: a verb plus an object, such as Explore tools or Copy rules.
- 可选图标：补充方向或状态，不能替代必要文字。
  Optional icon: clarifies direction or state without replacing necessary words.
- 交互区域：包含内边距、焦点轮廓和禁用语义。
  Hit area: includes padding, a focus outline, and disabled semantics.

## Parameters
- size.regular: 44px / 14px
  常规局部动作的最小高度与文字字号。
  Minimum height and label size for regular local actions.
- size.large: 48px / 16px
  手机主动作；桌面首页主推可用现有 56px 规格。
  Primary mobile actions; the desktop editorial lead may use the existing 56px variant.
- radius.control: 7px
  统一控件圆角；不要把所有按钮改成胶囊。
  Consistent control corners; avoid turning every control into a pill.
- emphasis: primary / secondary / text
  主动作、补充动作、轻量导航，按任务重要性选择。
  Primary action, supporting action, and quiet navigation, chosen by task importance.

## Rules
- 一个局部任务突出一个主动作，避免多个实心紫色按钮争抢注意。
  Give one local task one primary action rather than competing solid-violet controls.
- 执行动作用 button；跳转用 a。不可用的动作必须真的不能触发。
  Use button for actions and a for navigation. Disabled actions must be inoperable.
- 加载时保留按钮宽度，设置 aria-busy 并阻止重复提交。
  Keep button width during loading, set aria-busy, and prevent repeat submission.
- 收藏是可逆切换，不能用提交成功的临时状态代替选中状态。
  Saving is a reversible toggle, not a transient submission-success state.

## States
- 默认 / 悬停 / Default / hover: 标签清楚可读；悬停轻微改变表面，不移动布局。
  Keep labels readable; hover subtly changes the surface without moving layout.
- 键盘焦点 / Keyboard focus: 2px 可见描边与内容分离，Tab 可到达。
  Use a separate visible 2px outline and preserve Tab navigation.
- 加载 / Loading: 保留动作位置，禁止重复点击，完成后恢复可用并提示结果。
  Preserve position, prevent repeats, then restore the control and announce the result.
- 禁用 / Disabled: 原生 disabled，不响应鼠标和键盘；必要时说明前置条件。
  Native disabled semantics; no mouse or keyboard activation. Explain prerequisites when needed.

## Do / Avoid
- Do: “复制规则”执行本地复制，并给出完成或失败反馈。 / Copy rules performs a real clipboard action and reports success or failure.
- Avoid: 按钮写“了解更多”却没有目标，或用低透明度假装禁用。 / A Learn more button has no target, or opacity alone pretends to disable a control.

## Code mapping
- src/components/ActionButton.astro: 规范按钮与加载语义 / Guideline action button and loading semantics
- src/components/FavButton.astro: 站内收藏切换 / Site favorite toggle

## Dependencies
foundations, assets-motion

## Acceptance
- 主次层级、加载和禁用状态都能区分。
  Primary, secondary, loading, and disabled states remain distinct.
- 加载期间重复激活不会再次执行。
  Repeated activation during loading cannot repeat the action.
- 焦点、键盘和两种语言都可用。
  Focus, keyboard use, and both languages work.

## Implementation example
```
import ActionButton from "../components/ActionButton.astro";

<ActionButton variant="primary" size="regular">
  <Loc zh="复制规则" en="Copy rules" />
</ActionButton>
```

## Reference
Method reference: https://tmall-design.com/#style/component/button
Rules, parameters, examples, and branding in this file are specific to AI UP LAB.