building-forms

フォームシステムと入力パターン

体系的なコンポーネント選択、検証戦略、UX のベストプラクティスを活用して、アクセシブルで使いやすいフォームを構築します。

目的

フォームは、Web アプリケーションでユーザーデータを入力するための主要な仕組みです。このスキルでは、以下について体系的な指針を提供します。

• データ要件に基づいて適切な入力タイプを選択する
• ユーザーエクスペリエンスを向上させる検証戦略を実装する
• WCAG 2.1 AA のアクセシビリティ要件への準拠を確保する
• 複雑なパターン（マルチステップウィザード、条件付きフィールド、動的フォーム）を作成する

このスキルを使う場面

トリガー：

• お問い合わせフォーム、ログイン／登録フロー、購入手続きを構築する
• アンケート、質問票、設定ページを実装する
• ユーザー入力に検証を追加する
• マルチステップのワークフローやウィザードを作成する
• フォームのアクセシビリティを確保する
• 構造化データ（住所、クレジットカード、日付）を収集する

よくある依頼：

• 「検証機能付きの登録フォームを作成して」
• 「マルチステップの購入フローを構築して」
• 「メールアドレス入力にインライン検証を追加して」
• 「スクリーンリーダーで使えるフォームにして」
• 「条件付きの質問があるアンケートを実装して」

フォームの基本概念

コンポーネント選択フレームワーク

基本原則： データ型 → 入力コンポーネント → 検証パターン

収集するデータ型を特定してから、適切なコンポーネントを選択します。

クイックリファレンス：

• 短いテキスト（100 文字未満）→ テキスト入力、メール入力、パスワード入力
• 長いテキスト（100 文字超）→ テキストエリア、リッチテキストエディター、コードエディター
• 数値 → 数値入力、通貨入力、スライダー
• 日付／時刻 → 日付ピッカー、時刻ピッカー、日付範囲ピッカー
• ブール値 → チェックボックス、トグルスイッチ
• 単一選択 → ラジオボタングループ（2〜7 個の選択肢）、セレクトドロップダウン（7 個超の選択肢）、オートコンプリート（15 個超の選択肢）
• 複数選択 → チェックボックスグループ、複数選択、タグ入力
• ファイル／メディア → ファイルアップロード、画像アップロード
• 構造化データ → 住所入力、クレジットカード入力、電話番号入力

詳細な判断ツリー： references/decision-tree.md を参照してください。

検証タイミングの戦略

推奨されるデフォルト：フォーカス喪失時に検証し、段階的に拡張する

Field pristine (never touched): No validation
User typing: No errors shown
On blur (field loses focus): Validate and show errors
After first error: Switch to onChange for that field
On fix: Show success immediately

検証モード：

1. 送信時 - フォームの送信時に検証します（シンプルなフォーム向け）
2. フォーカス喪失時 - フィールドからフォーカスが外れたときに検証します（ほとんどのフォームに推奨）
3. 変更時 - ユーザーの入力中に検証します（パスワード強度、利用可能状況の確認）
4. デバウンス - ユーザーの入力が止まった後に検証します（API ベースの検証）
5. 段階的 - フォーカス喪失時の検証から始め、最初のエラーが発生した後は変更時の検証に切り替えます

検証の完全ガイド： references/validation-concepts.md を参照してください。

アクセシビリティ要件（WCAG 2.1 AA）

重要なアクセシビリティパターン：

ラベルと説明：

• すべての入力には、関連付けられた <label> または aria-label が必要です
• ラベルは視認でき、説明的である必要があります
• 必須フィールドは明確に示します（色だけで示さないでください）
• ラベルの代わりにプレースホルダーテキストを使わないでください
• 複雑な入力にはヘルプテキストを提供します

キーボード操作：

• 論理的で順序立ったタブ移動順序にします
• すべての入力をキーボードで操作できるようにします
• カスタムコンポーネントは矢印キーに対応させます
• Escape キーでモーダルやポップオーバーを閉じられるようにします
• フォーカスを視認できるようにします（アウトラインまたはカスタムインジケーター）

