ui-doctor

スキル：UI Doctor

アプリケーションの UI を監査し、IDS への準拠、アクセシビリティ、ユーザビリティ、認知負荷の観点からレビューします。このスキルは、コンポーネントの使用状況、アクセシビリティ（WCAG）、ユーザビリティのヒューリスティック（Nielsen の 10 原則）、認知負荷、段階的な情報開示を対象とした包括的な UI レビューを AI エージェントが行い、優先度を付けた実行可能な推奨事項を含むレポートを作成できるよう支援します。

使用するタイミング

ユーザーが次のようなことを言った場合に、このスキルを有効にします。

• 「このページ／コンポーネント／ファイルのアクセシビリティをレビューしてください」
• 「この UI のユーザビリティを確認してください」
• 「IDS に準拠しているか監査してください」
• 「認知負荷が高すぎるように感じます」
• 「IDS ガイドラインに従っていますか？」
• 「a11y の問題がないか確認してください」
• 「この UI をレビューしてください」
• 「このフォームはアクセシブルですか？」
• 「UX レビューをしてもらえますか？」

また、より一般的には、次のような場合に使用します。

• IDS への準拠について、アプリケーションの UI コードをレビューする
• アクセシビリティ（WCAG 2.1 AA）を検証する
• ユーザビリティと認知負荷を評価する
• デザイントークンの使用状況と一貫性を評価する
• 準拠スコアを含む UI ヘルスレポートを作成する
• UX、アクセシビリティ、IDS の導入を改善するための推奨事項を提示する

監査モード

デフォルト：クイック UX レビュー。 ユーザーがアクセシビリティまたは完全な準拠を明示的に求めていない限り、これを使用します。クイックレビューで重大な問題が見つかった場合は、より詳細なモードに切り替えます。

クイック UX レビュー（デフォルト）

ユーザーが一般的な UI レビュー、ユーザビリティの確認、または「これは適切に見えますか？」と尋ねた場合に使用します。

1. 認知負荷と情報アーキテクチャ — UI が圧倒的ではありませんか？ 一度に表示される項目、選択肢、アクションが多すぎませんか？
2. ユーザビリティのヒューリスティック — Nielsen の 10 原則に照らして評価します（監査チェックリスト § ユーザビリティのヒューリスティックを参照）
3. ボタンの階層とレイアウトの一貫性 — セクションごとに主要ボタンを 1 つにし、間隔を一貫させます
4. コンポーネントの簡易確認 — IDS コンポーネントがある箇所で、明らかな標準 HTML 要素が使われていませんか？

アクセシビリティレビュー

ユーザーが a11y、WCAG、キーボード操作、またはスクリーンリーダーのサポートについて尋ねた場合に使用します。

1. フォームのアクセシビリティ — ラベル、必須項目の表示、検証メッセージ、id/htmlFor の対応付け
2. キーボードとフォーカス — スキップリンク、モーダル／スライドアウト内のフォーカス制御、視認可能なフォーカスインジケーター
3. スクリーンリーダー — ARIA ランドマーク、動的コンテンツの通知、インタラクティブ要素のアクセシブルな名前
4. 色とコントラスト — WCAG AA のコントラスト比、色だけに依存しないこと
5. 認知負荷 — 段階的な情報開示、情報密度（監査チェックリスト § 認知負荷を参照）

完全準拠監査

ユーザーが IDS の完全な監査または準拠レポートを求めた場合に使用します。

1. 監査チェックリストのすべてのセクションを実施します
2. 置き換え表に照らしてコンポーネントの使用状況を検証します
3. デザイントークンの使用状況と Provider／CSS の設定を確認します
4. パターン（フォーム、読み込み、ナビゲーション）を評価します
5. ユーザビリティと認知負荷を評価します
6. レポートテンプレートを使用して完全なレポートを作成します

範囲を限定した監査

ユーザーが特定のファイル、コンポーネント、またはページについて尋ねた場合は、その範囲だけを対象に監査します。同じチェック項目を適用しますが、対象ファイルのみに限定します。依頼がない限り、アプリケーション全体をスキャンしないでください。

