atomic-design-molecules

name	atomic-design-molecules
description	Use when composing atoms into molecule components like form fields, search bars, and card headers. Molecules are functional groups of atoms.
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]

Atomic Design: Molecules

Master the creation of molecule components - functional groups of atoms that work together as a unit. Molecules combine multiple atoms to create more complex, purposeful UI elements.

What Are Molecules?

Molecules are the first level of composition in Atomic Design. They are:

• Composed of atoms only: Never include other molecules
• Single purpose: Do one thing well
• Functional units: Atoms working together for a specific task
• Reusable: Used across different organisms and contexts
• Minimally stateful: May have limited internal state for UI concerns

Common Molecule Types

Form Molecules

• Form fields (label + input + error)
• Search forms (input + button)
• Toggle groups (label + toggle)
• Date pickers (input + calendar trigger)
• File uploaders (dropzone + button)

Navigation Molecules

• Nav items (icon + text + indicator)
• Breadcrumb items (link + separator)
• Pagination controls (buttons + page indicator)
• Tab items (icon + label)

Display Molecules

• Media objects (avatar + text)
• Card headers (title + subtitle + action)
• List items (checkbox + content + actions)
• Stat displays (label + value + trend)

Action Molecules

• Button groups (multiple buttons)
• Dropdown triggers (button + icon)
• Icon buttons (icon + tooltip)
• Action menus (button + menu items)

FormField Molecule Example

Complete Implementation

// molecules/FormField/FormField.tsx
import React from 'react';
import { Label } from '@/components/atoms/Label';
import { Input, type InputProps } from '@/components/atoms/Input';
import { Text } from '@/components/atoms/Typography';
import styles from './FormField.module.css';

export interface FormFieldProps extends InputProps {
  /** Field label */
  label: string;
  /** Unique field identifier */
  name: string;
  /** Help text below input */
  helpText?: string;
  /** Error message */
  error?: string;
  /** Required field indicator */
  required?: boolean;
}

export const FormField = React.forwardRef<HTMLInputElement, FormFieldProps>(
  (
    {
      label,
      name,
      helpText,
      error,
      required = ,
      id,
      className,
      ...inputProps
    },
    ref
  ) => {
     fieldId = id || ;
     helpTextId = helpText ?  : ;
     errorId = error ?  : ;

     describedBy = [helpTextId, errorId].().() || ;

     (
      
    );
  }
);

. = ;

/* molecules/FormField/FormField.module.css */
.field {
  display: flex;
  flex-direction: column;
  gap: 6px;
}

.helpText {
  margin-top: 2px;
}

.error {
  margin-top: 2px;
  display: flex;
  align-items: center;
  gap: 4px;
}

SearchForm Molecule Example

// molecules/SearchForm/SearchForm.tsx
import React, { useState, useCallback } from 'react';
import { Input } from '@/components/atoms/Input';
import { Button } from '@/components/atoms/Button';
import { Icon } from '@/components/atoms/Icon';
import styles from './SearchForm.module.css';

export interface SearchFormProps {
  /** Placeholder text */
  placeholder?: string;
  /** Initial search value */
  defaultValue?: string;
  /** Submit handler */
  onSubmit: (query: string) => void;
  /** Change handler for live search */
  onChange?: (query: string) => void;
  /** Loading state */
  isLoading?: boolean;
  /** Size variant */
  size?: 'sm' | 'md' | 'lg';
  /** Show clear button */
  ?: ;
}

  : .<> =  {
   [query, setQuery] = (defaultValue);

   handleChange = (
     {
       value = e..;
      (value);
      onChange?.(value);
    },
    [onChange]
  );

   handleSubmit = (
     {
      e.();
      (query.());
    },
    [onSubmit, query]
  );

   handleClear = ( {
    ();
    onChange?.();
  }, [onChange]);

   (
    
  );
};

. = ;

/* molecules/SearchForm/SearchForm.module.css */
.form {
  display: flex;
  gap: 8px;
  align-items: stretch;
}

.clearButton {
  display: flex;
  align-items: center;
  justify-content: center;
  background: transparent;
  border: none;
  cursor: pointer;
  padding: 4px;
  color: var(--color-neutral-500);
  transition: color 150ms;
}

.clearButton:hover {
  color: var(--color-neutral-700);
}

MediaObject Molecule Example

// molecules/MediaObject/MediaObject.tsx
import React from 'react';
import { Avatar, type AvatarProps } from '@/components/atoms/Avatar';
import { Text, Heading } from '@/components/atoms/Typography';
import styles from './MediaObject.module.css';

