---
name: defining-form-specs
description: Defines form field specifications including validation rules, error states, and submission behavior. Updates the "フォーム仕様" section in screen spec.md.
allowed-tools: [Read, Write, Glob, mcp__figma__get_screenshot, mcp__figma__get_design_context, mcp__figma__get_metadata]
---

# Form Specification Skill

フォームフィールドの仕様（バリデーションルール、エラー状態、送信動作）を定義するスキルです。

## 目次

1. [概要](#概要)
2. [適用条件](#適用条件)
3. [クイックスタート](#クイックスタート)
4. [詳細ガイド](#詳細ガイド)
5. [出力形式](#出力形式)

## 概要

このスキルは以下のタスクをサポートします：

1. **フィールド定義**: 入力フィールドの型、必須/任意、制約
2. **バリデーションルール**: 形式、文字数、範囲等の検証ルール
3. **エラーメッセージ**: 各バリデーションエラー時のメッセージ
4. **バリデーションタイミング**: リアルタイム/onBlur/onSubmit
5. **送信動作**: フォーム送信時の挙動

## 禁止事項

**以下は絶対に行わないこと：**
- 実装コードの生成（React Hook Form/Zod等）
- バリデーションライブラリの提案
- 技術スタック固有の実装詳細

このスキルの目的は「フォームの仕様」の**情報整理のみ**です。

## 適用条件

このスキルは**入力フォームがある画面**にのみ適用します。

### 適用する画面の例

- ログイン/会員登録フォーム
- プロフィール編集
- 検索フォーム（複雑な条件入力）
- お問い合わせフォーム
- 設定画面（入力あり）
- データ入力/編集画面

### 適用しない画面の例

- 一覧表示のみの画面
- 詳細表示のみの画面
- ダッシュボード（入力なし）

**入力フォームがない場合**、spec.md のフォーム仕様セクションに「該当なし」と記載します。

## 出力先

このスキルは**画面仕様書（spec.md）の「フォーム仕様」セクション**を更新します。

```
.outputs/{screen-id}/
├── spec.md                 # ← このスキルが「フォーム仕様」セクションを更新
├── index.html              # 参照用HTML
└── assets/
```

## クイックスタート

### 基本的な使い方

```
以下のFigma画面のフォーム仕様を定義してください：
https://figma.com/design/XXXXX/Project?node-id=1234-5678
```

エージェントは自動的に：
1. 入力フィールドを検出
2. フィールド属性を整理
3. バリデーションルールを推測/文書化
4. **spec.md の「フォーム仕様」セクションを更新**

## 詳細ガイド

詳細な情報は以下のファイルを参照してください：

- **[workflow.md](references/workflow.md)**: フォーム仕様定義のワークフロー
- **[validation-patterns.md](references/validation-patterns.md)**: 一般的なバリデーションパターン
- **[section-template.md](references/section-template.md)**: セクション出力テンプレート

## Workflow

フォーム仕様定義時にこのチェックリストをコピー：

```
Form Specification Progress:
- [ ] Step 0: spec.md の存在確認
- [ ] Step 1: 入力フィールドを検出
- [ ] Step 2: フィールド属性を整理
- [ ] Step 3: バリデーションルールを定義
- [ ] Step 4: エラーメッセージを定義
- [ ] Step 5: バリデーションタイミングを決定
- [ ] Step 6: 送信動作を定義
- [ ] Step 7: spec.md の「フォーム仕様」セクションを更新
```

### Step 0: spec.md の存在確認

```bash
ls .outputs/{screen-id}/spec.md
```

### Step 1: 入力フィールドを検出

HTMLまたはFigmaから以下を抽出：

- `<input>` 各種（text, email, password, number, tel, date等）
- `<textarea>`
- `<select>` / ドロップダウン
- チェックボックス / ラジオボタン
- トグルスイッチ
- ファイルアップロード
- カスタム入力コンポーネント

### Step 2: フィールド属性を整理

各フィールドについて：

| 属性 | 説明 |
|------|------|
| フィールド名 | 表示ラベル |
| フィールドID | 識別子 |
| 入力タイプ | text/email/password/number等 |
| 必須/任意 | required or optional |
| 初期値 | デフォルト値 |
| プレースホルダー | 入力ヒント |
| 最大文字数 | maxlength |
| 入力マスク | 電話番号、日付等のフォーマット |

### Step 3: バリデーションルールを定義

各フィールドのバリデーションルール：

- **形式**: メール、URL、電話番号等
- **文字数**: 最小/最大文字数
- **範囲**: 数値の最小/最大値
- **パターン**: 正規表現
- **依存関係**: 他フィールドとの関係
- **カスタムルール**: ビジネスロジック固有

### Step 4: エラーメッセージを定義

各バリデーションエラーに対するメッセージ：

| ルール | エラーメッセージ |
|--------|-----------------|
| 必須 | 「{フィールド名}を入力してください」 |
| 形式 | 「有効な{形式}を入力してください」 |
| 文字数（最小） | 「{N}文字以上で入力してください」 |
| 文字数（最大） | 「{N}文字以内で入力してください」 |

### Step 5: バリデーションタイミングを決定

| タイミング | 説明 | 適用例 |
|-----------|------|--------|
| onChange | 入力のたびに検証 | 文字数カウント |
| onBlur | フォーカス離脱時に検証 | 形式チェック |
| onSubmit | 送信時に検証 | 全フィールド最終チェック |
| debounced | 入力停止後に検証 | 重複チェック（API） |

### Step 6: 送信動作を定義

- 送信ボタンの活性/非活性条件
- 送信中の状態（loading）
- 成功時の挙動
- 失敗時の挙動
- 再送信の可否

### Step 7: spec.md の「フォーム仕様」セクションを更新

1. セクションを特定（`## フォーム仕様`）
2. ステータスを「完了 ✓」に更新
3. `{{FORM_SPECS_CONTENT}}` を内容に置換
4. 完了チェックリストを更新
5. 変更履歴に追記

## 出力形式

### spec.md「フォーム仕様」セクションの内容

```markdown
## フォーム仕様

> **ステータス**: 完了 ✓  
> **生成スキル**: defining-form-specs  
> **更新日**: 2024-01-15

### フォーム概要

| 項目 | 値 |
|------|-----|
| フォーム名 | ユーザー登録フォーム |
| フィールド数 | 5 |
| 必須フィールド数 | 3 |

### フィールド一覧

| フィールド | 型 | 必須 | 最大文字数 | 備考 |
|-----------|-----|:----:|-----------|------|
| メールアドレス | email | ✓ | 254 | - |
| パスワード | password | ✓ | 128 | 8文字以上 |
| パスワード確認 | password | ✓ | 128 | パスワードと一致 |
| ニックネーム | text | - | 20 | - |
| 利用規約同意 | checkbox | ✓ | - | - |

### フィールド詳細

#### メールアドレス

| 項目 | 値 |
|------|-----|
| フィールドID | email |
| 入力タイプ | email |
| 必須 | ✓ |
| プレースホルダー | example@email.com |
| バリデーション | RFC 5322準拠、最大254文字 |
| エラーメッセージ | 有効なメールアドレスを入力してください |
| バリデーションタイミング | onBlur |

#### パスワード

| 項目 | 値 |
|------|-----|
| フィールドID | password |
| 入力タイプ | password |
| 必須 | ✓ |
| プレースホルダー | 8文字以上の英数字 |
| バリデーション | 8文字以上、英字と数字を含む |
| エラーメッセージ | パスワードは8文字以上で英数字を含めてください |
| バリデーションタイミング | onBlur |
| 追加機能 | パスワード表示トグル、強度インジケーター |

### バリデーションルール

| フィールド | ルール | 条件 | エラーメッセージ |
|-----------|--------|------|-----------------|
| メールアドレス | required | - | メールアドレスを入力してください |
| メールアドレス | format | RFC 5322 | 有効なメールアドレスを入力してください |
| メールアドレス | maxLength | 254 | メールアドレスは254文字以内で入力してください |
| パスワード | required | - | パスワードを入力してください |
| パスワード | minLength | 8 | パスワードは8文字以上で入力してください |
| パスワード | pattern | /^(?=.*[A-Za-z])(?=.*\d)/ | パスワードは英数字を含めてください |
| パスワード確認 | required | - | パスワード確認を入力してください |
| パスワード確認 | match | password | パスワードが一致しません |

### バリデーションタイミング

| タイミング | 対象フィールド |
|-----------|---------------|
| onChange | - |
| onBlur | メールアドレス、パスワード、パスワード確認、ニックネーム |
| onSubmit | 全フィールド |
| debounced (500ms) | メールアドレス（重複チェック） |

### 送信動作

| 項目 | 値 |
|------|-----|
| 送信ボタン | 登録する |
| 活性条件 | 必須フィールド入力済み & エラーなし |
| 送信中 | ボタン非活性 + ローディング表示 |
| 成功時 | 確認メール送信完了画面へ遷移 |
| 失敗時 | エラーメッセージ表示、フォーム維持 |
| 再送信 | エラー解消後に可能 |

### 特記事項

- メールアドレスの重複チェックはAPI経由で実行
- パスワード強度インジケーター: 弱/中/強の3段階
- 利用規約リンクは別タブで開く
```

## 完了チェックリスト

生成後、以下を確認：

```
- [ ] spec.md の「フォーム仕様」セクションが更新されている
- [ ] ステータスが「完了 ✓」になっている
- [ ] 全ての入力フィールドがリストされている
- [ ] バリデーションルールが明確
- [ ] エラーメッセージが定義されている
- [ ] バリデーションタイミングが決定されている
- [ ] 送信動作が定義されている
- [ ] 完了チェックリストが更新されている
- [ ] 変更履歴に記録が追加されている
```

## フォームがない場合

入力フォームがない画面の場合、以下のように記載：

```markdown
## フォーム仕様

> **ステータス**: 該当なし  
> **生成スキル**: defining-form-specs  
> **更新日**: 2024-01-15

この画面には入力フォームがありません。
```

## 注意事項

### 他のセクションを変更しない

このスキルは「フォーム仕様」セクションのみを更新します。

### バリデーションルールの推測

Figmaデザインからバリデーションルールが明確でない場合：

1. フィールドタイプから一般的なルールを推測
2. 「要確認」として明示
3. 設計者/PMへの確認事項としてリスト

### extracting-interactions との違い

| 観点 | extracting-interactions | defining-form-specs |
|------|------------------------|---------------------|
| 対象 | 全インタラクティブ要素 | フォームフィールドのみ |
| 内容 | 状態変化、トランジション | バリデーション、送信動作 |
| 重複 | focus/error状態 | バリデーションルール詳細 |

フィールドのfocus/error状態は両方で扱いますが、観点が異なります。

## 参照

- **[workflow.md](references/workflow.md)**: 詳細なワークフロー
- **[validation-patterns.md](references/validation-patterns.md)**: バリデーションパターン集
- **[section-template.md](references/section-template.md)**: セクション出力テンプレート
- **[managing-screen-specs](../managing-screen-specs/SKILL.md)**: 仕様書管理スキル