例：「UserProfileForm.tsx のアクセシビリティを確認してください」→ そのファイルだけを対象にアクセシビリティレビューモードを実施します。

監査範囲

開始する前に、スキャンするファイルを特定します。

スキャンするファイル

• src/（またはアプリケーションのソースディレクトリ）内のすべての .tsx、.jsx、.ts、.js ファイル
• ハードコードされたデザイン値を確認するための CSS／SCSS／styled-component ファイル
• Provider と CSS のインポートを確認するためのアプリケーションのエントリーポイント

重要： Provider とセットアップを評価する前に、実際のマウントポイント（例：main.tsx、index.tsx）からコンポーネントツリーを必ずたどってください。エントリーポイントはルートファイルとは限りません。カスタム要素のラッパー、シャドウ DOM ホスト、またはルーターをレンダリングする別のブートストラップファイルの場合もあります。親エントリーポイントですでに処理されている場合は、Provider／CSS の不足を問題として指摘しないでください。

除外するファイル

• テストファイル（*.test.tsx、*.spec.tsx、__tests__/） — テスト用モックでは、生の HTML が正当に使われることがあります
• Storybook のストーリー（*.stories.tsx） — 比較のため、生の HTML を意図的に表示することがあります
• 設定ファイル（*.config.ts、*.config.js） — UI コードではありません
• 型定義（*.d.ts） — 実行時の UI コードではありません
• サードパーティーのコード（node_modules/、ベンダーライブラリ） — アプリケーション側では制御できません
• ビルド出力（dist/、build/） — 生成されたコードです

バージョンを考慮した監査

IDS の現在のバージョンは 6 です。監査時には、次の点を確認してください。

• インストールされているバージョンを確認 — package.json で @iress-oss/ids-components を確認します
• v6 — すべてのルールをそのまま適用します
• v5 — v5 固有のパターンを「移行の機会」として指摘します（主な違い：IressForm は rules プロパティを使用し、react-hook-form は peer dependency、フォームの状態管理には useWatch／ref を使用）
• v5 より前 — 大規模な移行が必要であることを指摘し、まず Provider／CSS のセットアップを優先します
• 監査レポートのヘッダーには、必ずバージョンを記載します

監査プロセス

1. UX、アクセシビリティ、認知負荷を評価する

まずユーザーが体験する内容から始めます。コンポーネントへの準拠状況を確認する前に、UI の使いやすさ、アクセシビリティ、情報密度を評価してください。

a. ユーザビリティのヒューリスティック（Nielsen の 10 項目）

10 項目すべてのヒューリスティックに照らしてアプリケーションを評価してください。それぞれの IDS 固有のガイダンスは、監査チェックリスト § ユーザビリティのヒューリスティックを参照してください。主な項目は次のとおりです。

1. システムの状態を視認できる — ローディング状態には IressLoading（推奨）または IressSkeleton（カスタムコンテンツのプレースホルダーパターン用）を使用します。タブ、ナビゲーション、パンくずリストでは、アクティブな状態を視認できるようにします
2. システムと現実世界の一致 — ラベルには平易な言葉を使います。アイコンにはテキストを添えます。ステータスカラーは慣例に従います
3. ユーザーの制御と自由 — モーダル／スライドアウトは閉じられるようにします。破壊的な操作には確認を求めます。フォームにはキャンセル手段を設けます
4. 一貫性と標準 — すべてのコンポーネントに IDS を使用します。トークンを一貫して使用します。同じ操作には同じパターンを使います
5. エラーの防止 — 宣言的な rules によるバリデーションを使用します。必須フィールドを明示し、制約は hint で伝えます
6. 想起より認識 — ナビゲーションを常に表示します。パンくずリストを視認できるようにします。ラベルは常に表示し、プレースホルダーだけにしないでください
7. 柔軟性と効率性 — キーボードショートカット、スキップリンク、検索可能なセレクト、自動補完を用意します
8. 美しくミニマルなデザイン — 視覚的な階層を明確にします。間隔に一貫性を持たせます。各セクションの主要な操作は 1 つにします
9. ユーザーがエラーを認識し、回復できるようにする — 人が理解できるバリデーションメッセージを使用します。エラーをインラインで表示します。長いフォームには IressValidationSummary を使用します
10. ヘルプとドキュメント — ヒントテキストを用意します。UI の用途が自明でない場合はツールチップを使います。プレースホルダーはラベルの補助として使用します

