low-code-react-app-b/docs/architecture/atomic/ATOMIC_README.md

Atomic Component Library - Quick Start

📚 Documentation Overview

This project now uses an Atomic Design component architecture. Here's how to navigate the documentation:

Essential Reading (Start Here!)

1. ATOMIC_REFACTOR_SUMMARY.md - Overview of changes

   • What changed and why
   • Component inventory
   • Benefits and usage patterns
   • Next steps

2. ATOMIC_COMPONENTS.md - Complete guide

   • Atomic design methodology explained
   • Component hierarchy rules
   • When to create each type
   • Best practices and patterns
   • Migration guide

3. ATOMIC_USAGE_EXAMPLES.md - Practical examples

   • 10+ real-world usage examples
   • Code templates
   • Testing patterns
   • Quick start guide

4. COMPONENT_MAP.md - Visual reference

   • Component composition diagrams
   • Dependency maps
   • Data flow examples
   • Performance tips

🎯 Quick Reference

Component Levels

Level	Purpose	Example	Import From
Atom	Single UI element	AppLogo, StatusIcon	@/components/atoms
Molecule	2-5 atoms combined	SaveIndicator, ToolbarButton	@/components/molecules
Organism	Complex composition	AppHeader, NavigationMenu	@/components/organisms
Feature	Domain-specific	CodeEditor, ModelDesigner	@/components/[Name]

Directory Structure

src/components/
├── atoms/              # 7 building blocks
├── molecules/          # 10 simple combinations
├── organisms/          # 4 complex components
├── ui/                 # shadcn base components
└── [features]/        # Feature components

🚀 Usage Examples

Using Atoms

import { AppLogo, StatusIcon, ErrorBadge } from '@/components/atoms'

<AppLogo />
<StatusIcon type="saved" animate />
<ErrorBadge count={5} />

Using Molecules

import { SaveIndicator, ToolbarButton, EmptyState } from '@/components/molecules'

<SaveIndicator lastSaved={Date.now()} />
<ToolbarButton icon={<Plus />} label="Add" onClick={handleAdd} />
<EmptyState icon={<Code />} title="No files" description="Get started" />

Using Organisms

import { AppHeader, PageHeader, NavigationMenu } from '@/components/organisms'

<AppHeader
  activeTab={activeTab}
  onTabChange={setActiveTab}
  lastSaved={lastSaved}
  onExport={handleExport}
  {...props}
/>

📋 Component Inventory

Atoms (7)

• AppLogo - Application logo
• TabIcon - Icon with variants
• StatusIcon - Save/sync status
• ErrorBadge - Error counter
• IconWrapper - Icon container
• LoadingSpinner - Loading animation
• EmptyStateIcon - Empty state icon

Molecules (10)

• SaveIndicator - Save status display
• AppBranding - Logo + title
• PageHeaderContent - Page title section
• ToolbarButton - Button with tooltip
• NavigationItem - Nav link
• NavigationGroupHeader - Group header
• EmptyState - Empty state view
• LoadingState - Loading view
• StatCard - Statistics card
• LabelWithBadge - Label + badge

Organisms (4)

• NavigationMenu - Sidebar navigation
• PageHeader - Page header
• ToolbarActions - Action toolbar
• AppHeader - Application header

🛠️ Creating New Components

1. Determine Component Level

Ask yourself:

• Can it be broken down? → Not an atom
• Does it combine atoms? → At least a molecule
• Does it have complex state? → Probably an organism
• Is it feature-specific? → Feature component

2. Create the Component

// src/components/atoms/MyAtom.tsx
interface MyAtomProps {
  value: string
  variant?: 'default' | 'primary'
}

export function MyAtom({ value, variant = 'default' }: MyAtomProps) {
  return <span className={variant}>{value}</span>
}

3. Update Index File

// src/components/atoms/index.ts
export { MyAtom } from './MyAtom'

4. Use in Your Code

import { MyAtom } from '@/components/atoms'

<MyAtom value="Hello" variant="primary" />

✅ Best Practices

DO:

