Atom

What is an Atom?

Atoms are the fundamental building blocks of UI—single-purpose components that do one thing well (button, input, icon, label). They're the LEGO bricks of your interface, highly reusable and composable into complex UIs.

Key Principles

1. Single Responsibility: Each atom does ONE thing. A Button clicks, an Input captures text, an Icon displays a symbol. Never combine purposes.

2. Framework Agnostic Props: Accept simple, primitive props (strings, numbers, booleans, callbacks). Avoid framework-specific patterns in the interface.

3. Design Token Integration: Use design tokens (colors, spacing, typography) from theme—atoms enforce visual consistency across the entire application.

Best Practices

✅ DO:

• Keep atoms under 50 lines of code
• Accept className or style for customization
• Include accessibility attributes (aria-label, role)
• Make atoms stateless when possible—receive data via props
• Export with default and named exports for flexibility

❌ DON'T:

• Fetch data inside atoms
• Include business logic
• Hardcode colors/spacing—use theme tokens
• Create atoms that render other atoms (that's a molecule)
• Manage complex internal state

Code Patterns

Recommended

// Button.jsx - Single purpose atom
const Button = ({ 
  label, 
  onClick, 
  variant = 'primary',
  disabled = false,
  ariaLabel 
}) => (
  <button
    className={`btn btn--${variant}`}
    onClick={onClick}
    disabled={disabled}
    aria-label={ariaLabel || label}
  >
    {label}
  </button>
);

Avoid

// ❌ WRONG - Atom doing too much
const Button = ({ onClick }) => {
  const [loading, setLoading] = useState(false);
  const handleClick = async () => {
    setLoading(true);
    await fetch('/api/action'); // Don't fetch in atoms!
    setLoading(false);
  };
  return <button onClick={handleClick}>Submit</button>;
};

// ✅ CORRECT - Parent handles logic, atom stays pure
const Button = ({ label, onClick, loading }) => (
  <button onClick={onClick} disabled={loading}>
    {loading ? 'Loading...' : label}
  </button>
);

Related Terminologies

• Molecule (UI) - Composed of multiple atoms working together
• Component (UI) - Generic term; atoms are a type of component
• Props (UI) - How atoms receive data
• Theme (UI) - Provides design tokens atoms consume

Quality Gates

• Single responsibility maintained
• Props are simple primitives or callbacks
• No data fetching or business logic
• Accessibility attributes included
• Uses design tokens from theme

Source: /docs/ui/atom.md