Authentication shell

A semantic narrow page landmark that owns gutters and layout while applications own every visible authentication region.

Source: app/components/nitro_kit/auth_shell.rb
API: NitroKit::AuthShell.new(id:, html:, aria:, data:, desperately_need_a_class:) { ... }

Application-owned content

The shell supplies one semantic landmark, narrow constraint, gutters, and vertical rhythm. The application supplies every visible region.

Credentials form

A real Rails form and Card remain ordinary direct content.

Sign in to Nitro

Viewport640 px · sm

Width

Preset

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

render NitroKit::AuthShell.new(
  id: "gallery-auth-shell-credentials",
  aria: { label: "Credentials example" }
) do
  render_credentials_card
end

Caller-owned branding

Brand identity and supporting copy are siblings of the application-owned Card, not shell slots.

Analytical Engines

Secure workspace access for Research and Production.

Welcome back

Use your team account to continue to the workspace.

Viewport640 px · sm

Width

Preset

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

render NitroKit::AuthShell.new(
  id: "gallery-auth-shell-branding",
  aria: { labelledby: "gallery-auth-shell-brand-name" }
) do
  header(data: { gallery: "auth-branding" }) do
    h4(id: "gallery-auth-shell-brand-name") { "Analytical Engines" }
    p { "Secure workspace access for Research and Production." }
  end
  render_access_card
end

Caller-owned Turbo lifecycle

The named Turbo Frame surrounds the shell and can replace the complete authentication state.

Check your inbox

Verification pending

We sent a secure link to [email protected].

Viewport640 px · sm

Width

Preset

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

turbo_frame_tag("gallery-auth-shell-frame") do
  render NitroKit::AuthShell.new(
    id: "gallery-auth-shell-turbo",
    aria: { label: "Email verification status" }
  ) do
    render_verification_card
  end
end

State and content pressure

Validation, completion, long identity copy, and a deliberately narrow viewport all use the same optionless shell.

Validation failure

Model errors, alert intent, field semantics, and recovery navigation remain caller-owned.

Sign in to Nitro

We could not sign you in

Correct both fields below and try again.

Viewport640 px · sm

Width

Preset

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

render NitroKit::AuthShell.new(
  id: "gallery-auth-shell-validation",
  aria: { label: "Invalid credentials example" }
) do
  render_validation_card
end

Successful handoff

Completion content can replace the form without changing the shell contract.

Welcome back

Sign-in complete

Your secure session is ready for Analytical Engines.

Viewport640 px · sm

Width

Preset

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

render NitroKit::AuthShell.new(
  id: "gallery-auth-shell-success",
  aria: { label: "Successful sign-in example" }
) do
  render_success_card
end

Long account and workspace copy

Unbroken identity pressure shrinks inside the fixed medium content constraint.

Verify your account

We sent instructions to katherine.johnson+analytical-engines-research-and-production@example.test for the International Research, Production, and Reliability Engineering workspace.

Viewport640 px · sm

Width

Preset

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

render NitroKit::AuthShell.new(
  id: "gallery-auth-shell-long-copy",
  aria: { label: "Long account identity example" }
) do
  render_long_copy_card
end

Narrow mobile pressure

Gallery viewport metadata narrows the same shell; Nitro keeps gutters and descendants shrinkable.

Recover access

This link expired

Request a new link for your workspace account to continue securely.

Viewport640 px · sm

Width

Preset

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

render NitroKit::AuthShell.new(
  id: "gallery-auth-shell-mobile",
  aria: { label: "Mobile authentication example" },
  data: { gallery: "composition-surface", gallery_mobile: "true" }
) do
  render_mobile_card
end

Component contract

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

docs/component_contracts.md · NitroKit::AuthShell

Constructor: id: nil
Root: main[data-nk=auth-shell]
Compound contract: Requires direct content. Owns main → medium Container → Flex(dir: :col, gap: 6, align: :stretch); branding, Cards, and Turbo boundaries remain 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

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.

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.