--- name: atomic-design-fundamentals user-invocable: false description: Use when applying Atomic Design methodology to organize UI components into quarks, atoms, molecules, organisms, templates, and pages. Core principles and hierarchy. allowed-tools: - Bash - Read - Write - Edit - Glob - Grep --- # Atomic Design Fundamentals Master Brad Frost's Atomic Design methodology (extended with quarks) for building scalable, maintainable component-based user interfaces. This skill covers the core hierarchy, principles, and organization strategies for modern design systems. ## Overview Atomic Design is a methodology for creating design systems inspired by chemistry. Just as atoms combine to form molecules, which combine to form organisms, UI components follow a similar hierarchical structure. We extend this with **quarks** - the sub-atomic level of design tokens: 0. **Quarks** - Design tokens (colors, spacing, typography scales, shadows) 1. **Atoms** - Basic building blocks (buttons, inputs, labels) 2. **Molecules** - Groups of atoms functioning together (search form, card) 3. **Organisms** - Complex UI sections (header, footer, sidebar) 4. **Templates** - Page-level layouts without real content 5. **Pages** - Templates with real representative content ## The Six Stages ### 0. Quarks The sub-atomic building blocks - design tokens and primitive values that atoms consume. Quarks are not UI components themselves; they are the raw values that define your design language. **Examples:** - Color tokens (primary-500, neutral-100) - Spacing scales (4px, 8px, 16px) - Typography tokens (font sizes, weights, line heights) - Border radii - Shadow definitions - Animation durations and easing functions - Breakpoints **Characteristics:** - Pure values, not visual components - Cannot import from any other level - Define the design language - Enable theming and consistency - Single source of truth for design decisions ### 1. Atoms The smallest functional UI units of your interface. Atoms consume quarks for styling but cannot be broken down further without losing meaning. **Examples:** - Buttons - Input fields - Labels - Icons - Typography elements (headings, paragraphs) - Color swatches - Avatars **Characteristics:** - Self-contained and independent - No business logic - Highly reusable - Accept styling props - Framework-agnostic when possible ### 2. Molecules Combinations of atoms working together as a unit. Molecules have a single responsibility but are composed of multiple atoms. **Examples:** - Search form (input + button) - Form field (label + input + error message) - Media object (avatar + text) - Card header (icon + title + action button) - Navigation link (icon + text) **Characteristics:** - Composed of atoms only - Single purpose or function - Reusable across contexts - May have minimal internal state ### 3. Organisms Complex, standalone sections of an interface. Organisms represent distinct sections that could exist independently. **Examples:** - Header (logo + navigation + user menu) - Footer (links + social icons + copyright) - Product card (image + title + price + add to cart) - Comment section (avatar + content + actions) - Sidebar navigation **Characteristics:** - Composed of molecules and atoms - Represent distinct UI sections - May contain business logic - Context-specific but reusable ### 4. Templates Page-level layouts that define content structure without actual content. Templates show the skeletal structure of a page. **Examples:** - Blog post template (header + content area + sidebar + footer) - Dashboard layout (navigation + main content + widgets) - Product page layout (gallery + details + related products) - Landing page structure **Characteristics:** - Composed of organisms - Define page structure - Use placeholder content - Establish content hierarchy ### 5. Pages Specific instances of templates with real, representative content. Pages are what users actually see and interact with. **Examples:** - Homepage with actual hero content - Product detail with real product data - User profile with actual user information - Blog post with real article content **Characteristics:** - Templates filled with real content - Represent actual user experience - Used for testing and validation - May reveal design issues ## Directory Structure ### Standard Structure ```text src/ quarks/ # Design tokens index.ts colors.ts spacing.ts typography.ts shadows.ts borders.ts components/ atoms/ Button/ Button.tsx Button.test.tsx Button.stories.tsx index.ts Input/ Label/ Icon/ molecules/ SearchForm/ FormField/ Card/ organisms/ Header/ Footer/ ProductCard/ templates/ MainLayout/ DashboardLayout/ pages/ HomePage/ ProductPage/ ``` ### Alternative Flat Structure ```text src/ quarks/ colors.ts spacing.ts typography.ts components/ atoms/ Button.tsx Input.tsx Label.tsx molecules/ SearchForm.tsx FormField.tsx organisms/ Header.tsx Footer.tsx templates/ MainLayout.tsx pages/ HomePage.tsx ``` ### Feature-Based Hybrid ```text src/ quarks/ # Shared design tokens index.ts colors.ts spacing.ts features/ products/ components/ atoms/ molecules/ organisms/ templates/ pages/ checkout/ components/ atoms/ molecules/ organisms/ shared/ components/ atoms/ molecules/ ``` ## Component Naming Conventions ### File Naming ```text # PascalCase for component files Button.tsx SearchForm.tsx ProductCard.tsx # Index files for clean imports index.ts # Test files Button.test.tsx Button.spec.tsx # Story files (Storybook) Button.stories.tsx ``` ### Component Naming ```typescript // Atoms - simple, descriptive names Button Input Label Avatar Icon // Molecules - action or composition-based names SearchForm FormField MediaObject NavItem // Organisms - section or feature-based names Header Footer ProductCard CommentSection UserProfile // Templates - layout-focused names MainLayout DashboardLayout AuthLayout // Pages - page-specific names HomePage ProductDetailPage CheckoutPage ``` ## Import Patterns ### Barrel Exports ```typescript // src/components/atoms/index.ts export { Button } from './Button'; export { Input } from './Input'; export { Label } from './Label'; export { Icon } from './Icon'; // src/components/molecules/index.ts export { SearchForm } from './SearchForm'; export { FormField } from './FormField'; // src/components/index.ts export * from './atoms'; export * from './molecules'; export * from './organisms'; ``` ### Usage ```typescript // Clean imports from barrel files import { Button, Input, Label } from '@/components/atoms'; import { SearchForm, FormField } from '@/components/molecules'; import { Header, Footer } from '@/components/organisms'; // Or from unified barrel import { Button, SearchForm, Header } from '@/components'; ``` ## Composition Rules ### Strict Hierarchy ```text Quarks -> Used by: Atoms, Molecules, Organisms, Templates, Pages Atoms -> Used by: Molecules, Organisms, Templates, Pages Molecules -> Used by: Organisms, Templates, Pages Organisms -> Used by: Templates, Pages Templates -> Used by: Pages Pages -> Not used by other components ``` ### Valid Compositions ```typescript // Atom using quarks for styling import { colors, spacing } from '@/quarks'; const Button = styled.button` background: ${colors.primary[500]}; {/* Quark */} padding: ${spacing.md}; {/* Quark */} `; // Molecule using atoms only const SearchForm = () => ( ); // Organism using molecules and atoms const Header = () => (

