---
id: shell/application-shell
title: Responsive application shell
summary: Compose the JSKIT responsive shell, semantic placements, settings navigation, and accessible adaptive-shell browser checks.
keywords: adaptive, app, layout, navigation, placement, responsive, settings, shell
requires: @jskit-ai/kernel, @jskit-ai/shell-web
---

# Responsive application shell

## Use when

Use this pattern when adding the standard responsive JSKIT shell to an existing
application foundation.

## Do not use when

Do not copy the entire shell into an application that already has a coherent
JSKIT shell. Use the narrower page-and-placement pattern for incremental UI.

## Product decisions

Choose the product navigation, settings sections, surfaces, labels, icons, and
which controls remain visible at compact, medium, and expanded widths.

## Framework APIs

Use the shell provider, `ShellLayout`, `ShellOutlet`, link components,
placement registry, topology, and adaptive smoke helper exported by
`@jskit-ai/shell-web`.

## Invariants

- `App.vue`, the shell layout, placements, topology, and route pages agree.
- Route pages do not add a page header or standalone heading by default.
- Navigation uses semantic placements rather than direct component injection.
- Compact controls have accessible names and at least 48 CSS-pixel targets.
- Cached route/resource state hydrates writable UI state synchronously or with
  immediate watchers.
- Loading uses stable skeletons, not spinners or shifting status banners.
- `ShellErrorHost` stays directly inside `v-app`. Its banners float below a top
  app bar; on a surface without one (such as sign-in) they join the page flow
  above the content so they never cover it. A full-viewport fixed screen on
  such a surface starts at `var(--shell-error-banners-inline-height, 0px)`, as
  `@jskit-ai/auth-web`'s login and reset views do.
- Restyle shell chrome through its custom properties, not by overriding
  Vuetify internals: `--shell-chrome-border-width` and
  `--shell-chrome-border-color` for the shared dividers,
  `--shell-app-bar-border-width`, `--shell-navigation-border-width` and
  `--shell-bottom-navigation-border-width` per edge, and
  `--shell-app-bar-background`, `--shell-navigation-background` and
  `--shell-bottom-navigation-background` for the surfaces. The defaults keep
  one thin divider on each separating edge, because Vuetify's default themes
  define no Material 3 surface-container roles. A Material 3 restyle sets the
  border widths to `0` and gives navigation a tonal surface, for example
  `rgb(var(--v-theme-surface-container-low))` when the theme defines it.
- `createShellRouter()` from `@jskit-ai/kernel/client` installs
  `shellScrollBehavior`: a new screen opens at the top (or its hash target),
  Back/Forward restore the saved position, and query, hash, tab or sub-view
  changes within the same page keep it. A tab or sub-view is the same page when
  both locations share a parent page record below the surface root. Pass
  `scrollBehavior` to replace it, or `scrollBehavior: false` to disable it; do
  not wrap the router or reset scroll in page components.
- The adaptive browser check closes navigation through its public close control.

## Example files

`example/src/` contains the complete shell composition, standard link
components, settings routes, placement registry, and topology. The browser
example under `example/tests/` exercises the public adaptive-shell contract.
The `expected-existing/` files show the minimal foundation shapes replaced by
the complete shell; they are reference inputs, not merge instructions.

## Variation points

Change product navigation, surfaces, routes, settings sections, placements,
responsive outlet mappings, labels, icons, and application-owned components.

## Verification

Exercise direct navigation, browser back/forward with a warm cache, keyboard
navigation, current-link state, and compact/medium/expanded layouts. Run client
tests and a production build.

## Avoid

- custom navigation registries beside placements
- clicking Vuetify scrims or coordinates in browser tests
- magic generated-page classes
- source mutation or overwrite machinery