agentic-dev-template/packages/core-ui/AGENTS.md

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:

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

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