agent-rules-kit/templates/stacks/react/architectures/atomic/atomic-architecture.md

CLI tool to bootstrap AI agent rules for multiple IDEs and frameworks. Generates optimized rules for Cursor, VS Code, Claude, and 6+ other AI coding assistants.

---
description: Atomic Design architecture for React applications
globs: <root>/src/**/*.ts,<root>/src/**/*.tsx,<root>/src/**/*.js,<root>/src/**/*.jsx
alwaysApply: false
---

# Atomic Design Architecture

Atomic Design is a methodology composed of five distinct stages working together to create interface design systems in a more deliberate and hierarchical manner.

## Core Principles

1. **Atoms**: Basic building blocks (buttons, inputs, labels) that can't be broken down further
2. **Molecules**: Groups of atoms working together as a unit (form fields, navigation items)
3. **Organisms**: Groups of molecules forming a distinct section (headers, forms, content areas)
4. **Templates**: Page-level objects placing components into a layout
5. **Pages**: Specific instances of templates with real content

## Directory Structure

```
src/
├── components/
│   ├── atoms/
│   │   ├── Button/
│   │   │   ├── Button.jsx
│   │   │   ├── Button.test.jsx
│   │   │   └── Button.module.css
│   │   ├── Input/
│   │   ├── Label/
│   │   └── ...
│   ├── molecules/
│   │   ├── FormField/
│   │   ├── SearchBar/
│   │   └── ...
│   ├── organisms/
│   │   ├── Header/
│   │   ├── Footer/
│   │   ├── ProductCard/
│   │   └── ...
│   └── templates/
│       ├── HomeTemplate/
│       ├── ProductTemplate/
│       └── ...
├── pages/
│   ├── Home/
│   ├── Product/
│   └── ...
└── ...
```

## Implementation Guidelines

### 1. Atoms

```jsx
// Button.jsx
export const Button = ({
	children,
	variant = 'primary',
	size = 'medium',
	onClick,
	...props
}) => {
	return (
		<button
			className={`button ${variant} ${size}`}
			onClick={onClick}
			{...props}>
			{children}
		</button>
	);
};
```

-   Keep atoms as simple and pure as possible
-   Ensure they are highly reusable
-   Maintain clear props interfaces with good defaults
-   Avoid business logic at this level

### 2. Molecules

```jsx
// FormField.jsx
import { Input } from '../../atoms/Input';
import { Label } from '../../atoms/Label';
import { ErrorMessage } from '../../atoms/ErrorMessage';

export const FormField = ({ label, name, error, ...inputProps }) => {
	return (
		<div className='form-field'>
			<Label htmlFor={name}>{label}</Label>
			<Input
				id={name}
				name={name}
				aria-invalid={!!error}
				{...inputProps}
			/>
			{error && <ErrorMessage>{error}</ErrorMessage>}
		</div>
	);
};
```

-   Compose molecules from atoms
-   Focus on specific use cases
-   Maintain clear interfaces between components
-   Keep business logic minimal

### 3. Organisms

```jsx
// ProductCard.jsx
import { Heading } from '../../atoms/Heading';
import { Image } from '../../atoms/Image';
import { StarRating } from '../../molecules/StarRating';
import { PriceTag } from '../../molecules/PriceTag';
import { AddToCartButton } from '../../molecules/AddToCartButton';

export const ProductCard = ({ product }) => {
	return (
		<div className='product-card'>
			<Image src={product.image} alt={product.name} />
			<Heading level={3}>{product.name}</Heading>
			<StarRating value={product.rating} />
			<PriceTag price={product.price} discount={product.discount} />
			<AddToCartButton productId={product.id} />
		</div>
	);
};
```

-   Compose organisms from atoms and molecules
-   Can contain domain-specific logic
-   Connect to data sources or state management
-   Represent distinct sections of a UI

### 4. Templates

```jsx
// ProductTemplate.jsx
import { Header } from '../../organisms/Header';
import { ProductDetails } from '../../organisms/ProductDetails';
import { RelatedProducts } from '../../organisms/RelatedProducts';
import { Footer } from '../../organisms/Footer';

export const ProductTemplate = ({ product, relatedProducts }) => {
	return (
		<div className='product-page'>
			<Header />
			<main>
				<ProductDetails product={product} />
				<RelatedProducts products={relatedProducts} />
			</main>
			<Footer />
		</div>
	);
};
```

-   Create page layouts without specific content
-   Handle responsive layout concerns
-   Focus on component composition
-   Avoid business logic at this level

### 5. Pages

```jsx
// ProductPage.jsx
import { useEffect, useState } from 'react';
import { useParams } from 'react-router-dom';
import { ProductTemplate } from '../../components/templates/ProductTemplate';
import { fetchProduct, fetchRelatedProducts } from '../../api/products';

export const ProductPage = () => {
	const { productId } = useParams();
	const [product, setProduct] = useState(null);
	const [relatedProducts, setRelatedProducts] = useState([]);
	const [loading, setLoading] = useState(true);

	useEffect(() => {
		const loadData = async () => {
			setLoading(true);
			try {
				const productData = await fetchProduct(productId);
				setProduct(productData);

				const relatedData = await fetchRelatedProducts(productId);
				setRelatedProducts(relatedData);
			} catch (error) {
				console.error('Failed to load product data', error);
			} finally {
				setLoading(false);
			}
		};

		loadData();
	}, [productId]);

	if (loading) return <div>Loading...</div>;

	return (
		<ProductTemplate product={product} relatedProducts={relatedProducts} />
	);
};
```

-   Add specific data to templates
-   Connect to APIs, data sources, and state management
-   Handle routing and URL parameters
-   Focus on business logic and data fetching

## Best Practices

1. **Clear Component Boundaries**

    - Each component should have a single responsibility
    - Props interfaces should be well-defined
    - Document components with comments or prop-types

2. **Reusability**

    - Lower-level components (atoms, molecules) should be highly reusable
    - Avoid tightly coupling components to specific data structures
    - Use composition over inheritance

3. **Testability**

    - Each component should be easily testable in isolation
    - Write unit tests for atoms and molecules, integration tests for organisms and templates

4. **Composability**

    - Components should be easy to compose to create more complex UIs
    - Use React's children prop for flexible composition
    - Consider using render props or HOCs for complex sharing of behavior

5. **Consistency**
    - Maintain consistent naming conventions
    - Keep directory structure consistent
    - Use consistent patterns for handling props, state, and events

## When to Use Atomic Design

Atomic Design is particularly well-suited for:

-   Large applications with many UI components
-   Projects that require a design system
-   Teams with designers and developers working closely together
-   Products that need consistent UI across different areas

However, it may be overkill for small or simple applications. Evaluate if the structure benefits your project before implementing it.