エラー処理：

• エラーをプログラムで入力に関連付けます（aria-describedby）
• エラーメッセージは明確で、対処方法が分かるようにします
• スクリーンリーダーがエラーを通知するようにします（aria-live）
• 送信時に最初のエラーへフォーカスを移動します
• 色だけでエラーを伝えないでください

ARIA 属性：

• 必須フィールドには aria-required="true" を指定します
• 検証に失敗したときは aria-invalid="true" を指定します
• ヘルプテキスト／エラーテキストへの関連付けには aria-describedby を使用します
• 関連する入力には role="group" を使用します
• 検証メッセージには aria-live="polite" を使用します

アクセシビリティの完全なチェックリスト： references/accessibility-forms.md を参照してください。

UX のベストプラクティス

最新のフォーム UX の原則（2024～2025年）：

1. 段階的な情報開示 - 最初は必須項目のみを表示し、高度なオプションは必要に応じて表示します
2. スマートなデフォルト値 - 既知の情報を事前入力し、コンテキストに基づいて値を提案します
3. 肯定的なフィードバックを伴うインライン検証 - 入力が有効な場合は緑色のチェックマークを表示し、役立つエラーメッセージを提示します
4. モバイルファースト - タッチ領域を大きくし（最小44px）、適切なキーボードタイプを使用します
5. 認知負荷の軽減 - 関連する項目をグループ化し、わかりやすいラベルを使い、入力例を提示します
6. エラーの防止 - 制約によって無効な入力を防ぎ、オートコンプリートによって誤入力を減らします
7. 自動保存と復元 - 下書きの状態を自動的に保存し、データを失う前に警告します

詳しい UX パターンについては、こちらをご覧ください： references/ux-patterns.md

エラーメッセージのベストプラクティス

優れたエラーメッセージの構成：

1. 何が問題か - 「メールアドレスが無効です」
2. なぜ必要か - 「領収書の送付に必要です」
3. 修正方法 - 「形式：[email protected]」

例：

❌ 悪い例： 「入力が無効です」 ✅ 良い例： 「メールアドレスには @ 記号が必要です（例：[email protected]）」

❌ 悪い例： 「エラー」 ✅ 良い例： 「パスワードは8文字以上で入力してください」

❌ 悪い例： 「必須項目です」 ✅ 良い例： 「注文確認をお送りするため、メールアドレスを入力してください」

トーンに関するガイドライン：

• ロボットのようではなく、会話調にします
• 非難するのではなく、役立つ表現にします
• 一般的ではなく、具体的にします
• 説明だけでなく、次の行動を示します

言語別の実装

このスキルでは、上記の汎用的なフォームの概念と、以下の言語別の実装を提供します。

JavaScript/React（主要）

推奨スタック：

• React Hook Form - フォーム状態の管理（最高のパフォーマンス、バンドルサイズ8KB）
• Zod - TypeScript を第一に考えたスキーマ検証
• Radix UI または React Aria - アクセシブルなコンポーネントプリミティブ

クイックスタート：

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';

// Define validation schema
const schema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

type FormData = z.infer<typeof schema>;

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
    resolver: zodResolver(schema),
    mode: 'onBlur', // Validate on blur (recommended)
  });

  const onSubmit = (data: FormData) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label htmlFor="email">Email</label>
      <input id="email" {...register('email')} type="email" />
      {errors.email && <span role="alert">{errors.email.message}</span>}

      <label htmlFor="password">Password</label>
      <input id="password" {...register('password')} type="password" />
      {errors.password && <span role="alert">{errors.password.message}</span>}

      <button type="submit">Login</button>
    </form>
  );
}

JavaScript/React の詳しいドキュメント：

• references/javascript/react-hook-form.md - React Hook Form の完全ガイド
• references/javascript/zod-validation.md - Zod のスキーマ検証パターン
• references/javascript/examples/ - 動作するコード例

Python（主要）