b. 認知負荷と情報アーキテクチャ

UI が一度に表示する情報や選択肢が多すぎないか評価します。

• 項目数のしきい値 — 10 項目を超えるメニュー／ドロップダウンには searchable を使用します。8 フィールドを超える長いフォームには IressForm pattern="long" を使用します。トップレベル項目が 7 個を超えるナビゲーションはグループ化します
• 段階的な情報開示 — 必要になるまで副次的なコンテンツを非表示にするには、IressExpander または IressTabSet を使用します。複数ステップのフローでは、複雑なタスクを段階に分けます
• 情報密度 — 画面が圧迫感を与えていませんか？関連コンテンツのグループ化には IressCard／IressPanel を使用し、十分な間隔を確保するには IressStack を使用します
• 一括操作の安全性 — 一括操作（すべて選択＋削除）には、IressModal による明示的な確認が必要です。影響を受ける項目数を表示します
• 状態変更後のフォーカス管理 — モーダルを閉じた後はトリガーにフォーカスを戻します。項目を削除した後は次または前の項目にフォーカスを移します。フォーム送信後は結果またはエラーにフォーカスを移します
• 視覚的な階層 — 主要コンテンツを目立たせ、副次的なコンテンツを控えめにします。階層を明確にするには IressText textStyle を使用します

c. アクセシビリティ（WCAG 2.1 AA）

フォームのアクセシビリティ、キーボード操作とフォーカス、スクリーンリーダーのサポート、色とコントラストを確認します。全項目については、監査チェックリスト § アクセシビリティを参照してください。主な確認項目：

• すべてのフォーム入力にラベルがある（IressField または IressFormField を使用）
• スキップリンクがある（IressSkipLink）
• モーダル／スライドアウトでフォーカスがトラップされる（IDS では自動）
• ARIA ランドマーク（<nav>、<main>、<aside>）
• 動的コンテンツがスクリーンリーダーに通知される — 適切な階層を選択します：
  • IressAlert — 持続的なインラインのステータスメッセージ（aria-live は不要。すでに読み上げの流れに含まれています）
  • IressToaster — 注意を必要とする一時的な通知（aria-live="assertive"）。多用しないでください
  • aria-live="polite" を併置したマイクロアニメーション／インタラクション — トースト通知にするほどではない、控えめでユーザーが開始する更新（保存インジケーター、件数バッジ、ステータス変更など）に使用します。ライブリージョンはグローバルではなく、コンポーネントの近くに配置します
• 色のコントラストが WCAG AA を満たしている。色だけに依存しない

d. ボタンの階層

• 論理的なセクションごとに mode="primary" のボタンを 1 つ配置します
• 破壊的な操作には、独自の赤色スタイルではなく status="danger" を使用します
• アイコンのみのボタンには、アクセシブルなテキストを含めます

e. レイアウトの一貫性

• 縦方向のスタック → IressStack、横方向の行 → IressInline、グリッド → IressRow／IressCol
• 間隔には gap プロパティでトークン値（0～10）を使用します
• インラインスタイルの代わりに IressCSSProps（m、mx、p、px）を使用します
• レスポンシブ対応には hideFrom／hideBelow プロパティまたは useBreakpoint フックを使用します。グリッドレイアウトではレスポンシブな span（例：span={{ xs: 12, md: 6 }}）を使用します。モバイル表示では主要なタスクに焦点を当て、副次的なコンテンツは IressSlideout または折りたたみ可能なセクションに配置します

2. IDS コンポーネントの使用状況を検証する

IDS に相当するものがある生 HTML、サードパーティ製コンポーネント、独自実装をスキャンします。完全な対応表については、置換表を使用してください。

簡易チェック：

