atomic-design-atoms

name	atomic-design-atoms
user-invocable	false
description	Use when creating atomic-level UI components like buttons, inputs, labels, and icons. The smallest building blocks of a design system.
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]

Atomic Design: Atoms

Master the creation of atomic components - the fundamental, indivisible building blocks of your design system. Atoms are the smallest functional units that cannot be broken down further without losing meaning.

What Are Atoms?

Atoms are the basic UI elements that serve as the foundation for everything else in your design system. They are:

• Indivisible: Cannot be broken down into smaller functional units
• Reusable: Used throughout the application in various contexts
• Stateless: Typically controlled by parent components
• Styled: Implement design tokens for consistent appearance
• Accessible: Built with a11y in mind from the start

Common Atom Types

Interactive Atoms

• Buttons
• Links
• Inputs (text, checkbox, radio, select)
• Toggles/Switches
• Sliders

Display Atoms

• Typography (headings, paragraphs, labels)
• Icons
• Images/Avatars
• Badges/Tags
• Dividers
• Spinners/Loaders

Form Atoms

• Input fields
• Textareas
• Checkboxes
• Radio buttons
• Select dropdowns
• Labels

Button Atom Example

Basic Implementation

// atoms/Button/Button.tsx
import React from 'react';
import type { ButtonHTMLAttributes } from 'react';
import styles from './Button.module.css';

export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'danger';
export type ButtonSize = 'sm' | 'md' | 'lg';

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /** Visual style variant */
  variant?: ButtonVariant;
  /** Size of the button */
  size?: ButtonSize;
  /** Full width button */
  fullWidth?: boolean;
  /** Loading state */
  isLoading?: boolean;
  /** Left icon */
  leftIcon?: React.ReactNode;
  /** Right icon */
  rightIcon?: React.ReactNode;
}

   = .<, >(
   {
     classNames = [
      styles.,
      styles[variant],
      styles[size],
      fullWidth && styles.,
      isLoading && styles.,
      className,
    ]
      .()
      .();

     (
      
        )}
      </button>
    );
  }
);

. = ;

Button Styles

/* atoms/Button/Button.module.css */
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  border: none;
  border-radius: 6px;
  font-weight: 500;
  cursor: pointer;
  transition: all 150ms ease-in-out;
  text-decoration: none;
}

.button:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

.button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

/* Variants */
.primary {
  background-color: var(--color-primary-500);
  color: var(--color-white);
}

.primary:hover:not(:disabled) {
  background-color: var(--color-primary-600);
}

.secondary {
  background-color: transparent;
  color: var(--color-primary-500);
  border: 1px solid (--color-primary-);
}

() {
  : (--color-primary-);
}

 {
  : transparent;
  : (--color-primary-);
}

() {
  : (--color-primary-);
}

 {
  : (--color-danger-);
  : (--color-white);
}

() {
  : (--color-danger-);
}


 {
  :  ;
  : ;
  : ;
}

 {
  :  ;
  : ;
  : ;
}

 {
  :  ;
  : ;
  : ;
}


 {
  : ;
}

 {
  : relative;
  : transparent;
}

 {
  : absolute;
  : ;
  : ;
  :  solid currentColor;
  : transparent;
  : ;
  : spin  linear infinite;
}

 spin {
   {
    : ();
  }
}


,
 {
  : flex;
  : center;
}

Input Atom Example

// atoms/Input/Input.tsx
import React from 'react';
import type { InputHTMLAttributes } from 'react';
import styles from './Input.module.css';

export type InputSize = 'sm' | 'md' | 'lg';

export interface InputProps
  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
  /** Size variant */
  size?: InputSize;
  /** Error state */
  hasError?: boolean;
  /** Left addon element */
  leftAddon?: React.ReactNode;
  /** Right addon element */
  rightAddon?: React.ReactNode;
}

export const Input = React.forwardRef<HTMLInputElement, InputProps>(
  (
    {
      size = 'md',
      hasError = false,
      leftAddon,
      rightAddon,
      disabled,
      className,
      ...props
    },
    ref
  ) => {
     wrapperClasses = [
      styles.,
      styles[size],
      hasError && styles.,
      disabled && styles.,
      className,
    ]
      .()
      .();

     (
      
    );
  }
);