推奨スタック：

• Pydantic - データ検証と設定管理（実行時検証、型安全）
• FastAPI - 自動検証機能を備えた最新の非同期 Web フレームワーク
• WTForms - Flask/Django のフォーム処理（従来型のフレームワークを使用する場合）

クイックスタート（FastAPI + Pydantic）：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr, Field, validator

app = FastAPI()

# Define validation schema
class LoginForm(BaseModel):
    email: EmailStr  # Validates email format
    password: str = Field(..., min_length=8, description="Password must be at least 8 characters")

    @validator('password')
    def validate_password_strength(cls, v):
        if not any(char.isdigit() for char in v):
            raise ValueError('Password must contain at least one number')
        if not any(char.isupper() for char in v):
            raise ValueError('Password must contain at least one uppercase letter')
        return v

@app.post("/api/login")
async def login(form_data: LoginForm):
    # Pydantic automatically validates incoming data
    # If validation fails, returns 422 with error details
    return {"message": "Login successful", "email": form_data.email}

# Example error response (automatic):
# {
#   "detail": [
#     {
#       "loc": ["body", "email"],
#       "msg": "value is not a valid email address",
#       "type": "value_error.email"
#     }
#   ]
# }

Python の詳しいドキュメント：

• references/python/pydantic-forms.md - Pydantic の検証パターン
• references/python/wtforms.md - Flask/Django 向け WTForms
• references/python/examples/ - 動作するコード例

Rust（今後対応予定）

予定しているライブラリ：

• validator - 構造体フィールドの検証
• Leptos / Yew - リアクティブ Web フレームワーク

Rust の実装は必要に応じて追加されます。

Go（今後対応予定）

予定しているライブラリ：

• Templ - 型安全な HTML テンプレート
• html/template - 標準ライブラリのテンプレート

Go の実装は必要に応じて追加されます。

コンポーネントの階層

ティア1：基本的な入力コンポーネント

テキストベース：

• テキストフィールド（1行）
• テキストエリア（複数行）
• メール入力（検証付き）
• パスワード入力（表示切り替え付き）
• 数値入力（ステップ操作付き）
• 電話番号入力（書式設定付き）
• URL 入力（プロトコル検証付き）
• 検索入力（クリアボタン付き）

選択：

• ラジオボタングループ（2～7個のオプション）
• チェックボックス（真偽値または複数選択）
• トグルスイッチ（明確なオン／オフ状態）
• セレクトドロップダウン（多数のオプション）
• 複数選択（複数の項目を選択）

日付と時刻：

• 日付ピッカー（カレンダーインターフェース）
• 時刻ピッカー（時／分）
• 日付範囲ピッカー（開始日と終了日）
• 日時ピッカー（日付と時刻の組み合わせ）

Tier 2：リッチ入力コンポーネント

高度な選択：

• オートコンプリート／コンボボックス（入力して絞り込み）
• タグ入力（複数のタグ）
• 転送リスト（リスト間で項目を移動）
• リストボックス（キーボードで操作可能）

特化型：

• カラーピッカー（16 進数、RGB、HSL）
• ファイルアップローダー（単一、複数、ドラッグ＆ドロップ）
• 画像アップローダー（トリミング、サイズ変更、プレビュー）
• スライダー／範囲（単一または範囲）
• 評価入力（星、数値、絵文字）
• リッチテキストエディター（書式設定、メディア）
• コードエディター（構文ハイライト）
• Markdown エディター（プレビュー、ツールバー）

構造化データ：

• 住所入力（複数のフィールド）
• クレジットカード入力（書式設定）
• 電話番号（国際形式）
• 通貨入力（通貨記号、小数）

Tier 3：複雑なフォームパターン

複数ステップのフォーム：

• 直線型ウィザード（ステップ 1 → 2 → 3）
• 分岐型ウィザード（条件付きステップ）
• 進行状況インジケーター
• 保存して再開（下書き状態）
• 確認して送信するページ

動的フォーム：

