UI 视觉设计 / 系统课时
用 Token 编写 Button 组件
用 Token 编写 Button 组件
把 Figma 设计稿中的颜色、尺寸与交互状态 Token 接入一个可复用的 React Button。完成后,页面可以验证默认、悬停、按下、键盘焦点、禁用及加载反馈;颜色和尺寸集中在 Token 层,后续换主题不需要修改组件逻辑。
学习目标
- 建立基础色、语义色、组件 Token 到 Button 样式的映射。
- 用 React 和 TypeScript 实现尺寸、禁用、加载及点击行为。
- 通过鼠标、键盘和模拟异步请求验收状态与可访问性。
明确 Token 与状态的对应关系
以主按钮为例,采用两档尺寸:sm 高 36px,md 高 44px,圆角均为 8px。把 Figma 中的基础色 blue/600、blue/700、blue/800 分别映射为语义色,再转成 Button 专用 CSS 自定义属性,而不是把色值写进 JSX。
| 状态或属性 | 触发条件 | 使用的组件 Token |
|---|---|---|
| 默认 | 可操作,未交互 | --button-bg-default:#2563EB |
| 悬停 | :hover 且可操作 |
--button-bg-hover:#1D4ED8 |
| 按下 | :active 且可操作 |
--button-bg-pressed:#1E40AF |
| 键盘焦点 | :focus-visible |
--button-focus-ring:#1E40AF |
| 禁用与加载 | disabled 或 aria-disabled |
--button-bg-disabled:#E2E8F0 |
焦点描边可以与悬停颜色同时存在;加载态则阻止再次点击。映射关系和状态覆盖顺序如下,图片中的 Token 路径与后面的 CSS 一一对应。

