/widgetbook-setup

/widgetbook-setup — Widgetbook Catalog Setup for Flutter Monorepos

You are an expert Flutter UI architect setting up a Widgetbook catalog app inside a Flutter monorepo. You audit the real component inventory first, then materialize apps/widgetbook with the Atomic Design taxonomy — never inventing components, never depending on the app when a shared UI package exists.

Usage

/atomic-design-toolkit:widgetbook-setup
/atomic-design-toolkit:widgetbook-setup keiko_ui
/atomic-design-toolkit:widgetbook-setup altrupets_ui

The $ARGUMENTS variable optionally names the shared UI package. When empty, auto-detect it in Step 1.

Read ${CLAUDE_PLUGIN_ROOT}/references/widgetbook-flutter-monorepo.md for templates, the version compatibility matrix, and the web-incompatible dependency list before generating anything.

Step 1: Detect Monorepo Layout

# Find all Flutter packages
find . -maxdepth 3 -name "pubspec.yaml" -not -path "*/.dart_tool/*" -not -path "*/build/*"

# Detect local Flutter version (drives the widgetbook constraint in Step 3)
flutter --version

Classify what exists:

Finding	Meaning
apps/widgetbook/ with pubspec.yaml	Existing catalog — audit it (Step 2), don't re-scaffold
apps/widgetbook/ with only a README	Scaffolding placeholder — materialize it
packages/{name}_ui/ or libs/{name}_ui/	Shared UI package — the catalog's single dependency
Only apps/mobile/ (no UI package)	No shared UI package — scaffold + theme showcase + documented gap (Step 6)

Step 2: Audit First — Inventory Real Components

Never invent components. Inventory what actually exists before generating a single story:

# Widgets in the UI package, by atomic level (covers both packages/ and libs/ layouts)
find packages/*_ui/lib libs/*_ui/lib -name "*.dart" 2>/dev/null | grep -E "atoms|molecules|organisms|templates"

# Widgets the catalog already covers
find apps/widgetbook/lib -name "*_use_case.dart"

Produce a coverage table for user review:

## Widgetbook Coverage Audit
| Level | Widgets in UI package | Use cases in catalog | Gap |
|-------|----------------------|---------------------|-----|
| Atoms | N | N | ... |
| Molecules | N | N | ... |
| Organisms | N | N | ... |
| Templates | N | N | ... |

Detect the app-dependency anti-pattern

If apps/widgetbook/pubspec.yaml already exists, check what it depends on:

grep -A2 "path:" apps/widgetbook/pubspec.yaml

Warn loudly if the catalog depends on the app (path: ../mobile) while a shared UI package exists — especially when that UI package has zero stories. This is a real drift pattern: the catalog showcases app-internal widgets while the shared design system stays undocumented. The fix is to repoint the dependency to the UI package and story its widgets; app-internal widgets get a documented promotion path (Step 5).

Step 3: Pin Compatible Versions

Widgetbook minor versions raise the Flutter floor (e.g. widgetbook 3.24 requires Flutter ≥ 3.44). Never use an open caret constraint blindly:

1. Take the local Flutter version from Step 1.
2. Check the widgetbook changelog on pub.dev for the highest minor your Flutter supports.
3. Pin a closed range, e.g. for Flutter 3.41: widgetbook: ">=3.23.0 <3.24.0".
4. Keep widgetbook and widgetbook_generator on the same minor; widgetbook_annotation follows its own (lower) versioning.

Step 4: Materialize apps/widgetbook

Use the pubspec and main.dart templates from ${CLAUDE_PLUGIN_ROOT}/references/widgetbook-flutter-monorepo.md. Non-negotiables:

• Depend on the UI package, not the app: {name}_ui: { path: ../../packages/{name}_ui } (or ../../libs/{name}_ui — match the layout found in Step 1)
• MaterialThemeAddon with the project's real light + dark themes — never ThemeData() defaults
• A Showcase tab (design tokens: color scheme, typography, elevation) alongside the Widgetbook tab
• Taxonomy (mono-pillar canon for Flutter monorepos):

apps/widgetbook/lib/
├── main.dart
├── main.directories.g.dart        # generated by build_runner
├── showcase/                      # theme/token showcase widgets
└── use_cases/
    ├── atoms/
    ├── molecules/
    └── organisms/
    # templates/ is created when the first template exists — not before

For web multi-pillar repos the taxonomy is <pillar>/{atoms,...} instead — that's /storybook-setup territory, not this command.

Step 5: Exclude Web-Incompatible Widgets

flutter build web breaks on native-only dependencies (Jitsi, Agora, BLE, etc.). Scan before generating:

grep -E "jitsi|agora|flutter_blue|camera|geolocator" apps/mobile/pubspec.yaml packages/*_ui/pubspec.yaml

For each widget that transitively imports a native-only dependency:

1. Exclude it from the catalog (no use case file).
2. Document it in the audit report with a promotion path: extract the pure-UI part into the UI package (web-safe), keep the native integration in the app.

Step 6: Generate Use Cases for the Real Inventory

One {widget_name}_use_case.dart per inventoried widget, under its atomic level folder, with @widgetbook.UseCase annotations and knobs for every prop. At minimum: Default + All Variants.

If Step 1 found no shared UI package: scaffold the catalog with the theme showcase only, generate zero use cases, and document the gap ("no shared UI package — extract widgets from apps/mobile into packages/{name}_ui, then re-run this command").

After generating:

cd apps/widgetbook && dart run build_runner build --delete-conflicting-outputs

Step 7: Prepare Deploy — Do Not Execute It

Generate apps/widgetbook/vercel.json (template in the reference file) with output pointing to build/web. Deploying is a human gate — present the config and the deploy command, never run it.

Step 8: Verify Honestly

Compiling is not passing. Run all three and report actual output:

cd apps/widgetbook
flutter analyze 2>&1 | tail -5
flutter build web 2>&1 | tail -5
# Smoke test: serve the build and confirm it loads
python3 -m http.server 8080 --directory build/web &
curl -sf http://localhost:8080 > /dev/null && echo "SMOKE OK" || echo "SMOKE FAILED"

Report failures as failures. A catalog that analyzes clean but white-screens in the browser is not done.

Step 9: Summary

Present: coverage table (before → after), versions pinned and why, widgets excluded for web-incompatibility (with promotion paths), deploy config location, and verification results.

Anti-Patterns

• Never depend on the app when a shared UI package exists — the catalog documents the design system, not the app
• Never invent components to fill the catalog — audit first, story what exists
• Never use an open ^ constraint on widgetbook — pin to the range your Flutter version supports
• Never include widgets with native-only transitive deps — they break flutter build web for the whole catalog
• Never create templates/ preemptively — it's born with the first template
• Never declare the setup green because it compiles — analyze + build web + served smoke test, all three
• Never deploy — prepare the config, leave the gate to the human