Flutter Atomic Components

Overview

The same atomic-design discipline the web app follows applies to Flutter: build a shared component library organized by level and compose screens from it. This keeps the app visually consistent and makes screens small.

Core principle: Reuse before you build. Before writing any button/card/chip/input/list-row, search the component library — hand-rolling a duplicate is a review-blocking defect.

The Levels

Level	What	Flutter example
Atom	Smallest reusable UI, no app logic	AppButton, AppTextField, StatusChip, Avatar
Molecule	A few atoms forming a unit	TaskCard (title + chip + avatar), SearchBar
Organism	Section built from molecules/atoms	TaskList, BoardColumn, AppBarWithActions
Screen	Route wiring organisms to state	TaskBoardScreen

Library lives under lib/ui/core/{atoms,molecules,organisms} — the official Flutter architecture layout — alongside lib/ui/features/<feature>/ for screen-specific composition; follow the app's existing layout if it differs (e.g. a flat lib/ui/atoms).

INVENTORY.md

lib/ui/core/INVENTORY.md: header One line per component: level · name · purpose · variants, one bullet per component, added in the same commit that creates or meaningfully changes it. Check it before building anything — it's faster than grepping the tree and it's the thing the next task's agent will actually read. If the repo has no component library or theme yet, load mobile-design-system-foundation first.

Rules

• Before creating a component, check INVENTORY.md / grep the library. If an atom exists, use it. If it almost fits, extend it backward-compatibly — don't fork a near-duplicate.
• Place new components at the correct level. A button is an atom; a card composed of atoms is a molecule. A "component" that fetches data is not a component — split the presentation out.
• Atoms take data + callbacks, never talk to services. AppButton({required this.label, required this.onPressed}). State/data flows from the screen down.
• Atoms carry no outer margin of their own — spacing between atoms is the parent's job (a Row/Column with spacing:, or explicit SizedBox/padding at the call site), so the same atom composes correctly in every context without fighting a built-in margin.
• Style through the theme (see flutter-widget-architecture) so every instance of an atom looks identical.
• Changing a shared atom: grep every call site first; keep the change backward-compatible or update all callers in the same task. The build must stay green.

Worked Example

Task: "add a priority badge to task cards." Wrong: add a Container with a colored label inline in TaskCard. Right:

1. Check INVENTORY.md / grep atoms → no PriorityBadge, but there is a StatusChip atom. Priority is distinct enough → add a PriorityBadge atom next to it, themed the same way.
2. Compose it into the TaskCard molecule.
3. Both the badge atom and the card get a widget test.
4. Add the PriorityBadge line to INVENTORY.md in the same commit.

Now every screen showing a task card gets the badge for free, consistently.

Common Mistakes

• Inline Container/Text styling that reinvents an existing atom.
• A component with a network/service call inside → not a component.
• New component dumped at the wrong level (an organism where an atom belongs).
• Breaking a shared atom's constructor without updating callers.
• A new component added to the library with no INVENTORY.md line.
• An atom with a built-in outer margin, so it looks right in one layout and wrong in the next.

Red Flags

• Two screens render visually identical buttons built differently.
• A "widget" imports a repository or http client.
• Copy-pasted styled Containers across screens.
• lib/ui/core/ (or the repo's component folder) with no INVENTORY.md.