sgds-migration

SGDS 迁移技能

你将协助用户把现有前端应用从其他组件库（Material UI、Chakra UI、shadcn/ui、Bootstrap、Ant Design、Vuetify、Angular Material 等）迁移到 SGDS Web Components。

这是一个四阶段工作流：

1. 扫描现有前端技术栈（框架 + UI 库）
2. 设置 SGDS，使用 sgds-getting-started 技能
3. 迁移测试——升级到 Vitest + Playwright（路径 A），或修补现有的 Jest/RTL（路径 B）
4. 迁移样式 - 用 SGDS v3 工具类替换旧的 CSS 系统

每个阶段都基于前一阶段。用户应按顺序完成各个阶段。

---

阶段 1：扫描前端技术栈

目标：在进行更改之前，了解当前的技术栈。

需要识别的内容

询问用户当前的配置：

1. 前端框架：React？Vue？Angular？Vanilla JavaScript？Svelte？
2. 当前 UI 库：
   • SGDS v1（基于 Bulma 的 CSS 框架）？
   • SGDS v2（Bootstrap / React Bootstrap 组件）？
   • 其他：MUI、Chakra UI、shadcn/ui、Ant Design、Vuetify、Angular Material、Bootstrap、仅使用 Tailwind？
3. 测试运行器：Jest、Vitest、Karma、Playwright、Cypress？
4. 构建工具：Create React App、Next.js、Vite、Angular CLI、Webpack？
5. Node/包管理器：npm、pnpm、yarn？

分析工具

对于 React 项目，可以使用提供的分析脚本扫描代码库：

python scripts/analyze_react_stack.py <project_path>

此脚本会识别：

• React 组件文件及其导入
• 当前 UI 库依赖（MUI、Chakra 等）
• 组件用法和属性模式
• 测试文件和测试框架
• 输出 JSON 迁移计划

对于 Vue、Angular、Vanilla JS，建议手动讨论（工具仍在开发中）。

阶段 1 的输出

以结构化摘要的形式呈现分析结果：

Frontend Stack Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Framework:      React 18 (TypeScript)
UI Library:     Material UI (MUI)
Test Runner:    Jest + React Testing Library
Build Tool:     Vite
Package Mgr:    pnpm

Components to Migrate:
  - Button (25 instances)
  - Input (18 instances)
  - Modal (5 instances)
  - Card (12 instances)
  - […]

Components Already Compatible:
  - Custom Layout components
  - Business logic hooks

Estimated Scope: 2-3 weeks for full migration

如果没有找到测试怎么办？

如果代码库没有测试（或无法检测/分析测试）：

✅ 仍然继续迁移——测试基础设施仍然很有价值

处理方式调整为：

1. 设置测试环境（React 使用 vitest-browser-react）
2. 为一个简单组件（例如 Button）创建一个基本测试模板
3. 不要编写业务逻辑/产品逻辑测试（这由用户负责）
4. 继续在源代码中进行组件替换迁移
5. 用户之后可以根据自己的具体用例扩展测试模板

用户操作：组件迁移完成后，用户应编写针对其业务逻辑和产品需求的测试。

阶段 2：安装并配置 SGDS

目标：完成 SGDS 设置，确保组件以正确的字体和样式渲染。

完整遵循 sgds-getting-started 技能（步骤 1–3）：

步骤 1：设置字体

将 Inter 字体的 <link> 标签添加到 HTML <head>（或框架的对应位置）：

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,300;0,14..32,400;0,14..32,600;0,14..32,700;1,14..32,300;1,14..32,400;1,14..32,600;1,14..32,700&display=swap"
    rel="stylesheet"
  />
</head>

步骤 2：导入 CSS（在经过 Tailwind 处理的 CSS 文件中）

重要——导入顺序很关键。 将以下内容添加到项目的主 CSS 文件中（例如 globals.css）：

/* Tailwind WITHOUT preflight — preflight resets override SGDS component styles */
@import "tailwindcss/theme.css";
@import "tailwindcss/utilities.css";

/* SGDS CSS — this order is required */
@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/night.css"; /* optional: only if supporting dark mode */
@import "@govtechsg/sgds-web-component/css/sgds.css";
@import "@govtechsg/sgds-web-component/css/utility.css";