export interface MediaObjectProps {
  /** Avatar image source */
  avatarSrc?: string;
  /** Avatar alt text */
  avatarAlt: string;
  /** Avatar initials fallback */
  avatarInitials?: string;
  /** Avatar size */
  avatarSize?: AvatarProps['size'];
  /** Primary text/title */
  title: React.ReactNode;
  /** Secondary text/subtitle */
  subtitle?: React.ReactNode;
  /** Additional metadata */
  meta?: React.ReactNode;
  /** Right-aligned action element */
  action?: React.;
  
  ?:  |  | ;
  
  ?: ;
}

  : .<> =  {
   classNames = [styles., styles[], className]
    .()
    .();

   (
    
  );
};

. = ;

NavItem Molecule Example

// molecules/NavItem/NavItem.tsx
import React from 'react';
import { Icon } from '@/components/atoms/Icon';
import { Badge } from '@/components/atoms/Badge';
import styles from './NavItem.module.css';

export interface NavItemProps {
  /** Navigation icon */
  icon?: string;
  /** Item label */
  label: string;
  /** Link destination */
  href: string;
  /** Active state */
  isActive?: boolean;
  /** Badge count */
  badge?: number;
  /** Disabled state */
  disabled?: boolean;
  /** Click handler */
  onClick?: (e: React.MouseEvent) => void;
}

export const NavItem: React.FC<NavItemProps> = ({
  icon,
  label,
  href,
  isActive = ,
  badge,
  disabled = ,
  onClick,
}) => {
   classNames = [
    styles.,
    isActive && styles.,
    disabled && styles.,
  ]
    .()
    .();

    = () => {
     (disabled) {
      e.();
      ;
    }
    onClick?.(e);
  };

   (
    
  );
};

. = ;

CardHeader Molecule Example

// molecules/CardHeader/CardHeader.tsx
import React from 'react';
import { Heading, Text } from '@/components/atoms/Typography';
import { Icon } from '@/components/atoms/Icon';
import { Button } from '@/components/atoms/Button';
import styles from './CardHeader.module.css';

export interface CardHeaderProps {
  /** Card title */
  title: string;
  /** Optional subtitle */
  subtitle?: string;
  /** Title icon */
  icon?: string;
  /** Action button label */
  actionLabel?: string;
  /** Action button click handler */
  onAction?: () => void;
  /** Additional class name */
  className?: string;
}

export const CardHeader: React.FC<CardHeaderProps> = ({
  title,
  subtitle,
  icon,
  actionLabel,
  onAction,
  className,
}) => {
   (
    
  );
};

. = ;

ListItem Molecule Example

// molecules/ListItem/ListItem.tsx
import React from 'react';
import { Checkbox } from '@/components/atoms/Checkbox';
import { Text } from '@/components/atoms/Typography';
import { Icon } from '@/components/atoms/Icon';
import styles from './ListItem.module.css';

export interface ListItemProps {
  /** Item ID for selection */
  id: string;
  /** Primary content */
  primary: React.ReactNode;
  /** Secondary content */
  secondary?: React.ReactNode;
  /** Left icon */
  icon?: string;
  /** Whether item is selectable */
  selectable?: boolean;
  /** Selection state */
  selected?: boolean;
  /** Selection change handler */
  onSelect?: (id: string, selected: boolean) => void;
  
  ?: .;
  
  ?:  ;
}

  : .<> =  {
   classNames = [
    styles.,
    onClick && styles.,
    selected && styles.,
  ]
    .()
    .();

    = () => {
    onSelect?.(id, e..);
  };

   (
    
  );
};

. = ;

ButtonGroup Molecule Example

// molecules/ButtonGroup/ButtonGroup.tsx
import React from 'react';
import { Button, type ButtonProps } from '@/components/atoms/Button';
import styles from './ButtonGroup.module.css';

export interface ButtonGroupItem {
  id: string;
  label: string;
  icon?: string;
  disabled?: boolean;
}

export interface ButtonGroupProps {
  /** Button items */
  items: ButtonGroupItem[];
  /** Selected item ID(s) */
  value?: string | string[];
  /** Selection change handler */
  onChange?: (value: string | string[]) => void;
  /** Allow multiple selection */
  multiple?: boolean;
  /** Size variant */
  size?: ButtonProps['size'];
  /** Disabled state */
  disabled?: ;
}

  : .<> =  {
   selectedIds = .(value) ? value : [value].();

    = () => {
     (!onChange) ;

     (multiple) {
       newValue = selectedIds.(itemId)
        ? selectedIds.( id !== itemId)
        : [...selectedIds, itemId];
      (newValue);
    }  {
      (itemId);
    }
  };

   (
    
  );
};

