AgentSkillsCN

frontend-dev

前端开发（React/TypeScript）的最佳实践与规范

SKILL.md
--- frontmatter
name: frontend-dev
description: フロントエンド開発（React/TypeScript）のベストプラクティスと規約

フロントエンドのコーディング規約

  • •コンポーネント設計: UI はコンポーネントベースで構築し、再利用可能な構造を保つ。
  • •状態管理: 状態管理は一元化し、コンポーネントは必要最小限のデータのみを購読する。UI 固有の状態はコンポーネント内部でカプセル化し、過剰なグローバル状態共有を避ける。
  • •ロジック分離: ビジネスロジックは DOM 操作から切り離し、データ駆動型の UI 更新を行う。
  • •キャッシュ戦略: クライアントキャッシュを活用し、リアルタイム更新が不要なデータはsessionStorageやlocalStorageで保持する。
  • •UX/UI:
    • •エラーメッセージは具体的で、ユーザーに理解と行動を促す内容とする。
    • •成功状態は過剰に通知せず、明確な視覚的フィードバックを重視する。

WCAG 2.2 準拠ガイドライン

本プロジェクトはアクセシビリティのベストプラクティスとして WCAG 2.2 レベル AA に準拠する。

実装チェックリスト

アクセシビリティ（WCAG 2.2 AA）

  • • すべての画像に適切な alt テキストがあるか？
  • • すべてのフォーム入力に label またはアリアラベルがあるか？
  • • キーボード操作で全機能が使用可能か？（Tab, Enter, Escape等）
  • • フォーカスが視認可能か？（outline, box-shadow等で確認）
  • • 色だけで情報が伝わっていないか？（コントラスト比確認）
  • • テキストと背景のコントラスト比が 4.5:1 以上か？
  • • 大きなテキストの場合、コントラスト比が 3:1 以上か？
  • • ホバー機能がフォーカス時にも提供されているか？
  • • フォーカストラップはないか？（モーダルでのEscキー対応等）
  • • aria-label, role 属性は正しく使用されているか？
  • • エラーメッセージが具体的で改善策を示しているか？

デザイン品質

  • • コンポーネントは小さく、単一責任になっているか
  • • useEffect の依存配列は正しいか
  • • メモ化（useMemo, useCallback）は適切に使用されているか
  • • レスポンシブデザインは崩れていないか
  • • 型定義（Props, State）は明示的か
  • • ハードコードされた文字列はなく、定数や設定ファイルを使用しているか

Serendie Design System の思想（循環・共創・ひらめき）の準拠

1. 視覚情報の優先順位と「つながり」の可視化

Serendieでは、情報のつながりを直感的に理解させることが求められます。

  • •

    リレーションの明示:

  • •

    チャットの発言を選択してサイドバーに反映する際、どの発言がどのトピックに統合されたかを、**「線（コネクタ）」や「共通のカラーアクセント」**で一時的に結びつけるなど、データが「循環」している様子を視覚化します。

  • •

    階層構造の平坦化:

  • •

    深いメニュー階層は避け、チャットとサイドバーが一つのキャンバスのようにシームレスに連携する「ボーダレス」な画面構成を維持します。

2. インタラクション：軽快さとフィードバック

ユーザーの操作に対して、システムが「生きている」ように反応させます。

  • •

    マイクロインタラクション:

  • •

    チャットをタップして選択した際、単に色が変わるだけでなく、**「ふわりと浮かび上がる」「サイドバーの方へわずかに吸い寄せられるような予感」**を感じさせる動きを取り入れます。

  • •

    ローディングの「期待感」:

  • •

    AIの要約中、単なる「ぐるぐる（Spinner）」を出すのではなく、**「データが編み上げられているような抽象的なアニメーション」**を用い、待ち時間を「価値が生成されている時間」へと変えます。

3. アクセシビリティと「色の役割」 (Serendie Colors)

Serendie独自のカラーパレットを活用しつつ、WCAG 2.2の基準を満たします。

  • •

    カラーパレットの活用:

  • •

    ベースカラーは「Serendie Gray」などの洗練された無彩色を使い、AIの提案や重要な更新には「Serendie Blue」などのアクセントカラーを効果的に配置します。

  • •

    非カラー情報の付与:

  • •

    「誰かが編集中（ロック）」の状態は、色を変えるだけでなく、**「すりガラス（Glassmorphism）越しに誰かが作業しているようなテクスチャ」**を加え、情報の透明性と排他制御を両立させます。

4. エディトリアル・デザイン（編集のしやすさ）

「人が手を加えてまたAIに戻す」という循環を支えるルールです。

  • •一貫した編集体験:
  • •AIが生成したテキストも、人間が書いたテキストも、全く同じタイポグラフィ（フォントサイズ・行間）で表示します。
  • •AI生成部分には「AIによるドラフト」という小さなバッジやアイコンを添え、**「人間が仕上げるのを待っている」**という未完成の美学を持たせます。

5. ロック（排他制御）の振る舞い

「セレンディ」＝「共創」を邪魔しないロックの仕方を定義します。

  • •ポジティブな制約:
  • •「触るな」という禁止ではなく、「◯◯さんが思考中」といったメッセージを添え、他者の作業をリスペクトさせるUIにします。
  • •3分タイマーも「カウントダウンで追い込む」のではなく、**「ゲージがゆっくりと満ちていく」**ような穏やかな表現で自動解除を伝えます。