sgds-migration

SGDS 移行スキル

既存のフロントエンドアプリケーションを、別のコンポーネントライブラリ（Material UI、Chakra UI、shadcn/ui、Bootstrap、Ant Design、Vuetify、Angular Material など）から SGDS Web Components に移行するユーザーを支援します。

これは4 フェーズのワークフローです。

1. スキャン：既存のフロントエンド技術スタック（フレームワーク＋UI ライブラリ）を確認します
2. セットアップ：sgds-getting-started スキルを使用して SGDS をセットアップします
3. テストを移行：Vitest＋Playwright にアップグレードする（パス A）か、既存の Jest/RTL を修正します（パス B）
4. スタイルを移行：古い CSS システムを SGDS v3 ユーティリティに置き換えます

各フェーズは前のフェーズを踏まえて進みます。ユーザーは各フェーズを順番に完了してください。

---

フェーズ 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 については、46 個すべての <sgds-*> コンポーネントについて説明している ../sgds-components/SKILL.md を参照してください。

コンポーネント優先のルール

プレーンな 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

各マッピングファイルには、コンポーネント一覧表、props のマッピング、移行前後のコード例、削除された概念が記載されています。

以下も必ず読み込んでください：

• 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 を使用します。状況に応じて、次の 2 つの方法から選択してください。

方法 A（推奨）：Vitest + Playwright ブラウザテスト

適しているケース：新規プロジェクト、新規にテストスイートを構築する場合、またはテストインフラのアップグレードを予定しているチーム。

参照先：Vitest の設定、テストパターン、使用例を含む React の移行ワークフロー全体については、reference/react-test-migration.md を参照してください。

理由：実際の Chromium でテストを実行します。Shadow DOM を完全にサポートし、実際のブラウザーの動作を再現します。また、Playwright のロケーター API が Shadow DOM の境界を自動的に越えます。

方法 B：既存の Jest + RTL（JSDOM）にパッチを適用する

適しているケース：テストインフラの移行にコストがかかりすぎる、大規模な既存の Jest／RTL テストスイート。

参照先：パッチ適用の手順全体については、reference/jest-rtl-patching.md を参照してください。

内容：SGDS Web コンポーネントに JSDOM が対応できるように、ポリフィルとパッチを追加します（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 のユーティリティ（sgds: プレフィックスを使用した Tailwind ベース）に置き換えます。これにより、見た目は SGDS v3 のブランドとデザインシステムに合致しますが、要素の位置と配置は変わりません。

重要 — UX の一貫性：要素は同じ位置に配置してください。製品のユーザーは、ナビゲーション、ボタン、フォームなどの場所を覚えています。要素の位置を維持することで、ユーザーが戸惑ったり、必要な機能を見つけられなくなったりするのを防げます。更新するのは見た目（色、タイポグラフィ、スペーシングトークン）であり、ページ構造の並べ替えではありません。

開始時期：フェーズ 3 が完了し、コンポーネントが SGDS の Web コンポーネントを使用するようになってからです。

前提条件（フェーズ 2 ですでに完了しているはずです）：

• sgds.css の基盤 CSS をインポート済み（Inter フォントファミリー、タイポグラフィのリセットを提供）
• utility.css を Tailwind で処理される CSS ファイルにインポート済み
• Tailwind の preflight を無効化済み（tailwindcss/theme.css + tailwindcss/utilities.css を使用）

置き換えるもの：

• 古いレイアウトシステム（MUI の <Box>、Chakra の <Grid>、v1 Bulma の .columns、v2 Bootstrap の <Row>/<Col>）
• 古いユーティリティクラス（MUI の sx prop、Chakra の style props、Bulma の .is-*、Bootstrap の .m-* .p-*）
• 古い色・タイポグラフィシステム（SGDS の CSS トークンとユーティリティに置き換え）

範囲についてユーザーに確認する：作業を始める前に、今回の移行でどのページやルートを対象にするか、ユーザーに確認してください。アプリ全体を移行する場合もあれば、特定のページだけを移行する場合もあります。決めつけず、ユーザーに移行範囲を定めてもらってください。

移行方法：

参照：reference/css-utilities-migration.md で、古い CSS パターン（Bootstrap、Tailwind、MUI sx、Chakra style props）を sgds: に対応するパターンに変換するための早見表を確認してください。

参照：SGDS のすべてのユーティリティクラス、CSS トークン、スタイル設定については、../sgds-utilities/SKILL.md を確認してください。

