version-migration

スキル：IDS バージョン移行

使用するタイミング

• IDS v5（または v4）から IDS v6 へ移行する場合
• OUI（@iress/oui）から IDS v6 へ移行する場合
• @iress/components-react から @iress-oss/ids-components へインポートを更新する場合
• IressForm／IressFormField を使って、Formik フォームを React Hook Form に変換する場合
• IDS v4 のテストユーティリティを使うテストファイルを更新する場合
• 移行 PR の正確性をレビューする場合

判断表：どの移行パスを選ぶか

現在のスタック	移行パス	複雑さ	参照
OUI のみ	OUI→v6 ガイド	高（フォームアーキテクチャの変更）	prop-renames.md
IDS v4 のみ	v4→v6 ガイド	中（フォームアーキテクチャの変更）	prop-renames.md
IDS v5 のみ	v5→v6 ガイド	低～中	v5-to-v6-migration.md
OUI + IDS v4	OUI→v6 と v4→v6 の両方のガイド	高（フォームアーキテクチャの変更）	prop-renames.md
OUI + IDS v5	OUI→v6 ガイド + IDS の変更には v5→v6	高（フォームアーキテクチャの変更）	v5-to-v6-migration.md

差分ビューアーを備えたインタラクティブなガイドは、Storybook で利用できます。

• v4→v5 ガイド
• v5→v6 ガイド
• OUI→v6 ガイド

---

移行前の評価

移行を開始する前に、次のスクリプトを実行するか、手動で確認してください。

1. 現在のバージョンを特定する：scripts/detect-version.sh — IDS／OUI のバージョンを検出し、推奨する移行パスを提示します
2. コンポーネントの使用状況を監査する：scripts/audit-components.sh — コンポーネント使用状況レポートを生成します
3. 非推奨の props を確認する：scripts/find-deprecated-props.sh — 問題を引き起こす props を見つけます
4. フォームアーキテクチャを確認する：scripts/find-formik.sh — 移行が必要な Formik フォームを特定します
5. テストパターンを確認する：scripts/find-test-utils.sh — 古いテストユーティリティを見つけます
6. カスタム CSS を確認する：.oui-、.ids-、または iress- のクラスセレクターを検索し、問題が発生する可能性のあるものを確認します
7. VRT をセットアップする（推奨）：scripts/setup-playwright-vrt.sh — Playwright のビジュアルリグレッションテストを生成します
8. ベースラインのスクリーンショットを取得する：移行前に VRT スイートを実行し、現在の状態を記録します
9. 移行ブランチを作成する：必要に応じてロールバックできることを確認します

---

クイックリファレンス：パッケージの変更

インポートパス

// ❌ Old (IDS v4)
import { IressButton } from '@iress/components-react';

// ❌ Old (OUI)
import { Button, Input } from '@iress/oui';

// ✅ IDS v6 (install with @beta tag: npm install @iress-oss/ids-components@beta)
import { IressButton, IressInput } from '@iress-oss/ids-components';

重要： IDS v6 は現在ベータ版です。@beta タグを付けてインストールしてください。

npm install @iress-oss/ids-components@beta
npm install @iress-oss/ids-tokens@beta  # トークンを直接使用する場合

CSS エントリーポイント

// ✅ Required in your app entry point
import '@iress-oss/ids-components/dist/style.css';

トークンパッケージ

// ✅ Required for design tokens
import '@iress-oss/ids-tokens/build/css-vars.css';
import { cssVars } from '@iress-oss/ids-tokens';

---

主な移行項目

v5 → v6 の移行

IDS v5 から v6 への移行については、references/v5-to-v6-migration.md を参照してください。次の内容を扱っています。

• パッケージと CSS のインポート変更
• コンポーネント名の変更（IressBadge → IressPill、IressFilter → IressDropdownMenu など）
• コンポーネントごとの prop の変更（Button、Alert、Toggle、Field、Modal、Select）
• アイコンの移行（FontAwesome → Material Symbols）
• フォームの移行パターン

コンポーネント名の変更

バージョン間（IDS および OUI → v6）で名前が変更されたコンポーネント、削除されたコンポーネント、新しいコンポーネントについて説明します。全体の対応表はreferences/component-renames.mdを参照してください。

主な変更：IressBadge → IressPill、IressRichSelect → IressSelect、IressField → IressFormField、IressFilter → IressDropdownMenu。

プロパティ名の変更（重要 — ソースコードで確認済み）

古いプロパティ名を使用すると、エラーが表示されずに機能しなくなります。完全な一覧はreferences/prop-renames.mdを参照してください。

よくある変更：

コンポーネント	古いプロパティ（OUI）	新しいプロパティ（v6）
Alert	context	status
Modal	onHide	onShowChange
Fieldset/RadioGroup	legend	label
Label	optional	required

