Foundations
Typography
The platform UI font, a type scale named for jobs rather than sizes, and the reader's own text size.
opsinjs ships no typeface. The product theme's --font-sans starts with ui-sans-serif, system-ui, so the device answers: SF Pro on an iPhone, Roboto on Android, Segoe UI Variable on Windows.
Why the system font
- It is the font the reader already reads, tuned for the screen in their hand.
- Bold text, larger accessibility sizes and the platform's text-size controls apply to the system font.
- It never loads, so text never flashes or waits.
- SF Pro cannot be served as a webfont, because Apple licenses it for Apple platforms and not for redistribution. Read Apple's licence yourself.
system-uireaches the copy already installed.
A brand face is an opt-in through --font-sans.
Type scale
Roles are named for their job, not their size. Each sets size, line height, tracking and weight, and text-opsin-<role> applies it.
| Role | Use it for |
|---|---|
large-title | One number or word that is a surface's whole subject. No component uses it yet |
title1 | A screen title, and the display number in Value |
title2 | A section title, and the floor for a primary health value in a card |
title3 | A Dialog or Sheet title, and the unit beside a display value |
headline | A card title or an emphasised lead line, at body size and heavier |
body | Default reading text, at 17px |
callout | Secondary prose in a dense container |
subheadline | The label beside a value. subheadline-emphasis is its heavier twin for a compact control |
footnote | Provenance: who measured this, when, with what |
caption1 | Axis labels, legends and legal text |
caption2 | The floor, only for text that repeats a label shown elsewhere |
- Pick the role, never the size, and default to
body. - Set a health value at
title2or larger, and never belowbody. - A role is not a heading level. Choose
h2from the page outline and the role from how it should look. - Use two weights, three at most. Size and weight show hierarchy, never status.
- Nothing is smaller than
caption2. If text does not fit, change the layout.
Tabular figures
The product theme sets font-variant-numeric: tabular-nums on anything carrying data-opsinjs-value, so a changing reading does not shift the layout. The role does not set tabular figures, and font-opsin-numeric sets only the family. A resting heart rate is 62 in title1 with the attribute, bpm in title3, the label in subheadline and "Measured 3 hours ago" in footnote.
Text size
Every component must survive a 1.3× text multiplier with no clipping, truncation, overlap or horizontal scroll, and the system must stay usable at 200%. Every role is in rem and the multiplier is applied once at the root, so the reader's setting reaches every step. A single px font size opts that element out. Check with the text-size switch on any component preview.
Five layout habits break first:
- Fixed heights. Use a minimum height and let content decide.
white-space: nowrapand ellipses. Never truncate a value, a unit or a status word.- Label and value pairs forced side by side. Stack them with a container query.
- Icons sized in px beside text. Size them in
em. - Sticky headers and action bars. Let them collapse.
Never disable text scaling with a viewport meta tag, a fixed px size on the root or text-size-adjust: none. Set lang on the document, because hyphenation and screen-reader pronunciation depend on it.
Tokens
| Token | What it controls | Used by |
|---|---|---|
| --opsin-font-sanssystem-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif | The sans family stack. | no component |
| --opsin-font-monoui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace | The mono family stack. | no component |
| --opsin-font-numericsystem-ui, -apple-system, 'Segoe UI', Roboto, sans-serif | The numeric family stack. | result-card, value |
| --opsin-text-large-title-size2.125rem | The largest step in the scale, reserved for a surface whose entire subject is one number or one word. No component in the system sets a value at this step yet. | no component |
| --opsin-text-large-title-leading1.118 | Line height for largeTitle, unitless so it scales with the size. | no component |
| --opsin-text-large-title-tracking-0.032em | Letter spacing for largeTitle. | no component |
| --opsin-text-large-title-weight800 | Font weight for largeTitle. | no component |
| --opsin-text-title1-size1.75rem | A screen title, and the hero treatment a value's number takes at size display. | goal-ring, result-card, value |
| --opsin-text-title1-leading1.143 | Line height for title1, unitless so it scales with the size. | goal-ring, result-card, value |
| --opsin-text-title1-tracking-0.026em | Letter spacing for title1. | goal-ring, result-card, value |
| --opsin-text-title1-weight800 | Font weight for title1. | goal-ring, result-card, value |
| --opsin-text-title2-size1.375rem | Section title; the floor for a primary health value inside a card. | no component |
| --opsin-text-title2-leading1.227 | Line height for title2, unitless so it scales with the size. | no component |
| --opsin-text-title2-tracking-0.018em | Letter spacing for title2. | no component |
| --opsin-text-title2-weight700 | Font weight for title2. | no component |
| --opsin-text-title3-size1.25rem | A Dialog or Sheet title, and the unit beside a value's number at size display. | dialog, goal-ring, questionnaire, reading-input, sheet, value |
| --opsin-text-title3-leading1.25 | Line height for title3, unitless so it scales with the size. | dialog, goal-ring, questionnaire, reading-input, sheet, value |
| --opsin-text-title3-tracking-0.014em | Letter spacing for title3. | dialog, goal-ring, questionnaire, reading-input, sheet, value |
| --opsin-text-title3-weight700 | Font weight for title3. | dialog, goal-ring, questionnaire, reading-input, sheet, value |
| --opsin-text-headline-size1.0625rem | An emphasised line of body text, such as a status sentence or a question in a form. | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value |
| --opsin-text-headline-leading1.412 | Line height for headline, unitless so it scales with the size. | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value |
| --opsin-text-headline-tracking-0.006em | Letter spacing for headline. | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value |
| --opsin-text-headline-weight600 | Font weight for headline. | accordion, alert-banner, avatar, button, callout, card, care-card, empty-state, field, log-sheet, menu, popover, range-bar, reading-input, result-card, scale-input, segmented-control, status-pill, surface, tabs, textarea, timeline-entry, toast, trend-sparkline, value |
| --opsin-text-body-size1.0625rem | Everything a reader reads as prose. The anchor of the scale. | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden |
| --opsin-text-body-leading1.412 | Line height for body, unitless so it scales with the size. | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, skeleton, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden |
| --opsin-text-body-tracking-0.003em | Letter spacing for body. | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden |
| --opsin-text-body-weight400 | Font weight for body. | accordion, alert-banner, badge, callout, card, care-card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, empty-state, field, goal-ring, link, menu, number-field, popover, questionnaire, radio-group, range-bar, range-legend, reading-input, relative-time, result-card, score-dial, scroll-area, select, sheet, surface, switch, symptom-picker, table, tabs, term, textarea, timeline-entry, toast, tooltip, trend-sparkline, value, visually-hidden |
| --opsin-text-callout-size1rem | Secondary prose inside a card or a callout. | dialog, sheet, toast |
| --opsin-text-callout-leading1.375 | Line height for callout, unitless so it scales with the size. | dialog, sheet, toast |
| --opsin-text-callout-tracking-0.002em | Letter spacing for callout. | dialog, sheet, toast |
| --opsin-text-callout-weight400 | Font weight for callout. | dialog, sheet, toast |
| --opsin-text-subheadline-size0.9375rem | A supporting line under a title. | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table |
| --opsin-text-subheadline-leading1.333 | Line height for subheadline, unitless so it scales with the size. | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table |
| --opsin-text-subheadline-tracking-0.001em | Letter spacing for subheadline. | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table |
| --opsin-text-subheadline-weight400 | Font weight for subheadline. | care-card, empty-state, goal-ring, metric-tile, progress, radio-group, score-dial, segmented-control, slider, spinner, status-pill, stepper, table |
| --opsin-text-subheadline-emphasis-size0.9375rem | The emphasised twin of subheadline, for a compact control's label, where the control must read as narrower and never as quieter. | avatar, button |
| --opsin-text-subheadline-emphasis-leading1.333 | Line height for subheadlineEmphasis, unitless so it scales with the size. | avatar, button |
| --opsin-text-subheadline-emphasis-tracking-0.001em | Letter spacing for subheadlineEmphasis. | avatar, button |
| --opsin-text-subheadline-emphasis-weight600 | Font weight for subheadlineEmphasis. | avatar, button |
| --opsin-text-footnote-size0.8125rem | Provenance: who measured this, when, with what. | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline |
| --opsin-text-footnote-leading1.385 | Line height for footnote, unitless so it scales with the size. | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline |
| --opsin-text-footnote-tracking0em | Letter spacing for footnote. | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline |
| --opsin-text-footnote-weight400 | Font weight for footnote. | body-map, card, checkbox, combobox, consent-sheet, dialog, disclaimer-note, divider, dose-tracker, goal-ring, log-sheet, menu, metric-tile, questionnaire, radio-group, range-bar, range-legend, result-card, scale-input, score-dial, sheet, source-citation, status-pill, stepper, switch, symptom-picker, table, timeline-entry, toast, tooltip, trend-sparkline |
| --opsin-text-caption1-size0.75rem | Axis labels, legend text, and legal text. | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden |
| --opsin-text-caption1-leading1.333 | Line height for caption1, unitless so it scales with the size. | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden |
| --opsin-text-caption1-tracking0.002em | Letter spacing for caption1. | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden |
| --opsin-text-caption1-weight400 | Font weight for caption1. | avatar, badge, consent-sheet, dose-tracker, range-bar, skeleton, tab-bar, visually-hidden |
| --opsin-text-caption2-size0.6875rem | The smallest text the system permits, and only for text that repeats a label already present elsewhere. Never the only place a fact appears. | no component |
| --opsin-text-caption2-leading1.273 | Line height for caption2, unitless so it scales with the size. | no component |
| --opsin-text-caption2-tracking0.01em | Letter spacing for caption2. | no component |
| --opsin-text-caption2-weight600 | Font weight for caption2. | no component |
| --opsin-numeralstabular-nums | Every component that renders a number sets this, so a changing value does not shift its own layout. | no component |