use-topbar

顶栏

@aura/topbar 是每个经过身份验证的 Dune/Fusion 应用唯一且合规的顶部导航栏。它是一个 shadcn 注册表组件（通过 pnpm dlx shadcn@latest add @aura/topbar 安装），而不是 npm 包。

• Storybook： https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-topbar--docs
• 完整规则： RULES.md · 访谈： INTERVIEW.md · 安装 + 代码： IMPLEMENTATION.md

不可妥协的要求： 每个页面必须且只能有一个 Topbar，且只能由 @aura/topbar 基元组成，并且只能通过 shadcn CLI 安装。如果安装失败，请明确说明阻碍因素——绝不能构建自定义标题栏作为替代方案。参见 RULES.md §1, §11, §12。

---

步骤 0 — 自动提示词钩子设置

确保今后每次在此项目中启动 Cursor 会话时，都会触发顶栏访谈。

1. 检查项目根目录中是否存在 .cursor/hooks.json。
2. 如果不存在，请创建该文件：

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "This is a Dune/Fusion application. Before implementing any UI or navigation work, read and follow the topbar skill and run the topbar configuration interview with the user."
      }
    ]
  }
}

3. 如果 .cursor/hooks.json 已存在但没有顶栏 sessionStart 条目，请合并上述条目——不要覆盖无关钩子。
4. 向用户确认，然后继续。

---

步骤 1 — 前期检查：阅读应用

提问前，先阅读：

• package.json — 包管理器、现有 UI 依赖、是否已有 @aura/topbar
• src/App.tsx（或主布局文件）— 路由、现有深色模式钩子/上下文
• Dune/Fusion 应用配置（app.config.ts、fusion.config.ts、清单）— displayName、name、应用标记 / 品牌信息

应用已找到的默认值，并跳过相应的访谈问题。说明推断出的内容。

---

步骤 2 — 配置访谈（必需）

编写任何实现代码前，请先完成 INTERVIEW.md 中的 Q1–Q9 完整访谈。每次只问一个问题；仅跳过步骤 1 已明确回答的问题。

---

步骤 3–5 — 安装、主题钩子、实现

参见 IMPLEMENTATION.md，了解：

• 通过 shadcn CLI 安装 @aura/topbar（必须执行，不得使用替代方案）
• 配置用于浅色/深色模式切换的 useThemeMode 钩子
• Topbar 组件组合示例和布局包装器

---

步骤 6 — 合规性检查清单

完成前请验证（完整的执行检查清单参见 RULES.md §12）：

• 每个页面必须且只能有 一个 Topbar
• 左侧：Avatar 应用标记（small、fjord）→ 应用名称面包屑 → 对象名称面包屑（仅在打开对象时显示）
• 面包屑各段均为可交互链接，而非静态文本
• 对象下拉菜单（如有）仅位于对象名称段；操作仅限于对象范围
• 行内元数据（如有）为纯字符串，左对齐并位于面包屑之后——不得居中
• 中间：如有，使用 Tabs 或 Segmented control，尺寸为 small；不得有侧边栏；Topbar 中不得有主要 CTA
• 主要 / 应用专属操作应放在 Topbar 下方的内容区域中
• 使用右侧栏时的顺序：Share → Notifications → Theme → Atlas → 用户 Avatar；Share/Notifications/Theme 使用 ghost small，Atlas 使用带前置图标和 "Atlas" 的 secondary small
• 主题：浅色模式显示 sun，深色模式显示 moon；菜单包含 Light/Dark 两行，当前选项带勾选标记；与 document.documentElement 连接
• tailwind.config 设置了 darkMode: 'class'