use-topbar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Topbar

Topbar组件

@aura/topbar

is the single, compliant top navigation bar for every authenticated Dune/Fusion app. It is a shadcn registry component (installed via

pnpm dlx shadcn@latest add @aura/topbar

), not an npm package.

Storybook: https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-topbar--docs
Full rules: RULES.md · Interview: INTERVIEW.md · Install + code: IMPLEMENTATION.md

Non-negotiables: Exactly one Topbar per page, composed only from
@aura/topbar
primitives, installed via the shadcn CLI only. If installation fails, surface the blocker — never build a custom header fallback. See RULES.md §1, §11, §12.

@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。

Step 0 — Auto-prompt hook setup

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

Ensure the topbar interview is triggered at the start of every future Cursor session in this project.

Check whether
```
.cursor/hooks.json
```
exists in the project root.
If it does not exist, create it:

json

{
  "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."
      }
    ]
  }
}

If
```
.cursor/hooks.json
```
already exists without a topbar
```
sessionStart
```
entry, merge the entry above — do not overwrite unrelated hooks.
Confirm to the user, then continue.

确保在该项目未来的每一次Cursor会话启动时，都会触发Topbar配置访谈。

检查项目根目录下是否存在
```
.cursor/hooks.json
```
文件。
若不存在，创建该文件：

json

{
  "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."
      }
    ]
  }
}

若
```
.cursor/hooks.json
```
已存在但未包含Topbar的
```
sessionStart
```
条目，合并上述条目——请勿覆盖无关钩子。
向用户确认完成后，继续后续操作。

Step 1 — Pre-flight: read the app

步骤1 — 准备工作：读取应用信息

Before asking any questions, read:

```
package.json
```
— package manager, existing UI deps, existing
```
@aura/topbar
```
```
src/App.tsx
```
(or main layout file) — routing, existing dark-mode hook/context
Dune/Fusion app config (
```
app.config.ts
```
,
```
fusion.config.ts
```
, manifest) —
```
displayName
```
,
```
name
```
, app mark / branding

Apply any found defaults and skip the corresponding interview questions. State what was inferred.

在提问之前，先读取以下内容：

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

应用已找到的默认值，并跳过对应的访谈问题。告知用户已推断出的信息。

Step 2 — Configuration interview (mandatory)

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

Run the full Q1–Q9 interview in INTERVIEW.md before writing any implementation code. Ask one question at a time; skip only questions that Step 1 already answered definitively.

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

Steps 3–5 — Install, theme hook, implement

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

See IMPLEMENTATION.md for:

Installing
```
@aura/topbar
```
via the shadcn CLI (mandatory, no workarounds)
```
useThemeMode
```
hook wiring for light/dark switching
Topbar component composition example and layout wrapper

请查看IMPLEMENTATION.md获取以下内容：

通过shadcn CLI安装
```
@aura/topbar
```
（必填，不允许变通方案）
为明暗切换配置
```
useThemeMode
```
钩子
Topbar组件组合示例及布局包装器

Step 6 — Compliance checklist

步骤6 — 合规性检查清单

Verify before finishing (see RULES.md §12 for the full enforcement checklist):

Exactly one Topbar per page
Left:
```
Avatar
```
application mark (small, fjord) → app name breadcrumb → object name breadcrumb (only when an object is open)
Breadcrumb segments are interactive links — not static text
Object dropdown (if present) only on the object name segment; actions are object-scoped only
Inline metadata (if present) is a plain string, left-aligned after the breadcrumb — not centered
Middle: Tabs or Segmented control at small if present; no sidebar; no primary CTA in the Topbar
Primary / app-specific actions live in the content area below the Topbar
Right strip order when used: Share → Notifications → Theme → Atlas → user Avatar; Share/Notifications/Theme as ghost small, Atlas as secondary small with leading icon + "Atlas"
Theme: sun in light mode, moon in dark mode; Menu with Light/Dark rows + checkmark on active; wired to
```
document.documentElement
```
```
tailwind.config
```
has
```
darkMode: 'class'
```

完成前请验证以下内容（完整强制检查清单见RULES.md §12）：

每页仅能有一个Topbar
左侧：
```
Avatar
```
应用标识（小尺寸、fjord样式）→ 应用名称面包屑 → 对象名称面包屑（仅在打开对象时显示）
面包屑分段为可交互链接——而非静态文本
对象下拉菜单（若存在）仅在对象名称分段中显示；操作仅作用于该对象
内嵌元数据（若存在）为纯文本字符串，左对齐于面包屑之后——不居中显示
中部：若存在则为Tabs或分段控件，且为小尺寸；无侧边栏；Topbar中无主要CTA按钮
主要/应用专属操作位于Topbar下方的内容区域
右侧工具条使用顺序：分享 → 通知 → 主题 → Atlas → 用户Avatar；分享/通知/主题为幽灵小按钮，Atlas为次要小按钮，带前置图标+"Atlas"文本
主题：亮色模式显示太阳图标，暗色模式显示月亮图标；菜单包含亮色/暗色选项，当前激活项带勾选标记；关联到
```
document.documentElement
```
```
tailwind.config
```
中配置了
```
darkMode: 'class'
```