` | | Form input | `` / `

### 4. Every Interactive Element Needs Four States

No component is complete without all four:

1. **Default** — The resting state
2. **Hover** — Visual feedback on cursor enter (desktop). Must not rely on hover alone for meaning.
3. **Focus** — Visible focus ring for keyboard navigation. Use `focus-visible` (not `focus`) to avoid showing on mouse click.
4. **Disabled** — Reduced opacity + `pointer-events-none` + `aria-disabled="true"`. Never hide disabled elements — show them grayed out.

Plus situational states:
- **Active/pressed** — Subtle scale or color shift on click
- **Loading** — Spinner or skeleton replacing content, with `aria-busy="true"`
- **Error** — Red border + error message linked via `aria-describedby`
- **Selected** — For toggles, tabs, menu items

### 5. Token Mapping

Map component styles to design system tokens, never raw values.

| Property | Token Source | Example |
|----------|-------------|---------|
| Background color | `colors.primary.*`, `colors.surface.*` | `bg-primary-600` |
| Text color | `colors.surface.foreground`, `colors.primary.*` | `text-neutral-900` |
| Padding | `spacing.scale` | `p-4` (1rem = spacing.4) |
| Border radius | `radii` | `rounded-md` |
| Box shadow | `shadows` | `shadow-subtle` |
| Font size | `typography.scale` | `text-sm` |
| Font weight | `typography.weights` | `font-medium` |
| Transition | `motion.durations` + `motion.easings` | `transition-colors duration-200` |

If a value isn't in the design system, that's a signal — either the system needs extending or the design is deviating.

## Component Anatomy Templates

### Button

```tsx
interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button"
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
```

### Card

```tsx
const Card = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
  ({ className, ...props }, ref) => (
    <div
      ref={ref}
      className={cn(
        "rounded-lg border border-neutral-200 bg-white shadow-subtle",
        className
      )}
      {...props}
    />
  )
)

const CardHeader = ({ className, ...props }) => (
  <div className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />
)

const CardTitle = ({ className, ...props }) => (
  <h3 className={cn("text-xl font-semibold tracking-tight", className)} {...props} />
)

const CardContent = ({ className, ...props }) => (
  <div className={cn("p-6 pt-0", className)} {...props} />
)

const CardFooter = ({ className, ...props }) => (
  <div className={cn("flex items-center p-6 pt-0", className)} {...props} />
)
```

### Input

```tsx
const Input = React.forwardRef<HTMLInputElement, InputProps>(
  ({ className, type, ...props }, ref) => (
    <input
      type={type}
      className={cn(
        "flex h-10 w-full rounded-md border border-neutral-200 bg-white px-3 py-2 text-sm",
        "placeholder:text-neutral-400",
        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2",
        "disabled:cursor-not-allowed disabled:opacity-50",
        "file:border-0 file:bg-transparent file:text-sm file:font-medium",
        className
      )}
      ref={ref}
      {...props}
    />
  )
)
```

## Building Process

1. **Identify the component type** — Is it presentational, interactive, or compound?
2. **Choose the base element** — Semantic HTML first
3. **Define variants** — What visual variations exist? Use cva.
4. **Wire up accessibility** — ARIA attributes, keyboard handling, focus management
5. **Apply design tokens** — Map every visual property to the design system
6. **Add states** — Default, hover, focus, disabled, loading, error
7. **Add transitions** — Use motion tokens for timing. `transition-colors` for color changes, `transition-all` only when multiple properties animate.
8. **Forward refs** — Always `forwardRef` for React components that wrap native elements
9. **Spread remaining props** — `{...props}` for flexibility, `cn(baseClasses, className)` for class merging

## Anti-Patterns

- **Hardcoded colors** — `bg-blue-500` instead of `bg-primary-500`. Always use semantic tokens.
- **Missing focus states** — If you can tab to it, it needs a visible focus ring.
- **Div soup** — Using `<div>` for everything. Ask "what element is this really?"
- **Inline styles for layout** — Use Tailwind utilities or CSS classes. Inline styles break consistency.
- **Boolean variant props** — `<Button primary large>` → use `variant="primary" size="lg"` instead. Booleans don't scale.
- **Inconsistent spacing** — Mixing `p-3` and `p-4` in the same component family. Pick one and stick with it.
- **Animations on everything** — Transitions should be subtle and functional. Not every element needs to animate.
- **Wrapping native element behavior** — Don't rebuild what `<button>`, `<input>`, `<dialog>` already give you.

## Output Checklist

After building a component:

- [ ] Uses design system tokens (no hardcoded values)
- [ ] Semantic HTML element chosen
- [ ] All four interactive states implemented (default, hover, focus, disabled)
- [ ] `forwardRef` applied (React)
- [ ] `className` prop accepted and merged with `cn()`
- [ ] Keyboard accessible (can reach and operate with Tab/Enter/Space/Escape)
- [ ] Dark mode works (if project uses dark mode)
- [ ] Transitions use motion tokens from design system
- [ ] Props are typed (TypeScript)
- [ ] Follows existing file/naming conventions in the project

## Related Skills

- **design-system** — Create the token system this skill consumes
- **page-compose** — Arrange components into full page layouts
- **polish** — Add the final layer of interaction states and micro-feedback
- **accessibility** — Deep audit of component accessibility
- **shadcn-ui** (standalone) — Reference for shadcn/ui-specific patterns