Component Decomposition Advisor
You detected that the user is working on a UI component that needs decomposition into the Atomic Design hierarchy. This skill applies to Flutter widgets and Vite components (React / Vue / Svelte / Solid / vanilla JS+TS with HTML partials).
Stack Detection
Before proposing a decomposition, identify the stack:
pubspec.yaml at repo root → Fluttervite.config.{js,ts,mjs,cjs} at repo root or "vite" in package.json devDependencies → Vite- Within Vite, sub-detect from
package.json: React (react), Vue (vue), Svelte (svelte), Solid (solid-js), or Vanilla when none of those are present
File conventions differ per stack — the Atomic Design methodology does not.
Atomic Design Levels
Read ${CLAUDE_PLUGIN_ROOT}/references/atomic-methodology.md for the full methodology.
Quick reference:
| Level |
Responsibility |
State? |
Examples |
| Atom |
Single-purpose UI element, no business logic |
No (stateless) |
Button, Avatar, Badge, TextInput, Icon |
| Molecule |
Atoms composed with local interaction logic |
Minimal (form state) |
SearchBar, UserChip, RatingStars |
| Organism |
Molecules with data binding and state management |
Yes (provider / store / hook) |
UserList, CommentThread, ProductCard |
| Template |
Page layout structure, slots for organisms |
No (layout only) |
DashboardTemplate, DetailTemplate |
| Page |
Template bound to route and data providers |
Yes (route + DI) |
DashboardPage, ProfilePage |
When a Component Needs Decomposition
Signals are consistent across stacks, with framework-specific thresholds:
- Size — Flutter widget >150 lines; React/Vue/Svelte component >250 lines; vanilla HTML partial >400 lines.
- Mixing layout + logic + state — Concerns should live at different atomic levels.
- Used in 2+ features — Candidate for extraction to a shared location.
- Stateful primitive — A "button atom" that owns a store / context / hook is misclassified; it is really an organism.
- Inline compositions — Sub-components built inline should become their own files so they can be tested and reused.
- Missing gallery entry — A shared component without a Widgetbook / Storybook / Histoire story is harder to discover and review.
How To Help
- Read the component the user is working on.
- Identify which parts are atoms, molecules, and organisms.
- Propose a decomposition table (same format as
/atomic-design-toolkit:generate).
- Ask for approval before refactoring.
- Generate the decomposed files with the appropriate gallery entries (Widgetbook for Flutter, Storybook / Histoire for Vite SPA frameworks, a static demo page or Playwright visual test for vanilla Vite).
File Placement Rules
Flutter
- Shared widgets →
core/widgets/{atoms|molecules|organisms}/
- Feature-specific →
features/{feature}/presentation/{templates|pages}/
- Widgetbook →
{widget_name}.widgetbook.dart alongside the widget
Vite — React / Vue / Svelte / Solid
- Shared components →
src/components/{atoms|molecules|organisms}/
- Templates / layouts →
src/layouts/ or src/templates/
- Pages / routes →
src/pages/ or src/routes/
- Stories →
{ComponentName}.stories.{tsx,jsx,vue,svelte} alongside the component (Storybook) or {ComponentName}.story.{tsx,vue,svelte} (Histoire)
Vite — Vanilla (Seacrets pattern)
- A "component" is a triple: HTML partial + ESM module + SCSS/CSS
- Atoms / molecules / organisms split across three parallel directories:
resources/views/{atoms|molecules|organisms}/resources/js/{atoms|molecules|modules}/resources/scss/{atoms|molecules|organisms}/
- Templates →
resources/views/layouts/
- Pages →
resources/views/pages/ (or rendered by a server-side controller)
Anti-Patterns
Cross-Stack
- Never hardcode colors — use the stack's token system.
- Never skip gallery entries for shared components.
- Never put business logic in atoms or molecules.
- Never create a page without a template.
Flutter-Specific
- Use
Theme.of(context).colorScheme / textTheme, never literal Color(0x...) values.
- Use the project's state management (Riverpod / Bloc / Provider) in organisms, not
setState.
Vite-Specific
- React / Vue / Solid: tokens come from CSS variables or Tailwind theme — never hardcode hex values in JSX / templates.
- Vanilla + Bootstrap: use Bootstrap utility classes or Sass variables; never inline styles.
- Keep the partial / module / style triple co-located so a reviewer can find all three in one place.
1---2name: widget-decomposition3description: Auto-activates when the user is working on a UI component that needs decomposition into the Atomic Design hierarchy. Works for Flutter widgets and for Vite components (React, Vue, Svelte, Solid, vanilla JS+TS modules with HTML partials). Triggers on: "decompose this widget", "decompose this component", "this widget is too big", "refactor into atoms", "split this into molecules", "extract reusable component", "widget is monolithic", "component is monolithic", "too many responsibilities", "move to core/widgets", "move to src/components", "create atom from this", "Widgetbook entry", "Storybook story", "Histoire story". Do NOT trigger for: design system comparisons (use design-system-analyzer), full codebase audits (use /atomic-design-toolkit:audit command), or non-UI code.4---56# Component Decomposition Advisor78You detected that the user is working on a UI component that needs decomposition into the Atomic Design hierarchy. This skill applies to **Flutter** widgets and **Vite** components (React / Vue / Svelte / Solid / vanilla JS+TS with HTML partials).910## Stack Detection1112Before proposing a decomposition, identify the stack:1314- `pubspec.yaml` at repo root → **Flutter**15- `vite.config.{js,ts,mjs,cjs}` at repo root or `"vite"` in `package.json` devDependencies → **Vite**16- Within Vite, sub-detect from `package.json`: React (`react`), Vue (`vue`), Svelte (`svelte`), Solid (`solid-js`), or **Vanilla** when none of those are present1718File conventions differ per stack — the Atomic Design methodology does not.1920## Atomic Design Levels2122Read `${CLAUDE_PLUGIN_ROOT}/references/atomic-methodology.md` for the full methodology.2324Quick reference:2526| Level | Responsibility | State? | Examples |27|-------|---------------|--------|----------|28| **Atom** | Single-purpose UI element, no business logic | No (stateless) | Button, Avatar, Badge, TextInput, Icon |29| **Molecule** | Atoms composed with local interaction logic | Minimal (form state) | SearchBar, UserChip, RatingStars |30| **Organism** | Molecules with data binding and state management | Yes (provider / store / hook) | UserList, CommentThread, ProductCard |31| **Template** | Page layout structure, slots for organisms | No (layout only) | DashboardTemplate, DetailTemplate |32| **Page** | Template bound to route and data providers | Yes (route + DI) | DashboardPage, ProfilePage |3334## When a Component Needs Decomposition3536Signals are consistent across stacks, with framework-specific thresholds:3738- **Size** — Flutter widget >150 lines; React/Vue/Svelte component >250 lines; vanilla HTML partial >400 lines.39- **Mixing layout + logic + state** — Concerns should live at different atomic levels.40- **Used in 2+ features** — Candidate for extraction to a shared location.41- **Stateful primitive** — A "button atom" that owns a store / context / hook is misclassified; it is really an organism.42- **Inline compositions** — Sub-components built inline should become their own files so they can be tested and reused.43- **Missing gallery entry** — A shared component without a Widgetbook / Storybook / Histoire story is harder to discover and review.4445## How To Help46471. Read the component the user is working on.482. Identify which parts are atoms, molecules, and organisms.493. Propose a decomposition table (same format as `/atomic-design-toolkit:generate`).504. Ask for approval before refactoring.515. Generate the decomposed files with the appropriate gallery entries (Widgetbook for Flutter, Storybook / Histoire for Vite SPA frameworks, a static demo page or Playwright visual test for vanilla Vite).5253## File Placement Rules5455### Flutter56- Shared widgets → `core/widgets/{atoms|molecules|organisms}/`57- Feature-specific → `features/{feature}/presentation/{templates|pages}/`58- Widgetbook → `{widget_name}.widgetbook.dart` alongside the widget5960### Vite — React / Vue / Svelte / Solid61- Shared components → `src/components/{atoms|molecules|organisms}/`62- Templates / layouts → `src/layouts/` or `src/templates/`63- Pages / routes → `src/pages/` or `src/routes/`64- Stories → `{ComponentName}.stories.{tsx,jsx,vue,svelte}` alongside the component (Storybook) or `{ComponentName}.story.{tsx,vue,svelte}` (Histoire)6566### Vite — Vanilla (Seacrets pattern)67- A "component" is a triple: HTML partial + ESM module + SCSS/CSS68- Atoms / molecules / organisms split across three parallel directories:69 - `resources/views/{atoms|molecules|organisms}/`70 - `resources/js/{atoms|molecules|modules}/`71 - `resources/scss/{atoms|molecules|organisms}/`72- Templates → `resources/views/layouts/`73- Pages → `resources/views/pages/` (or rendered by a server-side controller)7475## Anti-Patterns7677### Cross-Stack78- Never hardcode colors — use the stack's token system.79- Never skip gallery entries for shared components.80- Never put business logic in atoms or molecules.81- Never create a page without a template.8283### Flutter-Specific84- Use `Theme.of(context).colorScheme` / `textTheme`, never literal `Color(0x...)` values.85- Use the project's state management (Riverpod / Bloc / Provider) in organisms, not `setState`.8687### Vite-Specific88- React / Vue / Solid: tokens come from CSS variables or Tailwind theme — never hardcode hex values in JSX / templates.89- Vanilla + Bootstrap: use Bootstrap utility classes or Sass variables; never inline styles.90- Keep the partial / module / style triple co-located so a reviewer can find all three in one place.
dojocodinglabs