Skip to content

Harbor DS / components

The parts, typed

Every entry is rendered from its schema and fixtures: the examples are the real components, the schema block is the real source, and the build checks that each loading state keeps its footprint.

40 components in 8 groups: 0 in draft, 40 in review, 0 stable.

How to read an entry

  1. Header. The name, its status, the coverage ids it closes, what it is for, and the one decision it honors.
  2. Example and Anatomy. The real component, then each of its parts, numbered against the rendered markup.
  3. Variants and sizes, States, Density and theme, Edges. Every form it takes: each variant and size, each state at rest and forced, both densities and themes, and three container widths.
  4. Do and don't, Accessibility. The rule each pair proves, and how the component reads to assistive technology.
  5. Schema. Its typed source, and every token it reads, with links to the foundations that define them.

Status

Draft
Its batch is still being built. Anything in it can change.
Review
Built and reported. It waits on an independent review and on a product flow that uses it.
Stable
Reviewed, and used by at least one flow. Safe to build on.

Layout nodes

Layout ยท PG-15, S-07, B-14

BentoGrid

Review

A mosaic of metric tiles in grid units: two 2-unit tiles stack to exactly one 4-unit tile. Registered as a node; behavior unchanged from DS-C1.

Honors: Give it a size, it lays itself out, and DOM order is reading order at every width (DS-C1, DS-P1 ยง14).

Layout ยท PG-15

Cluster

Review

A variable count of intrinsically sized items on a line that wraps: chips, codes, meta facts, action rows.

Honors: Chips, codes and action rows wrap between items, never inside one (DS-P1 ยง15.7).

Layout ยท PG-15

Split

Review

Two regions side by side from a container width up, stacked in DOM order below it. The patient header's identity and actions split.

Honors: Reflow moves a region from beside to below, never up; components answer to their pane, not the viewport (DS-P1 ยง15.10).

Layout ยท PG-15

Stack

Review

The default layout: a vertical sequence with one gap. A loading stack loads its whole subtree at once.

Honors: Every gap is a rung on the ladder; no magic numbers (DS-P1 ยง15.5).

Actions

Actions ยท P-01, H-08 (call)

Button

Review

One label, one command. Eight intents say what kind of action it is; six sizes come from one formula.

Honors: Tonal buttons are the status-pill family, and violet is the one key action per screen (DS-P1 ยง3.4, Nik).

Actions ยท P-01 (icon form), H-08 (call)

IconButton

Review

A square control with one glyph, for dense toolbars, rows and the in-call bar.

Honors: An icon alone names nothing: the label is required, and it is the accessible name.

Actions ยท PG-14 (Link)

Review

Navigation in running text, a row or a card footer. Text-sized: it takes the type role around it, not the control scale.

Honors: Links are underlined, because color alone fails WCAG 1.4.1 (DS-P1 ยง3.2). A link goes somewhere; doing something is a Button.

Actions ยท P-26, PG-03 (context menu)

Menu

Review

The commands that do not earn a button of their own: a row's actions behind `more`, a Send menu, a region's context menu; and the site's page picker where its segments do not fit. Commands or links; a choice of values is a Select, a Combobox or a SegmentedControl.

Honors: A destructive command is set apart by construction: its own list, last, after a divider, in the tonal critical form and never a solid fill.

Actions ยท P-10

SegmentedControl

Review

One choice among two to four equals, on one track: going to a page (nav), switching panels in place (tabs) or setting a value (radio). The specimen's page picker and display options.

Honors: Selected is a raised segment, never the solid focus form and never a second stroke: selection and focus must never look alike.

Status

Status ยท P-16, F-04

Avatar

Review

A person: their photo (optional, approved for the chart header), or their initials on their own earthy tint.

Honors: A person keeps one color everywhere: the tint is hash(id) mod 5, never chosen by the caller, and never olive or forest (DS-P1 ยง3.7).

Status ยท P-14

Badge

Review

A count on something else: a nav item, a tab, a button. Counts only; a status is a StatusChip or StatusDot.

Honors: A number alone names nothing: the label says the whole count ("3 unread messages"), and the digits are decorative.

Status ยท PG-17, H-23

CopyValue

Review

An identifier staff copy into another system: an MRN, a member ID, a claim number. Text-sized, so it sits in a line of facts.

Honors: A value you copy whole is one button, named for the whole action ("Copy MRN 0084-117-OI09"). A value's data tag masks it (D43, F-A8), and the masked value is itself the reveal (Nik, D47): press it to see the value, which masks itself again; the copy glyph still copies the whole value.

