use-topbar

Topbar

@aura/topbar 是所有已认证 Flows/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 会话时，都会触发 Topbar 访谈。

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

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "This is a Flows/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 已存在，但没有 Topbar 的 sessionStart 条目，请合并上面的条目，不要覆盖无关钩子。
4. 向用户确认，然后继续。

---

步骤 1 — 预检：读取应用信息

在提出任何问题之前，先阅读：

• package.json — 包管理器、现有 UI 依赖、是否已有 @aura/topbar
• src/App.tsx（或主布局文件）— 路由、现有深色模式钩子/上下文
• Flows/Fusion 应用配置（app.config.ts、fusion.config.ts、manifest）— 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 使用 secondary small，带前置图标和“Atlas”文字（打开 EOS 侧边栏；如果应用具有 AI，则默认开启——integrate-fusion-agent）
• 主题：浅色模式显示太阳，深色模式显示月亮；菜单包含浅色/深色选项行，并在当前选项旁显示勾号；与 document.documentElement 接线
• tailwind.config 中设置了 darkMode: 'class'