atomic-design-fundamentals

$27

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

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

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

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

# 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

// 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

// 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

// 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

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

// 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 = () => (

  <form>

    <Input placeholder="Search..." />  {/* Atom */}

    <Button>Search</Button>            {/* Atom */}

  </form>

);

// Organism using molecules and atoms

const Header = () => (

  <header>

    <Logo />                           {/* Atom */}

    <Navigation />                     {/* Molecule */}

    <SearchForm />                     {/* Molecule */}

    <UserMenu />                       {/* Molecule */}

  </header>

);

// Template using organisms

const MainLayout = ({ children }) => (

  <div>

    <Header />                         {/* Organism */}

    <main>{children}</main>

    <Footer />                         {/* Organism */}

  </div>

);

Invalid Compositions (Anti-patterns)

// 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

// 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

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:

// 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 }) => (

  <div>

    <Label>{label}</Label>

    <Input {...inputProps} />

  </div>

);

// 3. Build organisms from molecules

const LoginForm = () => (

  <form>

    <FormField label="Email" type="email" />

    <FormField label="Password" type="password" />

    <Button>Login</Button>

  </form>

);

2. Props Flow Downward

// 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<InputProps>;

  buttonProps?: Partial<ButtonProps>;

}

// Organisms receive domain-specific props

interface HeaderProps {

  user?: User;

  onLogout: () => void;

  navigation: NavItem[];

}

3. Avoid Business Logic in Atoms

// BAD: Atom with business logic

const PriceButton = ({ productId }) => {

  const price = useProductPrice(productId); // WRONG!

  return <Button>${price}</Button>;

};

// GOOD: Atom receives processed data

const PriceButton = ({ price, onClick }) => (

  <Button onClick={onClick}>${price}</Button>

);

// Business logic lives in organisms or higher

const ProductCard = ({ productId }) => {

  const { price } = useProduct(productId);

  return <PriceButton price={price} onClick={handleBuy} />;

};

4. Document Component Purpose

/**

 * Button - Atomic component for user actions

 *

 * @level Atom

 * @example

 * <Button variant="primary" size="md">Click me</Button>

 */

export const Button: React.FC<ButtonProps> = ({ ... }) => { ... };

/**

 * SearchForm - Search input with submit button

 *

 * @level Molecule

 * @composition Input, Button

 * @example

 * <SearchForm onSubmit={(query) => search(query)} />

 */

export const SearchForm: React.FC<SearchFormProps> = ({ ... }) => { ... };

Common Pitfalls

1. Over-Atomization

// BAD: Too granular - unnecessary atoms

const ButtonText = ({ children }) => <span>{children}</span>;

const ButtonContainer = ({ children }) => <div>{children}</div>;

// GOOD: Appropriate granularity

const Button = ({ children }) => (

  <button className="btn">{children}</button>

);

2. Under-Atomization

// BAD: Too much in one component

const MegaForm = () => (

  <form>

    <div><label>Name</label><input /></div>

    <div><label>Email</label><input /></div>

    <div><label>Message</label><textarea /></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

// 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

// 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/