{
  "feature": "form-design",
  "version": "1.0.0",
  "category": "ui",
  "description": "Design forms that are easy to scan and complete by organizing fields clearly, providing immediate feedback, handling errors gracefully, and minimizing cognitive load through smart defaults.\n",
  "rules": {
    "group_related_fields_logically": "Group related fields logically — use spacing and optional section headers to communicate field relationships",
    "labels_are_crucial_signals": "Labels are crucial signals — descriptive labels above or beside inputs (avoid placeholders as labels)",
    "provide_immediate_feedback": "Provide immediate feedback — validation feedback (errors, success, warnings) appears without additional steps",
    "smart_defaults_reduce_effort": "Smart defaults reduce effort — pre-fill when possible; use sensible defaults for optional fields",
    "error_messages_are_user_safe": "Error messages are user-safe — explain what went wrong and how to fix it, never expose system details",
    "dont_over_design_for_edge_cases": "Don't over-design for edge cases — handle common paths smoothly; edge cases can be addressed with help text"
  },
  "outcomes": {
    "form_presented_to_user": {
      "priority": 1,
      "given": [
        "form is presented to user"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "field_grouping",
          "value": "logically related fields grouped with spacing"
        },
        {
          "action": "set_field",
          "target": "label_placement",
          "value": "above input (mobile) or beside (desktop)"
        },
        {
          "action": "set_field",
          "target": "required_indicator",
          "value": "clear visual marker (asterisk, color, or text)"
        }
      ],
      "result": "form is scannable and user understands what's required"
    },
    "user_enters_invalid_data": {
      "priority": 2,
      "given": [
        "user enters invalid data in field"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "error_message",
          "value": "appears immediately (on blur or submit)"
        },
        {
          "action": "set_field",
          "target": "message_tone",
          "value": "helpful, not critical"
        },
        {
          "action": "set_field",
          "target": "message_content",
          "value": "states problem and solution"
        },
        {
          "action": "set_field",
          "target": "visual_indicator",
          "value": "red border, icon, or background"
        }
      ],
      "result": "user understands error and knows how to fix it"
    },
    "form_submission_successful": {
      "priority": 3,
      "given": [
        "form submission is successful"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "form.submission.success",
          "payload": [
            "confirmation_message",
            "redirect_or_next_step"
          ]
        },
        {
          "action": "set_field",
          "target": "feedback",
          "value": "clear success state (message, icon, animation)"
        }
      ],
      "result": "user confident that action completed"
    },
    "form_has_optional_conditional_fields": {
      "priority": 4,
      "given": [
        "form has optional or conditional fields"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "disclosure_strategy",
          "value": "progressive disclosure or clear grouping"
        },
        {
          "action": "set_field",
          "target": "conditional_logic",
          "value": "show/hide based on user input"
        }
      ],
      "result": "form doesn't overwhelm with unnecessary fields"
    },
    "form_is_long": {
      "priority": 5,
      "given": [
        "form is long (>5 fields)"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "organization",
          "value": "multi-step or grouped sections with visual breaks"
        },
        {
          "action": "set_field",
          "target": "progress_indicator",
          "value": "step count or progress bar if multi-step"
        }
      ],
      "result": "long form feels manageable and completion is visible"
    }
  },
  "fields": [
    {
      "name": "field_count",
      "type": "number",
      "label": "Number of input fields in form",
      "required": false
    },
    {
      "name": "required_fields",
      "type": "number",
      "label": "How many fields are required vs optional",
      "required": false
    },
    {
      "name": "error_handling_strategy",
      "type": "text",
      "label": "Real-time validation, on-blur, or on-submit",
      "required": false
    },
    {
      "name": "success_feedback",
      "type": "text",
      "label": "How success is communicated (message, redirect, animation)",
      "required": false
    },
    {
      "name": "conditional_fields",
      "type": "text",
      "label": "Fields that show/hide based on user input",
      "required": false
    }
  ],
  "tags": [
    "ui",
    "interaction-design",
    "user-experience"
  ],
  "related": [
    {
      "feature": "form-validation",
      "type": "required",
      "reason": "Forms require robust validation rules and error handling"
    },
    {
      "feature": "accessibility",
      "type": "required",
      "reason": "Forms must be keyboard-navigable with proper label/input associations"
    },
    {
      "feature": "visual-hierarchy",
      "type": "recommended",
      "reason": "Form hierarchy guides user through logical field progression"
    },
    {
      "feature": "error-handling",
      "type": "recommended",
      "reason": "Error states integrate with broader error handling system"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_form_design",
        "description": "Design forms that are easy to scan and complete by organizing fields clearly, providing immediate feedback, handling errors gracefully, and minimizing cognitive load through smart defaults.\n",
        "success_metrics": [
          {
            "metric": "success_rate",
            "target": ">= 99%",
            "measurement": "Successful operations divided by total attempts"
          },
          {
            "metric": "error_rate",
            "target": "< 1%",
            "measurement": "Failed operations divided by total attempts"
          }
        ],
        "constraints": []
      }
    ],
    "autonomy": {
      "level": "semi_autonomous"
    },
    "safety": {
      "action_permissions": [
        {
          "action": "form_presented_to_user",
          "permission": "autonomous"
        },
        {
          "action": "user_enters_invalid_data",
          "permission": "autonomous"
        },
        {
          "action": "form_submission_successful",
          "permission": "autonomous"
        },
        {
          "action": "form_has_optional_conditional_fields",
          "permission": "autonomous"
        },
        {
          "action": "form_is_long",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accessibility",
        "over": "aesthetics",
        "reason": "UI must be usable by all users including those with disabilities"
      }
    ],
    "coordination": {
      "protocol": "request_response",
      "consumes": [
        {
          "capability": "form_validation",
          "from": "form-validation",
          "fallback": "degrade"
        },
        {
          "capability": "accessibility",
          "from": "accessibility",
          "fallback": "degrade"
        }
      ]
    }
  }
}