kufu · schktjm · Apr 13, 2025 · schktjm · Apr 14, 2025 · schktjm
@@ -0,0 +1,172 @@
+---
+description: SmartHR UIのレビューガイドライン
+globs: packages/smarthr-ui/**/*.*
+alwaysApply: true
+---
+# SmartHR UI リポジトリ コーディング＆レビューガイドライン
+
+このガイドラインは、SmartHR UI リポジトリにおける開発およびコードレビューの品質、一貫性、保守性を高めることを目的としています。開発者およびレビュー担当者は、以下の点を遵守・確認してください。
+
+## 1. コードの可読性とスタイル
+
+コードは他の開発者が見ても理解しやすく、メンテナンスしやすい状態を保つことが重要です。
+
+* **命名規則:**
+    * 【推奨】関数名はキャメルケース (`exampleFunctionName`) を使用してください。React イベントハンドラーには `handle` プレフィックス (`handleClick`, `handleChange`) の使用を検討し、簡潔な名前を推奨します。Boolean Props は `isXxx`, `hasXxx` 形式 (`isActive`, `isDisabled`) を推奨します。
+    * **【避けるべきこと】** 関数名に、定数のようなすべて大文字のスネークケース (`EXAMPLE_FUNCTION_NAME`) を使用しないでください。
+
+* **配列アクセス:**
+    * 【推奨】配列の末尾要素などへのアクセスには、`.at(-1)` メソッドの使用を検討してください（可読性・パフォーマンス向上）。
+    * **【避けるべきこと・注意点】**
+        * 古いブラウザ（目安3年以上前）のサポートが必要な場合は、`.at()` は使用できないため避けてください。
+        * 上記の場合を除き、特別な理由がない限り、速度や可読性の面で劣る可能性がある `.length - 1` を用いたアクセスは推奨しません。
+
+* **`new` キーワードの使用:**
+    * 【推奨】プリミティブ型を扱う際は、リテラル表記 (`""`, `0`, `true`) や適切な変換関数 (`toString()`) を使用してください。
+    * **【避けるべきこと】** `new String()`, `new Boolean()`, `new Number()` のように `new` キーワードをプリミティブ型の生成に使用すると、意図せずオブジェクトが生成され、予期せぬ挙動や混乱を招くため避けてください。
+
+* **コンポーネントのスタイリングと状態制御:**
+    * 【推奨】CSS クラスの適用は、CSS Modules やそれに類する仕組み（例: `styles` オブジェクト）を介して行ってください。
+    * 【推奨】`hidden`, `disabled` などの状態変化は、Props を介して `style` 属性を変化させる方法や、`styled-components` の `attrs` メソッドなどを検討してください（スタイルの再計算コスト回避）。
+    * **【避けるべきこと】** コンポーネント内で直接 `className` 属性を文字列操作したり、クラス名の追加/削除によって `hidden` や `disabled` などの状態を制御したりすることは、外部 CSS の影響や意図しない副作用を招く可能性があるため避けてください。
+
+* **メモ化 (Memoization):**
+    * 【推奨】不要な再レンダリングを避けるため、`React.memo`, `useCallback`, `useMemo` を適切に使用し、パフォーマンスを最適化してください。
+
+* **Decorators:**
+    * 【推奨】Decorators の扱いは、共通化された `useDecorators` フックの利用を検討し、一貫性を保ってください。
+
+* **コードのシンプルさ:**
+    * 【推奨】常にコードをシンプルで理解しやすい状態に保ち、GitHub の Code タブでの見やすさも意識してください。
+
+* **副作用のあるコードでの配列メソッド:**
+    * 【推奨】配列を走査して特定の要素を見つけ次第、副作用（関数呼び出しなど）を実行してループを終了したい場合は、`for...of` ループと `break` 文、あるいは `find` メソッドなど、意図が明確で効率的な方法を採用してください。
+    * **【避けるべきこと】** このようなケースで `some` メソッドを使用し、その返り値（boolean）を利用しないコードは、意図が不明確になり、パフォーマンス上の利点もないため避けてください。
+
+* **Tailwind CSS (スタイル関連):**
+    * 【推奨】クラス名のソートには `prettier-plugin-tailwindcss` の導入を検討してください。
+    * 【推奨】CSS のショートハンドプロパティは、可読性を損なわない範囲で活用してください。
+    * **【避けるべきこと】** `variants` を持たないコンポーネントに対して、型定義で `VariantProps<typeof Component>` を使用することは、型が `{}` となり不必要であるため避けてください。
+
+## 2. アクセシビリティ (a11y)
+
+すべてのユーザーが情報にアクセスし、機能を利用できるよう、アクセシビリティへの配慮は不可欠です。
+
+* **カラーコントラスト:**
+    * 【必須】テキストや UI 要素と背景色のコントラスト比が WCAG 2.1 の達成基準を満たしていることを確認してください（特に非テキストコンテンツは 3:1 以上）。
+* **スクリーンリーダー対応:**
+    * 【必須】適切な `aria` 属性（`aria-current="page"`, `role="alert"` 等）を付与し、スクリーンリーダーで正しく情報が伝わるようにしてください。エラーメッセージなどは色だけでなく、明確なテキストでも伝えてください。
+* **フォーカス表示:**
+    * 【必須】キーボード操作時にフォーカスされている要素が視覚的に明確になるようにしてください。
+    * **【注意点】** `:focus-visible` の Storybook 上での表示不具合が報告されているため、実ブラウザでの確認も重要です。
+* **強制カラーモード対応:**
+    * 【必須】OS の強制カラーモード（ハイコントラストモード等）でも、コンテンツが適切に表示・操作できることを確認してください（システムカラーの利用も検討）。
+
+## 3. コンポーネントの設計と API
+
+コンポーネントは再利用可能で、使いやすく、意図が明確であることが望ましいです。
+
+* **Props の命名:**
+    * 【推奨】Props 名はその役割と意図が明確に伝わるように命名してください（Boolean は `isXxx` 等）。文脈に応じて `type` より `color` のような具体的な名前を検討してください。
+* **コンポーネントの基本設計:**
+    * 【推奨】シンプルで再利用しやすい単位で設計してください。
+* **不要な Props の削除:**
+    * 【推奨】不要になった Props は速やかに削除してください。
+* **Props の型定義:**
+    * 【推奨】TypeScript では具体的かつ正確な型定義を行いつつ、必要に応じて `React.ReactNode` などで柔軟性も持たせてください。
+* **サイズオプション:**
+    * 【推奨】サイズオプション（S, M など）の命名規則を統一してください（現状 `s` が多い）。
+* **コンポーネントの目的とセマンティクス:**
+    * 【推奨】コンポーネントの目的に応じて、適切な HTML 要素 (`<a>`, `<button>` など) を使用し、HTML のセマンティクスを尊重してください。
+* **一括選択チェックボックスの HTML 構造:**
+    * 【推奨】可視ラベルを追加する際は、`<label>` が許可するコンテンツ（記述コンテンツ）を考慮し、適切な HTML 構造（必要なら `<p>` を `<span>` にするなど）にしてください。
+* **コンポーネントの利用前提:**
+    * 【推奨】コンポーネントは、ライブラリとして提供される範囲内で、想定される使い方で機能するように設計してください。
+    * **【避けるべきこと】** ライブラリの想定外の使い方（例: 他の UI ライブラリとの強制的な組み合わせ）を前提としたスタイリングや回避策をコンポーネント内部に実装することは、保守性を低下させるため避けてください。
+
+## 4. テスト
+
+コードの品質を担保し、デグレードを防ぐためにテストは重要です。
+
+* **Visual Regression Tests (VRT):**
+    * 【推奨】UI の見た目に関する変更やアクセシビリティ修正時には、VRT の追加・更新を検討してください。
+* **テストの記述:**
+    * 【推奨】テストコードは可読性を第一に記述してください。基本はクリック操作によるテストとし、キーボード操作のテストはユーザーシナリオ上重要で、かつ可読性を損なわない範囲で記述してください。
+    * **【避けるべきこと】** 初見で理解しにくい複雑なキーボード操作（例: `userEvent.tab({ shift: true })` と `userEvent.keyboard('{ }')` の組み合わせなど）をテストの基本としたり、多用したりすることは、可読性を著しく低下させるため避けてください。
+* **非同期処理のテスト:**
+    * 【推奨】非同期処理の完了は、テストフレームワークが提供する適切な待機メカニズム（例: Testing Library の `waitFor`, `findBy*` クエリ、Playwright の Auto-wait など）を用いて確認してください。
+    * **【避けるべきこと】** `waitFor` や明示的な待機処理なしに、非同期処理の結果を `expect(...).toBeNull()` のように記述して期待することは、テストの不安定性（Flaky Test）を招くため避けてください。
+* **テストの構造化 (`test.step`):**
+    * 【推奨】テストの論理的な区切りとして `test.step` を使用することは、特に長いテストケースにおいて有効ですが、視認性や安定性とのバランスを考慮してください。
+    * **【注意点】** テストを過度に `test.step` で細かく分割しすぎることは、かえってテスト全体の把握を困難にし、安定性を損なう可能性があるため注意してください。
+* **テストランナー:**
+    * 【推奨】新規コンポーネントや大規模変更には Vitest の利用を検討してください（Jest から移行中）。Vitest 設定 (`include`, `environment`, `globals`) を確認し、Jest 設定ファイルへの追記忘れにも注意してください。
+
+## 5. パフォーマンス
+
+アプリケーションの応答性を保つために、パフォーマンスへの配慮も重要です。
+
+* **配列アクセス:**
+    * 【推奨】状況に応じて `.at()` メソッドの利用を検討してください（可読性・速度）。（詳細は 1. を参照）
+* **不要な再レンダリングの防止:**
+    * 【推奨】`React.memo`, `useCallback`, `useMemo` を適切に使用してください。
+* **事前生成:**
+    * 【推奨】事前に生成可能なパターン（例: アクティブ/非アクティブ状態のスタイル）は、実行時ではなくビルド時などに生成することを検討してください。
+* **Debounce 処理:**
+    * 【推奨】頻繁に発生するイベント処理には、必要に応じて `debounce` を実装し、過剰な処理実行を防いでください（共通関数の利用も検討）。
+
+## 6. HTML の有効性とセマンティクス
+
+正しく、意味的に適切な HTML マークアップを心がけてください。
+
+* **適切な HTML 要素:**
+    * 【推奨】コンテンツの意味や役割に応じて、最も適切な HTML 要素を使用してください（例: `Textarea` を `<span>` で提供する必要がある場合など）。
+* **`<label>` 内の要素:**
+    * 【推奨】`<label>` 要素内には記述コンテンツ（Phrasing content）を配置してください。
+    * **【避けるべきこと】** `<label>` 要素内に見出し要素 (`<h1>`〜`<h6>`) などを配置することは、HTML の仕様上許可されていないため避けてください。
+* **`<form>` 要素:**
+    * 【検討】`<form className="shr-contents" />` のような使い方も検討の余地があります（ユースケースによる）。
+
+## 7. 国際化 (i18n)
+
+将来的な多言語対応の可能性も考慮してください。
+
+* **テキスト要素の変更可能性:**
+    * 【考慮】ラベルやメッセージなどのテキストは変更される可能性があることを念頭に置き、ハードコーディングを避け、将来的な翻訳対応がしやすい設計を心がけてください。
+
+## 8. ツールと設定
+
+開発体験とコード品質を維持するためのツール設定も重要です。
+
+* **テスト:**
+    * 【推奨】新規テストは Vitest での記述を検討してください。
+* **Tailwind CSS:**
+    * 【推奨】クラス名の自動ソートのために `prettier-plugin-tailwindcss` の導入を検討してください。
+
+## 9. Storybook
+
+Storybook は UI コンポーネントの開発、テスト、ドキュメンテーションにおいて重要なツールです。
+
+* **Story の作成:**
+    * 【推奨】コンポーネントの機能、状態、バリエーションが明確に理解できる、網羅的で分かりやすい Story を作成してください。Code タブでの見やすさも重要です。
+    * **【避けるべきこと】** Props の変化（例: `gap` の違い）が視覚的に分かりにくい Story は避けてください。複数のコンポーネントを並べるなど、違いが明確になるように工夫してください。
+* **Props の操作:**
+    * 【推奨】`argTypes` を適切に設定し、Controls アドオンから Props をインタラクティブに操作できるようにしてください（`Icon` コンポーネント参考）。
+* **非推奨 Props の表示:**
+    * 【推奨】Props が非推奨になった場合、Storybook 上でそれが明確に分かるように明示してください（例: Props 名を `'size （非推奨）'` のように変更する）。
+    * **【避けるべきこと】** 非推奨になった Props を、その旨を明示せずに Storybook に表示し続けることは避けてください。
+* **新規コンポーネント:**
+    * 【推奨】新しい Storybook の形式（CSF 3.0 など）での記述を検討してください。
+
+## 10. Tailwind CSS
+
+Tailwind CSS を使用する際のガイドラインです。（詳細は 1. も参照）
+
+* **ユーティリティクラスの活用:**
+    * 【推奨】Tailwind が提供するユーティリティクラスを効果的に活用してください。
+* **Variants:**
+    * 【推奨】コンポーネントの状態に応じたスタイル定義には、Tailwind Variants の `variants` 機能などを適切に使用してください。
+
+---
+
+これらのガイドラインを遵守し、より高品質で保守性の高いコードを目指しましょう。建設的で質の高いコードレビューへのご協力をお願いいたします。