{/* Atom */} {/* Molecule */} {/* Molecule */} {/* Molecule */}

); // Template using organisms const MainLayout = ({ children }) => (

{/* Organism */}

{children}

); ``` ### Invalid Compositions (Anti-patterns) ```typescript // BAD: Atom importing from molecule // atoms/Button.tsx import { FormField } from '../molecules'; // WRONG! // BAD: Molecule importing from organism // molecules/SearchForm.tsx import { Header } from '../organisms'; // WRONG! // BAD: Skipping levels without justification // organisms/Header.tsx import { MainLayout } from '../templates'; // WRONG! ``` ## Design Tokens Integration ### Token Structure ```typescript // design-tokens/colors.ts export const colors = { primary: { 50: '#e3f2fd', 100: '#bbdefb', 500: '#2196f3', 900: '#0d47a1', }, neutral: { 0: '#ffffff', 100: '#f5f5f5', 900: '#212121', }, }; // design-tokens/spacing.ts export const spacing = { xs: '4px', sm: '8px', md: '16px', lg: '24px', xl: '32px', }; // design-tokens/typography.ts export const typography = { fontFamily: { sans: 'Inter, system-ui, sans-serif', mono: 'Fira Code, monospace', }, fontSize: { xs: '12px', sm: '14px', base: '16px', lg: '18px', xl: '24px', }, }; ``` ### Using Tokens in Atoms ```typescript import { colors, spacing, typography } from '@/design-tokens'; const Button = styled.button` background-color: ${colors.primary[500]}; padding: ${spacing.sm} ${spacing.md}; font-family: ${typography.fontFamily.sans}; font-size: ${typography.fontSize.base}; `; ``` ## Best Practices ### 1. Start with Atoms Build your design system from the ground up: ```typescript // 1. Define core atoms first const Button = ({ variant, size, children }) => { ... }; const Input = ({ type, placeholder }) => { ... }; const Label = ({ htmlFor, children }) => { ... }; // 2. Compose into molecules const FormField = ({ label, ...inputProps }) => (