• ✅ Use atoms for single-purpose elements
• ✅ Compose molecules from atoms
• ✅ Build organisms from molecules/atoms
• ✅ Keep feature logic in feature components
• ✅ Export from index files
• ✅ Use TypeScript types
• ✅ Follow naming conventions

DON'T:

• ❌ Import organisms in atoms
• ❌ Import molecules in atoms
• ❌ Duplicate atom functionality
• ❌ Mix business logic in atoms/molecules
• ❌ Skip TypeScript types
• ❌ Create "god components"

📊 Import Hierarchy

Feature Components
       ↓ can import
    Organisms
       ↓ can import
    Molecules
       ↓ can import
      Atoms
       ↓ can import
   shadcn UI

🔧 Common Patterns

Pattern 1: Status Display

const isRecent = Date.now() - lastSaved < 3000
<StatusIcon type={isRecent ? 'saved' : 'synced'} />

Pattern 2: Empty State

<EmptyState
  icon={<FileCode size={32} />}
  title="No files yet"
  description="Create your first file"
  action={<Button onClick={onCreate}>Create File</Button>}
/>

Pattern 3: Loading State

{isLoading ? (
  <LoadingState message="Loading files..." />
) : (
  <FileList files={files} />
)}

Pattern 4: Stat Cards

<div className="grid grid-cols-3 gap-4">
  <StatCard icon={<Code />} label="Files" value={fileCount} />
  <StatCard icon={<Database />} label="Models" value={modelCount} />
  <StatCard icon={<Tree />} label="Components" value={compCount} />
</div>

🧪 Testing

Atoms (Unit Tests)

describe('StatusIcon', () => {
  it('shows CheckCircle when saved', () => {
    render(<StatusIcon type="saved" />)
    expect(screen.getByTestId('check-circle')).toBeInTheDocument()
  })
})

Molecules (Integration Tests)

describe('SaveIndicator', () => {
  it('shows saved text when recent', () => {
    render(<SaveIndicator lastSaved={Date.now() - 1000} />)
    expect(screen.getByText('Saved')).toBeInTheDocument()
  })
})

Organisms (E2E Tests)

describe('NavigationMenu', () => {
  it('navigates when item clicked', () => {
    render(<NavigationMenu {...props} />)
    userEvent.click(screen.getByText('Code Editor'))
    expect(onTabChange).toHaveBeenCalledWith('code')
  })
})

🎨 Styling

All components use:

• Tailwind for utility classes
• CSS variables for theming
• Responsive design patterns
• Accessible markup

Example:

<div className="flex items-center gap-2 sm:gap-3 text-sm sm:text-base">
  {/* Responsive spacing and text sizing */}
</div>

📝 TypeScript

All components are fully typed:

interface ComponentProps {
  required: string
  optional?: number
  callback?: () => void
  variant?: 'default' | 'primary'
}

export function Component({ required, optional = 0 }: ComponentProps) {
  // Implementation
}

🚦 Next Steps

1. Read the docs - Start with ATOMIC_REFACTOR_SUMMARY.md
2. Review examples - Check ATOMIC_USAGE_EXAMPLES.md
3. Study the maps - See COMPONENT_MAP.md for visual guides
4. Try it out - Create a new molecule or atom
5. Refactor - Identify components to atomize

💡 Tips

• Start with molecules for most use cases
• Extract atoms when you see duplication
• Build organisms for major UI sections
• Keep feature components for domain logic
• Use index files for clean imports
• Follow the existing patterns

🤝 Contributing

When adding new atomic components:

1. Choose the appropriate level
2. Create the component file
3. Add TypeScript types
4. Update the index.ts
5. Add to COMPONENT_MAP.md
6. Create usage examples
7. Write tests

📞 Need Help?

1. Check the documentation files
2. Look at existing component examples
3. Review the component map
4. Follow established patterns
5. Ask questions in code reviews

🔗 Resources

• Atomic Design: https://atomicdesign.bradfrost.com/
• Component-Driven: https://www.componentdriven.org/
• React Patterns: https://reactpatterns.com/

---

Remember: The atomic structure makes components more reusable, testable, and maintainable. When in doubt, start small (atom/molecule) and grow as needed!