Skip to content
opsinjs
Edit this page

Foundations

Space and layout

A 4px spacing scale, the 44pt touch floor, responsive modes, and the shell every screen sits in.

opsinjs is roomy on purpose. Scrolling costs a reader a second, but a mis-tap logs a reading they did not take or dismisses an alert they did not read.

Spacing scale

The scale is a 4px grid. Tailwind derives every spacing utility from --spacing, which the product theme sets to 0.25rem, so p-4 is 16px. The fixed steps are --opsin-space-*, written p-opsin-4, and at the default density both spellings land on the same pixel.

[data-density="compact"] multiplies --spacing by 0.875, so p-4 renders 14px and leaves the grid on purpose. Type size, the touch floor and the fixed steps do not move. Card pads with the scaled p-5, and Dialog with a fixed step that holds its inset. Use compact for dense lists, never for a screen's primary value.

  • Use a step, never a one-off value. A 13px gap ignores density and breaks the nesting arithmetic in Shape.
  • Group by proximity before reaching for a border. Gaps inside and between groups need two steps of difference to read as groups.
  • Never remove padding to make something fit. Cut the content or change the layout.
  • Steps are in rem, so space grows with the reader's text size.

Touch targets

Anything a person taps is at least 44pt on both axes, measured on the interactive area rather than the visible box. The floor is --opsin-target-minimum, in rem so it grows with text. It sits above the 24 by 24 CSS pixels of WCAG 2.2 SC 2.5.8, and opsinjs does not use that criterion's spacing exception. The product theme backstops buttons and form controls with a minimum size, which is a safety net rather than a sizing method.

  • --opsin-target-separation is the minimum gap between targets whose visible boxes are smaller than the floor.
  • Controls with unequal consequences, such as save beside delete, sit further apart or not side by side.
  • Never stretch a hit area invisibly into a neighbour's space.
  • Anything behind a hover is also reachable on tap and on focus.
  • Primary actions sit low, where a thumb rests, and destructive ones do not. This is opinion informed by platform guidance.

Responsive modes

On a wider screen nothing gets bigger. The reader sees more of the story at once: a reading beside its history, a list beside its detail, a sheet that becomes a pane.

May change with modeNever changes
Columns and regionsBody text size
Whether a surface is a sheet or a paneThe touch floor and radius rungs
How much history and provenance showsThe line-length cap
The outer gutterThe meaning, order and wording of content

The space tokens define phone, tablet and wide modes, each with its own --opsin-gutter-*. Prose stops at --opsin-measure-comfortable however wide the screen. Components query their container, never the viewport, so a tile in a narrow pane lays out as it would on a phone. Only the shell reads the viewport, because nothing sits above it.

Nothing may be reachable in only one mode, and DOM order never changes with mode. Design the narrowest mode first, then ask what did not fit.

Layout

The shell has four regions, in DOM order:

  1. Header, with the screen's H1 and at most one secondary action.
  2. Content, one scrolling column.
  3. Action, the persistent primary action, pinned low but last in the DOM so focus reaches it after the content.
  4. Chrome, the tab bar, outside the screen's landmark.

Add the --opsin-safe-* insets to the gutter at screen edges, and to a fixed action bar's padding rather than its height. Keep the action region and a focused field above the on-screen keyboard.

An overview screen is a heading, a run of tiles that each carry their own status and freshness, and a persistent action, with a ceiling on urgent surfaces set by Alerts. A reading screen puts the value with its unit, status and range first, then what it means, what to do, when it was taken and its history. Nothing covers the value, and it sits above the fold on the smallest supported screen.

Tokens

