{
  "id": "button",
  "name": "Button",
  "level": "atom",
  "status": "stable",
  "purpose": "The action a reader takes, from the one primary call to quiet secondary ones.",
  "description": "**Purpose.** The verb of the system — a control that *commits an action* with a side effect. Buttons are how users do things; they are not how users navigate.\n\n**When to use.**\n- Submit a form, save changes, confirm a dialog, run an operation.\n- Trigger a destructive action (`intent=\"danger\"`) where the consequence is reversible only by a counter-action.\n- Open a modal, panel or other in-product surface that the user is *staying* in (the URL does not change).\n\n**When NOT to use.**\n- The control changes the URL or opens an external page → use `Link`. Buttons break right-click, middle-click, history and crawlability.\n- The control is icon-only → use `IconButton`. It enforces square hit-area, focus ring and a required `aria-label`.\n- The control is part of a segmented set with persistent selection → use `Tabs` or a `RadioGroup` styled as a toolbar.\n\n**Composes with.**\n- `Icon` (decorative leading glyph) reinforces the label without replacing it.\n- `Spinner` is rendered automatically by the Button when `loading` is true; do not place a `Spinner` inside the children.\n- `Field`, `Dialog`, `FormSection` consume Button as the commit affordance; the Button never owns submit logic itself.\n\n**Accessibility.**\n- Renders a real `<button>` element; `Enter` and `Space` activate it; tab-order participates by default.\n- `loading` sets `aria-busy=\"true\"` and disables interaction without removing the focus ring; the label remains visible to screen readers.\n- `disabled` is exposed as the native attribute and removes the control from the tab sequence.\n- Icon-only Buttons are forbidden; the `Button` API requires text children (use `IconButton` instead).\n\n**Related patterns.**\n- `Patterns/Decision Matrix · ComponentChoice` — Button vs Link vs IconButton.\n- `Patterns/Visual Priority · ActionEmphasisLadder` — primary / secondary / quiet emphasis order on a surface.\n- `Patterns/Composition · CompositionChecklist` — how Button slots into Field, Dialog and FormSection.",
  "role": "action",
  "import": "@rrios-forge/ui/atoms/button",
  "exports": [
    "Button",
    "buttonVariants",
    "BUTTON_INTENTS",
    "BUTTON_EMPHASES",
    "BUTTON_VARIANTS",
    "BUTTON_SIZES"
  ],
  "source": "packages/ui/src/atoms/button",
  "axes": [
    {
      "axis": "emphasis",
      "part": null,
      "values": [
        "solid",
        "soft",
        "outline",
        "ghost"
      ],
      "default": "solid",
      "meaning": "How strongly a control or chip asserts itself, quiet to loud."
    },
    {
      "axis": "intent",
      "part": null,
      "values": [
        "primary",
        "secondary",
        "danger",
        "neutral"
      ],
      "default": "primary",
      "meaning": "What an action does."
    },
    {
      "axis": "size",
      "part": null,
      "values": [
        "sm",
        "md",
        "lg"
      ],
      "default": "md",
      "meaning": "Ergonomic scale, in three families (control, text, container)."
    }
  ],
  "needs": [
    {
      "need": "Primary CTA",
      "answer": "`Button intent=\"primary\" emphasis=\"solid\"`"
    },
    {
      "need": "Destructive action",
      "answer": "`Button intent=\"danger\" emphasis=\"solid\"`"
    },
    {
      "need": "Quiet secondary action",
      "answer": "`Button intent=\"neutral\" emphasis=\"ghost\"`"
    }
  ],
  "patterns": [
    "Patterns/Decision Matrix · ComponentChoice",
    "Patterns/Visual Priority · ActionEmphasisLadder",
    "Patterns/Composition · CompositionChecklist"
  ],
  "a11yExceptions": [],
  "decisions": [
    {
      "id": "ADR-002",
      "title": "Component variants live in `variants.ts` and export their option metadata"
    },
    {
      "id": "ADR-003",
      "title": "Storybook editorial convention and pattern↔component bidirectionality"
    },
    {
      "id": "ADR-005",
      "title": "Visual operational rules: surfaces, interaction, motion"
    },
    {
      "id": "ADR-006",
      "title": "Geometry and typography signature"
    },
    {
      "id": "ADR-017",
      "title": "Actionable components adopt the `asChild` slot pattern for framework-aware routing"
    },
    {
      "id": "ADR-019",
      "title": "Composer organism (message/post authoring surface)"
    },
    {
      "id": "ADR-022",
      "title": "The material family: `solid` and `vibrant`"
    },
    {
      "id": "ADR-028",
      "title": "The label is not the fill"
    },
    {
      "id": "ADR-030",
      "title": "Axis vocabulary: one name, one meaning"
    },
    {
      "id": "ADR-043",
      "title": "The default theme is monochrome"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-atoms-button--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--playground",
      "frame": "/iframe.html?id=components-atoms-button--playground&viewMode=story"
    },
    {
      "name": "In context",
      "id": "components-atoms-button--in-context",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--in-context",
      "frame": "/iframe.html?id=components-atoms-button--in-context&viewMode=story"
    },
    {
      "name": "Intents",
      "id": "components-atoms-button--intents",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--intents",
      "frame": "/iframe.html?id=components-atoms-button--intents&viewMode=story"
    },
    {
      "name": "Variants",
      "id": "components-atoms-button--variants",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--variants",
      "frame": "/iframe.html?id=components-atoms-button--variants&viewMode=story"
    },
    {
      "name": "Sizes",
      "id": "components-atoms-button--sizes",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--sizes",
      "frame": "/iframe.html?id=components-atoms-button--sizes&viewMode=story"
    },
    {
      "name": "Focus (keyboard)",
      "id": "components-atoms-button--focus-visible",
      "interaction": true,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--focus-visible",
      "frame": "/iframe.html?id=components-atoms-button--focus-visible&viewMode=story"
    },
    {
      "name": "States",
      "id": "components-atoms-button--states",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-button--states",
      "frame": "/iframe.html?id=components-atoms-button--states&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/atoms/button.stories.tsx"
}