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
- Header. The name, its status, the coverage ids it closes, what it is for, and the one decision it honors.
- Example and Anatomy. The real component, then each of its parts, numbered against the rendered markup.
- 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.
- Do and don't, Accessibility. The rule each pair proves, and how the component reads to assistive technology.
- 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
ReviewA 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
ReviewA 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
ReviewTwo 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
ReviewThe 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
ReviewOne 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
ReviewA 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)
Link
ReviewNavigation 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-10
SegmentedControl
ReviewOne 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
ReviewA 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
ReviewA 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
ReviewAn 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
ReviewA 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
ReviewA 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
ReviewNeutral 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
ReviewOne 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
ReviewA 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
ReviewOne 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
ReviewA 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
ReviewThe 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
ReviewNamed 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
ReviewText 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
ReviewOne 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
ReviewA 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
ReviewFinding 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
ReviewA 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
ReviewFiltering 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
ReviewOne 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
ReviewFree 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
ReviewOne 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
ReviewA 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
ReviewWhat 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
ReviewHow 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
ReviewA 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
ReviewTwo 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
ReviewA 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
ReviewA 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
ReviewLabelled 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
ReviewA 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
ReviewThe 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).