metabuilder/docs/implementation/ATOMIC_DESIGN.md

Atomic Design Structure for MetaBuilder

Overview

This document describes the atomic design pattern implementation for MetaBuilder's React components. Components are organized into three categories: Atoms, Molecules, and Organisms.

Principles

Atoms

Definition: Smallest, indivisible UI elements that cannot be broken down further without losing meaning.

Characteristics:

• Single responsibility
• No dependencies on other custom components (only shadcn/ui)
• Highly reusable
• Stateless or minimal state
• Examples: buttons, inputs, labels, badges, icons

Location: src/components/atoms/

Molecules

Definition: Groups of atoms that function together as a cohesive unit.

Characteristics:

• Composed of 2-5 atoms
• Single, focused purpose
• Reusable across multiple contexts
• Can have internal state but no complex business logic
• Examples: form fields with labels, search bars, card headers

Location: src/components/molecules/

Organisms

Definition: Complex components that form distinct sections of an interface.

Characteristics:

• Composed of molecules and atoms
• May contain business logic
• Often specific to a particular feature
• Can be entire sections or panels
• Examples: navigation bars, data tables, forms, editors

Location: src/components/organisms/

Current Component Organization

Atoms (src/components/atoms/)

Foundational elements that should remain in the atoms folder:

• All shadcn/ui components (@/components/ui/*)
• Icon components (from @phosphor-icons/react)
• Basic styled elements

Molecules (src/components/molecules/)

Simple composite components:

• SecurityBadge - Severity indicator for security warnings
• UserCard - Compact user display
• TenantCard - Tenant information display
• TabNavigation - Tab bar with scroll
• EmptyState - Empty state placeholder
• CredentialsDisplay - Username/password display with copy
• PreviewBanner - Preview mode indicator
• PropertyField - Form field with label and input
• ClassBadge - CSS class display badge
• DropdownOption - Single dropdown option

Organisms (src/components/organisms/)

Complex feature components:

• SchemaEditor - Full schema editing interface
• ComponentCatalog - Component browsing and selection
• PropertyInspector - Component property editor
• CssClassBuilder - Visual CSS class selector
• CssClassManager - CSS class library management
• DropdownConfigManager - Dropdown configuration interface
• DatabaseManager - Database management panel
• UserManagement - User CRUD interface
• PackageManager - Package browsing and installation
• PackageImportExport - Import/export functionality
• LuaEditor - Lua script editor
• LuaSnippetLibrary - Lua snippet management
• JsonEditor - JSON editing interface
• CodeEditor - Monaco-based code editor
• NerdModeIDE - Full IDE panel
• ThemeEditor - Theme customization interface
• SMTPConfigEditor - SMTP configuration form
• IRCWebchat - IRC chat interface
• IRCWebchatDeclarative - Declarative IRC chat
• WorkflowEditor - Workflow configuration
• PageRoutesManager - Page routing management
• GodCredentialsSettings - God credentials management
• ScreenshotAnalyzer - Screenshot analysis tool
• GitHubActionsFetcher - GitHub actions integration
• AuditLogViewer - Audit log display

Pages/Levels (src/components/)

Top-level page components (remain at root level):

• Level1 - Public landing page
• Level2 - User dashboard
• Level3 - Admin panel
• Level4 - God-tier builder
• Level5 - Super God panel
• Login - Authentication
• UnifiedLogin - Unified auth interface
• PasswordChangeDialog - Password change modal

Shared Utilities (src/components/shared/)

Shared helpers and utilities:

• constants.ts - Shared constants
• types.ts - Shared type definitions
• utils.ts - Shared utility functions

Migration Guide

Step 1: Create Folder Structure

src/components/
├── atoms/              # Smallest UI elements
├── molecules/          # Simple composite components
├── organisms/          # Complex feature components
├── shared/             # Shared utilities and types
├── ui/                 # shadcn components (existing)
└── [Level components]  # Top-level pages remain at root

Step 2: Move Components

Components should be moved according to their complexity:

1. Start with atoms (if any custom ones exist)
2. Move molecules (2-5 atom combinations)
3. Move organisms (complex features)
4. Update all import paths

Step 3: Update Imports

Old import:

import { ComponentCatalog } from '@/components/ComponentCatalog'

New import:

import { ComponentCatalog } from '@/components/organisms/ComponentCatalog'

Step 4: Create Index Files

Each folder should have an index.ts for easier imports:

// src/components/molecules/index.ts
export { SecurityBadge } from './SecurityBadge'
export { UserCard } from './UserCard'
export { TenantCard } from './TenantCard'
// ... etc

This allows cleaner imports:

import { SecurityBadge, UserCard } from '@/components/molecules'

Benefits

1. Clarity: Easy to understand component complexity at a glance
2. Reusability: Clear separation encourages reuse of simpler components
3. Maintainability: Changes to atoms automatically propagate to molecules and organisms
4. Testability: Atoms and molecules are easier to test in isolation
5. Documentation: Clear hierarchy serves as living documentation
6. Onboarding: New developers can quickly understand the architecture
7. Refactoring: Easy to identify when organisms should be broken down

Best Practices

1. Atoms should never import molecules or organisms
2. Molecules should only import atoms
3. Organisms can import atoms, molecules, and other organisms
4. Use TypeScript interfaces to define props clearly
5. Keep business logic in organisms, not atoms/molecules
6. Make atoms and molecules as generic as possible
7. Use composition over inheritance
8. Document complex organisms with JSDoc comments

File Naming Conventions

• Use PascalCase for component files: SecurityBadge.tsx
• Use kebab-case for style files: security-badge.module.css
• Use camelCase for utility files: formatUtils.ts
• Index files should re-export components: index.ts

Component Template

// src/components/atoms/ExampleAtom.tsx
import { cn } from '@/lib/utils'

interface ExampleAtomProps {
  label: string
  variant?: 'primary' | 'secondary'
  className?: string
}

export function ExampleAtom({ 
  label, 
  variant = 'primary', 
  className 
}: ExampleAtomProps) {
  return (
    <div className={cn('base-styles', className)}>
      {label}
    </div>
  )
}

Migration Checklist

• Create folder structure (atoms, molecules, organisms, shared)
• Identify and categorize all existing components
• Create index files for each folder
• Move atoms to their folder
• Move molecules to their folder
• Move organisms to their folder
• Update all import statements
• Update tests to use new paths
• Verify application builds successfully
• Verify all functionality works
• Update documentation

References

• Atomic Design by Brad Frost
• React Component Patterns
• Component-Driven Development