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.
Navigation
- 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
currentColorso they follow their text; muted by default, accent only when active.
States checklist
Every interactive component needs: