{
  "id": "heading",
  "name": "Heading",
  "level": "atom",
  "status": "stable",
  "purpose": "The title ramp, from section headings to the display serif.",
  "description": "**Purpose.** Section / page title. `as` (h1-h6) is **required** — Heading refuses to guess a document outline level. Visual `size` (sm | md | lg | display) is independent of the rendered HTML level. Pick the level for the outline; pick the size for the visual rhythm.\n\n**Size guidance** (validated by `Foundations/Identity/Display Hierarchy`):\n\n| Size | font-size | tracking | When to use |\n|---|---|---|---|\n| `sm` | 20 px | tight (-0.01em) | Card titles, in-page section heads, dense content groups |\n| `md` | 24 px | compact (-0.015em) | Sub-section heads, MetricCard values, settings sub-pages where breadcrumb already locates the user |\n| `lg` | 30 px | snug (-0.022em) | **Default app page lead** — Settings overview, Dashboard, content section pages |\n| `display` | 48 px | hero (-0.03em) | **Empty pages, marketing surfaces, hero / lead areas** where the heading is the protagonist |\n\n**Why no `6xl` (60 px).** Tested against three real surfaces (Settings header, Empty page, Dashboard lead) under `Foundations/Identity/Display Hierarchy` and rejected — no real surface needed it. The ramp is deliberately short. Extend the surrounding composition before reaching for a bigger size.\n\n**Related**: `Foundations/Identity/Overview`, ADR-006.",
  "role": "content",
  "import": "@rrios-forge/ui/atoms/heading",
  "exports": [
    "Heading",
    "headingVariants",
    "HEADING_SIZES",
    "HEADING_TONES",
    "HEADING_WEIGHTS"
  ],
  "source": "packages/ui/src/atoms/heading",
  "axes": [
    {
      "axis": "size",
      "part": null,
      "values": [
        "sm",
        "md",
        "lg",
        "display"
      ],
      "default": "md",
      "meaning": "Ergonomic scale, in three families (control, text, container)."
    },
    {
      "axis": "weight",
      "part": null,
      "values": [
        "regular",
        "medium",
        "semibold"
      ],
      "default": "semibold",
      "meaning": "Type weight within the ramp."
    },
    {
      "axis": "tone",
      "part": null,
      "values": [
        "neutral",
        "muted",
        "inverse",
        "danger"
      ],
      "default": "neutral",
      "meaning": "Which semantic colour family the element speaks in."
    }
  ],
  "needs": [
    {
      "need": "Text / heading / helper / code / shortcut",
      "answer": "`Text` / `Heading` / `Description` / `Code` / `Kbd`"
    }
  ],
  "patterns": [],
  "a11yExceptions": [],
  "decisions": [
    {
      "id": "ADR-005",
      "title": "Visual operational rules: surfaces, interaction, motion"
    },
    {
      "id": "ADR-006",
      "title": "Geometry and typography signature"
    },
    {
      "id": "ADR-014",
      "title": "PageShell: Apple Mail / macOS Big Sur visual register"
    },
    {
      "id": "ADR-046",
      "title": "Markdown is painted with atoms, and apps fill its slots"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-atoms-heading--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-heading--playground",
      "frame": "/iframe.html?id=components-atoms-heading--playground&viewMode=story"
    },
    {
      "name": "Sizes",
      "id": "components-atoms-heading--sizes",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-heading--sizes",
      "frame": "/iframe.html?id=components-atoms-heading--sizes&viewMode=story"
    },
    {
      "name": "Levels",
      "id": "components-atoms-heading--levels",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-heading--levels",
      "frame": "/iframe.html?id=components-atoms-heading--levels&viewMode=story"
    },
    {
      "name": "Tones",
      "id": "components-atoms-heading--tones",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-heading--tones",
      "frame": "/iframe.html?id=components-atoms-heading--tones&viewMode=story"
    },
    {
      "name": "In context",
      "id": "components-atoms-heading--in-context",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-atoms-heading--in-context",
      "frame": "/iframe.html?id=components-atoms-heading--in-context&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/atoms/heading.stories.tsx"
}