Components

Components are where usability lives. Keep them predictable and consistent; let the direction show in their surface (type, color, radius, border), not in unusual behavior.

Buttons

  • Three levels: primary (solid accent fill), secondary (outline or tonal fill), tertiary (text only). One primary per region; most buttons on a screen should be secondary or tertiary.
  • Heights from the density: 32, 40 or 48px, matching the inputs beside them.
  • Labels say what happens: "Save changes", "Send invite", "Delete project". Not "OK", "Submit", "Yes".
  • Icons go before the label, 16–20px, with 8px between them. Icon-only buttons need a tooltip and an accessible name.
  • Destructive actions use the danger color at the moment of confirmation, not everywhere a delete appears.
  • Loading keeps the button's width and shows a spinner or progress in place of the label or beside it.
  • Placement stays consistent: primary on the right in dialogs and toolbars, or on the left of a form's footer. Pick one and keep it.

Inputs and forms

  • A visible label above every field. Placeholders are examples, never labels.
  • Helper text below the field in the secondary text color; an error replaces or joins it, in the danger color, with an icon and a message saying how to fix it ("Use at least 8 characters", not "Invalid input").
  • Input height matches the buttons; borders at 3:1 contrast or stronger; a clear focus ring (2px, offset, accent).
  • Group related fields under a short heading. Ask only for what's needed; mark optional fields rather than required ones when most are required.
  • Use the right control: segmented controls for 2–4 options, radios for up to about 6 visible choices, a select or combobox beyond that, toggles only for settings that apply immediately.
  • Validate on blur or submit, not on every keystroke.

Cards

  • Use a card when the content is a separate object people act on: something they click, drag, select or compare. Otherwise, grouping with space and headings is calmer.
  • Never nest cards in cards. Inside a card, separate with space and dividers.
  • Consistent padding (16–24px) and a clear internal hierarchy: one title, one key value or image, muted metadata, at most one or two actions.
  • If the whole card is clickable, make it obviously so (hover state, cursor) and avoid buttons inside it that compete.

Tables and lists

  • Left-align text, right-align numbers (with tabular figures), and align headers with their column's content.
  • Use row dividers or zebra striping, not both. Hover rows in interactive tables.
  • Muted, smaller headers; the data is the point.
  • Truncate long text with an ellipsis and a way to see the rest; don't let one column explode the layout.
  • Sticky header for long tables; pagination or virtual scrolling for very long ones.
  • Every list has an empty state, a loading state and an error state.
  • The current location is always obvious: a strong active state, not just a slightly different gray.
  • Five to seven top-level items at most; group the rest.
  • Icons with labels in sidebars; labels alone are fine in top navigation; icons alone only for universally known actions.
  • Breadcrumbs for deep hierarchies; tabs for switching views of the same object.

Badges, tags and status

  • Tonal: a light tint background with dark text of the same hue. Solid fills only for the single most urgent status.
  • Keep the set of status colors small and meaningful, and pair color with a word or an icon.
  • Small type (12px), medium weight, modest padding (2–4px × 8px).

Dialogs, popovers and toasts

  • Dialogs interrupt. Use them for decisions that need focus (confirming a destructive action, a short form), not for information.
  • The title states the action ("Delete 3 files?"); the body says the consequence; the buttons repeat the verb ("Delete files" / "Cancel").
  • Escape and a click outside close non-destructive dialogs; focus moves into the dialog and returns when it closes.
  • Toasts for quiet confirmation of something that already happened, with Undo where possible. Errors that need action stay inline.
  • Skeletons for loading that takes longer than about 300ms, in the shape of the content to come.

Elevation, radii and borders

  • Two or three elevation levels: base, raised (cards, menus), overlay (dialogs). In dark themes, raise by lightening the surface.
  • Shadows look real when they're layered: a tight, slightly darker one for contact and a large, soft, faint one for distance, tinted with the text or surface hue. For example 0 1px 2px rgb(20 18 15 / 0.06), 0 8px 24px rgb(20 18 15 / 0.08).
  • Radius grows with size: chips and checkboxes smaller, cards and dialogs larger, all from the direction's personality. Nested corners: inner radius = outer radius − padding.
  • Borders at one weight (1px, or 2px in bold directions) and one or two colors.

Icons

  • One set throughout (Lucide, Phosphor, Tabler, Heroicons) at one stroke width (1.5 or 2px).
  • Sized to the text: 16px beside 13–14px text, 20px beside 16px, 24px for standalone.
  • Colored with currentColor so they follow their text; muted by default, accent only when active.

States checklist

Every interactive component needs:

Defaultas designed
Hovera small shift: background tint, darker border, underline
Focus-visiblea clear 2px ring with offset, never removed
Active/presseddarker or slightly inset
Selectedaccent or strong neutral; not just bold
Disabledreduced contrast and no hover, with a reason nearby if possible
Loadingspinner or skeleton, size preserved
Errordanger color, icon, message