Topbar

<caos-topbar>

the platform top bar: identity, workspace controls, and the app name

May be placed on a seam in the workspace frame.

Inputs

Name	Attribute	Description	Type	Default	Required
`userName`	`user-name`, markup only	The signed-in person’s display name. It sets the avatar’s two initials, the name in the bar and the name at the head of the account menu. With no name at all the whole account control is hidden, which is what a bar above a sign-in screen looks like.	text	none declared	Optional
`userSub`	`user-sub`, markup only	The line under the name — a role, a company, an email. Drawn small, uppercase and clipped at a width.	text	none declared	Optional
`theme`	`theme`, markup only	Which theme the page is on: system, light or dark. The bar only DISPLAYS this — the button shows where a press would take you (a moon while light or system, a sun while dark) and the label names where you are. The host has to keep it true.	text — one of system, light, dark	system	Optional
`env`	`env`, markup only	The environment chip beside the wordmark — “SANDBOX”, “TEST”. Drawn in the warning colour with a soft hairline and no fill. Unset ⇒ no chip, which is what production looks like.	text	none declared	Optional
`wordmark`	`wordmark`, markup only	Override the brand name in the lockup. Unset ⇒ the `--brand-wordmark` token from the compiled token floor. Cleared to empty, no wordmark is drawn — an org may deliberately have no company name here.	text	none declared	Optional
`osSuffix`	`os-suffix`, markup only	The accent line under the wordmark. Unset ⇒ the `--brand-os-suffix` token from the compiled token floor — the platform identity that stays put when a tenant sets their own name above it. Cleared to empty, no tagline is drawn.	text	none declared	Optional
`showSetup`	`show-setup`, markup only	Offer Setup in the gear menu. A permission statement: leave it off for somebody who may not configure the platform. The gear itself is drawn whenever it has anything to hold — with this off and `show-edit-page` on it still appears, carrying that entry alone, so a control the host claimed is never left unreachable.	boolean	false	Optional
`showEditPage`	`show-edit-page`, markup only	Offer “Edit this page” in the gear menu, under a divider below Setup. The bar cannot edit anything, so this is the host declaring it has an editor to open; left off, the entry is not rendered at all.	boolean	false	Optional
`personaOptions`	property only	The permission-set groups this person may preview as, as `{ key, label, description? }`. An empty list hides the whole “Viewing as:” block. The menu says plainly that the switch previews what is VISIBLE and does not change which rows the data layer returns.	json	empty list	Optional
`activePersonaKey`	`active-persona-key`, markup only	Which persona is being previewed. Its row in the submenu carries the tick.	text	none declared	Optional
`personaLabel`	`persona-label`, markup only	What the “Viewing as:” line reads. Given explicitly it wins; otherwise it is derived from the active key against the offered personas, and only a key matching nothing falls back to “Default”.	text	Default	Optional
`impersonationOptions`	property only	The people an administrator may look at the app as, as `{ id, label }`. An empty list hides the “Log in as another user” block entirely, so it is only ever offered to somebody who may use it.	json	empty list	Optional

Events

Name	When it fires	What it carries
`topbar-theme`	The theme button was pressed. The bar does not change the theme — it says it was asked to.	nothing
`topbar-setup`	“Setup” was chosen from the gear menu — the gear itself only opens the menu.	nothing
`topbar-profile`	“View my profile” was chosen from the account menu.	nothing
`topbar-edit-page`	“Edit this page” was chosen from the gear menu — the host binds whatever edits the surface underneath.	nothing
`topbar-my-feedback`	“My feedback” was chosen: what this person has reported, and what happened to it.	nothing
`topbar-persona`	A persona was picked from “Viewing as:”, or “Reset to default” was chosen there.	`{ key, label }` — both null on a reset.
`topbar-impersonate`	Somebody was picked from “Log in as another user”.	`{ id, label }` — who to look at the app as.
`topbar-signout`	“Sign out” was chosen. Ending the session is the host’s half.	nothing

Slots

Name	What goes in it
`center`	The middle column, which is otherwise empty — the global search box goes here.
`commands`	Extra command buttons at the head of the right-hand cluster, before the Setup gear. A slotted `<button slot="commands">` is given the same bordered, accent-glyph treatment as the bar’s own.

Styling hooks

