Layout

Overview

Layout in opsinjs is deliberately small. There is no grid system, no twelve columns, no layout component zoo. A consumer health app is, structurally, a scrolling column with a persistent action, on a device held in one hand. Almost everything that goes wrong with its layout goes wrong at the edges: under the notch, behind the home indicator, beneath the on-screen keyboard, or above the fold on a small phone where the one thing the reader came for is the one thing they cannot see.

So this page specifies the shell, the edges, and two screen shapes. Everything about how the shell changes with available width belongs to Responsive modes, and everything about how much room things get belongs to Space.

The thing this is most often confused with is a page template. A template prescribes content. A shell prescribes the frame, the insets and the ordering rules. What content goes in it is a pattern or a screen.

How it works

The shell has four regions, and their order in the DOM is the order a screen reader meets them, which is not always the order they appear on screen:

1. Header has the screen's name and at most one secondary action. It is a heading, not a picture of one.
2. Content is a single scrolling column. Multiple scroll containers on one screen is the most reliable way to lose somebody using a keyboard or a switch.
3. Action is the persistent primary action, if the screen has one. It is the last thing in the DOM and it is pinned visually, so tab order reaches it after the content rather than before it.
4. Chrome is the tab bar or equivalent, outside the screen's landmark entirely.

The edges are a contract, not a per-screen decision. Every one of the four regions resolves its outer padding from a token that already includes the platform inset, so a component never writes env(safe-area-inset-bottom) itself and a screen never ends up with a dismiss control under the home indicator. The same applies to the on-screen keyboard: the action region and any focused field sit above the keyboard inset, so typing a reading never hides the field you are typing it into.

Reach beats symmetry. On a phone, the bottom third of the screen is where a thumb comfortably lands and the top corners are where it does not. Primary actions go low; destructive and irreversible ones do not go where a thumb rests by default. This is opinion informed by the platform guidance rather than a measured result, and it is stated as such.

Two shapes cover most screens.

The overview shell. One heading, then a vertical run of tiles or cards, one per category or per metric, then a persistent action. Its rules: every tile carries its own status and its own freshness; there is no sort order that mixes the two axes; and the screen has a stated escalation budget, because an overview is where alarm fatigue is manufactured. See Alarm fatigue.

The reading shell. One value at the top with its unit, its status and its range; then what it means; then what to do; then history. Its rules: the value is above the fold on the smallest supported screen, nothing may cover it (see Layering), and the meaning precedes the action because a reader who is told what to do before they are told what it is will usually do neither.

Using it

Do not invent a third shell without writing down why. Most requests for one are actually a request for a different arrangement of content inside the reading shell. If you genuinely need one, it belongs in Screens with a spec, not as a local layout.

Order for the reader, not for the designer.

One scroll container, one landmark set, one H1. The header region is the H1; sections inside content are H2. A screen with two H1s is a screen that will be described wrongly by every tool that summarises it, including the ones your readers use.

Content has a maximum measure, even on a large screen. Wide screens get more of the story visible at once, not wider paragraphs. The rule and its mechanism are on Responsive modes.

Tokens

Layout consumes the space scale, the safe-area insets and the container thresholds; it owns no scale of its own. The shell's outer padding, the action region's inset and the keyboard-avoidance offset are generated from tokens/space.json by scripts/build-tokens.mts.

Accessibility impact

Layout is where document structure and visual arrangement can silently disagree, and every item below is a real failure that passes a visual review.

• DOM order is reading order. The pinned action region is last in the DOM even though it is visually low on screen, so tab order and screen-reader order both reach it after the content it applies to. Any layout technique that reorders content visually without reordering it in the DOM breaks this.
• Landmarks are not decoration. Header, main, and the chrome region are distinct landmarks with distinct names, which is how somebody using a screen reader skips to the content without listening to the tab bar first.
• Safe areas are an accessibility requirement. A control under the home indicator or behind the keyboard is not merely inconvenient; for somebody with limited dexterity it is unreachable, and for somebody using a screen reader it is reachable but described in the wrong place.
• Reflow. The shell must survive 400% zoom without a second scroll axis, and must survive a 1.3× text-size multiplier with no clipping at all. The checks are on Text resizing and zoom and Dynamic Type.
• Sticky regions must not eat the viewport. A sticky header plus a sticky action bar on a small phone at a large text size can leave almost no content visible. Both collapse under the compact mode rules rather than persisting at full height.

Related

• Responsive modes shows how this shell behaves as the container grows, and why the rule is "more of the story", not "bigger".
• Layering and elevation says what may sit over the shell, and the rule that nothing may cover the value.
• Screens covers whole-screen specimens built from these two shapes.