Application shell

Sidebar, topbar, and hybrid application frames that reflow one AppNavigation tree through an accessible narrow drawer.

Source: app/components/nitro_kit/app_shell.rb
API: NitroKit::AppShell.new(id:, layout: :sidebar, skip_link_label:, open_navigation_label:, close_navigation_label:, navigation_dialog_label:) { |shell| shell.navigation { ... }; shell.main { ... } }

Layout variants

All three layouts reflow the same AppNavigation tree while the application supplies brand, actions, routes, and main content.

A sticky product sidebar surrounds a compact operational dashboard.

Rubytest/dummy/app/components/gallery/components/app_shell_page.rb

render NitroKit::AppShell.new(
  id:,
  layout:,
  navigation_dialog_label: "Workspace navigation",
  data: {
    gallery_shell_preview: layout,
    gallery_shell_long: long ? "true" : nil
  }.compact
) do |shell|
  shell.brand do
    strong do
      long ? "International Analytical Engine Operations" : "Northstar"
    end
  end if brand

  shell.navigation do
    render_shell_navigation(id:, current:, dense:, long:)
  end

  shell.topbar do
    render NitroKit::ButtonGroup.new(label: "Workspace actions") do |group|
      group.button("Search", href: "#search", variant: :ghost, size: :sm, icon: :search)
      group.button("Account", href: "#account", variant: :ghost, size: :sm, icon: :circle_user_round)
    end
  end if actions

  shell.main { render_workspace_main(layout:, long:) }
end

Brand, navigation, and account actions share the desktop header before the same tree becomes a narrow drawer.

Hybrid operations

Persistent navigation and a sticky action row combine without a second navigation copy.

Northstar

Search Account

Hybrid

Workspace overview

A caller-owned dashboard composed from ordinary Nitro components.

Active projects

Three need a decision this week.

Deployments

All production checks are passing.

Open incidents

Both have an assigned responder.

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/app_shell_page.rb

render_workspace_shell(id: "gallery-app-shell-hybrid", layout: :hybrid, current: :incidents, dense: true)

Optional chrome and pressure

Optional regions disappear cleanly while long destinations, nested content, and narrow disclosure keep the same contract.

Navigation and main only

Brand and topbar are optional; the required navigation and main regions still form a complete application frame.

Sidebar

Workspace overview

A caller-owned dashboard composed from ordinary Nitro components.

Active projects

Three need a decision this week.

Deployments

All production checks are passing.

Open incidents

Both have an assigned responder.

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/app_shell_page.rb

render_workspace_shell(
  id: "gallery-app-shell-minimal",
  layout: :sidebar,
  current: :overview,
  brand: false,
  actions: false
)

Long workspace pressure

Long brand, route, and content copy shrink inside the owned columns without a layout option or utility class.

International Analytical Engine Operations

Search Account

Hybrid

International research, reliability, and production readiness

Coordinate analytical engine capacity, operational handoffs, and incident readiness across every research and production region.

Active projects

Three need a decision this week.

Deployments

All production checks are passing.

Open incidents

Both have an assigned responder.

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/app_shell_page.rb

render_workspace_shell(
  id: "gallery-app-shell-long",
  layout: :hybrid,
  current: :capacity,
  long: true,
  dense: true
)

Component contract

Constructor options, rendered root, closed vocabularies, and compound boundary for this component, exactly as shipped.

docs/component_contracts.md · NitroKit::AppShell

Constructor: required id:; layout: :sidebar; configurable skip/open/close/dialog labels defaulting to nitro_kit.app_shell.*
Root: div[data-nk=app-shell][data-layout]; layouts sidebar topbar hybrid; states open closed; data-enhanced is written by the Stimulus controller and reserved
Compound contract: Requires exactly one navigation and one main; optional brand and topbar are unique. Regions are declared inside the render block only. One navigation tree moves between its neutral desktop wrapper and a native modal dialog at narrow widths. IDs are fragment-safe; product policy remains caller-owned.

Relevant patterns

Application conventions this component belongs to. Each summary is the leading section of its pattern document.

docs/patterns/application_foundation.md · docs/patterns/crud_resource.md

Application foundation

Model User, Team, and Membership; roles belong to memberships, and tenant-owned records load through Current.team.
Use one AppShell for the authenticated product and one application-owned content gutter inside shell.main.
Put route titles and persistent actions in the shell Toolbar; keep destinations in AppNavigation.
Use links for settings destinations and one layout-level Toast::FlashMessages region for server feedback.

Complete product resource

Define the resource, tenant boundary, actor, lifecycle, visibility, and states before writing views.
Build index, form, detail, destructive action, and tests as one product surface.
Use one shell toolbar title and one application-owned page gutter; do not repeat hierarchy across nested components.
Scope every lookup through the current tenant and model meaningful lifecycle transitions as noun resources.

System rules for coding agents

Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section.

test/dummy/app/components/gallery/agent_rules.rb

View agent instructions

Nitro Kit 2.0 is a gem-owned, Phlex-only UI system for Rails. Render components directly: render NitroKit::Button.new("Save", variant: :primary).
Compose Nitro components inside application-owned Phlex classes. Public initializers and declared slots are the component API; private methods are not.
Public options are explicit keywords, and enumerated options are closed vocabularies. Invalid names or values raise ArgumentError; this component's accepted options are in the contract above.
Pass native attributes through their typed boundary: html: for HTML, aria: for ARIA, and data: for application data. class and style are forbidden, including inside html:.
Nitro owns NitroKit::Component::RESERVED_DATA_ATTRIBUTES: data-nk, data-slot, data-variant, data-size, data-nk-escape, data-enhanced, data-state, data-disabled, data-required, data-orientation, data-presentation, data-placement, data-layout, data-side, data-field-type, data-dir, data-gap, data-align, data-justify, data-wrap, data-cols, data-mode, data-key. Do not pass them through data:. data-action, data-controller are additive and compose with Nitro behavior.
If an integration truly requires a class, use desperately_need_a_class:. It requires a non-blank String and marks the exception with data-nk-escape="class".
Every root emits data-nk; owned parts emit component-qualified data-slot values such as field-control or card-title. Select on those attributes, never on classes.
Customize components with documented --nk-* custom properties in an application stylesheet. Variables beginning with --_nk-* are private component mechanics.
Use NitroKit::Flex and NitroKit::Grid for layout. Parents own external placement and available width; components own their intrinsic geometry.
Preserve native elements and accessibility semantics. State is exposed through native semantics and ARIA first, and through data-state when styling or behavior also needs it.

Application shell

Layout variants

Sidebar workspace

Workspace overview

Active projects

Deployments

Open incidents

Topbar workspace

Workspace overview

Active projects

Deployments

Open incidents

Hybrid operations

Workspace overview

Active projects

Deployments

Open incidents

Optional chrome and pressure

Navigation and main only

Workspace overview

Active projects

Deployments

Open incidents

Long workspace pressure

International research, reliability, and production readiness

Active projects

Deployments

Open incidents

Component contract

Relevant patterns

Application foundation

Complete product resource

System rules for coding agents