Status ยท P-13 (toned), S-09, B-03, M-08, H-26

StatusChip

Review

A clinical status in a word, with its role's glyph. Generic: domain components derive the tone from their status.

Honors: Every status carries an icon and a word; color is never alone (DS-P1 ยง3.5, the tonal recipe Nik approved).

Status ยท PG-16

StatusDot

Review

A status where a chip will not fit: a row's leading edge, an avatar's corner, a nav item.

Honors: Color is never the only cue: the dot's label is always present for assistive tech, and the quiet roles differ in shape.

Status ยท P-13 (neutral)

Tag

Review

Neutral metadata: a source, a category, a visit type. Statuses use StatusChip.

Honors: Metadata is never a status: a tag has no tone and no glyph, so it can never be read as one.

Content

Content ยท M-07, DM-07

Attachment

Review

One file shown as a file: in an upload, a message, a document list. The one file display in the system (ยง1.8).

Honors: A file that did not arrive always says what to do next: failed and blocked carry a Problem, with a fix or a handoff (D50).

Content ยท P-33

Divider

Review

A hairline between groups that space alone cannot separate. Labelled, it names the group that follows.

Honors: Box only what you can act on; inside one, a rule (DS-P1 ยง15.3). A divider is the last resort after space.

Content ยท F-01, DM-01

Icon

Review

One glyph from the page sprite, at a control tier's icon size or the size of the control it sits in.

Honors: A closed set of simple geometric glyphs drawn for Harbor; status glyphs carry meaning only next to a word.

Content ยท P-34

Kbd

Review

A keyboard shortcut, one cap per key in the order pressed, in menus, tooltips and help text.

Honors: A shortcut is a hint beside the action, never the only way to reach it.

Content ยท P-31

Skeleton

Review

The static loading shape: a line, a paragraph, a circle or a block, in the sunken fill, with no border.

Honors: Loading never shifts the layout: a skeleton has the footprint of what it stands for, and it is static (Nik).

Content ยท P-30

Spinner

Review

Named work in progress, for a wait whose shape is unknown. When the shape is known, the component skeletons itself instead.

Honors: No motion this sprint: work in progress is a named, static ring. The turn comes with the motion sprint.

Content ยท PG-14, H-25 (dates and times)

Text

Review

Text in one type role, from a plain string or typed runs. Dates and times come formatted, with their ISO value for machines.

Honors: Inter carries every role: one role per run of text, and every number in the data role (DS-P1 ยง4).

Forms

Forms ยท P-07

Checkbox

Review

One yes-or-no answer with its label beside the box: consent to reminders, "I need an interpreter", a select-all box over a list. Several answers to one question are a ChoiceGroup.

Honors: Checked is tonal, a tint and a glyph, never a solid fill; the mark's own border is the one focus stroke.

Forms ยท PG-10, P-08, B-10

ChoiceGroup

Review

A question answered by choosing: cards for the patient-facing question step, rows for practice forms; one answer, several, or a tap that answers and moves on. Checkbox: one yes-or-no answer. SegmentedControl: two to four short, equal views or settings applied at once, never a form answer. ChoiceGroup: a form answer from two to about seven options, any option that needs a description or a reason, or several answers to one question. Select: one answer from a known list of about eight or more short labels the person recognizes without comparing them. Combobox: a list too long to scroll, or one that comes from a search.

Honors: Selected is the brand tint plus a mark, never a solid fill and never colour alone; focus is one stroke, the card's border or, in a list, the mark's.

Forms ยท P-06

Combobox

Review

Finding one value in a long or remote list as the person types: a payer, a pharmacy, a provider. A short fixed list is a Select; two to four equal choices a SegmentedControl or ChoiceGroup.

Honors: A lookup's progress is `results`, and each arm carries only what it needs: a listbox can never claim options it does not hold, and searching is a skeleton, never an empty box.

Forms ยท PG-06, PG-07

DateTimeInput

Review

A date (a date of birth, a visit), a time of day (a dose, an arrival), or both (a specimen collected). Replaces DateInput and TimeInput.

Honors: Dates and times are typed as numbers, one short box per part, in the order and with the hints the locale and the org's clock give (format.ts): no generator writes "DD/MM/YYYY", and nobody guesses the order. Shown, not edited, a value reads in the system's formats: "Oct 23, 2026", "10/23/2026", "2:30 PM".

Forms ยท P-04, DM-11 (with SegmentedControl)

SearchField

Review

