UI 视觉设计 / 系统课时
迁移旧页面中的硬编码样式
迁移旧页面中的硬编码样式
旧订单查询页把按钮颜色、圆角和间距散落在局部样式中,直接全局替换容易改变布局或交互。本篇以一个可运行的 React 页面演示:先保存旧版基线,再接入语义 Token 与共享按钮,最后用截图和自动化操作检查迁移结果。
学习目标
- 识别适合抽成 Token 的重复样式,保留页面特有的布局值。
- 让业务页面通过共享组件和 CSS 变量使用设计系统。
- 验证移动端、桌面端的视觉效果,以及查询与键盘操作。
锁定迁移范围与旧版基线
选一条低风险业务路由,例如「订单查询」,先只改查询卡片里的输入框、按钮和间距,不顺手重构数据请求或筛选算法。在原项目的旧版本上固定浏览器缩放 100%、Light 主题、同一字体与测试数据,分别保存 375×800 和 1280×800 视口截图。
同时记录三个可复测的行为:页面初始显示两条订单;输入「已发货」并按 Enter 后只剩「已发货订单」;按 Tab 能从输入框移到查询按钮。把旧截图与对应 Git 修订一起保存,避免迁移之后才生成所谓的旧版基准。
把重复值映射为语义 Token
先按「用途+状态」归类,而不是见到相同数值就全文替换。下表是本次页面的映射清单;值以示例旧页面为准,真实项目应先与 Figma 的变量及 Mode 核对。
| 旧样式及用途 | 迁移目标 | 消费位置 |
|---|---|---|
#2563EB,主按钮背景 |
--color-action-primary |
共享按钮 |
#1D4ED8,悬停背景 |
--color-action-hover |
共享按钮悬停态 |
#FFFFFF,卡片底色 |
--color-surface |
卡片、输入框 |
8px,控件圆角 |
--radius-200 |
输入框、按钮、卡片 |
16px,内边距和元素间距 |
--space-400 |
卡片、筛选行 |
44px,控件最小高度 |
--control-min-height |
输入框、按钮 |
8px 的圆角与 8px 的特殊图标偏移不一定共享一个 Token;页面的 max-width: 960px 也可以继续作为局部布局规则。语义变量应由设计系统统一提供,页面只消费,不复制颜色常量。