. = ;

Stat Molecule Example

// molecules/Stat/Stat.tsx
import React from 'react';
import { Text, Heading } from '@/components/atoms/Typography';
import { Icon } from '@/components/atoms/Icon';
import styles from './Stat.module.css';

export type TrendDirection = 'up' | 'down' | 'neutral';

export interface StatProps {
  /** Stat label */
  label: string;
  /** Stat value */
  value: string | number;
  /** Previous value for comparison */
  previousValue?: string | number;
  /** Trend direction */
  trend?: TrendDirection;
  /** Trend percentage */
  trendValue?: string;
  /** Stat icon */
  icon?: string;
  /** Help text */
  helpText?: string;
}

export const Stat: .<> =  {
    = () => {
     (direction) {
       :
         ;
       :
         ;
      :
         ;
    }
  };

    = () => {
     (direction) {
       :
         ;
       :
         ;
      :
         ;
    }
  };

   (
    
  );
};

. = ;

Best Practices

1. Keep Molecules Focused

// GOOD: Single, clear purpose
const SearchForm = () => (
  <form>
    <Input placeholder="Search..." />
    <Button>Search</Button>
  </form>
);

// BAD: Doing too much
const SearchWithFiltersAndResults = () => (
  <div>
    <Input />
    <Button>Search</Button>
    <FilterDropdown />       {/* Should be separate molecule */}
    <ResultsList />          {/* Should be organism */}
    <Pagination />           {/* Should be separate molecule */}
  </div>
);

2. Only Import from Atoms

// GOOD: Only uses atoms
import { Button } from '@/components/atoms/Button';
import { Input } from '@/components/atoms/Input';
import { Icon } from '@/components/atoms/Icon';

// BAD: Importing from other molecules
import { FormField } from '@/components/molecules/FormField'; // Wrong level!
import { Button } from '@/components/atoms/Button';

3. Compose Props Carefully

// GOOD: Clear prop forwarding
interface SearchFormProps {
  onSubmit: (query: string) => void;
  inputProps?: Partial<InputProps>;
  buttonProps?: Partial<ButtonProps>;
}

// BAD: Confusing prop naming
interface SearchFormProps {
  inputPlaceholder?: string;
  inputDisabled?: boolean;
  inputSize?: string;
  buttonVariant?: string;
  buttonDisabled?: boolean;
  // ... endless prop forwarding
}

4. Manage Internal State Minimally

// GOOD: Minimal UI state
const SearchForm = ({ onSubmit }) => {
  const [query, setQuery] = useState('');

  return (
    <form onSubmit={() => onSubmit(query)}>
      <Input value={query} onChange={(e) => setQuery(e.target.value)} />
      <Button type="submit">Search</Button>
    </form>
  );
};

// BAD: Too much internal state
const SearchForm = () => {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);  // Should be in parent
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetchResults(query).then(setResults);  // Business logic in molecule!
  }, [query]);
};

Anti-Patterns to Avoid

1. Molecules Containing Molecules

// BAD: Molecule importing another molecule
// molecules/ComplexForm/ComplexForm.tsx
import { FormField } from '../FormField';  // Wrong!
import { SearchForm } from '../SearchForm'; // Wrong!

// GOOD: Keep at atom level, or promote to organism
// organisms/ComplexForm/ComplexForm.tsx
import { FormField } from '@/components/molecules/FormField';
import { SearchForm } from '@/components/molecules/SearchForm';

2. Business Logic in Molecules

// BAD: API calls in molecule
const SearchForm = ({ apiEndpoint }) => {
  const handleSubmit = async (query) => {
    const results = await fetch(`${apiEndpoint}?q=${query}`);
    // Processing results here...
  };
};

// GOOD: Delegate to parent
const SearchForm = ({ onSubmit }) => {
  const handleSubmit = (query) => {
    onSubmit(query); // Parent handles API logic
  };
};

3. Over-Abstraction

// BAD: Unnecessary molecule for single atom
const IconWrapper = ({ icon }) => <Icon name={icon} />;

// GOOD: Just use the atom directly
<Icon name="search" />

When to Use This Skill

• Combining atoms for specific functionality
• Creating reusable form components
• Building navigation elements
• Creating card and list components
• Establishing patterns for common UI combinations

Related Skills

• atomic-design-fundamentals - Core methodology overview
• atomic-design-atoms - Creating atomic components
• atomic-design-organisms - Building complex organisms