{label}

); // 3. Build organisms from molecules const LoginForm = () => (

); ``` ### 2. Props Flow Downward ```typescript // Atoms receive primitive props interface ButtonProps { variant: 'primary' | 'secondary'; size: 'sm' | 'md' | 'lg'; disabled?: boolean; onClick?: () => void; children: React.ReactNode; } // Molecules receive atoms' props via spread interface SearchFormProps { onSubmit: (query: string) => void; inputProps?: Partial; buttonProps?: Partial; } // Organisms receive domain-specific props interface HeaderProps { user?: User; onLogout: () => void; navigation: NavItem[]; } ``` ### 3. Avoid Business Logic in Atoms ```typescript // BAD: Atom with business logic const PriceButton = ({ productId }) => { const price = useProductPrice(productId); // WRONG! return ; }; // GOOD: Atom receives processed data const PriceButton = ({ price, onClick }) => ( ); // Business logic lives in organisms or higher const ProductCard = ({ productId }) => { const { price } = useProduct(productId); return ; }; ``` ### 4. Document Component Purpose ```typescript /** * Button - Atomic component for user actions * * @level Atom * @example * */ export const Button: React.FC = ({ ... }) => { ... }; /** * SearchForm - Search input with submit button * * @level Molecule * @composition Input, Button * @example * search(query)} /> */ export const SearchForm: React.FC = ({ ... }) => { ... }; ``` ## Common Pitfalls ### 1. Over-Atomization ```typescript // BAD: Too granular - unnecessary atoms const ButtonText = ({ children }) => {children}; const ButtonContainer = ({ children }) =>

{children}

; // GOOD: Appropriate granularity const Button = ({ children }) => ( ); ``` ### 2. Under-Atomization ```typescript // BAD: Too much in one component const MegaForm = () => (

Name

Message

</div>
    <button>Submit</button>
  </form>
);

// GOOD: Properly decomposed
const ContactForm = () => (
  <form>
    <FormField label="Name" type="text" />
    <FormField label="Email" type="email" />
    <TextAreaField label="Message" />
    <Button type="submit">Submit</Button>
  </form>
);
```

### 3. Circular Dependencies

```typescript
// BAD: Atoms importing from molecules
// atoms/Icon.tsx
import { IconButton } from '../molecules'; // Creates circular dep!

// GOOD: Keep imports flowing downward
// molecules/IconButton.tsx
import { Icon } from '../atoms';
import { Button } from '../atoms';
```

### 4. Inconsistent Naming

```typescript
// BAD: Inconsistent naming patterns
atoms/btn.tsx
atoms/InputField.tsx
atoms/text-label.tsx

// GOOD: Consistent PascalCase
atoms/Button.tsx
atoms/Input.tsx
atoms/Label.tsx
```

## When to Use This Skill

- Setting up a new design system
- Organizing an existing component library
- Onboarding team members to atomic design
- Auditing component structure
- Planning component architecture
- Creating documentation for design systems
- Refactoring monolithic components

## Related Skills

- `atomic-design-quarks` - Design tokens and primitive values
- `atomic-design-atoms` - Creating atomic-level components
- `atomic-design-molecules` - Composing atoms into molecules
- `atomic-design-organisms` - Building complex organisms
- `atomic-design-templates` - Page layouts without content
- `atomic-design-integration` - Framework-specific implementation

## Resources

### Documentation

- Brad Frost's Atomic Design: <https://atomicdesign.bradfrost.com/>
- Pattern Lab: <https://patternlab.io/>

### Books

- "Atomic Design" by Brad Frost
- "Design Systems" by Alla Kholmatova

### Tools

- Storybook: <https://storybook.js.org/>
- Pattern Lab: <https://patternlab.io/>
- Fractal: <https://fractal.build/>
</article></body></html>

atomic-design-fundamentals

Install this skill

Comments