{
  "component": {
    "id": "button",
    "name": "Button",
    "version": "2.1.0",
    "category": "actions",
    "description": "A versatile button component for user interactions and form submissions",
    "status": "stable",
    "a11y": {
      "wcag_level": "AA",
      "aria_support": true,
      "keyboard_navigable": true
    }
  },
  "metadata": {
    "last_updated": "2025-01-15",
    "maintainer": "Design System Team",
    "figma_url": "https://figma.com/file/abc123/button",
    "storybook_url": "https://storybook.company.com/?path=/docs/button",
    "source_code": "src/components/Button/Button.tsx"
  },
  "variants": {
    "appearance": {
      "type": "enum",
      "default": "primary",
      "options": [
        {
          "value": "primary",
          "description": "High emphasis actions",
          "use_case": "Main call-to-action on a page or form",
          "visual_weight": "high"
        },
        {
          "value": "secondary",
          "description": "Medium emphasis actions",
          "use_case": "Secondary actions or alternative paths",
          "visual_weight": "medium"
        },
        {
          "value": "tertiary",
          "description": "Low emphasis actions",
          "use_case": "Less important actions or inline controls",
          "visual_weight": "low"
        },
        {
          "value": "danger",
          "description": "Destructive actions",
          "use_case": "Delete, remove, or other irreversible actions",
          "visual_weight": "high"
        },
        {
          "value": "ghost",
          "description": "Minimal visual presence",
          "use_case": "Toolbar actions or subtle interactive elements",
          "visual_weight": "minimal"
        }
      ]
    },
    "size": {
      "type": "enum",
      "default": "medium",
      "options": [
        {
          "value": "small",
          "height": "32px",
          "padding": "0 12px",
          "font_size": "14px",
          "icon_size": "16px"
        },
        {
          "value": "medium",
          "height": "40px",
          "padding": "0 16px",
          "font_size": "16px",
          "icon_size": "20px"
        },
        {
          "value": "large",
          "height": "48px",
          "padding": "0 20px",
          "font_size": "18px",
          "icon_size": "24px"
        }
      ]
    },
    "width": {
      "type": "enum",
      "default": "auto",
      "options": [
        {
          "value": "auto",
          "description": "Width based on content"
        },
        {
          "value": "full",
          "description": "100% width of container"
        }
      ]
    }
  },
  "props": {
    "children": {
      "type": "ReactNode",
      "required": true,
      "description": "Button label text or content"
    },
    "onClick": {
      "type": "function",
      "required": false,
      "description": "Handler called when button is clicked",
      "signature": "(event: MouseEvent) => void"
    },
    "disabled": {
      "type": "boolean",
      "default": false,
      "description": "Disables button interaction"
    },
    "loading": {
      "type": "boolean",
      "default": false,
      "description": "Shows loading spinner and disables interaction"
    },
    "iconBefore": {
      "type": "ReactElement",
      "required": false,
      "description": "Icon displayed before label"
    },
    "iconAfter": {
      "type": "ReactElement",
      "required": false,
      "description": "Icon displayed after label"
    },
    "type": {
      "type": "enum",
      "default": "button",
      "options": ["button", "submit", "reset"],
      "description": "HTML button type attribute"
    },
    "ariaLabel": {
      "type": "string",
      "required": false,
      "description": "Accessible label for screen readers"
    },
    "testId": {
      "type": "string",
      "required": false,
      "description": "Data attribute for testing"
    }
  },
  "design_tokens": {
    "primary": {
      "background": {
        "default": "var(--color-brand-600)",
        "hover": "var(--color-brand-700)",
        "active": "var(--color-brand-800)",
        "disabled": "var(--color-neutral-200)"
      },
      "text": {
        "default": "var(--color-neutral-0)",
        "disabled": "var(--color-neutral-400)"
      },
      "border": {
        "default": "transparent",
        "focus": "var(--color-brand-600)"
      }
    },
    "secondary": {
      "background": {
        "default": "transparent",
        "hover": "var(--color-neutral-100)",
        "active": "var(--color-neutral-200)",
        "disabled": "transparent"
      },
      "text": {
        "default": "var(--color-neutral-900)",
        "disabled": "var(--color-neutral-400)"
      },
      "border": {
        "default": "var(--color-neutral-300)",
        "focus": "var(--color-brand-600)"
      }
    },
    "spacing": {
      "padding_horizontal": {
        "small": "var(--spacing-3)",
        "medium": "var(--spacing-4)",
        "large": "var(--spacing-5)"
      },
      "gap_icon": "var(--spacing-2)"
    },
    "typography": {
      "font_family": "var(--font-family-body)",
      "font_weight": "var(--font-weight-semibold)",
      "line_height": "var(--line-height-tight)"
    },
    "border_radius": "var(--radius-md)",
    "focus_ring": {
      "width": "2px",
      "offset": "2px",
      "color": "var(--color-brand-600)"
    },
    "transition": {
      "duration": "150ms",
      "timing": "ease-in-out"
    }
  },
  "states": {
    "default": {
      "description": "Initial resting state",
      "cursor": "pointer"
    },
    "hover": {
      "description": "Mouse over state",
      "triggers": ["mouseenter"],
      "visual_changes": ["background", "elevation"]
    },
    "active": {
      "description": "Pressed/clicked state",
      "triggers": ["mousedown", "touch"],
      "visual_changes": ["background", "transform"]
    },
    "focus": {
      "description": "Keyboard focus state",
      "triggers": ["keyboard_navigation", "tab"],
      "visual_changes": ["focus_ring"],
      "a11y_required": true
    },
    "disabled": {
      "description": "Non-interactive state",
      "cursor": "not-allowed",
      "visual_changes": ["background", "text_color", "opacity"],
      "aria_disabled": true
    },
    "loading": {
      "description": "Processing state",
      "cursor": "wait",
      "visual_changes": ["spinner", "opacity"],
      "aria_busy": true
    }
  },
  "interactions": {
    "click": {
      "handler": "onClick",
      "keyboard_equivalent": ["Enter", "Space"],
      "touch_target_size": "44px"
    },
    "keyboard": {
      "focusable": true,
      "tab_order": "natural",
      "shortcuts": []
    }
  },
  "responsive_behavior": {
    "mobile": {
      "min_touch_target": "44px",
      "recommended_size": "medium",
      "full_width_recommended": true
    },
    "tablet": {
      "recommended_size": "medium"
    },
    "desktop": {
      "recommended_size": "medium",
      "max_width": "320px"
    }
  },
  "usage_guidelines": {
    "do": [
      "Use primary buttons for the main action on a page",
      "Provide clear, action-oriented labels (e.g., 'Save changes', not 'OK')",
      "Limit to one primary button per section",
      "Ensure sufficient color contrast for accessibility",
      "Use loading state for async operations"
    ],
    "dont": [
      "Use multiple primary buttons in close proximity",
      "Use generic labels like 'Click here'",
      "Disable buttons without explanation",
      "Use buttons for navigation (use links instead)",
      "Make destructive actions too easy to trigger"
    ]
  },
  "examples": [
    {
      "name": "Primary action",
      "code": "<Button appearance=\"primary\">Save changes</Button>",
      "use_case": "Form submission or primary page action"
    },
    {
      "name": "With icon",
      "code": "<Button appearance=\"primary\" iconBefore={<AddIcon />}>Add item</Button>",
      "use_case": "Actions that benefit from visual reinforcement"
    },
    {
      "name": "Loading state",
      "code": "<Button appearance=\"primary\" loading>Processing...</Button>",
      "use_case": "Async operations like API calls"
    },
    {
      "name": "Full width mobile",
      "code": "<Button appearance=\"primary\" width=\"full\">Continue</Button>",
      "use_case": "Mobile forms or CTAs"
    },
    {
      "name": "Destructive action",
      "code": "<Button appearance=\"danger\">Delete account</Button>",
      "use_case": "Irreversible or dangerous actions"
    }
  ],
  "composition_patterns": {
    "button_group": {
      "description": "Multiple related buttons",
      "spacing": "var(--spacing-2)",
      "alignment": "right",
      "example": "Save and Cancel buttons"
    },
    "split_button": {
      "description": "Primary action with dropdown menu",
      "components": ["Button", "Dropdown"],
      "example": "Send with options menu"
    },
    "icon_button": {
      "description": "Button with only an icon",
      "requires": ["ariaLabel"],
      "min_size": "32px",
      "example": "Close, menu, or action buttons"
    }
  },
  "testing": {
    "unit_tests": [
      "Renders with correct text",
      "Calls onClick when clicked",
      "Applies disabled state correctly",
      "Shows loading spinner when loading",
      "Applies correct variant styles"
    ],
    "a11y_tests": [
      "Has accessible name",
      "Keyboard navigable",
      "Focus visible",
      "Color contrast meets WCAG AA",
      "Announces state changes to screen readers"
    ],
    "visual_regression": [
      "All appearance variants",
      "All size variants",
      "All interactive states",
      "With and without icons",
      "Loading state"
    ]
  },
  "analytics": {
    "trackable_events": [
      {
        "event": "button_click",
        "properties": ["appearance", "label", "location"]
      },
      {
        "event": "button_loading",
        "properties": ["duration", "success"]
      }
    ]
  },
  "dependencies": {
    "required": [],
    "optional": [
      {
        "component": "Spinner",
        "use": "Loading state"
      },
      {
        "component": "Icon",
        "use": "Icon variants"
      }
    ]
  },
  "ai_metadata": {
    "semantic_purpose": "interactive_control",
    "intent_keywords": ["action", "submit", "click", "interact", "trigger"],
    "generation_hints": {
      "label_should_be": "action-oriented verb phrase",
      "context_aware_appearance": {
        "destructive_actions": "danger",
        "primary_flow": "primary",
        "optional_actions": "secondary"
      },
      "icon_suggestions": {
        "add": "plus icon before",
        "delete": "trash icon before",
        "submit": "checkmark icon before",
        "next": "arrow icon after"
      }
    },
    "natural_language_mappings": [
      {
        "phrase": "save button",
        "maps_to": {
          "appearance": "primary",
          "children": "Save",
          "type": "submit"
        }
      },
      {
        "phrase": "cancel link",
        "maps_to": {
          "appearance": "ghost",
          "children": "Cancel"
        }
      },
      {
        "phrase": "delete button",
        "maps_to": {
          "appearance": "danger",
          "children": "Delete"
        }
      }
    ]
  }
}