不要使用 @import "tailwindcss"——它会引入 Tailwind 的 preflight 重置（*, :after, :before { border: 0 solid; margin: 0; padding: 0; }），从而覆盖 SGDS Web Components 的内部样式。

步骤 3：注册 SGDS Web Components

在应用入口处导入一次：

import '@govtechsg/sgds-web-component';

完成后

阶段 2 完成后：

• SGDS Web Components 会使用正确的 Inter 字体和设计令牌进行渲染
• sgds: 工具类可用且正常工作
• 基础样式（排版、标题、正文）已应用
• 现有组件仍使用旧 UI 库（MUI、Chakra、Bootstrap、v1 Bulma 等）

---

组件迁移策略

无论你要从哪个 UI 库迁移，策略都相同（MUI、Chakra、v1 Bulma、v2 Bootstrap 等）。

先迁移组件，因为 Web 组件使用 Shadow DOM，不会与旧 CSS 冲突。组件迁移完成后，在阶段 4 迁移样式。

有关组件特定的详情和 API，请参阅 ../sgds-components/SKILL.md，其中记录了全部 46 个 <sgds-*> 组件。

组件优先规则

在使用纯 HTML 和实用类构建任何 UI 元素之前，务必先检查 SGDS Web 组件是否已满足需求。请先查阅 ../sgds-components/SKILL.md。仅当没有适用于该用例的 SGDS 组件时，才使用自定义标记。

需要避免的常见错误：

• 不要使用带实用类的原生 <table> — 请使用 <SgdsTable>、<SgdsTableRow>、<SgdsTableHead>、<SgdsTableCell>
• 不要使用带实用类的原生 <input> — 请使用 <SgdsInput>（内置标签、验证和提示文本）
• 不要使用带实用类的原生 <select> — 请使用 <SgdsSelect> + <SgdsSelectOption>

React：始终使用 PascalCase React 包装器

