ai-agents-workspace-starter: Skill for Claude Code

Skill: Frontend Patterns

Core guidelines and fundamental rules for implementing frontend functionality using React and TypeScript.

---

1. UI Components (Metric UI)

• Base your UI architecture on the provided metric-ui library.
• Create wrapper components only to encapsulate repetitive logic (e.g., extending a Button to handle an isLoading prop and render an inline spinner).

2. API Client (Axios)

• Route all HTTP communication through a centralized Axios instance (apiClient).
• Configure interceptors for dynamic token injection (setting the Authorization: Bearer header) and global error handling (e.g., triggering a logout on 401 Unauthorized errors).
• The client wrapper should unpack the response envelope (e.g., stripping the outer ApiEnvelope<T>) before returning data to consumers.

3. Server State Management (React Query / TanStack Query)

• Use useQuery exclusively for data fetching and useMutation for side effects and writes.
• Define strict, strongly-typed Query Keys (as constant arrays) to allow reliable cache invalidation via QueryClient.invalidateQueries.
• Configure sensible staleTime defaults (e.g., 5 minutes) for immutable or slow-moving resources.

4. Feature-Based Architecture

• Group views, hooks, and logic into bounded business "features" rather than file-type directories.
• Provide comprehensive lifecycle state management inside container components:
  • isLoading -> render skeleton loaders (Skeleton).
  • isError -> render a dedicated error component (ErrorAlert).
  • empty payload -> render a centered null-state (EmptyState).
• Map over data collections using small, isolated presentation components (Cards, List rows).

5. Testing Tools (Vitest + Testing Library)

• Build reusable test utilities (e.g., renderWithProviders) that wrap the component under test with essential context providers (MemoryRouter, QueryClientProvider with retries disabled).
• Mock network boundaries deterministically using MSW (Mock Service Worker).