PixelPilot uiux-states.instructions.md

UI/UX Component States 2026

Every UI component has states. This file defines ALL 10 states every component must handle — from Figma variables to CSS to JS — per design language. Missing states = broken UX. This is what separates AI slop from real products.

---

THE 10 STATES EVERY COMPONENT MUST HANDLE

1. Default    — resting state
2. Hover      — mouse/pointer over
3. Focus      — keyboard/tab navigation
4. Active     — being pressed / in-progress click
5. Loading    — async action pending
6. Disabled   — not interactable
7. Error      — validation failed / system error
8. Success    — action confirmed / validated
9. Empty      — no data yet (tables, feeds, search)
10. Busy      — container is updating (live feed, real-time data)

Optional (context-dependent):

11. Selected  — chosen from a list
12. Dragging  — being dragged (sortable lists)
13. Skeleton  — pre-data placeholder (see uiux-motion.md)

---

STATE 10 — BUSY (Live Updating Containers)

Rule: When a container or section is actively updating (live feeds, real-time dashboards, polling data), use aria-busy="true" and provide visual feedback with reduced opacity and a spinner overlay.

When to Use Busy State

• Live feed is fetching new items
• Dashboard widget is refreshing data
• Chat is receiving streaming response
• Table is filtering/sorting large datasets
• Any container awaiting real-time update

HTML Structure

<!-- Busy container with aria-busy -->
<div class="live-feed" id="live-feed" aria-busy="true" aria-live="polite">
  <div class="live-feed__spinner">
    <span class="spinner"></span>
    <span class="sr-only">Updating feed...</span>
  </div>
  <ul class="live-feed__items">
    <!-- Feed items -->
  </ul>
</div>

CSS Implementation

/* Busy state — reduced opacity + spinner overlay */
[aria-busy="true"] {
  position: relative;
  pointer-events: none;
}

[aria-busy="true"]::before {
  content: '';
  position: absolute;
  inset: 0;
  background: color-mix(in srgb, var(--bg) 60%, transparent);
  z-index: 10;
  border-radius: inherit;
}

/* Spinner overlay for busy containers */
.live-feed__spinner {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  z-index: 11;
  display: none;
}

[aria-busy="true"] .live-feed__spinner {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: var(--space-2);
}

/* Busy state visual feedback */
[aria-busy="true"] > *:not(.live-feed__spinner) {
  opacity: 0.4;
  filter: blur(1px);
  transition: opacity var(--transition-base), filter var(--transition-base);
}

/* Spinner animation */
.spinner {
  width: 24px;
  height: 24px;
  border: 2px solid var(--border);
  border-top-color: var(--accent);
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  .spinner {
    animation: none;
    border-top-color: var(--accent);
    border-right-color: var(--accent);
  }
  
  [aria-busy="true"] > *:not(.live-feed__spinner) {
    filter: none;
  }
}

/* Per-design-language busy styles */
[data-lang="luxury"] [aria-busy="true"]::before {
  background: color-mix(in srgb, var(--bg) 70%, transparent);
}

[data-lang="technical"] [aria-busy="true"]::before {
  background: color-mix(in srgb, var(--bg) 80%, transparent);
}

[data-lang="technical"] .spinner {
  width: 16px;
  height: 16px;
  border-width: 1.5px;
}