重要な原則：レイアウトの配置を維持しながら、古いレイアウト・ユーティリティシステムを SGDS v3 のユーティリティ（sgds: プレフィックスを使用した Tailwind ベース）に置き換えます。グリッドは sgds:grid に、フレックスは sgds:flex に、スペーシングは sgds:gap-*、sgds:p-* などに置き換えます。

結果：元の情報アーキテクチャとレイアウトの設計を維持したまま、アプリケーションで SGDS v3 のブランドカラー、タイポグラフィ、スペーシングトークンが使用されます。

所要時間の目安：CSS の対象範囲の広さに応じて1～2週間

---

フェーズ 5：移行後の検証

目標：移行が完了し、すべてが正しく設定されていることを確認します。

すべてのフェーズが完了したら、次のチェックリストを確認してください。

フォントの確認

• テキストが Inter フォントで表示される（ブラウザーのデフォルトのセリフ体／サンセリフ体ではない）
• DevTools で確認：<body> の font-family に Inter が含まれている
• Google Fonts の <link> タグが <head> にある

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）

トークンの確認

• テーマトークンが有効になっている：sgds:bg-primary-default、sgds:text-body-secondary などが実際の色に解決される
• 昼夜のテーマ切り替えが機能する（該当する場合）

テストの確認

• すべてのテストに合格する（pnpm test）
• イベントハンドラーが SGDS の正しいパターンを使用している（ネイティブの onChange ではなく、onSgdsChange、onSgdsInput）

---

全体のワークフロー

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 コンポーネントの移行とテスト基盤を扱います。製品固有のロジックやビジネス要件に関するテストの作成は、ご自身で行ってください。

「段階的に移行できますか？」

はい。 コンポーネントを1つずつ（テスト＋ソース）移行してください。移行期間中は、古いコンポーネントと新しい SGDS コンポーネントをアプリケーション内で共存させることができます。

「テストランナーが実際のブラウザーに対応していない場合はどうすればよいですか？」

選択肢は2つあります：（1）Shadow DOM を完全にサポートする Vitest ＋ Playwright にアップグレードする（パス A）、または（2）ポリフィルを使って既存の Jest/RTL 環境にパッチを適用し、JSDOM で SGDS コンポーネントが動作するようにする（パス 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）を使っている場合はどうすればよいですか？」

同じ4段階の戦略を適用できます — スキャン、セットアップ、テストの移行、スタイリングの移行です。コンポーネントの置き換え方法は、ほかのライブラリと同じです。

「すべてのコンポーネントを書き直す必要がありますか？」

SGDS に移行するものだけです。SGDS に相当するものがないカスタムコンポーネント（レイアウト、ロジックなど）は、そのまま変更せずに使用できます。

---

AI エージェント向け

このスキルを使用する際は、次の点に従ってください。

1. フェーズ 1 から開始する：推奨事項を提示する前に、必ずユーザーに現在のスタックについて尋ねてください。
2. 参照先のスキルを優先する：委任する際は、スキル名を正確に使用してください。
   • セットアップ（フェーズ 2）には ../sgds-getting-started/SKILL.md
   • コンポーネント固有の API には ../sgds-components/SKILL.md
   • フォームのレイアウトパターン（アクションボタンを右揃え）には ../sgds-forms/SKILL.md
   • React のテスト移行（フェーズ 3、パス A）には reference/react-test-migration.md
   • Jest/RTL のパッチ適用（フェーズ 3、パス B）には reference/jest-rtl-patching.md
   • ライブラリごとのマッピングには reference/from-mui.md、reference/from-chakra.md、reference/from-shadcn.md、reference/from-sgds-react.md
   • イベント処理パターンには reference/events.md
   • CSS 移行の検索用テーブル（フェーズ 4）には reference/css-utilities-migration.md
   • CSS ユーティリティとスタイリングの全般には ../sgds-utilities/SKILL.md
3. 重複させない：ここで getting-started、コンポーネント、ユーティリティの手順を書き直さないでください。代わりに、それらへのリンクを記載してください。
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 コンポーネントで要件を満たせるか確認してください。<table> より <SgdsTable>、<input> より <SgdsInput> など、必ずコンポーネントを優先してください。
9. Tailwind の preflight を無効にする — @import "tailwindcss" の代わりに、@import "tailwindcss/theme.css" と @import "tailwindcss/utilities.css" を使用してください。preflight のリセットは SGDS コンポーネントのスタイルを上書きします。
10. フェーズ 5 の検証を実施する — すべての移行作業が完了したら、ユーザーと一緒に移行後のチェックリストを確認し、すべてが正しく設定されていることを確かめてください。