# 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 `currentColor` so they follow their text; muted by default, accent only when active.

## States checklist

Every interactive component needs:

| State          | Treatment                                                       |
| -------------- | --------------------------------------------------------------- |
| Default        | as designed                                                     |
| Hover          | a small shift: background tint, darker border, underline        |
| Focus-visible  | a clear 2px ring with offset, never removed                     |
| Active/pressed | darker or slightly inset                                        |
| Selected       | accent or strong neutral; not just bold                         |
| Disabled       | reduced contrast and no hover, with a reason nearby if possible |
| Loading        | spinner or skeleton, size preserved                             |
| Error          | danger color, icon, message                                     |