• 生の <button>、<input>、<select>、<form>、<table> を使用していない — IDS の対応コンポーネントを使用します
• IDS に相当するものがある場合、サードパーティ製 UI ライブラリ（MUI、Ant、Chakra、Bootstrap、Radix、Headless UI）をインポートしていない
• 独自のモーダル、ドロワー、タブ、ツールチップ、アラートを使用していない — IDS のパターンを使用します
• 独自のローディングスピナーを使用していない — IressLoading（推奨）またはカスタムコンテンツのプレースホルダーパターン用の IressSkeleton を使用します
• Flex／グリッドスタイルを適用したレイアウト用 div → IressStack、IressInline、IressRow／IressCol

許容される例外（指摘しないでください）：テストファイル内の生要素、アプリで制御できないサードパーティ製ウィジェット、<input type="hidden">、内部で IDS を使用するラッパーとしての独自コンポーネント。置換表 § 許容される例外を参照してください。

3. IDS の原則とセットアップを検証する

a. プロバイダーと CSS の設定

• IressProvider はアプリケーションのルートをラップする必要があります — フォント、CSS 変数、テーマ設定に必要です。IressProvider にはすでに IressModalProvider、IressSlideoutProvider、IressToasterProvider、IressPopoverProvider、IressIconProvider が含まれているため、これらを個別に追加する必要はありません。同様に、IressShadow には内部で IressProvider が含まれているため、IressShadow を使用する場合、追加のプロバイダーは不要です。
• IDS コンポーネントの CSS をインポートする必要があります — @iress-oss/ids-components/dist/style.css には、すべてのコンポーネントのスタイルが含まれています。
• インストールが必要なのは @iress-oss/ids-components@beta のみです — トークンはコンポーネントライブラリにバンドルされているため、別途インストールする必要はありません。IDS v6 は現在ベータ版のため、@beta タグが必要です（例：npm install @iress-oss/ids-components@beta）。
• CSP で IDS の外部オリジンを許可リストに追加する必要があります — アプリでコンテンツセキュリティポリシーを適用している場合は、fonts.googleapis.com と fonts.gstatic.com を style-src／font-src に追加する必要があります。レガシーな Font Awesome アイコンまたは IressTheme を使用する場合は、cdn.iress.com を追加してください。IressShadow を使用し、インラインスタイルがブロックされている場合は、<head> に <meta name="csp-nonce" content="..."> を追加してください。詳細は、node_modules/@iress-oss/ids-components/.ai/guides/get-started-content-security-policy.md の CSP ガイドを参照してください（参照するには @iress-oss/ids-components がインストールされている必要があります）。
• アプリケーションコードでデザイントークンを直接使用する場合（カスタムスタイル設定など）は、@iress-oss/ids-tokens@beta もインストールし、@iress-oss/ids-tokens/build/css-vars.css をインポートしてください。

// ✅ Minimum required setup (option A — standard)
import '@iress-oss/ids-components/dist/style.css';
import { IressProvider } from '@iress-oss/ids-components';

function App() {
  return <IressProvider>{/* app content */}</IressProvider>;
}

// ✅ Minimum required setup (option B — IressShadow)
// IressShadow is a superset of IressProvider — it wraps children in a shadow DOM,
// injects style.css automatically, and provides the IressProvider context.
// No separate IressProvider or CSS import is needed when using IressShadow.
import { IressShadow } from '@iress-oss/ids-components';

function App() {
  return <IressShadow>{/* app content */}</IressShadow>;
}

// ✅ With direct token usage in application code (optional)
import '@iress-oss/ids-components/dist/style.css';
import '@iress-oss/ids-tokens/build/css-vars.css';
import { IressProvider } from '@iress-oss/ids-components';
import { cssVars } from '@iress-oss/ids-tokens';

function App() {
  return (
    <IressProvider>
      <div style={{ padding: cssVars.spacing[4] }}>{/* app content */}</div>
    </IressProvider>
  );
}

// ❌ Incorrect — missing component CSS
import { IressProvider } from '@iress-oss/ids-components';
// Components will render without styles!

// ❌ Incorrect — installing tokens separately just for provider setup
yarn add @iress-oss/ids-tokens@beta  // Not needed unless using tokens directly

// ❌ Incorrect — installing without @beta tag (will not resolve to v6)
yarn add @iress-oss/ids-components  // Must use @beta tag

b. デザイントークンの使用

