Components and states

A component is not done until every state is designed. The default state is the easy tenth of the work. Hover, focus, disabled, loading, error and empty are where interfaces feel finished or broken.

This page lists the states, how each is triggered and styled, the target sizes, and the prop names every component in a project should share.

See themCopy Anchor Link

Every state, namedCopy Anchor Link

• MUST design every row that applies before a component is marked done. Missing states go in the pull request as open items.
• MUST put hover styles behind @media (hover: hover). Tailwind v4's hover: variant already does this; hand-written CSS must add it, or touch screens keep a sticky hover after a tap.
• MUST use :focus-visible, not :focus, for the focus ring, so mouse clicks do not flash it and keyboards always see it.
• MUST keep the focus ring at 3:1 contrast against the background next to it (WCAG 2.2, 1.4.11).
• MUST NOT show state by colour alone. Pair it with an icon, text, weight or position (WCAG 2.2, 1.4.1).

The order of state stylesCopy Anchor Link

When several states apply at once, the later rule must win. Write them in this order:

.button { /* default */ }
.button:hover { }
.button:focus-visible { }
.button:active { }
.button[aria-busy='true'] { }
.button:disabled,
.button[aria-disabled='true'] { } /* last: disabled beats everything */

Focus ringCopy Anchor Link

One ring for the whole product. Copy it once, reference it everywhere.

:root { --color-focus: var(--color-accent); }

:where(a, button, input, select, textarea, [tabindex]):focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

• MUST NOT write outline: none without a replacement focus style in the same rule.
• SHOULD use outline, not box-shadow, for focus. Outlines stay visible in Windows high contrast mode.

Disabled, loading, error, emptyCopy Anchor Link

• Disabled. Use the disabled attribute when the control does nothing and needs no explanation. Use aria-disabled="true" when it must stay focusable to show a tooltip explaining why. SHOULD prefer explaining over disabling: a submit button that stays enabled and then points at the missing field teaches more than a grey one.
• Loading. MUST keep the button the same width, so the layout does not jump. MUST ignore repeat clicks while pending. SHOULD wait about 300ms before showing a spinner, so fast responses never flash one, and keep the label readable to screen readers (aria-busy="true" plus visually hidden "Saving…").
• Error. MUST say what went wrong and how to fix it, next to the field, in text. MUST keep what the person typed. MUST move focus to the first invalid field on submit.
• Empty. MUST tell three cases apart: first use ("No projects yet"), no results ("No projects match 'rivr'"), and cleared ("All caught up"). Each gets a heading, one sentence and at most one action.

Touch targetsCopy Anchor Link

• MUST give every control a hit area of at least 44 × 44px on touch screens. This is the house rule in the rules.
• MUST never go below 24 × 24px anywhere, including dense desktop tables.
• SHOULD leave at least 8px between neighbouring targets.
• SHOULD grow the hit area, not the visual, when the design needs a small control:

.icon-button { position: relative; width: 32px; height: 32px; }
.icon-button::after {
  content: '';
  position: absolute;
  inset: 50% auto auto 50%;
  width: 44px;
  height: 44px;
  translate: -50% -50%;
}

One API for every componentCopy Anchor Link

Every component takes the same prop names for the same ideas. Learn one, know them all.

Sizes map to fixed heights, so buttons, inputs and selects line up in a row:

sm is below 44px, so on touch screens it needs the hit-area pattern above.

import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/cn';

const button = cva(
  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors duration-150 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        primary: 'bg-accent text-white hover:bg-accent-hover',
        secondary: 'border border-border bg-surface-raised hover:bg-surface',
        ghost: 'hover:bg-surface-raised',
        destructive: 'bg-danger text-white hover:bg-danger-hover',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-5 text-base',
      },
    },
    defaultVariants: { variant: 'secondary', size: 'md' },
  },
);

type ButtonProps = React.ComponentProps<'button'> & VariantProps<typeof button> & { loading?: boolean };

export function Button({ variant, size, loading = false, disabled, className, children, onClick, ...props }: ButtonProps) {
  return (
    <button
      type="button"
      className={cn(button({ variant, size }), className)}
      disabled={disabled}
      aria-busy={loading || undefined}
      onClick={loading ? (e) => e.preventDefault() : onClick}
      data-size={size ?? 'md'}
      {...props}
    >
      {children}
    </button>
  );
}

• MUST use string unions for visual options: variant="ghost", never a boolean like ghost or isGhost. Booleans multiply into impossible combinations.
• MUST spread remaining props onto the root element and accept ref, so native attributes, test IDs and aria-* just work. In React 19, ref is an ordinary prop.
• MUST default type="button" on buttons, so a button inside a form does not submit it by accident.
• MUST use the native attribute name when one exists: disabled, required, open, checked.
• SHOULD expose state as data attributes (data-state="open", data-size="md") so callers can style it without new props.
• SHOULD keep variant to four values or fewer. A fifth variant usually means a second component.
• SHOULD NOT add a prop for every style tweak (rounded, shadow, color). That is what className is for.

Controlled and uncontrolledCopy Anchor Link

A stateful component, such as a tabs set, a dialog, a switch or a text field, SHOULD work both ways. Uncontrolled for quick use, controlled when the parent needs the value.

import { useState } from 'react';

export function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (v: T) => void) {
  const [inner, setInner] = useState(defaultValue);
  const controlled = value !== undefined;
  const current = controlled ? value : inner;
  const set = (next: T) => {
    if (!controlled) setInner(next);
    onChange?.(next);
  };
  return [current, set] as const;
}

• MUST name the trio value, defaultValue, onValueChange, and the same for open and checked. Never initialValue, isOpen or setOpen.
• MUST pass the new value as the first argument of the change event, not the DOM event.
• MUST NOT switch a component between controlled and uncontrolled during its life. React warns, and state goes out of sync.

Why it worksCopy Anchor Link

States are where people decide whether software can be trusted: a button that does nothing visible on press, or a form that eats their input on error, feels broken even when it works. Shared prop names make a component library feel like one product, because once someone knows how Dialog opens, they already know how Popover and Accordion do.

SourcesCopy Anchor Link