agentic-dev/packages/ui/AGENTS.md

@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

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