{
  "id": "nav-item",
  "name": "NavItem",
  "level": "molecule",
  "status": "stable",
  "purpose": "A navigation row — an icon in the rail that opens its peek, a labelled row in a panel.",
  "description": "Renders <a> when href is provided, otherwise <button>. active sets aria-current=page; collapsed compresses to icon-only with sr-only label. Patterns consulted: Patterns/Navigation · NavigationLayers, Patterns/Visual Priority · QuietSecondaryActions.",
  "role": "navigation",
  "import": "@rrios-forge/ui/molecules/nav-item",
  "exports": [
    "NavItem",
    "NAV_ITEM_STATES",
    "navItemVariants"
  ],
  "source": "packages/ui/src/molecules/nav-item",
  "axes": [
    {
      "axis": "active",
      "part": null,
      "values": [
        "true",
        "false"
      ],
      "default": "false",
      "meaning": "The current destination or item: marked as current to assistive tech."
    },
    {
      "axis": "disabled",
      "part": null,
      "values": [
        "true",
        "false"
      ],
      "default": "false",
      "meaning": "Not available: dimmed, skipped by the keyboard, ignores the pointer."
    },
    {
      "axis": "collapsed",
      "part": null,
      "values": [
        "true",
        "false"
      ],
      "default": "false",
      "meaning": "Folded to its compact form (an icon rail, a closed group)."
    }
  ],
  "needs": [
    {
      "need": "App frame / navigation",
      "answer": "**The rail that peeks (ADR-044) — the default and the recommendation.** `PageShell` (defaults: `sidebarMode=\"rail\"`, `sidebarPresentation=\"inset\"`, `mobileNav=\"tabs\"`) + `SidebarSection aria-label` + ONE untitled `NavGroup`: home, search, the rooms, settings — same size, same gap. Wrap every `NavItem` in `PageShell.RailPeek` and compose its panel with `PageShell.PeekHeader` / `PeekFacts` / `PeekLinks`. Search is a button row opening `CommandMenu` (⌘K); settings' peek holds the quick controls; phones get `PageShell.MobileTabBar` (≤ 5). No `TopBar` in an app frame. Opt-ins only when a product needs them: the labelled panel (`sidebarMode=\"auto\"`, ⌘\\\\ collapse, ADR-040), `island`/`column` (ADR-025), the bubble (`mobileNav=\"bubble\"`)"
    }
  ],
  "patterns": [],
  "a11yExceptions": [],
  "decisions": [
    {
      "id": "ADR-005",
      "title": "Visual operational rules: surfaces, interaction, motion"
    },
    {
      "id": "ADR-009",
      "title": "Editorial Frame: PageShell v3 + new `TopBar` molecule"
    },
    {
      "id": "ADR-010",
      "title": "PageShell v4: bottom dock + mobile floating bubble"
    },
    {
      "id": "ADR-011",
      "title": "PageShell v5: adaptive lateral sidebar + mobile nav bubble"
    },
    {
      "id": "ADR-014",
      "title": "PageShell: Apple Mail / macOS Big Sur visual register"
    },
    {
      "id": "ADR-017",
      "title": "Actionable components adopt the `asChild` slot pattern for framework-aware routing"
    },
    {
      "id": "ADR-018",
      "title": "Motion language as a Pattern Layer contract"
    },
    {
      "id": "ADR-025",
      "title": "The sidebar is an island, not a wall (amended: two stagings)"
    },
    {
      "id": "ADR-037",
      "title": "Continuity motion: a decelerating curve, a travelling indicator, view transitions and the SegmentedControl"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-molecules-navitem--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--playground",
      "frame": "/iframe.html?id=components-molecules-navitem--playground&viewMode=story"
    },
    {
      "name": "Active",
      "id": "components-molecules-navitem--active",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--active",
      "frame": "/iframe.html?id=components-molecules-navitem--active&viewMode=story"
    },
    {
      "name": "With badge",
      "id": "components-molecules-navitem--with-badge",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--with-badge",
      "frame": "/iframe.html?id=components-molecules-navitem--with-badge&viewMode=story"
    },
    {
      "name": "Collapsed",
      "id": "components-molecules-navitem--collapsed",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--collapsed",
      "frame": "/iframe.html?id=components-molecules-navitem--collapsed&viewMode=story"
    },
    {
      "name": "Disabled",
      "id": "components-molecules-navitem--disabled",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--disabled",
      "frame": "/iframe.html?id=components-molecules-navitem--disabled&viewMode=story"
    },
    {
      "name": "As button",
      "id": "components-molecules-navitem--button-branch",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--button-branch",
      "frame": "/iframe.html?id=components-molecules-navitem--button-branch&viewMode=story"
    },
    {
      "name": "With a router link",
      "id": "components-molecules-navitem--as-child-with-link",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--as-child-with-link",
      "frame": "/iframe.html?id=components-molecules-navitem--as-child-with-link&viewMode=story"
    },
    {
      "name": "Client-side navigation",
      "id": "components-molecules-navitem--as-child-prevents-navigation",
      "interaction": true,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--as-child-prevents-navigation",
      "frame": "/iframe.html?id=components-molecules-navitem--as-child-prevents-navigation&viewMode=story"
    },
    {
      "name": "In the rail, with a tooltip",
      "id": "components-molecules-navitem--collapsed-with-tooltip",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--collapsed-with-tooltip",
      "frame": "/iframe.html?id=components-molecules-navitem--collapsed-with-tooltip&viewMode=story"
    },
    {
      "name": "With a trailing action",
      "id": "components-molecules-navitem--with-trailing-action",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--with-trailing-action",
      "frame": "/iframe.html?id=components-molecules-navitem--with-trailing-action&viewMode=story"
    },
    {
      "name": "Plain link (deprecated)",
      "id": "components-molecules-navitem--plain-link",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-navitem--plain-link",
      "frame": "/iframe.html?id=components-molecules-navitem--plain-link&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/molecules/nav-item.stories.tsx"
}