在页面中替换共享控件
以下示例使用 Vite 的 React + TypeScript 模板。先检查 Node.js 满足当前 Vite 要求(20.19+ 或 22.12+ 的适用版本),执行:
# 创建独立示例,避免直接覆盖业务仓库。
npm create vite@latest token-migration-demo -- --template react-ts
cd token-migration-demo
npm install预期结果:生成项目与 package.json,安装完成后命令退出码为 0;下载数量和耗时随环境变化。
将 src/index.css 替换为以下内容。为了可独立复现,这里用 :root 模拟 Token 包导出的变量;真实项目应导入版本化 Token 样式产物,不能再在页面里维护第二份色值。
:root {
/* 共享组件只读取语义变量,避免散落相同的色值。 */
font-family: system-ui, sans-serif;
--color-text-default: #0f172a;
--color-page: #f8fafc;
--color-surface: #ffffff;
--color-border: #cbd5e1;
--color-action-primary: #2563eb;
--color-action-hover: #1d4ed8;
--color-on-action: #ffffff;
--color-focus: #2563eb;
--space-400: 16px;
--radius-200: 8px;
--control-min-height: 44px;
}
* { box-sizing: border-box; }
body { margin: 0; color: var(--color-text-default); background: var(--color-page); }
.page { max-width: 960px; margin: 0 auto; padding: var(--space-400); }
.card {
padding: var(--space-400);
border: 1px solid var(--color-border);
border-radius: var(--radius-200);
background: var(--color-surface);
}
.search-row { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-400); }
.ds-input {
flex: 1 1 220px;
min-height: var(--control-min-height);
padding: 0 var(--space-400);
border: 1px solid var(--color-border);
border-radius: var(--radius-200);
background: var(--color-surface);
color: inherit;
}
.ds-button {
min-height: var(--control-min-height);
padding: 0 var(--space-400);
border: 0;
border-radius: var(--radius-200);
background: var(--color-action-primary);
color: var(--color-on-action);
cursor: pointer;
}
.ds-button:hover:not(:disabled) { background: var(--color-action-hover); }
/* 键盘焦点需要独立于悬停态的可见反馈。 */
.ds-input:focus-visible, .ds-button:focus-visible {
outline: 2px solid var(--color-focus);
outline-offset: 2px;
}
.ds-button:disabled { opacity: 0.5; cursor: not-allowed; }
.results { padding: 0 var(--space-400); }再将 src/App.tsx 替换为下列完整组件。按钮样式归共享组件,表单筛选与页面数据仍由业务页面负责;原生 form 同时支持按钮点击和 Enter 提交。
import { useState, type FormEvent, type ReactNode } from 'react';
type ButtonProps = {
children: ReactNode;
type?: 'button' | 'submit';
disabled?: boolean;
};
// 共享组件提供外观与原生按钮语义,不保存业务筛选状态。
function PrimaryButton({ children, type = 'button', disabled = false }: ButtonProps) {
return <button className='ds-button' type={type} disabled={disabled}>{children}</button>;
}
const ORDERS = ['待发货订单', '已发货订单'];
export default function App() {
const [keyword, setKeyword] = useState('');
const [submitted, setSubmitted] = useState('');
const visible = ORDERS.filter(order => order.includes(submitted.trim()));
// 查询只在提交时更新,避免改样式顺带改变原有交互时机。
function handleSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
setSubmitted(keyword);
}
return (
<main className='page'>
<h1>订单查询</h1>
<div className='card'>
<form className='search-row' onSubmit={handleSubmit}>
<label htmlFor='order-keyword'>订单关键字</label>
<input id='order-keyword' className='ds-input'
value={keyword} onChange={event => setKeyword(event.target.value)} />
<PrimaryButton type='submit'>查询</PrimaryButton>
</form>
</div>
<ul className='results' aria-live='polite'>
{visible.length
? visible.map(order => <li key={order}>{order}</li>)
: <li>无匹配结果</li>}
</ul>
</main>
);
}预期页面:初始显示两条订单;输入「已发货」点击查询或按 Enter 后只显示「已发货订单」。缩窄视口时,筛选行会换行而不是出现横向滚动。
检查视觉与交互回归
先启动本地服务;固定端口可避免自动化脚本访问错实例。此终端保持运行,另开一个终端做测试。
npm run dev -- --host 127.0.0.1 --port 5173 --strictPort预期控制台会显示本地访问地址:
http://127.0.0.1:5173/在另一终端安装 Playwright Test 和 Chromium,并新建 tests/order-migration.spec.ts:
npm install -D @playwright/test
npx playwright install chromium预期结果:安装命令均以退出码 0 结束;首次安装浏览器可能需要下载,终端细节随环境变化。
import { test, expect } from '@playwright/test';
test('订单查询迁移后样式和交互保持正确', async ({ page }) => {
await page.setViewportSize({ width: 375, height: 800 });
await page.goto('http://127.0.0.1:5173/');
const input = page.getByRole('textbox', { name: '订单关键字' });
const button = page.getByRole('button', { name: '查询' });
// 检查计算后的样式,避免其他旧 CSS 覆盖 Token。
await expect(button).toHaveCSS('background-color', 'rgb(37, 99, 235)');
await expect(button).toHaveCSS('min-height', '44px');
await page.screenshot({ path: 'after-mobile.png', fullPage: true });
await page.setViewportSize({ width: 1280, height: 800 });
await page.screenshot({ path: 'after-desktop.png', fullPage: true });
// 回车筛选后,Tab 仍应进入原生查询按钮。
await page.setViewportSize({ width: 375, height: 800 });
await input.fill('已发货');
await input.press('Enter');
await expect(page.getByRole('listitem')).toHaveCount(1);
await expect(page.getByRole('listitem')).toHaveText('已发货订单');
await input.press('Tab');
await expect(button).toBeFocused();
});预期结果:两张迁移后截图写入示例项目根目录,按钮计算背景为 rgb(37, 99, 235)、最小高度为 44px,筛选和焦点断言通过。执行测试并确认构建:
npx playwright test tests/order-migration.spec.ts
npm run build预期控制台关键结果如下;耗时以 <TIME> 表示,实际数值不同:
1 passed (<TIME>)
✓ built in <TIME>把 after-mobile.png、after-desktop.png 与旧版本相同视口、数据、浏览器环境的截图并排比对,重点看换行、卡片内边距和按钮尺寸;聚焦描边另用 Tab 操作检查。这里的截图是供人工比对的产物,不会自行判断与旧版是否一致;需要自动像素回归时,应先在旧分支建立经过评审的截图基线,再使用 Playwright 的 toHaveScreenshot() 比较。
分批提交与修复偏差
只提交本页样式和共享控件接入,不混入接口变更。验收要求是 两档视口均无未解释的视觉差异、查询与键盘测试全部通过、构建成功;设计系统规范明确要求的外观变化,要单独记录并由设计与开发共同确认。
如果按钮仍显示旧颜色,先在浏览器开发者工具的 Computed 面板查看 background-color 和命中的 CSS 规则,排查高优先级选择器、行内 style 或仍被导入的旧样式。若新 Token 让其他页面发生变化,应撤回本页接入或恢复前一版本的 Token 包,而不是在业务页补一个更高优先级的硬编码颜色。