{
  "id": "top-bar",
  "name": "TopBar",
  "level": "molecule",
  "status": "stable",
  "purpose": "Brand, search and actions across the top of a page without a rail.",
  "description": "Page-level command bar that hosts the brand mark on the left, a search/command pill in the centre, and an actions cluster on the right. Compose with `<PageShell>` for the editorial frame, or render alone above any full-page surface.",
  "role": "navigation",
  "import": "@rrios-forge/ui/molecules/top-bar",
  "exports": [
    "TopBar",
    "TopBarSearchTrigger",
    "topBarActionsColumnVariants",
    "topBarActionsVariants",
    "topBarBrandVariants",
    "topBarSearchSlotVariants",
    "topBarSearchTriggerLabelVariants",
    "topBarSearchTriggerVariants",
    "topBarVariants"
  ],
  "source": "packages/ui/src/molecules/top-bar",
  "axes": [
    {
      "axis": "size",
      "part": null,
      "values": [
        "sm",
        "md"
      ],
      "default": "md",
      "meaning": "Ergonomic scale, in three families (control, text, container)."
    }
  ],
  "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-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-013",
      "title": "PageShell: mobile-nav polymorphism"
    },
    {
      "id": "ADR-014",
      "title": "PageShell: Apple Mail / macOS Big Sur visual register"
    },
    {
      "id": "ADR-016",
      "title": "NotificationCenter v2: Popover → Drawer + Provider/Hooks"
    },
    {
      "id": "ADR-022",
      "title": "The material family: `solid` and `vibrant`"
    },
    {
      "id": "ADR-030",
      "title": "Axis vocabulary: one name, one meaning"
    },
    {
      "id": "ADR-044",
      "title": "Navigation is a rail that peeks"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-molecules-topbar--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-topbar--playground",
      "frame": "/iframe.html?id=components-molecules-topbar--playground&viewMode=story"
    },
    {
      "name": "Brand only",
      "id": "components-molecules-topbar--brand-only",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-topbar--brand-only",
      "frame": "/iframe.html?id=components-molecules-topbar--brand-only&viewMode=story"
    },
    {
      "name": "Search only",
      "id": "components-molecules-topbar--search-only",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-topbar--search-only",
      "frame": "/iframe.html?id=components-molecules-topbar--search-only&viewMode=story"
    },
    {
      "name": "Actions only",
      "id": "components-molecules-topbar--actions-only",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-topbar--actions-only",
      "frame": "/iframe.html?id=components-molecules-topbar--actions-only&viewMode=story"
    },
    {
      "name": "Compact (mobile)",
      "id": "components-molecules-topbar--compact",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-topbar--compact",
      "frame": "/iframe.html?id=components-molecules-topbar--compact&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/molecules/top-bar.stories.tsx"
}