60 lines
2.1 KiB
Markdown
60 lines
2.1 KiB
Markdown
# @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
|