在 React 应用中，始终从 @govtechsg/sgds-web-component/react/* 导入并使用 PascalCase React 包装器。不要混用小写 Web 组件标签（<sgds-modal>）和 React 包装器组件（<SgdsButton>）。

// ✅ Correct — consistent PascalCase React wrappers
import SgdsModal from "@govtechsg/sgds-web-component/react/modal";
import SgdsButton from "@govtechsg/sgds-web-component/react/button";

<SgdsModal open={open} onSgdsClose={() => setOpen(false)}>
  <SgdsButton variant="primary">Submit</SgdsButton>
</SgdsModal>

// ❌ Wrong — mixing lowercase tags with React wrappers
<sgds-modal open={open} onsgds-close={() => setOpen(false)}>
  <SgdsButton variant="primary">Submit</SgdsButton>
</sgds-modal>

特定库的映射参考

根据阶段 1 检测到的源库，加载相应的映射文件：

源库	映射参考
@govtechsg/sgds-react (v2)	reference/from-sgds-react.md
@mui/material / @material-ui/*	reference/from-mui.md
@chakra-ui/react	reference/from-chakra.md
@radix-ui/* / shadcn components/ui/*	reference/from-shadcn.md

每个映射文件都提供：组件表、属性映射、迁移前后代码示例，以及已移除的概念。

还务必加载：

• reference/events.md — 通用 SGDS 事件映射（onSgdsChange、onSgdsInput 等）以及各组件的值访问模式
• reference/css-utilities-migration.md — 阶段 4 使用的 CSS 迁移表（Bootstrap/Tailwind/MUI sx/Chakra → sgds: 实用类）

表单模式规则

迁移表单时，请遵循 sgds-forms 技能中的模式：

• 操作按钮（提交、取消、返回）必须在表单底部靠右对齐：

  <div class="sgds:flex sgds:justify-end sgds:gap-component-xs">
    <sgds-button variant="outline">Cancel</sgds-button>
    <sgds-button variant="primary" type="submit">Submit</sgds-button>
  </div>
  

• 这适用于独立表单和模态框中的表单（使用 slot="footer" 和 sgds:justify-end）

---

阶段 3：设置测试环境并迁移测试

目标：确保迁移后，测试套件能够与 SGDS Web 组件协同工作。

SGDS Web 组件使用 Shadow DOM。请根据实际情况选择以下两种方案之一：

方案 A（推荐）：Vitest + Playwright 浏览器测试

适用场景：新项目、全新测试套件，或准备升级测试基础设施的团队。

请阅读：reference/react-test-migration.md，了解完整的 React 迁移工作流，包括 Vitest 设置、测试模式和示例。

原因：在真实的 Chromium 中运行测试——全面支持 Shadow DOM，行为与真实浏览器一致，Playwright 定位器 API 可自动穿透 Shadow DOM 边界。

方案 B：修补现有 Jest + RTL（JSDOM）

适用场景：规模较大的现有 Jest/RTL 测试套件，迁移测试基础设施的成本过高。

请阅读：reference/jest-rtl-patching.md，查看完整的修补指南。

作用：添加 polyfill 和修补程序，使 JSDOM 能够兼容 SGDS Web 组件（ElementInternals、HTMLSlotElement、动画、Shadow DOM 模拟、针对 sgds: 类的 querySelector 修复、快照稳定化）。

权衡：JSDOM 无法全面测试 Shadow DOM 内部结构。由于 SGDS 组件能够优雅降级，测试可以正常运行，但你将无法与 Shadow Root 内的元素交互。之后可以考虑升级到方案 A。

选择迁移路径

因素	路径 A（Vitest + Playwright）	路径 B（修补 Jest/RTL）
Shadow DOM 测试	完全支持	仅支持宿主级别
迁移工作量	中等（重写测试基础设施）	低（添加设置文件）
长期质量	更高	足够
现有测试套件	需要重写	通过修补予以保留

React（两条路径均完全支持）

预计耗时：1–2 周，具体取决于测试覆盖率

没有现有测试？ 仍然继续——即使代码库目前没有测试，路径 A 也会提供设置 Vitest 浏览器环境和创建测试模板的指导。

---

对于 Vue、Angular 和其他框架：使用相同的 Vitest + Playwright 方法（路径 A）。React 迁移指南展示了你可以采用的测试模式；设置方式因框架而异，但基础是一致的。

---

第 4 阶段：迁移基础样式和 CSS

目标：用 SGDS v3 工具类（基于 Tailwind，并带有 sgds: 前缀）替换旧的样式系统。视觉样式将与 SGDS v3 品牌和设计系统相匹配，但元素的位置和排列方式保持不变。

重要——保持 UX 一致性：元素必须保持在相同位置。产品用户已经熟悉各项内容的位置（导航、按钮、表单等）。保留元素位置可确保用户不会感到困惑，也不会找不到依赖的功能。你要更新的是外观（颜色、排版、间距令牌），而不是重新排列页面结构。

开始时间：第 3 阶段完成且组件已使用 SGDS Web 组件后。

前置条件（应已在第 2 阶段完成）：

• 已导入 sgds.css 基础 CSS（提供 Inter 字体系列和排版重置）
• 已在经过 Tailwind 处理的 CSS 文件中导入 utility.css
• 已禁用 Tailwind preflight（使用 tailwindcss/theme.css + tailwindcss/utilities.css）

需要替换的内容：

• 旧布局系统（MUI <Box>、Chakra <Grid>、v1 Bulma .columns、v2 Bootstrap <Row>/<Col>）
• 旧工具类（MUI sx 属性、Chakra 样式属性、Bulma .is-*、Bootstrap .m-* .p-*）
• 旧颜色／排版系统（替换为 SGDS CSS 令牌和工具类）

询问用户迁移范围：开始前，询问用户本次要迁移哪些页面／路由。他们可能想迁移整个应用，也可能只迁移特定页面。不要擅自假设——让用户定义迁移边界。

迁移方法：

阅读：reference/css-utilities-migration.md，其中提供了快速查阅表，将旧 CSS 模式（Bootstrap、Tailwind、MUI sx、Chakra 样式属性）映射到对应的 sgds: 类。

阅读：../sgds-utilities/SKILL.md，了解所有 SGDS 工具类、CSS 令牌和样式的完整参考。

核心原则：用 SGDS v3 工具类（基于 Tailwind，并带有 sgds: 前缀）替换旧布局／工具类系统，同时保留布局排列方式——将网格改为 sgds:grid，将 flex 改为 sgds:flex，将间距改为 sgds:gap-*、sgds:p-* 等。

结果：应用现在使用 SGDS v3 品牌颜色、排版和间距令牌，同时保持原有的信息架构和布局决策。

预计耗时：1–2 周，具体取决于 CSS 涉及范围的大小

---

第 5 阶段：迁移后验证

目标：确认迁移已完成，且所有配置均正确。

完成所有阶段后，请按此清单逐项检查：

字体检查

• 文本以 Inter 字体呈现（而非浏览器默认的衬线／无衬线字体）
• 在 DevTools 中验证：<body> 上的 font-family 包含 Inter
• <head> 中存在 Google Fonts <link> 标签

CSS 设置检查

• sgds: 工具类生效（检查元素，确认样式已应用，而非被忽略）
• Tailwind preflight 未启用（检查计算样式中是否没有 *, :after, :before { border: 0 solid; margin: 0; padding: 0; }）
• SGDS 组件具有正确的内部样式（边框、内边距、颜色均可见）

组件检查

• 所有 SGDS 组件都使用 PascalCase React 包装器（React 中没有混用小写的 <sgds-*> 标签）
• 在存在 SGDS 组件的情况下，不使用原生 HTML 元素（table、select、input）
• 表单操作按钮右对齐（sgds:justify-end）

Token 检查

• 主题 token 已启用：sgds:bg-primary-default、sgds:text-body-secondary 等可解析为实际颜色
• 日间／夜间主题切换正常工作（如适用）

测试检查

• 所有测试均通过（pnpm test）
• 事件处理器使用正确的 SGDS 模式（onSgdsChange、onSgdsInput，而非原生 onChange）

---

整体工作流

Phase 1: Scan
  ↓
  Understand framework, UI library, test runner
  Load library-specific mapping (from-mui.md, from-chakra.md, etc.)
  Output: Stack summary + scope estimate

Phase 2: Set Up SGDS
  ↓
  Follow sgds-getting-started skill (font + CSS + component registration)
  Disable Tailwind preflight
  Output: SGDS components available, Inter font active, utilities working

Phase 3: Migrate Tests & Components
  ↓
  Path A: Vitest + Playwright (reference/react-test-migration.md)
  Path B: Patch Jest/RTL (reference/jest-rtl-patching.md)
  Use: reference/events.md for event patterns
  Use PascalCase React wrappers consistently
  Use SGDS components (not raw HTML) where available
  Output: Tests passing, components using SGDS web components

Phase 4: Migrate Foundation & Styling CSS
  ↓
  Use: reference/css-utilities-migration.md for lookup tables
  Use: ../sgds-utilities/SKILL.md for complete reference
  Use: ../sgds-forms/SKILL.md for form layout patterns
  Output: All styling uses SGDS v3 utilities (Tailwind + sgds: prefix)

Phase 5: Verify
  ↓
  Run post-migration checklist
  Output: All checks pass — migration complete

---

提示与常见问题

“我可以迁移组件而不迁移测试吗？”

不推荐。 为旧 UI 库（MUI、Chakra）编写的测试，在将组件替换为 SGDS 后可能会失败（API 不同、使用 Shadow DOM）。请先迁移测试，再迁移组件，这样你就能确认每次更改前后都能正常工作。

不过，如果你没有测试，仍然可以继续：配置测试环境，提供一个简单的模板测试，然后替换组件。之后由你（用户）添加业务逻辑测试。

核心原则：此技能负责 UI 组件迁移和测试基础设施。你需要为产品逻辑和业务需求编写相应的测试。

“我可以逐步迁移吗？”

可以。 一次迁移一个组件（测试 + 源码）。迁移期间，旧组件可以与新的 SGDS 组件在应用中共存。

“如果我的测试运行器不支持真实浏览器怎么办？”

有两种选择：(1) 升级到 Vitest + Playwright，以获得完整的 Shadow DOM 支持（路径 A）；或 (2) 使用 polyfill 修补现有的 Jest/RTL 环境，让 SGDS 组件能在 JSDOM 中工作（路径 B——参见 reference/jest-rtl-patching.md）。路径 B 以牺牲 Shadow DOM 测试深度为代价，减少迁移工作量。

“这需要多长时间？”

取决于：

• 需要迁移的组件数量（button、input 等）
• 当前测试覆盖率（覆盖率越高，迁移工作越多）
• 团队对 SGDS 和新测试工具的熟悉程度
• 是否还需要迁移布局 CSS
• 估算：典型的中型 React 应用需要 1–4 周

“为什么先迁移组件，再迁移布局 CSS？”

先迁移组件，因为：

• Web 组件使用 Shadow DOM，不会与旧 CSS 冲突
• 可以随时安全迁移
• 边界清晰：替换组件后，可干净地移除旧 CSS

再迁移布局，因为：

• 避免旧布局系统与 v3 布局同时运行
• 组件迁移完成后，旧 CSS 基本已过时
• 最终状态更清晰，CSS 冲突更少

“如果我使用的是 SGDS v1（Bulma）或 v2（Bootstrap）呢？”

同样适用四阶段策略——扫描、设置、迁移测试、迁移样式。组件替换方式与其他库相同。

“我需要重写所有组件吗？”

只需要重写要迁移到 SGDS 的组件。如果你有 SGDS 没有对应实现的自定义组件（布局、逻辑等），可以保持不变。

---

面向 AI Agent

使用此技能时：

1. 从阶段 1 开始：提出建议前，务必先询问用户当前使用的技术栈。
2. 遵循所引用的技能：委派时使用准确的技能名称：
   • ../sgds-getting-started/SKILL.md 用于设置（阶段 2）
   • ../sgds-components/SKILL.md 用于特定组件的 API
   • ../sgds-forms/SKILL.md 用于表单布局模式（操作按钮右对齐）
   • reference/react-test-migration.md 用于 React 测试迁移（阶段 3，路径 A）
   • reference/jest-rtl-patching.md 用于 Jest/RTL 补丁（阶段 3，路径 B）
   • reference/from-mui.md、reference/from-chakra.md、reference/from-shadcn.md、reference/from-sgds-react.md 用于特定库的映射
   • reference/events.md 用于事件处理模式
   • reference/css-utilities-migration.md 用于 CSS 迁移查找表（阶段 4）
   • ../sgds-utilities/SKILL.md 用于完整的 CSS 工具类和样式说明（阶段 4）
3. 不要重复内容：不要在此处重写入门、组件或工具类说明，而应链接到相应内容。
4. 如实说明支持范围：清楚说明支持哪些框架（支持 React；其他框架请使用 Vitest + Playwright 基础方案），并明确预期。
5. 谨慎选择测试路径：如果用户已有包含大量测试的 Jest + RTL 项目，除非用户明确希望升级，否则建议选择路径 B（打补丁）。如果是从头开始，则建议选择路径 A（Vitest + Playwright）。
6. 开始迁移工作前先询问澄清问题：
   • 有多少个组件需要迁移？（用于安排工作优先级）
   • 是否有需要保留的自定义组件？（便于快速决策）
   • 测试覆盖率和测试运行器是什么？（会影响测试迁移路径的选择）
   • 是否愿意更改测试基础设施？（路径 A 或路径 B）
7. React：仅使用 PascalCase — 始终使用来自 @govtechsg/sgds-web-component/react/* 的 React 包装器（如 SgdsModal、SgdsButton 等）。绝不要在 React 组件中使用小写的 <sgds-*> 标签。
8. 组件优先原则 — 使用原始 HTML + 工具类之前，先检查 SGDS 组件是否能满足需求。始终优先使用 <SgdsTable> 而不是 <table>、<SgdsInput> 而不是 <input> 等。
9. 禁用 Tailwind preflight — 使用 @import "tailwindcss/theme.css" + @import "tailwindcss/utilities.css"，而不是 @import "tailwindcss"。preflight 重置会覆盖 SGDS 组件样式。
10. 运行阶段 5 验证 — 所有迁移工作完成后，与用户一起逐项检查迁移后清单，确认所有配置正确。