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 也可以继续作为局部布局规则。语义变量应由设计系统统一提供,页面只消费,不复制颜色常量。

旧页面硬编码样式迁移到 Token 与共享 React 组件的依赖关系

在页面中替换共享控件

以下示例使用 Vite 的 React + TypeScript 模板。先检查 Node.js 满足当前 Vite 要求(20.19+ 或 22.12+ 的适用版本),执行:

bash
# 创建独立示例,避免直接覆盖业务仓库。
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 样式产物,不能再在页面里维护第二份色值。

css
: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 提交。

tsx
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 后只显示「已发货订单」。缩窄视口时,筛选行会换行而不是出现横向滚动。

检查视觉与交互回归

先启动本地服务;固定端口可避免自动化脚本访问错实例。此终端保持运行,另开一个终端做测试。

bash
npm run dev -- --host 127.0.0.1 --port 5173 --strictPort

预期控制台会显示本地访问地址:

text
http://127.0.0.1:5173/

在另一终端安装 Playwright Test 和 Chromium,并新建 tests/order-migration.spec.ts:

bash
npm install -D @playwright/test
npx playwright install chromium

预期结果:安装命令均以退出码 0 结束;首次安装浏览器可能需要下载,终端细节随环境变化。

ts
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,筛选和焦点断言通过。执行测试并确认构建:

bash
npx playwright test tests/order-migration.spec.ts
npm run build

预期控制台关键结果如下;耗时以 <TIME> 表示,实际数值不同:

text
1 passed (<TIME>)
✓ built in <TIME>

把 after-mobile.png、after-desktop.png 与旧版本相同视口、数据、浏览器环境的截图并排比对,重点看换行、卡片内边距和按钮尺寸;聚焦描边另用 Tab 操作检查。这里的截图是供人工比对的产物,不会自行判断与旧版是否一致;需要自动像素回归时,应先在旧分支建立经过评审的截图基线,再使用 Playwright 的 toHaveScreenshot() 比较。

分批提交与修复偏差

只提交本页样式和共享控件接入,不混入接口变更。验收要求是 两档视口均无未解释的视觉差异、查询与键盘测试全部通过、构建成功;设计系统规范明确要求的外观变化,要单独记录并由设计与开发共同确认。

如果按钮仍显示旧颜色,先在浏览器开发者工具的 Computed 面板查看 background-color 和命中的 CSS 规则,排查高优先级选择器、行内 style 或仍被导入的旧样式。若新 Token 让其他页面发生变化,应撤回本页接入或恢复前一版本的 Token 包,而不是在业务页补一个更高优先级的硬编码颜色。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

迁移旧页面中的硬编码样式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通