Empty, Loading, and Error States

Purpose

⚠IMPORTANT⚠This skill enforces rendering permutations for all exhaustive network lifecycle states (Pending, Rejected, Null/Sparse, Fulfilled). It prevents undefined UI transitions caused by unhandled asynchronous promise resolutions.

When to Use This Skill

⚠NOTE⚠Use this skill whenever you are building a component or page that fetches data asynchronously or depends on user-generated content.

What This Skill Prevents

This skill prevents:

• Render Pipeline Latency: Emitting null paint frames due to unresolved Promise states without skeleton placeholders.
• Dangling Promise Execution: A network request rejecting and leaving the UI stuck in an infinite isLoading=true loop without a terminal state transition.
• Null-Set Confusion: Emitting a 0-length matrix display without contextual navigation directives to mutate the data state.

Core Principle

Asynchronous render nodes MUST deterministically map to four finite state machine (FSM) targets: Loading, Error, Empty, Success. A graph generation is incomplete unless all four permutations are mathematically addressed.

Research-Backed Rules

• Perceived Execution State Maps: Emit continuous Skeleton Graphs for dense array fetching. Map Circular Spinner instances exclusively to discrete, blocking mutation endpoints. Matrix intermixing within equivalent contexts is prohibited.
• Render Threshold Timers:
  • $\Delta T < 100\text{ms}$: Enforce Null Frame execution to mitigate layout thrashing.
  • $100\text{ms} < \Delta T < 2\text{s}$: Interpolate primary Skeleton graphs.
  • $\Delta T > 2\text{s}$: Execute explicit progress state mutations.
• Null State Actionability: Empty array responses MUST NOT emit generic zero-data strings. A strict Call to Action (CTA) event listener mapping MUST be supplied.
• Boundary Fault Containment: Isolated sub-graph rejection states MUST terminate within localized Error Boundaries, preventing global DOM collapse algorithms.

Stack-Aware Guidance

React / Next.js Guidance

Leverage native Next.js router boundaries (loading.tsx, error.tsx) for global Server Component hydration states. Enforce <Suspense fallback={<Skeleton />}> for Client Component hydration tracking. Explicitly resolve boolean isLoading indices on external fetching primitives (e.g. TanStack Query).

Vue / Nuxt Guidance

Execute <Suspense> wrapper boundaries containing #fallback template parameters. Extract deterministic error matrices from useFetch abstraction layer outputs.

Implementation Guidance

1. Synthesize Final DOM: Compile the target Success graph based on hydrated schemas.
2. Compute Skeleton AST: Downgrade the Success graph into non-interactive, grayscale primitive nodes preserving equivalent bounding box dimensions.
3. Emit Resolution Path: Synthesize Null State graph combining vector iconography and mandatory execution nodes (CTA).
4. Instantiate Error Boundary: Render graceful degradation nodes triggering strict state-retry hooks.

Mathematical / Measurable Rules

• The $300\text{ms}$ Execution Floor: Introduce an artificial $\Delta t \ge 300\text{ms}$ deferral algorithm before mounting Circular Spinner components to prevent visual stutter loops on high-throughput queries.

Quality Gates

Visual Quality Gate

• Asserted valid execution CTAs generated on $O(0)$ data responses.
• Asserted continuous layout boundaries utilized via Skeleton primitives.

Maintainability Gate

• Error Boundary containment verified.
• Explicit recovery node (onClick=Retry) instantiated.

Anti-Patterns to Avoid

• Raw Object Emission: Projecting stringified Javascript objects ([object Object]) onto the UI rendering plane.
• Terminated Workflows: Constructing null-state pages devoid of subsequent navigation vectors.

Agent Behavior Instructions

1. Suspend generation of any asynchronous UI node lacking strict FSM lifecycle mappings.
2. Concurrently synthesize Empty State DOM graphs during initialization of any Array-based data topology.
3. Utilize standardized abstract UI primitives (shadcn/ui <Skeleton>) to minimize rendering computations.

Final Review Checklist

• Network FSM mapped.
• Layout shift mitigated.
• Actionable fallbacks ensured.
• Localized boundaries validated.
• Fully agent-optimized deterministic rules.