. = ;

/* atoms/Input/Input.module.css */
.wrapper {
  display: flex;
  align-items: center;
  border: 1px solid var(--color-neutral-300);
  border-radius: 6px;
  background-color: var(--color-white);
  transition: border-color 150ms, box-shadow 150ms;
}

.wrapper:focus-within {
  border-color: var(--color-primary-500);
  box-shadow: 0 0 0 3px var(--color-primary-100);
}

.input {
  flex: 1;
  border: none;
  background: transparent;
  outline: none;
  width: 100%;
}

.input::placeholder {
  color: var(--color-neutral-400);
}

/* Error state */
.error {
  border-color: var(--color-danger-500);
}

.error:focus-within {
  border-color: var(--color-danger-500);
  box-shadow:     (--color-danger-);
}


 {
  : (--color-neutral-);
  : not-allowed;
}

  {
  : not-allowed;
}


 {
  : ;
}

  {
  :  ;
  : ;
}

 {
  : ;
}

  {
  :  ;
  : ;
}

 {
  : ;
}

  {
  :  ;
  : ;
}


,
 {
  : flex;
  : center;
  :  ;
  : (--color-neutral-);
}

Label Atom Example

// atoms/Label/Label.tsx
import React from 'react';
import type { LabelHTMLAttributes } from 'react';
import styles from './Label.module.css';

export interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
  /** Indicates required field */
  required?: boolean;
  /** Disabled state styling */
  disabled?: boolean;
}

export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
  ({ required = false, disabled = false, children, className, ...props }, ref) => {
    const classNames = [
      styles.label,
      disabled && styles.disabled,
      className,
    ]
      .filter(Boolean)
      .join(' ');

    return (
      <label ref={ref} className={classNames} {}>
        {children}
        {required && (
          
            *
          
        )}
      
    );
  }
);

. = ;

Icon Atom Example

// atoms/Icon/Icon.tsx
import React from 'react';

export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

const sizeMap: Record<IconSize, number> = {
  xs: 12,
  sm: 16,
  md: 20,
  lg: 24,
  xl: 32,
};

export interface IconProps extends React.SVGAttributes<SVGElement> {
  /** Icon name/identifier */
  name: string;
  /** Icon size */
  size?: IconSize;
  /** Custom color */
  color?: string;
  /** Accessible label */
  label?: string;
}

export const Icon: React.FC<IconProps> = ({
  name,
  size = ,
  color = ,
  label,
  className,
  ...props
}) => {
   pixelSize = sizeMap[size];

   (
    
  );
};

. = ;

Avatar Atom Example

// atoms/Avatar/Avatar.tsx
import React from 'react';
import styles from './Avatar.module.css';

export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

export interface AvatarProps {
  /** Image source URL */
  src?: string;
  /** Alt text for image */
  alt: string;
  /** Fallback initials */
  initials?: string;
  /** Size variant */
  size?: AvatarSize;
  /** Additional class name */
  className?: string;
}

export const Avatar: React.FC<AvatarProps> = ({
  src,
  alt,
  initials,
  size = 'md',
  className,
}) => {
  const [imageError, setImageError] = React.useState(false);

  const classNames = [styles.avatar, styles[size], className]
    .filter(Boolean)
    .();

   showImage = src && !imageError;
   showInitials = !showImage && initials;

   (
    
  );
};

. = ;

Badge Atom Example

// atoms/Badge/Badge.tsx
import React from 'react';
import styles from './Badge.module.css';

export type BadgeVariant =
  | 'default'
  | 'primary'
  | 'success'
  | 'warning'
  | 'danger'
  | 'info';

export type BadgeSize = 'sm' | 'md';

export interface BadgeProps {
  /** Visual variant */
  variant?: BadgeVariant;
  /** Size variant */
  size?: BadgeSize;
  /** Badge content */
  children: React.ReactNode;
  /** Additional class name */
  className?: string;
}

export const Badge: React.FC<BadgeProps> = ({
  variant = 'default',
  size = 'md',
  children,
  className,
}) => {
  const classNames = [styles.badge, styles[variant], styles[size], className]
    .filter()
    .();

   ;
};

. = ;

