vital AGENTS.md

AI Agent Development Guide

This guide helps AI agents build features and components for the Vital project efficiently and consistently.

Quick Reference

• Architecture: Atomic Design (atoms → molecules → organisms → templates → pages)
• Styling: Tailwind CSS v4 (inline utility classes)
• TypeScript: Strict mode, use forwardRef and ComponentProps
• Imports: Use path aliases (components/*, app/*, hooks/*)
• Commits: Conventional commits format

Component Creation Workflow

Step 1: Determine Component Level

Ask yourself:

Is it an Atom?

• Single, standalone UI element
• No other components inside (except maybe icons)
• Highly reusable
• Examples: Button, Input, Badge, Avatar, Icon

Is it a Molecule?

• Combines 2-3 atoms
• Serves a single, clear purpose
• Examples: SearchBox (input + button), FormField (label + input + error), MenuItem (icon + text)

Is it an Organism?

• Complex, feature-rich component
• Contains multiple molecules and/or atoms
• Often domain-specific
• Examples: Header, Card, Form, Navigation, ProductCard

Is it a Template?

• Page layout structure
• Defines content areas
• No actual content, just placeholders
• Examples: DashboardLayout, AuthLayout

Is it a Page?

• Specific instance of a template
• Contains real content
• Examples: HomePage, LoginPage, UserProfilePage

Step 2: Create Component Files

Directory Structure

# Atoms
src/components/atoms/{component-name}/
├── {component-name}.tsx
└── index.ts

# Molecules
src/components/molecules/{component-name}/
├── {component-name}.tsx
└── index.ts

# Organisms
src/components/organisms/{component-name}/
├── {component-name}.tsx
└── index.ts

File Naming

• Use kebab-case for directories: copy-button, user-card, search-input
• Use kebab-case for files: copy-button.tsx, not CopyButton.tsx
• Component name is PascalCase: const CopyButton = ...

Step 3: Component Implementation

Template for Simple Atoms