• 色の hex／rgb 値をハードコードしないでください — IDS のカラートークンを使用してください。
• ピクセル単位の間隔をハードコードしないでください — IDS のスペーシングトークンを使用してください。
• フォントプロパティをハードコードしないでください — IDS のタイポグラフィトークンを使用してください。
• 角丸の半径をハードコードしないでください — IDS のラディウストークンを使用してください。

// ❌ Hardcoded values
<div style={{ color: '#003271', padding: '16px', borderRadius: '4px' }}>

// ✅ IDS tokens
import { cssVars } from '@iress-oss/ids-tokens';
<div style={{
  color: cssVars.colour.primary.fill,
  padding: cssVars.spacing[4],
  borderRadius: cssVars.radius[1]
}}>

c. フォームとパターンへの準拠

IDS には、一貫性のある UI を実現するためのパターンが用意されています。適切な箇所で使用状況を検証してください。

フォームパターン（IressForm）：

• すべてのフォームで IressForm と IressFormField を使用します
• 検証には rules プロパティを使用し、条件付きフィールドには useWatch を使用します
• フィールドが 8 個を超えるフォームでは pattern="long" を使用します
• react-hook-form はピア依存関係です

読み込みパターン（IressLoading／IressSkeleton）：

• page、component、start-up、validate、long のパターンがあります
• 表示タイミングのしきい値を自動的に処理します（500ms 未満ではインジケーターなし、500ms でスピナー、2s でメッセージ）
• 標準的な読み込み状態には IressLoading を優先してください。タイミング、メッセージ、アクセシビリティを自動的に処理します
• ページレイアウトを反映したスケルトン画面が必要な、カスタムコンテンツのプレースホルダーパターンでは IressSkeleton も有効です。可能であれば IressLoading を使用してください
• ページが事前にデータを格納したキャッシュ（例：前のページによってデータが格納された SWR、React Query、または TanStack Query のキャッシュ）から読み込む場合、別途読み込み状態を設ける必要がないことがあります。指摘する前に、データソースがキャッシュからの読み込みか、新規の取得かを確認してください

ナビゲーションパターン：

• フィルター／アクションのトリガーには IressDropdownMenu を使用します（フォーム内では使用しません）
• 行レベルのアクションには ariaLabel を指定して IressContextualMenu を使用します
• アプリケーションシェルのナビゲーションには IressSideNav を使用します
• 階層ナビゲーションには IressBreadcrumbs を使用します

エラーバウンダリーパターン：

React のエラーバウンダリーはコンポーネントのクラッシュを捕捉し、カスタムエラーページや生の HTML ではなく、フォールバック UI として IDS コンポーネントを表示する必要があります。

エラーの範囲	IDS コンポーネント	理由
ページ全体のクラッシュ（ルートエラーバウンダリー）	IressModal status="danger" と再試行／再読み込みアクション	操作をブロックし、注意を促し、構造化された復旧手段を提供します
セクション／機能のクラッシュ（スコープされたバウンダリー）	インラインフォールバックとしての IressAlert status="danger"	表示が持続し、コンテキスト内に収まります。ページの残りの部分は引き続き動作します
一時的な API／ネットワーク障害（クラッシュではない）	IressToaster	再試行可能で、UI をブロックしません

• エラーバウンダリーに IressToaster を使用しないでください。トーストは一時的で、閉じることができます。ユーザーが閉じると、壊れたコンポーネントツリーに復旧用 UI が残りません
• ルートレベルのエラーバウンダリーには IressModal status="danger" を第一候補として推奨します。actions プロパティを使用して、「再試行」または「再読み込み」ボタンを表示してください
• 個々の機能をラップするスコープされたバウンダリーには IressAlert status="danger" を推奨します。壊れたコンポーネントがあった場所にインラインで表示されます

エラーハンドリングの不足を指摘する前に： 監査対象のファイルをカバーするエラーバウンダリーが、親コンポーネントまたはレイアウトルートにすでに設けられているか確認してください。エラーバウンダリーはアプリ全体に適用するパターンです。親バウンダリーがすでにエラーを捕捉して IDS ベースのフォールバック UI（例：ナビゲーションを考慮した復旧機能を備えた IressModal status="danger"）を表示する場合、ページコンポーネントに独自のエラー／空状態の処理は必要ありません。エラーハンドリングを提供する祖先がない場合にのみ指摘してください。