Filtering a list or finding a record: patients, the inbox, codes. Never disabled or read-only: a search that cannot be used is not shown, and a value someone must read is a read-only TextInput, not a disabled one.

Honors: A filter is its own node, not a TextInput without its label (DS-C2b ยง1.2): a search landmark around the same harbor-input surface, named by a hidden label, with Enter as its one command and a local clear.

Forms ยท P-05

Select

Review

One answer from a known list, in the native list the platform draws: a relationship, a language, a state. Checkbox: one yes-or-no answer. SegmentedControl: two to four short, equal views or settings applied at once, never a form answer. ChoiceGroup: a form answer from two to about seven options, any option that needs a description or a reason, or several answers to one question. Select: one answer from a known list of about eight or more short labels the person recognizes without comparing them. Combobox: a list too long to scroll, or one that comes from a search.

Honors: A Select never picks for the person: with no value it shows its placeholder, and a locked Select refuses the change itself.

Forms ยท P-03

Textarea

Review

Free text over several lines: a visit reason, a note to the clinic, an address.

Honors: A text area is a fixed number of lines from a short scale, in every state, so nothing moves under the person typing; a maximum shows as a count of characters used, in the hint line, never as a surprise at the limit.

Forms ยท P-02, PG-05 (through FieldFrame)

TextInput

Review

One line of text a person types: a name, an email, a phone number, a password, a number with its unit.

Honors: A field shows its label, its hint and its error in words, always visible, and holds one tag that says what its value is. The kind brings the right keyboard, and a locked field that holds an identifier is masked by its tag, never by its label (D66 as amended).

Feedback

Feedback ยท PG-01, L-08, P-23 (problem)

Callout

Review

A note set into the content: a calm brand note, a status the reader should know, or a failure with its fix.

Honors: A problem always comes with a way forward, and it is drawn one way: an inline critical Callout (DS-C2b ยง1.9).

Feedback ยท P-32, PG-20

EmptyState

Review

What a container shows when it has nothing to show: why it is empty, and what the reader can do next.

Honors: EmptyState is the only empty-state expression, and each kind requires its own way forward (DS-C2b ยง1.14).

Feedback ยท P-29, B-07 (meter)

ProgressBar

Review

How far a task has gone, or where a quantity sits in its range, with the amount said in words.

Honors: One bar for every known amount; an unknown amount is a Spinner, and the bar never carries a status color (DS-C2b ยง1.6).

Feedback ยท P-23

Toast

Review

A short message about something the reader just did, with Undo when it can be reversed, or the way forward when it failed.

Honors: Toasts name the new value, offer Undo for 6 s that pauses on hover or focus, and errors persist with an action; never a toast for routine autosave (DS-R4 ยง7.14).

Overlays

Overlays ยท P-21, P-22 (panel), M-05 (lightbox width)

Dialog

Review

Two kinds, one pattern. A confirm asks one question and states what it will change. A panel holds work that does not fit the page; on a phone it is a bottom sheet.

Honors: A modal never uses the top layer, and never makes the call, toast or dialog regions inert, so End stays reachable (D68, D69).

Overlays ยท P-25, toggletip pattern

Popover

Review

A small non-modal dialog anchored to the control that opened it: the toggletip that explains a number, the chip that edits one value. Anything larger is a Dialog panel; a list of commands is a Menu.

Honors: An anchored popup is never in the top layer and renders beside the control that opened it, so it stays in that control's region: inside a dialog's trap, inside the call bar (D68, D69).

Containers

Containers ยท P-17, P-18

Card

Review

A titled container: a visit, a coverage, a consent, a summary. Lift makes the whole card one link or button.

Honors: Actions anchor to the bottom with the one bottom-anchor rule, so cards that share a row end on one line (Nik).

Containers ยท DM-18, P-18 (facts)

DescriptionList

Review

Labelled values: a patient's facts, a document's metadata, an insurance card's fields. Not a form and not a ledger.

Honors: A read-only identifier is a CopyValue with its data tag inside the list, never words: masking follows the tag (ยง1.13, D61).

Containers ยท PG-02

Disclosure

Review

A titled section that opens and closes in place: a chart group, earlier visits, a note's history. Frameless, so it sits inside any container.

Honors: One toggle per region and nothing nested in it: the count rides inside the toggle as a Badge, the actions sit beside it.

Containers ยท P-19, S-08, DM-12, H-26

ListRow

Review

The base row for every list: medications, problems, inbox items, code rows. Domain rows render it and add no CSS (ยง1.18-3).

Honors: How a row is used is one union: a whole-row control holds nothing interactive, and only an option has selected, both by type (D10).