Design token	What it controls
`--caos-color-bg`	The bar’s own frosted band — the PAGE base, not a surface, so the chrome reads continuous with the page.
`--caos-color-border`	The hairline under the bar, the command buttons’ outlines, the rule beside the account, and the menu’s outline.
`--caos-color-border-strong`	A command button’s outline while the pointer is over it.
`--caos-color-surface`	The account menu’s background.
`--caos-color-surface-2`	A menu row’s fill on hover.
`--caos-color-accent`	Every command glyph, the avatar’s gradient, and the tick beside the persona in force.
`--caos-color-accent-strong`	The far end of the avatar’s gradient.
`--caos-color-text`	The wordmark, the signed-in name, and the menu rows.
`--caos-color-text-muted`	The menu’s sub-line, the row glyphs, and the submenu notes.
`--caos-color-text-ghost`	The small uppercase line under the name, and the submenu carets.
`--caos-color-warning`	The environment chip’s hairline, mixed down to about a third.
`--caos-color-warning-text`	The environment chip’s text.
`--caos-focus-ring`	The ring on a command button reached by keyboard.
`--caos-font-display`	The wordmark and the avatar’s initials.
`--caos-font-mono`	The accent suffix line, the environment chip, and the small line under the name.
`--caos-radius-sm`	The corner radius of the command buttons, the environment chip and the avatar.
`--caos-shadow-float`	The shadow that lifts the account menu off the bar.
`--brand-wordmark`	The brand name in the lockup. Read in script rather than by the stylesheet, and overridden by the `wordmark` attribute.
`--brand-os-suffix`	The accent line under the wordmark. Read in script, and overridden by the `os-suffix` attribute.

Methods

Nothing else drives this piece by calling it.

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
`::part(brand)`	the brand lockup	Always
`::part(brand-primary)`	the first word of the wordmark	Always
`::part(brand-secondary)`	the accent suffix under it	Always
`::part(env)`	the environment chip	Always
`::part(setup-block)`	the Setup gear and its menu together	Always
`::part(setup)`	the Setup gear — the button that opens the menu	Always
`::part(theme)`	the theme button	Always
`::part(account)`	the account control at the right	Always

When to use it

Only as the platform’s top bar. It is the one place identity, the environment, and the session-level controls live, and there is exactly one of it per screen.

What to use instead

WorkspaceTabs — You want the app-scoped row of destinations that sits under this bar.
PageHeader — You want to name the surface a person is looking at, not the platform they are signed in to.
ActionBar — The controls act on the record or the list in front of them rather than on the session.
ImpersonationBanner — You need to SHOW that a session is being viewed as somebody else; this bar only starts that.

Accessibility

The bar builds real buttons throughout: the account trigger carries aria-haspopup="menu" and an aria-expanded kept in step, the dropdown is a role="menu" labelled “Account menu” with role="menuitem" rows, the persona rows are role="menuitemradio" with aria-checked tracking the active key, and the two submenus keep their own aria-expanded. The theme button’s accessible name states the CURRENT preference rather than the glyph, so a screen reader hears “Theme: Dark” rather than “sun”. Escape and a click outside close the menu, and every glyph is hidden from assistive technology. What is left to the author: focus is not moved into the menu when it opens, is not trapped there, and does not return to the trigger when it closes; and anything projected into the commands slot brings its own accessible name — those buttons are usually glyph-only.

Examples

Signed in

The whole bar as a person sees it at work: the lockup, the Setup gear, the theme control, and an account menu holding the profile, the persona preview, Log in as, and sign out.

The page around it: The surrounding page owns the theme: the bar shows the page’s current setting, and a press cycles it for real — the same setting the control at the top of this page and the Appearance preference drive, so all three agree the instant any of them is used.

{
  "id": "example",
  "section": "Signed in",
  "columns": 1,
  "items": [
    {
      "id": "topbar_1",
      "type": "component",
      "key": "topbar",
      "inputs": {
        "user_name": "Dana Whitfield",
        "user_sub": "Sales manager · Meridian Supply",
        "wordmark": "Cloud Atlantis",
        "os_suffix": "OS",
        "show_setup": true,
        "persona_label": "Sales manager",
        "active_persona_key": "sales-manager",
        "persona_options": [
          {
            "key": "sales-manager",
            "label": "Sales manager",
            "description": "Works accounts and orders"
          },
          {
            "key": "admin",
            "label": "Administrator",
            "description": "Configures the platform"
          }
        ],
        "impersonation_options": [
          {
            "id": "u2",
            "label": "Marcus Ellery"
          }
        ]
      }
    }
  ]
}

<caos-topbar id="topbar1" user-name="Dana Whitfield" user-sub="Sales manager · Meridian Supply" wordmark="Cloud Atlantis" os-suffix="OS" show-setup persona-label="Sales manager" active-persona-key="sales-manager"></caos-topbar>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const topbar1 = document.getElementById('topbar1');
topbar1.personaOptions = [
  {
    "key": "sales-manager",
    "label": "Sales manager",
    "description": "Works accounts and orders"
  },
  {
    "key": "admin",
    "label": "Administrator",
    "description": "Configures the platform"
  }
];
topbar1.impersonationOptions = [
  {
    "id": "u2",
    "label": "Marcus Ellery"
  }
];

Nobody signed in, on a test environment

The same bar with no signed-in name: the account control is hidden entirely rather than drawn empty, and the environment chip says where you are.

{
  "id": "example",
  "section": "Nobody signed in, on a test environment",
  "columns": 1,
  "items": [
    {
      "id": "topbar_1",
      "type": "component",
      "key": "topbar",
      "inputs": {
        "wordmark": "Cloud Atlantis",
        "os_suffix": "OS",
        "env": "Sandbox"
      }
    }
  ]
}

<caos-topbar wordmark="Cloud Atlantis" os-suffix="OS" env="Sandbox"></caos-topbar>