Components And States

Components, Variants & States

A component is a contract: a stable anatomy (named parts), an API (props/slots), and a complete state matrix. Ship all three or you ship a liability. The #1 source of "feels broken" UI is missing states — not missing features.

1. Component anatomy — the parts model

Every component decomposes into named parts. Name them; style each part independently; expose them as slots. Headless libraries (Radix, ARK, React Aria) formalize this as Root, Trigger, Content, Item, etc.

┌─ Container (Root) ──────────────────────────────┐
│  [leading slot]  Label / Value  [trailing slot] │
│                  Helper / Description text       │
└─────────────────────────────────────────────────┘

Rule: A slot accepts arbitrary children (composition); a prop configures a fixed dimension (config). Prefer slots for content, props for behavior/appearance. See §9.

2. The interaction state matrix (define + treat EVERY one)

This is the heart of the skill. Each state needs a defined visual treatment and a11y signal. Use data-state attributes (set by headless libs or your own code) + native pseudo-classes.

Combined states are real: hover + selected, focus-visible + invalid, loading + disabled. Test them. Precedence (highest wins): disabled > loading > error > selected/active > focus-visible > hover > rest. A disabled element shows no hover and no error styling change on pointer.

/* Modern state-driven button — pseudo-classes + data-state + tokens */
.btn {
  --btn-bg: var(--accent-9);
  --btn-fg: white;
  display: inline-flex; align-items: center; gap: var(--space-2);
  block-size: var(--control-h-md); padding-inline: var(--space-4);
  border-radius: var(--radius-2); border: 1px solid transparent;
  background: var(--btn-bg); color: var(--btn-fg);
  font: inherit; cursor: pointer;
  transition: background .12s, box-shadow .12s, transform .04s;
}
.btn:where(:hover)            { --btn-bg: var(--accent-10); }
.btn:active                   { transform: translateY(.5px) scale(.99); }
.btn:focus-visible            { outline: 2px solid var(--focus-ring); outline-offset: 2px; }
.btn:disabled,
.btn[aria-disabled="true"]    { opacity: .5; cursor: not-allowed; }
.btn[aria-busy="true"]        { pointer-events: none; }
.btn[data-state="loading"] .btn__label { visibility: hidden; }
/* :where() keeps specificity 0 so app overrides win without !important */

Use :is()/:where() to group selectors, and :has() for parent-aware styling (.field:has(:invalid) lights the whole field). Prefer :focus-visible over :focus — never strip the ring without replacing it.

3. Variants vs sizes vs states vs shape

Keep these axes orthogonal. A button is variant × size × state, not 30 hand-named classes.

• Semantic variants (intent/emphasis): primary (one per view), secondary, tertiary, ghost (transparent until hover), outline, danger/destructive, link. Map to meaning, not color — themes reskin them.
• Sizes (one scale, shared across controls):

• Shape: rounded (default), pill (border-radius: 9999px), square (icon-only). Shape ≠ size.
• States: §2 — runtime, never a variant.

Props API design: variant, size, shape, plus boolean state-ish props (disabled, loading, selected). Booleans use is/has/can/should. Avoid boolean explosion (isPrimary isSecondary…) — use one variant union. Validate at the boundary (Zod / TS union). Slots (leadingIcon, children, trailingIcon) over a dozen content props.

4. Core components — anatomy · states · a11y

5. Sizing tokens

Touch targets are non-negotiable on mobile: a 24px icon-button needs invisible padding to reach 44/48. Spacing between adjacent targets ≥8px.

6. States in code — attributes & theming

Drive styling off semantic attributes, not class soup:

<button data-state="loading" aria-busy="true" disabled>…</button>
<div role="tab" aria-selected="true" data-state="active" tabindex="0">…</div>
<div class="field" data-invalid>
  <input aria-invalid="true" aria-describedby="email-err" />
  <p id="email-err" role="alert">Enter a valid email.</p>
</div>

/* Per-component theming via CSS custom properties — override anywhere up the tree */
.field {
  --field-border: var(--gray-7);
  --field-ring: var(--accent-8);
}
.field:has(:focus-visible) { box-shadow: 0 0 0 2px var(--field-ring); }
.field:has([aria-invalid="true"]),
.field[data-invalid]       { --field-border: var(--red-8); }
.field input               { border: 1px solid var(--field-border); }
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: .01ms !important; transition-duration: .01ms !important; }
}

data-state (open/closed/active/loading) reads cleanly, is what Radix/ARK emit, and survives SSR. Reserve ARIA for semantics the AT needs (aria-busy, aria-invalid, aria-expanded), not for styling hooks you could express with data-*.

7. Density, RTL, theming, composition, control model

• Density modes: a single --density knob scaling heights/padding (comfortable 40 / compact 32 / spacious 48). Drive via data-density on root → recompute token sizes. Don't shrink touch targets below platform minimums in compact mode on touch devices.
• RTL: use logical properties everywhere (margin-inline-start, padding-block, inset-inline-start, text-align: start). Set dir="rtl"; mirror directional icons (chevrons, back arrows) but not literal ones (clock, logos). :dir(rtl) selector for the rest.
• Theming hooks: token layers — primitive (--blue-500) → semantic (--accent-9, --fg, --bg) → component (--btn-bg). Theme by reassigning semantic tokens ([data-theme=dark]). Support color-scheme + prefers-color-scheme. Never hardcode hex in a component.
• Composition over config: prefer <Card><Card.Header/><Card.Body/></Card> slots over a 20-prop <Card title subtitle media footer …/>. Slots scale; config props don't (rule of 3 before adding a prop).
• Controlled vs uncontrolled: support both. Uncontrolled (internal state, defaultValue) for simple cases; controlled (value + onChange) when the parent owns truth. Pattern: value ?? internalState. Document which props make it controlled. Never silently switch a component between the two.

8. Cross-platform component equivalences

Platform conventions differ: iOS puts primary nav at the bottom tab bar; Material uses bottom navigation (≤5 items) or a nav rail/drawer; web is flexible (top or side). Respect each platform's default control rather than porting web pixel-for-pixel. Map intent to native components; don't reskin a web button to look iOS-native — use the platform control.

9. Common mistakes (do / don't)

Checklist before "component done": anatomy named · all §2 states defined incl. combined · focus-visible ring · disabled has a reason · loading/empty/error exist · touch target ≥44/48 · keyboard-operable · labelled for AT · sizes from the scale · RTL via logical props · reduced-motion honored · controlled+uncontrolled supported.