在任何现代 UI 设计系统与前端组件库中，按钮（Button） 都是使用频次最高、交互场景最繁杂、也最容易因封装不当导致系统性崩塌的“第一基石原子组件”。

然而，在许多团队的 Figma 资源库中，按钮组件的设计与维护往往深陷以下顽疾：

1. 变体排列爆炸（Variant Explosion）：为了穷尽 Primary、Secondary、危险态、4 种尺寸、带左图标、带右图标、纯图标、纯文字等组合，机械地创建出上百个变体切片，导致组件加载缓慢、文件内存飙升，设计师在侧边栏挑选属性时如履薄冰；
2. 文字撑破与图标形变：未建立严谨的 Auto Layout 自动布局 尺寸约束模型，一旦按钮文案变长（如中英文国际化适配）或更替不同比例的矢量图标，按钮高度忽高忽低、文字被异常截断或图标被拉伸变形；
3. 状态机缺失与无障碍断层：设计稿中仅定义了静态的默认态（Default）与悬停态（Hover），遗漏了极具工程挑战性的加载中状态（Loading Spinner）、键盘聚焦外发光（Focus Visible）以及防重复点击的禁用锁定态（Disabled）；
4. 前端交付语义割裂：研发工程师在 Dev Mode 开发模式 中只能看到一层层硬编码的绝对数值（如 padding: 9px 15px），无法直接对齐 Ant Design、Radix UI 或 Tailwind CSS 的语义化属性（Props）。

本文将从工业级分层模型切入，系统演示如何利用 Figma 现代组件属性（Component Properties）解耦变体，打通从交互状态机到前端代码的高效交付链路。

---

工业级按钮分层模型与视觉层级矩阵

按钮绝非单纯的带圆角彩色矩形，它在页面中承担着明确的操作优先级引导作用。设计系统应当严格划分 5 大核心层级：

按钮类型 (Button Hierarchy)	视觉权重	边框与背景规范	典型业务场景	页面共存原则
Primary (主要按钮)	最高视觉优先级	实心品牌高饱和填充，无边框，高反差反白文字	表单提交、确定购买、新建项目、核心主转化流程	每个主要视口或模态弹窗原则上只允许出现 1 个
Secondary (次要按钮)	中等视觉优先级	浅底色弱对比填充（Subtle Tint）或纯白底色	筛选过滤、次要操作项、批量导出、上一步	与 Primary 搭配出现，数量通常不超过 2 个
Outline (线框按钮)	次低视觉优先级	1px 语义中性边框，背景完全透明	取消操作、次要辅助跳转、重置设置	适合在信息密集型卡片或表格工具栏中低调呈现
Ghost / Text (幽灵/文本按钮)	极简低干扰	无边框、无背景填充，仅保留文字与图标，悬停显底色	表格操作列（编辑/删除）、面包屑返回、辅助链接	用于极高密度列表，避免界面充满方框产生视觉压迫
Danger (破坏/危险按钮)	强阻断警示	警示红色实色或浅红色描边填充	删除资源、注销账户、清空数据、强制终止	必须搭配二次确认弹窗或严格的二次确认交互

---

Auto Layout 尺寸自适应与文本抗拉伸架构

为了确保按钮在响应式布局中既能自适应文案长度，又能保持规范统一的高度节奏，必须建立四级规范档位：

┌────────────────────────────────────────────────────────┐
│  Large (44px/48px)   - 触控友好，移动端主按钮/营销大屏   │
│  Medium (36px/40px)  - 工业标准默认值，通用表单与工具栏  │
│  Small (28px/32px)   - 紧凑型，B 端复杂表格行内操作      │
│  Mini (22px/24px)    - 超紧凑型，标签内辅助按钮/微交互   │
└────────────────────────────────────────────────────────┘

1. 核心 Auto Layout 尺寸约束配置

以标准 Medium 尺寸按钮为例：