Shadow DOM パターン（IressShadow）：

• IressShadow は IressProvider の機能をすべて含みます。シャドウルートを作成し、その中に style.css を挿入して、IressProvider のコンテキストを自動的に提供します。アプリのエントリーポイントで IressShadow を使用する場合、別途 IressProvider や CSS のインポートは不要です。
• マイクロフロントエンドの CSS 分離によく使われますが、あらゆるアプリケーションで単独の Provider と CSS の設定として使用することもできます
• <div> にシャドウルートを作成します。子要素は標準的な React コンポーネントです
• slot 属性は関係ありません。常に React のプロパティ（prepend、append、footer など）を使用してください

4. 推奨事項を提示する

以下のレベルで調査結果に優先順位を付けます。

優先度	説明	対応
Critical	Provider/CSS がない、ラベルのない生の入力、スキップリンクがない、フォームで IressForm を使用していない	直ちに修正する
High	IDS に相当する生の HTML 要素、カスタムフォーム処理、アクセシビリティ上の問題、認知負荷が高い問題	今回のスプリントで修正する
Medium	ハードコードされたトークン、IressText がない、カスタムレイアウト、ARIA ランドマークがない、情報密度の問題	次回のスプリントで計画する
Low	IressImage がない、カスタムバッジ、軽微なトークンの不整合、優先度の低い UX 改善	バックログに追加する

各調査結果には、次の項目を記載します。（1）見つかった内容、（2）重要である理由、（3）修正方法（修正前／修正後のコードを含む）、（4）優先度。

5. コンプライアンスレポートを生成する

レポートテンプレートを使用して、構造化されたレポートを作成します。

監査出力の例

クイックスキャンの概要

IDS UI Doctor — Quick Scan
================================
Files scanned:     42
Components found:  18 IDS / 7 raw HTML
Patterns used:     3/7 available
Token compliance:  73%
Accessibility:     82%

Top Issues:
  ⚠ 3× raw <button> found (should be IressButton)
  ⚠ 2× hardcoded colours found (#333, #f5f5f5)
  ⚠ 1× <input> without IressField wrapper
  ⚠ 2× custom <form> found (should use IressForm)
  ⚠ 1× custom loading spinner (should use IressLoading)
  ⚠ 1× missing skip link for keyboard navigation
  ✓ IressProvider correctly configured
  ✓ Component CSS imported
  ✓ IressBreadcrumbs used for navigation hierarchy
  ✓ Colour contrast passes WCAG AA

参考資料

注： コンポーネントのドキュメント、パターンのドキュメント、およびマニフェストは、パッケージ内にあります。

• コンポーネントのドキュメント： 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
• トークン使用スキル： .agents/skills/token-usage/SKILL.md
• Figma マッピングスキル： .agents/skills/figma-to-ids/SKILL.md
• UI 翻訳スキル： .agents/skills/ui-translation/SKILL.md
• Storybook とガイドライン： https://main--691abcc79dfa560a36d0a74f.chromatic.com
• よくある間違いのガイド： node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md（@iress-oss/ids-components のインストールが必要です）

監査で指摘すべきよくある間違い

コード例を含むよくあるアンチパターンの全一覧については、node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md にある「よくある間違いのガイド」を参照してください（@iress-oss/ids-components のインストールが必要です）。監査では、以下の優先度と監査ルールに従ってこれらを指摘してください。

IressButton の disabled 属性 — High 優先度

監査ルール： すべての <IressButton> で disabled を検索します。一致するものはすべて指摘事項です。

IressText の冗長な textStyle — Medium 優先度

監査ルール： element と textStyle の両方を指定した IressText のうち、textStyle が element のデフォルトスタイルと一致するものを検索します（例：element="h1" textStyle="typography.heading.1"）。

レガシーな slot 属性（v4 パターン）— High 優先度

監査ルール： すべての <Iress*> コンポーネント内で slot=" を検索します。一致するものはすべて指摘事項です。