use-topbar

A wiring skill for adding the Aura Topbar (@aura/topbar) into Cognite Flows and Fusion applications as the single, compliant top navigation bar. The Topbar provides breadcrumbs, an optional center Tabs or Segmented control, a right-side utility strip (Share, notifications, theme menu, Atlas, and a user Avatar), and light/dark theme switching. It is the right skill when adding a topbar, app header, navigation bar, breadcrumbs, or theme switcher to a Flows or Fusion app, or when scaffolding a new such application. A key distinction is that @aura/topbar is a shadcn registry component installed via the shadcn CLI (pnpm dlx shadcn@latest add @aura/topbar), not an npm package.

The workflow is interview-driven and opinionated. Step 0 ensures a .cursor/hooks.json sessionStart hook is present so the topbar interview is triggered at the start of future Cursor sessions, merging into an existing hooks file without overwriting unrelated hooks. Step 1 reads the app first, inspecting package.json, the main layout file such as src/App.tsx, and the Flows or Fusion app config for branding and existing dark-mode wiring, then applies and states any inferred defaults. Step 2 runs a mandatory Q1 to Q9 configuration interview from INTERVIEW.md, one question at a time, before any implementation code is written. Steps 3 to 5 cover installing via the shadcn CLI, wiring a useThemeMode hook for light/dark switching, and composing the Topbar, detailed in IMPLEMENTATION.md.

Compliance is strongly enforced. Non-negotiables include exactly one Topbar per page composed only from @aura/topbar primitives and installed via the shadcn CLI only, with the blocker surfaced rather than a custom header fallback built if installation fails. A final Step 6 checklist verifies details such as the breadcrumb structure (a small fjord Avatar app mark, app name and object name breadcrumbs as interactive links), the center Tabs or Segmented control at small size with no sidebar and no primary CTA in the Topbar, the right strip order of Share, Notifications, Theme, Atlas, and user Avatar, theme behavior showing a sun in light mode and a moon in dark mode wired to document.documentElement, and a tailwind config with darkMode set to class. Full rules live in RULES.md.