1. 排列方向：设为横向 Auto Layout（Horizontal Layout），垂直居中对齐（Align Center）；
2. 尺寸约束法则：
   • 宽度（Width）：设为 Hug contents（适应内容）；若在移动端全宽容器中，设为 Fill container（撑满容器）；
   • 高度（Height）：强制锁定为固定值（Fixed 36px），或设置垂直内边距并搭配最小高度（Min-Height 36px），防止换行或空文字时高度坍塌；
3. 水平内边距（Horizontal Padding）：设置为 16px，确保文字左右留白匀称；
4. 子项间距（Item Spacing / Gap）：图标与文字之间的间距固定设为 8px。

2. 文本图层抗挤压与截断设置

• 按钮内部文字图层的水平伸缩属性务必设为 Hug contents，禁止设为 Fixed 宽度，避免文案被无故换行；
• 字体排印行高（Line Height）必须与字体大小（Font Size）成比例，推荐 14px 文本使用 20px 或 22px 行高，确保文本在基准线垂直居中。

---

状态机闭环：六大交互状态与 Loading 动画架构

完整的按钮组件必须涵盖交互生命周期中的所有边界状态：

[ Default ] ──(Hover)──► [ Hover ] ──(Click)──► [ Active/Pressed ]
     │                                                │
 (Tab Key)                                        (Async API)
     ▼                                                ▼
[ Focus Ring ]                                  [ Loading State ]
(外发光高对比双环)                              (旋转 Spinner + 锁死点击)

1. 六大交互状态定义与视觉规范

交互状态 (State)	视觉触发机制	关键视觉表现	交互限制与无障碍
Default (默认态)	初始静止状态	标准品牌色填充，正常阴影（Elevation 1）	可正常响应交互
Hover (悬停态)	鼠标光标移入	填充色亮度加深 10% 或变亮，阴影层级提升（Elevation 2）	鼠标指针变为 pointer
Active / Pressed (按压态)	鼠标左键按下未抬起	填充色进一步加深 15%，整体微缩放或内阴影	产生即时力反馈
Focus-Visible (键盘聚焦态)	键盘 Tab 键导航聚焦	外层出现 2px 品牌主色高对比轮廓环，与按钮间隔 2px 空白	WCAG 2.2 强制合规标准，不可仅依靠弱颜色变化
Disabled (禁用态)	条件不满足不可点击	整体不透明度降为 40% 或灰阶填充，文字中性灰	光标变为 not-allowed，阻止一切点击事件
Loading (加载态)	提交后等待异步响应	原有前置图标平滑替换为旋转菊花（Spinner），文本保持可见	内部状态等同于 Disabled，阻断重复连击

2. Loading 旋转动效与布局防跳动方案

许多团队在制作 Loading 状态时，直接将文字替换为 Spinner，导致按钮宽度瞬间缩短，触发周围布局严重跳动（Layout Shift）。 工业级防跳动做法：

1. 保持按钮原有宽度与文字不变；
2. 将前置图标图层（Leading Icon）通过组件实例替换机制换成 Spinner 矢量组件；
3. 将文字色值临时调为半透明或保持原有文案（如“提交中...”）；
4. 保证整体 Auto Layout 宽度依然稳固，无缝过渡。

---

打破变体爆炸：Component Properties 与 Slot 插槽机制

过去采用全变体罗列法，5 种层级 × 4 种尺寸 × 6 种状态 × 4 种图标组合，瞬间诞生 480 个变体。使用 Figma 现代属性系统，只需保留真正的视觉形态层级：

┌────────────────────────────────────────────────────────┐
│  Button Component Sets                                 │
│  Variants (仅保留形态维度):                             │
│  - Hierarchy: Primary | Secondary | Outline | Danger   │
│  - Size: Large | Medium | Small                        │
│  - State: Default | Hover | Active | Disabled | Loading│
├────────────────────────────────────────────────────────┤
│  Component Properties (降维属性解耦):                  │
│  - showLeadingIcon: Boolean (默认 true)                │
│  - showTrailingIcon: Boolean (默认 false)              │
│  - leadingIconSlot: Instance Swap (绑定通用图标库)     │
│  - buttonText: Text Property (绑定 "按钮文案")         │
└────────────────────────────────────────────────────────┘

