# @repo/ui — Atomic Design Component Library

shadcn/ui + Tailwind CSS v4 + Atomic Design. Components organized by level with co-located stories.

## Atomic Classification Guide

| Level | Definition | Examples |
|---|---|---|
| Atom | Single element, can't break down further | Button, Input, Label, Badge, Separator |
| Molecule | 2-3 atoms, single responsibility | FormField, SearchBar, Tooltip, Select |
| Organism | Complex section, self-contained | DataTable, Dialog, Header, Sidebar, Card |
| Template | Page layout, content-agnostic | DashboardLayout, AuthLayout |
| Page | Template + real data | **LIVES IN apps/, NOT HERE** |

## Import Rules

| Level | Can import from | NEVER import from |
|---|---|---|
| Atoms | lib/, hooks/, styles/ | molecules/, organisms/, templates/ |
| Molecules | atoms/, lib/, hooks/ | organisms/, templates/ |
| Organisms | atoms/, molecules/, lib/, hooks/ | templates/ |
| Templates | atoms/, molecules/, organisms/, lib/, hooks/ | (top level) |

## Component Rules

- **Atoms:** No margins/positioning, no state, no business logic
- **Molecules:** Single responsibility, minimal controlled state
- **Organisms:** Can have internal state and sub-components
- **Templates:** Use children/slots, NEVER hard-code content
- **All:** Co-locate `.stories.tsx` next to component

## shadcn/ui Workflow

1. `pnpm dlx shadcn@latest add [component]` — lands in atoms/ by default
2. Check classification guide above
3. If not atom → move to correct directory
4. Create `.stories.tsx` with title: `"{Level}/{ComponentName}"`
5. Update level's `index.ts` barrel

## Story Template

```tsx
import type { Meta, StoryObj } from "@storybook/react";
import { MyComponent } from "./my-component.js";

const meta = {
  title: "{Level}/{ComponentName}",
  component: MyComponent,
  tags: ["autodocs"],
} satisfies Meta<typeof MyComponent>;
export default meta;
```

## Storybook MCP

Before creating UI components, query Storybook MCP:
- `list-all-documentation` — check for existing components
- `get-documentation` — understand props/variants
- After creating: `run-story-tests` to validate