> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyqdeck.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Component Architecture

> Standard patterns for React components in the PyqDeck frontend

## The 3-File Pattern

PyqDeck follows a strict separation of concerns for complex components, especially within the Studio. Most components are split into three files:

1. **`{component}.jsx` (Logic/Container)**: Handles state, data fetching (using `useApi`), and event handlers. It passes data and callbacks to the view.
2. **`{component}.view.jsx` (Pure View)**: A functional component that only cares about rendering UI. It receives all data and actions via props. This makes it easy to test and preview in isolation.
3. **`{component}.stories.jsx` (Storybook)**: Defines various states (Loading, Empty, Success, Error) for the view component to be visualized in Storybook.

### Benefits

* **Testability**: You can test UI logic without mocking API calls.
* **Speed**: Storybook allows developing UI components without running the entire app or backend.
* **Maintainability**: Clear separation between "how it works" and "how it looks".

## UI Primitives (shadcn/ui)

We use **shadcn/ui** for our base component library. These are accessible, unstyled components built on top of Radix UI and styled with Tailwind CSS.

* **Location**: `frontend/src/components/ui/`
* **Philosophy**: We "own" these components. They are copied into the codebase and can be customized as needed.
* **Consistency**: All high-level components should use these primitives (Button, Card, Input, etc.) to ensure a consistent look and feel.

## Storybook Setup

Storybook is used as a workshop for building and documenting components in isolation.

* **Run locally**: `pnpm storybook` (from `frontend/` directory)
* **Deployment**: Storybook is automatically deployed to `storybook.pyqdeck.in` on every push to the main branch.
* **Visual Testing**: We use Storybook to verify component states across different themes and screen sizes.

## Design Patterns

* **Controlled Components**: Form inputs are generally controlled by React state or `react-hook-form`.
* **Skeleton Screens**: Use the `Skeleton` primitive from shadcn/ui to handle loading states gracefully.
* **Empty States**: Use the `Empty` component to provide feedback when no data is available.
* **Composition**: Prefer component composition (passing children) over complex prop drilling.