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

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

2.0 KiB Raw Blame History