What is a MOLECULE in Atomic Design?

A MOLECULE is a small UI pattern formed by combining atoms into a functional React component, intended to be reusable and lightly stateful for UI concerns.

Should MOLECULEs fetch data or orchestrate apps?

No. They should avoid remote fetching and app-level orchestration; keep state local to the widget unless otherwise required.

How should you handle state: controlled vs uncontrolled?

Prefer controlled where it matters; if you support both, do it intentionally and document the behavior.

atomic-molecule

npx machina-cli add skill andireuter/skills-webapp/atomic-molecule --openclaw

Files (1)

SKILL.md

1.5 KB

Atomic Design: MOLECULE (React Functional Components)

You are creating a MOLECULE: a composition of atoms that forms a small UI pattern.

Hard rules

Functional components only.
Composition over configuration:
- Prefer composing atoms with children/slots.
- Keep props focused on the pattern’s essential degrees of freedom.
State scope:
- Local UI state is allowed only when it’s intrinsic to the widget (e.g., input focus, password visibility).
- No remote fetching; no app-level orchestration.
Accessibility:
- Ensure correct labeling relationships (label + htmlFor, aria-describedby, error messaging).
Controlled/uncontrolled:
- Prefer controlled where it matters; if supporting both, do it intentionally and document behavior.

Output expectations

Provide:
1. Component.tsx
2. Component.test.tsx (render + key interactions + a11y-critical attributes)
3. Component.stories.tsx (happy path + edge states like error/disabled)

Recommended folder conventions

src/components/molecules/<ComponentName>/...

Molecule checklist

Built from atoms
Minimal and well-documented props
Handles validation/error UI predictably
No domain-specific coupling

Source

git clone https://github.com/andireuter/skills-webapp/blob/main/skills/atomic-molecule/SKILL.mdView on GitHub

Overview

MOLECULEs are small UI patterns created by composing atoms into a functional React component. They cover input groups, labeled fields, search bars, and card headers, enabling consistent, reusable UI blocks. They stay lightly stateful, focusing on UI concerns and accessibility.

How This Skill Works

Each MOLECULE is a functional component that composes atoms via children or slots. Props are minimal and focused on the pattern’s essential degrees of freedom while avoiding app-wide orchestration or data fetching. Local UI state is allowed only when intrinsic to the widget, and accessibility is enforced through proper label relationships and ARIA attributes.

When to Use It

When building an input group with a label, helper text, and validation.
For labeled fields like search bars or form rows that repeat across pages.
To assemble a card header or section header from smaller atoms.
When refactoring legacy UI into reusable small UI patterns.
When the component needs only local UI state (e.g., focus, visibility).

Quick Start

Step 1: Create a functional Component.tsx that composes atoms into a MOLECULE.
Step 2: Expose a minimal, well-documented set of props for label, hint, error, and disabled.
Step 3: Add Component.test.tsx and Component.stories.tsx covering happy paths and edge cases (error/disabled) and ensure accessibility attributes.

Best Practices

Compose from atoms using children/slots rather than heavy config objects.
Keep props minimal and document the pattern’s essential knobs.
Prefer controlled inputs where it matters; support both if necessary and document behavior.
Limit internal state to UI concerns; avoid remote data and app orchestration.
Ensure accessibility: correct label relationships, aria attributes, and error messaging.

Example Use Cases

SearchBar composed of an input atom plus an action button.
Labeled input group with inline helper and error messaging.
CardHeader molecule with a title and trailing actions.
Password field with visibility toggle.
Form row that displays validation state without fetching data.

Frequently Asked Questions

Add this skill to your agents