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
13pxgap 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-separationis 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 mode | Never changes |
|---|---|
| Columns and regions | Body text size |
| Whether a surface is a sheet or a pane | The touch floor and radius rungs |
| How much history and provenance shows | The line-length cap |
| The outer gutter | The 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:
- Header, with the screen's H1 and at most one secondary action.
- Content, one scrolling column.
- Action, the persistent primary action, pinned low but last in the DOM so focus reaches it after the content.
- 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
| Token | What it controls | Used by |
|---|---|---|
| --opsin-space-00rem | 0px. | no component |
| --opsin-space-10.25rem | Gap 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.5rem | Gap 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.75rem | Inner 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-41rem | The 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.25rem | Card inner padding on a phone. | avatar, button, consent-sheet, dialog, menu, questionnaire, sheet, slider, switch, symptom-picker |
| --opsin-space-61.5rem | Card 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-82rem | Gap between sections within a screen. | avatar, body-map, disclaimer-note, popover, range-bar, reading-input, sheet, stepper, tab-bar |
| --opsin-space-102.5rem | Space above a section heading. | avatar, sheet, skeleton, switch |
| --opsin-space-123rem | Gap between major regions of a screen. | avatar, trend-sparkline |
| --opsin-space-164rem | Top of a screen below the safe area; the space a consent sheet leaves above its first question. | dialog, skeleton |
| --opsin-space-205rem | Empty-state vertical rhythm. | no component |
| --opsin-space-246rem | The largest step. Beyond this, use a layout, not a gap. | no component |
| --opsin-space-px0.0625rem | Hairline borders only. | body-map, trend-sparkline |
| --opsin-space-0-50.125rem | Optical 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.75rem | The 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-comfortable3rem | The default for a primary action in the product theme. | dialog |
| --opsin-target-generous3.5rem | A single primary action on a consent, escalation or emergency surface, where a mis-tap has a real cost. | no component |
| --opsin-target-separation0.5rem | The 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-phone16px | The screen gutter in the phone responsive mode. | no component |
| --opsin-gutter-tablet24px | The screen gutter in the tablet responsive mode. | no component |
| --opsin-gutter-wide32px | The screen gutter in the wide responsive mode. | no component |
| --opsin-measure-tight45ch | A caption or a legend. | dialog, empty-state, goal-ring, popover, tooltip |
| --opsin-measure-comfortable66ch | The 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-wide80ch | Code and machine output only. | no component |
| --opsin-graphic-dial17rem | The 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 |