通过这一层解耦，底层物理变体数量直接从 480 个暴跌至 60 个，文件体积缩减 87.5%，且设计师在侧边栏能够极其自然地打勾开启/关闭图标、输入文案，彻底告别卡顿。

---

Dev Mode 前端工程化映射与生产代码交付

在 Dev Mode 开发模式 中，规范的按钮组件可无缝映射到现代前端组件体系。

1. React + TypeScript 标准组件接口定义

通过 Code Connect，Figma 的组件属性与 React Props 形成 1:1 双向映射：

import React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { Loader2 } from 'lucide-react';

const buttonVariants = cva(
  "inline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 select-none",
  {
    variants: {
      hierarchy: {
        primary: "bg-indigo-600 text-white hover:bg-indigo-700 active:bg-indigo-800 focus-visible:ring-indigo-500",
        secondary: "bg-slate-100 text-slate-900 hover:bg-slate-200 active:bg-slate-300 focus-visible:ring-slate-400",
        outline: "border border-slate-300 bg-transparent text-slate-700 hover:bg-slate-50 focus-visible:ring-slate-400",
        danger: "bg-red-600 text-white hover:bg-red-700 active:bg-red-800 focus-visible:ring-red-500",
      },
      size: {
        large: "h-12 px-6 text-base rounded-lg gap-2.5",
        medium: "h-9 px-4 text-sm rounded-md gap-2",
        small: "h-7 px-3 text-xs rounded gap-1.5",
      },
    },
    defaultVariants: {
      hierarchy: "primary",
      size: "medium",
    },
  }
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  isLoading?: boolean;
  leadingIcon?: React.ReactNode;
  trailingIcon?: React.ReactNode;
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, hierarchy, size, isLoading, leadingIcon, trailingIcon, children, disabled, ...props }, ref) => {
    return (
      <button
        ref={ref}
        disabled={disabled || isLoading}
        aria-busy={isLoading}
        className={buttonVariants({ hierarchy, size, className })}
        {...props}
      >
        {isLoading ? <Loader2 className="animate-spin w-4 h-4" /> : leadingIcon}
        <span>{children}</span>
        {!isLoading && trailingIcon}
      </button>
    );
  }
);

2. 无障碍（a11y）交付核查点

• Focus Ring 必须保留：严禁在前端全局抹去 outline: none 而不补充替代外发光环；
• Loading 状态的可访问性标注：加载中按钮必须配置 aria-busy="true" 并挂载 aria-disabled="true"，防止屏幕阅读器重复朗读或辅助设备误触发。

---

工业级按钮架构避坑与排障矩阵

故障现象	根源剖析	生产级标准修复方案
文字换行导致按钮被拉扯成极高方块	文本图层被意外设为 Fixed 宽度，或外层使用了绝对约束	文本图层宽度必须强制为 Hug contents，按钮整体高度设为固定数值基准（Fixed 36px）
替换图标后，图标发生非等比压缩扭曲	矢量图标本身缺少外层 1:1 正方形 Frame 保护	所有图标母版必须封装在 16×16、20×20 或 24×24 的正方形 Frame 中，内部矢量路径设为 Center 居中或 Scale
Loading 状态下触发按钮重复提交	仅更改了视觉样式，未在组件逻辑中禁用指针事件	在组件状态中绑定 Disabled 属性，并在前端代码中添加 pointer-events-none 阻断一切微事件
切换暗色模式时，Outline 边框彻底隐形	边框直接绑定了硬编码灰色，未绑定跨模式语义 Token	将边框色绑定为 Variables 变量 中的 border/neutral/subtle 语义令牌

更深入的组件变体与属性封装技巧，可参考 变体与组件属性高级指南 与 设计令牌速查表。