• 条件付きフィールド（表示／非表示）
• 繰り返しセクション（追加／削除）
• フィールド配列（動的リスト）
• ネストされたフォーム（複雑なオブジェクト）

高度なパターン：

• インライン編集（クリックして編集）
• 一括編集（複数のレコード）
• 自動保存（定期的または変更時）
• 楽観的更新
• 元に戻す／やり直し機能

デザイントークンとの統合

すべてのフォームコンポーネントは、ビジュアルスタイル設定に design-tokens スキルを使用し、テーマの切り替え（ライト／ダーク／ハイコントラスト／カスタムブランド）を可能にします。

主なトークンカテゴリ：

• 色 - 入力欄の背景、境界線、テキスト、エラー／成功状態
• 余白 - パディング、フィールド間の間隔、ラベルのマージン
• タイポグラフィ - 入力欄、ラベル、エラーのフォントサイズと太さ
• 境界線 - 境界線の幅、角丸、フォーカスリング
• シャドウ - フォーカスインジケーター、エレベーション

参照： テーマ設定の詳細については、skills/design-tokens/ をご覧ください。

一般的な使用例

お問い合わせフォーム

// Basic contact form with validation
// See: references/javascript/examples/basic-form.tsx

登録フロー

// Multi-step registration with password strength
// See: references/javascript/examples/multi-step-wizard.tsx

インライン検証

// Real-time validation with debouncing
// See: references/javascript/examples/inline-validation.tsx

条件付きロジックを使ったアンケート

// Dynamic form with conditional fields
// See: references/javascript/examples/conditional-form.tsx

設定ページ

// Mixed input types with autosave
// See: references/javascript/examples/settings-form.tsx

簡単な選択ガイド

質問：どの入力を使えばよいですか？ → 完全な決定木については、references/decision-tree.md をご覧ください

質問：いつ検証すればよいですか？ → フォーカスが外れたときに検証し、段階的に強化します（最初のエラー後は変更時にも検証） → すべての戦略については、references/validation-concepts.md をご覧ください

質問：フォームをアクセシブルにするにはどうすればよいですか？ → セマンティック HTML を使い、すべての入力にラベルを付け、キーボード操作に対応します → WCAG 2.1 のチェックリストについては、references/accessibility-forms.md をご覧ください

質問：複雑な検証はどのように処理すればよいですか？ → スキーマ検証を使います（TypeScript では Zod、JavaScript では Yup） → パターンについては、references/javascript/zod-validation.md をご覧ください

質問：複数ステップのフォームはどのように構築すればよいですか？ → 進行状況の追跡を伴う状態管理を使います → references/javascript/examples/multi-step-wizard.tsx をご覧ください

ベストプラクティスのまとめ

1. セマンティック HTML から始める - 可能な限りネイティブの <input>、<select>、<textarea> を使う
2. すべてにラベルを付ける - すべての入力に、表示される分かりやすいラベルが必要です
3. フォーカスが外れたときに検証する - ほとんどのフォームで最適な UX のバランスです
4. 役立つエラーを表示する - 何が問題なのか、どう修正すればよいのかを説明する
5. キーボード操作に対応する - Tab 順序、矢印キー、Escape キーによる閉じる操作
6. モバイルファースト - 大きなタッチターゲット、適切なキーボード
7. 段階的開示 - すべてのフィールドを一度に表示して、ユーザーを圧倒しない
8. 可能な限り自動保存する - データの損失を防ぐ
9. スクリーンリーダーでテストする - ARIA 属性が正しく機能することを確認する
10. デザイントークンを使う - 一貫したスタイル設定とテーマ対応

追加リソース

• references/decision-tree.md - コンポーネント選択の完全なフレームワーク
• references/validation-concepts.md - すべての検証戦略とパターン
• references/accessibility-forms.md - WCAG 2.1 AA 準拠チェックリスト
• references/ux-patterns.md - 最新のフォーム UX のベストプラクティス
• references/javascript/ - JavaScript／React の実装ガイド