TokenWhat it controlsUsed by
--opsin-space-00rem0px.no component
--opsin-space-10.25remGap between an icon and its label.badge, button, callout, care-card, checkbox, combobox, dialog, dose-tracker, empty-state, field, goal-ring, log-sheet, menu, questionnaire, radio-group, range-bar, result-card, scale-input, scroll-area, segmented-control, select, sheet, slider, source-citation, stepper, surface, symptom-picker, tab-bar, tabs, timeline-entry, toast, tooltip, trend-sparkline
--opsin-space-20.5remGap between tightly related lines. For the separation between two interactive targets see targets.separation, which is the same number and carries its scope.alert-banner, avatar, badge, body-map, button, callout, combobox, consent-sheet, dialog, disclaimer-note, dose-tracker, empty-state, field, icon-button, log-sheet, menu, metric-tile, number-field, popover, progress, questionnaire, radio-group, range-bar, reading-input, relative-time, scale-input, score-dial, scroll-area, segmented-control, select, sheet, skeleton, slider, spinner, surface, symptom-picker, tab-bar, table, tabs, textarea, timeline-entry, toast, tooltip, trend-sparkline, visually-hidden
--opsin-space-30.75remInner padding of a compact control.accordion, alert-banner, button, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, empty-state, field, log-sheet, menu, metric-tile, progress, radio-group, range-legend, reading-input, result-card, scroll-area, segmented-control, select, sheet, slider, status-pill, stepper, surface, symptom-picker, table, tabs, textarea, timeline-entry, toast, tooltip, value
--opsin-space-41remThe default gap between elements inside a card.accordion, alert-banner, avatar, badge, button, callout, care-card, consent-sheet, dialog, divider, empty-state, field, goal-ring, link, log-sheet, menu, popover, range-bar, result-card, scale-input, score-dial, segmented-control, sheet, surface, switch, tabs, timeline-entry, toast
--opsin-space-51.25remCard inner padding on a phone.avatar, button, consent-sheet, dialog, menu, questionnaire, sheet, slider, switch, symptom-picker
--opsin-space-61.5remCard inner padding on a wide screen; gap between cards.avatar, card, dialog, disclaimer-note, empty-state, field, log-sheet, skeleton, stepper, switch, tab-bar, toast, trend-sparkline
--opsin-space-82remGap between sections within a screen.avatar, body-map, disclaimer-note, popover, range-bar, reading-input, sheet, stepper, tab-bar
--opsin-space-102.5remSpace above a section heading.avatar, sheet, skeleton, switch
--opsin-space-123remGap between major regions of a screen.avatar, trend-sparkline
--opsin-space-164remTop of a screen below the safe area; the space a consent sheet leaves above its first question.dialog, skeleton
--opsin-space-205remEmpty-state vertical rhythm.no component
--opsin-space-246remThe largest step. Beyond this, use a layout, not a gap.no component
--opsin-space-px0.0625remHairline borders only.body-map, trend-sparkline
--opsin-space-0-50.125remOptical nudges. Not a layout step.badge, dose-tracker, radio-group, range-legend, result-card, scroll-area, segmented-control, stepper, switch, tab-bar, tabs, term, trend-sparkline
--opsin-target-minimum2.75remThe opsinjs floor for any interactive control, applied to the hit area rather than to the visible box.accordion, body-map, button, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, field, icon-button, menu, metric-tile, number-field, popover, questionnaire, radio-group, reading-input, scale-input, segmented-control, select, sheet, slider, source-citation, switch, symptom-picker, tab-bar, tabs, textarea, toast, tooltip
--opsin-target-comfortable3remThe default for a primary action in the product theme.dialog
--opsin-target-generous3.5remA single primary action on a consent, escalation or emergency surface, where a mis-tap has a real cost.no component
--opsin-target-separation0.5remThe minimum gap between two adjacent targets whose visible boxes are smaller than 44px. It is a floor for undersized targets only. Two targets that both meet the 44px minimum are outside its scope, and separating those is governed by the differing cost of a mis-tap between them rather than by a fixed gap.alert-banner, card, care-card, consent-sheet, result-card
--opsin-gutter-phone16pxThe screen gutter in the phone responsive mode.no component
--opsin-gutter-tablet24pxThe screen gutter in the tablet responsive mode.no component
--opsin-gutter-wide32pxThe screen gutter in the wide responsive mode.no component
--opsin-measure-tight45chA caption or a legend.dialog, empty-state, goal-ring, popover, tooltip
--opsin-measure-comfortable66chThe maximum line length for prose anywhere in the product, including a disclaimer nobody wants to read.disclaimer-note, result-card, score-dial, sheet, source-citation, term
--opsin-measure-wide80chCode and machine output only.no component
--opsin-graphic-dial17remThe maximum width of the ScoreDial arc. This is 16em against the product body of 1.0625rem, which is 17rem and lands on the 4px grid at 68 steps, and it yields to w-full when the column is narrower.goal-ring, score-dial
--opsin-safe-topenv(safe-area-inset-top, 0px)The top safe-area inset, for installed web apps where browser chrome does not protect the edge.no component
--opsin-safe-rightenv(safe-area-inset-right, 0px)The right safe-area inset, for installed web apps where browser chrome does not protect the edge.sheet
--opsin-safe-bottomenv(safe-area-inset-bottom, 0px)The bottom safe-area inset, for installed web apps where browser chrome does not protect the edge.dialog, sheet
--opsin-safe-leftenv(safe-area-inset-left, 0px)The left safe-area inset, for installed web apps where browser chrome does not protect the edge.sheet