コンポーネント（IDS v4/v5）	古いプロパティ	新しいプロパティ（v6）
IressButton	variant	mode
IressAlert	variant	status
IressModal	isOpen	show
IressModal	onClose	onShowChange
IressModal	title	heading
IressPanel	background	bg
IressStack/IressInline	gutter	gap

フォームの移行（Formik → React Hook Form）

アーキテクチャ上、最も大きな変更です。フォームでは、Formik の <Field as={...}> パターンに代わり、render プロパティを使用する IressForm + IressFormField を使用します。Yup スキーマは、フィールドごとの rules プロパティになります。

検証方法の対応、変更前後の例、一般的なパターンについては、references/form-migration.mdを参照してください。

簡単な例：

<IressForm defaultValues={{ email: '' }} onSubmit={handle}>
  <IressFormField
    name="email"
    label="Email"
    render={(props) => <IressInput {...props} type="email" />}
    rules={{ required: 'Required' }}
  />
  <IressButton type="submit" mode="primary">
    Submit
  </IressButton>
</IressForm>

テストの移行

IDS v6 では、特別なテストユーティリティを使わず、標準の React Testing Library を使用します。idsFireEvent を fireEvent/userEvent に置き換え、mockLazyLoadedComponents を削除し、getByTestId よりも getByRole/getByLabelText を優先してください。

インポートの変更、パターンの対応、設定の更新、フォームのテスト例については、references/testing-migration.mdを参照してください。

スタイリングの移行

OUI の CSS クラスと IDS v4 の Stencil クラスは削除されました。スタイリングプロパティ（p、m、bg、gap、scrollable）またはデザイントークン（var(--iress-*)）を使用してください。カスタム CSS が上書きされる場合は、@layer の順序を宣言してください。

例と AG Grid の移行については、references/styling-migration.mdを参照してください。

---

移行後の検証

移行が完了したら、scripts/validate-migration.sh を実行するか、手動で次の項目を確認してください。

1. 自動チェック：検証スクリプトを実行し、一般的な問題がないか確認します
2. ビジュアルリグレッション：VRT スイートを実行し、すべての視覚的な差分を確認します（references/visual-regression-testing.mdを参照）
3. 表示の確認：すべてのコンポーネントがコンソールエラーや警告なしでレンダリングされることを確認します
4. フォームの機能：フォームを送信し、検証ルールが正しく機能することを確認します
5. テストスイート：新しいテストパターンですべてのテストが通ることを確認します（idsFireEvent などが残っていないこと）
6. アクセシビリティ：キーボード操作とスクリーンリーダーの機能が維持されていることを確認します
7. スタイリング：スタイルの欠落がないことを確認し、レスポンシブのブレークポイントをチェックします
8. インタラクティブな状態：ホバー、フォーカス、無効、読み込み中の各状態が想定どおりに機能することを確認します
9. ビルド：本番ビルドがエラーなく完了することを確認し、バンドルサイズをチェックします

検証スクリプトでは、次の項目をチェックします。

• 古いインポート（@iress/oui、@iress/components-react）
• 古いテストユーティリティ（idsFireEvent、mockLazyLoadedComponents）
• 非推奨のプロパティ（variant=、isOpen=、gutter= など）
• 必須の CSS インポート
• Formik の使用箇所

---

よくある落とし穴

トラブルシューティングの詳細なガイドについては、references/common-gotchas.md を参照してください。次の内容を取り上げています。

• 重大な破壊的変更（CSS の欠落、バリデーション、名前が変更された props）
• IDS v4 React → v6 React の落とし穴（テストユーティリティ、スロット、ヘルパー、アイコン）
• OUI 固有の落とし穴（名前が変更された prop、削除されたコンポーネント）
• コンポーネント API の変更（フォームフィールド、スタイリング、コンポジションパターン）
• フォームアーキテクチャの変更（Formik → React Hook Form）

---

相互参照

生成された移行ガイド（詳細についてはこちらをお読みください）

• v4→v5 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-v5.md
• v5→v6 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-v6.md
• OUI→v6 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-oui.md

コンポーネントとパターンのドキュメント

• コンポーネントのドキュメント — node_modules/@iress-oss/ids-components/.ai/components/
• パターンのドキュメント — node_modules/@iress-oss/ids-components/.ai/patterns/
• インデックス — node_modules/@iress-oss/ids-components/.ai/index.json

関連スキル

• token-usage — デザイントークンの使用パターン
• ui-translation — IDS v6 の UI をゼロから構築
• ui-doctor — IDS 準拠状況の監査

参考資料

• Storybook とガイドライン： https://main--691abcc79dfa560a36d0a74f.chromatic.com