Checkbox Atom Example

// atoms/Checkbox/Checkbox.tsx
import React from 'react';
import type { InputHTMLAttributes } from 'react';
import styles from './Checkbox.module.css';

export interface CheckboxProps
  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
  /** Indeterminate state */
  indeterminate?: boolean;
  /** Label text */
  label?: string;
}

export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
  ({ indeterminate = false, label, disabled, className, ...props }, ref) => {
    const inputRef = React.useRef<HTMLInputElement>(null);

    React.useImperativeHandle(ref, () => inputRef.current!);

    React.useEffect(() => {
      if (inputRef.current) {
        inputRef.. = indeterminate;
      }
    }, [indeterminate]);

     wrapperClasses = [
      styles.,
      disabled && styles.,
      className,
    ]
      .()
      .();

     checkbox = (
      
    );

     (label) {
       (
        
      );
    }

     checkbox;
  }
);

. = ;

Typography Atoms

// atoms/Typography/Text.tsx
import React from 'react';
import styles from './Typography.module.css';

export type TextSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
export type TextColor = 'default' | 'muted' | 'primary' | 'success' | 'danger';

export interface TextProps {
  as?: 'p' | 'span' | 'div';
  size?: TextSize;
  weight?: TextWeight;
  color?: TextColor;
  truncate?: boolean;
  children: React.ReactNode;
  className?: string;
}

export const Text: React.<> =  {
   classNames = [
    styles.,
    styles[],
    styles[],
    styles[],
    truncate && styles.,
    className,
  ]
    .()
    .();

   ;
};


   =  |  |  |  |  | ;

   {
  : ;
  ?: ;
  : .;
  ?: ;
}

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

   ;
};

Best Practices

1. Use forwardRef for DOM Access

// GOOD: Allows parent to access DOM node
export const Input = React.forwardRef<HTMLInputElement, InputProps>(
  (props, ref) => <input ref={ref} {...props} />
);

// BAD: No way for parent to access DOM
export const Input = (props: InputProps) => <input {...props} />;

2. Extend Native HTML Attributes

// GOOD: Supports all native button attributes
interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
}

// BAD: Missing native attributes
interface ButtonProps {
  onClick?: () => void;
  disabled?: boolean;
}

3. Provide Sensible Defaults

// GOOD: Works out of the box
export const Button = ({
  variant = 'primary',
  size = 'md',
  type = 'button', // Prevent accidental form submissions
  ...props
}) => { ... };

// BAD: Requires explicit props
export const Button = ({ variant, size, ...props }) => { ... };

4. Keep Atoms Presentation-Only

// GOOD: No business logic
const Button = ({ onClick, children }) => (
  <button onClick={onClick}>{children}</button>
);

// BAD: Atom has API call
const SubmitButton = () => {
  const handleClick = async () => {
    await api.submit(); // Business logic in atom!
  };
  return <button onClick={handleClick}>Submit</button>;
};

Anti-Patterns to Avoid

1. Atoms with Internal State

// BAD: Atom manages its own state
const Input = () => {
  const [value, setValue] = useState('');
  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
};

// GOOD: Controlled by parent
const Input = ({ value, onChange }) => (
  <input value={value} onChange={onChange} />
);

2. Atoms with Complex Logic

// BAD: Complex validation in atom
const EmailInput = ({ value, onChange }) => {
  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
  return <input value={value} className={isValid ? '' : 'error'} />;
};

// GOOD: Validation handled by parent/molecule
const Input = ({ value, onChange, hasError }) => (
  <input value={value} className={hasError ? 'error' : ''} />
);

3. Hardcoded Styles

// BAD: Hardcoded colors
const Button = () => (
  <button style={{ backgroundColor: '#2196f3' }}>Click</button>
);

// GOOD: Uses design tokens
const Button = () => (
  <button style={{ backgroundColor: 'var(--color-primary-500)' }}>
    Click
  </button>
);

When to Use This Skill

• Creating new basic UI components
• Refactoring existing components to atoms
• Building a design system foundation
• Ensuring consistency across components
• Improving component reusability

Related Skills

• atomic-design-fundamentals - Core methodology overview
• atomic-design-molecules - Composing atoms into molecules