# AGENTS.md — core-ui

Design-system primitives organized by Atomic Design. Only **generic components** (atoms, molecules, generic organisms) live here. Feature-specific components live in their respective feature packages.

## Responsibilities

- **Atoms** — Single HTML elements: Button, Input, Label, Card
- **Molecules** — Combinations: FormField (Label + Input), Badge, Avatar
- **Generic Organisms** — Reusable complex layouts: Modal, Tabs, NavigationMenu, CommandPalette
- **Templates** — Page layouts: AuthLayout, DashboardLayout, LandingLayout
- **Utilities** — `cn()` for className merging, design tokens, Tailwind config

## Feature-specific boundary

Feature-specific organisms (e.g., `ArticleCard`, `ArticleList`, `HeaderNavMenu`) live in their feature's `ui/` folder, NOT here. This boundary keeps `core-ui` framework-agnostic and reusable.

## Must NOT import

- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
- Any app package
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`

> Note: `@repo/core-trpc` is an optional package scaffolded via `pnpm turbo gen core-package trpc`. If not present, this constraint still applies to any future installation.

## Public exports

From `package.json`:

- `.` — all atoms, molecules, organisms, templates

Example usage:

```typescript
import { Button, Input, Label } from "@repo/core-ui";
import { FormField } from "@repo/core-ui";
import { Modal, Tabs } from "@repo/core-ui";
```

## Test conventions

- Tests colocated: `src/atoms/button/button.tsx` → `src/atoms/button/button.test.tsx`
- Vitest environment: `jsdom` (React component testing)
- Alias: `@/` resolves to `src/`
- Run: `pnpm test --filter @repo/core-ui`
- Storybook stories colocated: `src/atoms/button/button.stories.tsx`

## Structure

> To scaffold a new component, use `pnpm turbo gen core-ui-component` rather than creating files manually. The generator emits the 4-file pattern below and splices the export into the tier barrel.

```
src/
  atoms/
    {name}/
      {name}.tsx             # Component
      {name}.test.tsx        # Tests
      {name}.stories.tsx     # Storybook story
      index.ts               # Barrel export
  molecules/
    {name}/
      ...
  organisms/
    {name}/
      ...
  templates/
    {name}/
      ...
  lib/
    utils.ts                 # cn() and helpers
  index.ts                   # Re-exports everything
```