PixelPilot uiux-architecture.instructions.md

UI/UX Architecture 2026

Feature-Sliced Design, component architecture, state management (Signals vs Context), folder structure, and code organization patterns for scalable UI systems. Prevents spaghetti code in large applications.

---

DECISION TREE — Architecture Tier

Project size?
├─ Small (1 dev, <10 routes, <3 months)
│   └─ Flat structure: /components, /hooks, /pages — that's enough
├─ Medium (2–5 devs, 10–30 routes)
│   └─ Layer by type: /features, /shared, /pages
└─ Large (5+ devs, 30+ routes, long-lived)
    └─ Feature-Sliced Design (FSD) — see below

---

STATE MANAGEMENT DECISION TREE

Use this tree to choose the right state management tool for your specific use case:

• Local Component State (e.g., form input, toggle, local counter)
  • Tool: useState / useReducer
  • Why: Simplest, built-in, no overhead.
• Shared UI State (e.g., theme, current user, small group of components)
  • Tool: useContext
  • Why: Built-in, avoids prop drilling for shared static or low-frequency data.
• Global App State (e.g., cart, multi-step workflow, complex cross-page data)
  • Tool: Zustand
  • Why: Global, simple API, excellent performance, supports persistence (localStorage).
• High-Frequency / Fine-Grained State (e.g., real-time dashboards, complex animations)
  • Tool: Signals (Preact Signals in React)
  • Why: Fine-grained reactivity; only components reading the signal re-render. Massive performance gain.
• Server State (e.g., API responses, loading/error states, caching)
  • Tool: TanStack Query (React Query)
  • Why: Mandatory. Handles caching, revalidation, and loading states automatically.

---

FEATURE-SLICED DESIGN (FSD) — Large Apps

FSD organizes by business domain, not file type. Prevents import cycles. Rule: each layer can only import from layers below it.

src/
├─ app/          (L1 — top) config, providers, global styles, router
├─ pages/        (L2) page components — compose features, no business logic
├─ widgets/      (L3) self-contained page sections (Header, Sidebar, PlayerBar)
├─ features/     (L4) user interactions (auth, cart, search, notifications)
├─ entities/     (L5) business objects (User, Product, Order)
└─ shared/       (L6 — bottom) UI kit, utils, API clients, hooks
    ├─ ui/       (Button, Input, Card — no business knowledge)
    ├─ api/      (base fetch client)
    ├─ lib/      (date, format, validate utils)
    └─ config/   (env vars, constants)