建立最小 React 工程
准备 Node.js 22.12+、npm 和浏览器。以下使用 Vite 的 react-ts 模板;已有 React TypeScript 工程可直接新建下节文件。Vite 的 Node.js 版本要求以官方指南为准。
npm create vite@latest token-button-demo -- --template react-ts
cd token-button-demo
npm install预期结果:三个命令正常完成,项目中存在 src/main.tsx、src/App.tsx 和 src/index.css。安装日志和耗时取决于环境,退出状态码应为 0。
编写 Button 与 Token 样式
新建 src/Button.tsx。真正不可使用时采用原生 disabled;加载中改用 aria-disabled 加事件拦截,避免正在操作的按钮从键盘焦点顺序中消失。type 默认设为 button,防止放进表单时意外提交。
import type { ComponentPropsWithoutRef, ReactNode } from "react";
type ButtonProps = Omit<ComponentPropsWithoutRef<"button">, "children"> & {
children: ReactNode;
size?: "sm" | "md";
loading?: boolean;
};
export function Button({
children,
size = "md",
loading = false,
disabled = false,
type = "button",
className,
onClick,
...rest
}: ButtonProps) {
// 明确禁用优先:同时传入 disabled 和 loading 时以禁用为准
const busy = loading && !disabled;
return (
<button
{...rest}
type={type}
className={["ds-button", className].filter(Boolean).join(" ")}
data-size={size}
disabled={disabled}
aria-disabled={busy || undefined}
aria-busy={busy || undefined}
onClick={(event) => {
// aria-disabled 只声明语义,不会自动阻止点击或表单提交
if (busy) {
event.preventDefault();
return;
}
onClick?.(event);
}}
>
{busy && <span className="ds-button__spinner" aria-hidden="true" />}
<span>{busy ? "处理中…" : children}</span>
</button>
);
}用下列内容替换模板自带的 src/index.css。最上方三组变量分别是基础色、语义色和组件 Token;在正式项目中,这部分应由设计令牌构建流程生成,Button 选择器只读取 Token。
:root {
--ref-blue-600: #2563eb;
--ref-blue-700: #1d4ed8;
--ref-blue-800: #1e40af;
--sys-action-default: var(--ref-blue-600);
--sys-action-hover: var(--ref-blue-700);
--sys-action-pressed: var(--ref-blue-800);
--button-bg-default: var(--sys-action-default);
--button-bg-hover: var(--sys-action-hover);
--button-bg-pressed: var(--sys-action-pressed);
--button-bg-disabled: #e2e8f0;
--button-fg-default: #ffffff;
--button-fg-disabled: #475569;
--button-focus-ring: var(--ref-blue-800);
--button-height-sm: 36px;
--button-height-md: 44px;
--button-radius: 8px;
}
body {
margin: 0;
color: #0f172a;
background: #ffffff;
font-family: system-ui, sans-serif;
}
.ds-button {
box-sizing: border-box;
display: inline-flex;
align-items: center;
justify-content: center;
gap: 8px;
min-height: var(--button-height-md);
padding: 0 16px;
border: 1px solid transparent;
border-radius: var(--button-radius);
background: var(--button-bg-default);
color: var(--button-fg-default);
font: 600 14px/20px system-ui, sans-serif;
cursor: pointer;
transition: background-color 120ms ease;
}
/* 尺寸只由组件 Token 控制,不随内容变化 */
.ds-button[data-size="sm"] {
min-height: var(--button-height-sm);
padding-inline: 12px;
}
.ds-button:hover:not(:disabled):not([aria-disabled="true"]) {
background: var(--button-bg-hover);
}
.ds-button:active:not(:disabled):not([aria-disabled="true"]) {
background: var(--button-bg-pressed);
}
.ds-button:focus-visible {
outline: 3px solid var(--button-focus-ring);
outline-offset: 2px;
}
.ds-button:disabled,
.ds-button[aria-disabled="true"] {
background: var(--button-bg-disabled);
color: var(--button-fg-disabled);
cursor: not-allowed;
}
.ds-button[aria-disabled="true"] {
cursor: progress;
}
.ds-button__spinner {
width: 14px;
height: 14px;
border: 2px solid currentColor;
border-right-color: transparent;
border-radius: 50%;
animation: ds-spin 700ms linear infinite;
}
@keyframes ds-spin {
to { transform: rotate(360deg); }
}
/* 尊重系统减少动态效果的偏好 */
@media (prefers-reduced-motion: reduce) {
.ds-button { transition: none; }
.ds-button__spinner { animation: none; }
}
.demo-row {
display: flex;
align-items: center;
flex-wrap: wrap;
gap: 12px;
}disabled 由浏览器原生阻止交互并退出 Tab 顺序;aria-disabled 不会自动阻止事件,所以加载时既要添加语义属性,也要在点击回调中拦截。只用降低透明度来模拟禁用,不具备这些行为。
运行示例并逐项验收
替换 src/App.tsx。第一个按钮模拟耗时 800ms 的保存操作,第二个验证尺寸与点击,第三个验证原生禁用;role="status" 把异步反馈提供给辅助技术。
import { useState } from "react";
import { Button } from "./Button";
export default function App() {
const [loading, setLoading] = useState(false);
const [message, setMessage] = useState("尚未提交");
async function handleSave() {
setLoading(true);
setMessage("正在处理…");
try {
// 仅用于演示;生产环境替换为真实的异步请求
await new Promise<void>((resolve) => window.setTimeout(resolve, 800));
setMessage("提交成功(演示)");
} finally {
setLoading(false);
}
}
return (
<main style={{ padding: 24 }}>
<h1>Button 状态验收</h1>
<div className="demo-row">
<Button loading={loading} onClick={handleSave}>提交</Button>
<Button size="sm" onClick={() => setMessage("小号已点击")}>
小号按钮
</Button>
<Button disabled onClick={() => setMessage("错误:禁用仍可点击")}>
不可操作
</Button>
</div>
<p role="status">{message}</p>
</main>
);
}执行开发服务器命令:
npm run dev预期输出会包含本地访问地址(以下只摘录关键字段):
Local: http://localhost:<PORT>/<PORT> 是实际端口占位符,可能因本机占用情况变化。打开终端显示的真实地址,按下表验证:
| 操作 | 预期结果 |
|---|---|
| 鼠标悬停、按住主按钮 | 背景依次使用 #1D4ED8、#1E40AF |
| 按 Tab 定位主按钮,再按 Enter 或 Space | 出现 3px 焦点描边,并可触发提交 |
| 点击“提交”后立即重复点击 | 约 800ms 内显示“处理中…”和旋转指示,不会重复触发提交 |
| 点击或尝试 Tab 定位“不可操作” | 不触发回调,也不进入正常 Tab 焦点顺序 |
| 检查“小号按钮”与主按钮 | 最小高度分别为 36px 和 44px |
| 打开系统“减少动态效果”偏好 | 转场与旋转动画停用,状态文字仍可读 |
需要核对内部属性时,使用浏览器开发者工具检查加载按钮是否同时出现 aria-disabled="true" 与 aria-busy="true"。完成后执行 npm run build,构建应成功生成 dist 产物;若仍沿用 Vite 模板的 src/main.tsx,它已负责加载 src/index.css,不需要重复导入。
避免三个常见实现错误
- 把加载态等同于原生禁用。 请求期间直接设置
disabled容易使当前焦点丢失。本实现保留加载态焦点,但必须配合事件拦截;若业务规定加载时也不可聚焦,可以改成原生禁用并重新测试焦点体验。 - 只给
aria-disabled不拦截事件。 辅助技术会读出“不可用”,但鼠标或键盘仍可能触发处理函数。组件中的preventDefault()与提前返回缺一不可,尤其是在type="submit"的表单里。 - 把状态色写死在组件。 不要在
onMouseEnter中直接修改style.backgroundColor;主题变更应替换--sys-action-*的值,悬停、按下和禁用的优先级交给 CSS 选择器管理。
验收时保留一份默认、焦点、禁用与加载态的对照记录,并检查 role="status" 在加载结束后能播报完成消息。这样组件既能对齐设计 Token,也能在鼠标、键盘和异步交互中保持一致行为。