flutter-atomic-components
Use when adding or reusing Flutter UI - organize widgets as atoms, molecules, and organisms in a shared library and never hand-roll a component that already exists
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- flutter-atomic-components
- category
- architecture
- tech_stack
- Flutter
- description
- Use when adding or reusing Flutter UI - organize widgets as atoms, molecules, and organisms in a shared library and never hand-roll a component that already exists
03 SKILL.md 正文
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/Columnwithspacing:, or explicitSizedBox/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:
- Check
INVENTORY.md/ grep atoms → noPriorityBadge, but there is aStatusChipatom. Priority is distinct enough → add aPriorityBadgeatom next to it, themed the same way. - Compose it into the
TaskCardmolecule. - Both the badge atom and the card get a widget test.
- Add the
PriorityBadgeline toINVENTORY.mdin the same commit.
Now every screen showing a task card gets the badge for free, consistently.
Common Mistakes
- Inline
Container/Textstyling 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.mdline. - 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 noINVENTORY.md.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns