widgetbook-agent

Widgetbook component showcase specialist. Used for UseCase writing and component catalog configuration

항목	내용
Invoke	/shared:widgetbook
Aliases	/widgetbook:add, /catalog:create
Tools	Read, Edit, Write, Glob, Grep
Model	sonnet
Skills	flutter-ui

/shared:widgetbook — 화면 부품 전시장 만들기#

한마디로#

앱에 들어가는 버튼·카드·입력창 같은 UI 부품들을 한곳에 모아 보여주는 "전시장(카탈로그)"을 만들어 주는 도우미입니다. 가구점에 가면 소파 하나를 색깔·크기별로 쭉 진열해 둔 것처럼, 우리 앱 부품도 상태별·기기별로 한눈에 모아 보게 해 줍니다.

누가·언제 쓰나요#

디자이너·기획자가 앱에 들어간 UI 부품이 실제로 어떻게 보이는지 직접 눌러 보며 확인하고 싶을 때
개발자가 새 부품(버튼, 카드 등)을 만들고 나서 전시장에 등록하고 싶을 때
/shared:widgetbook 명령을 실행하거나, 부품 카탈로그·UseCase 작성 작업이 필요할 때 자동으로 동작합니다

무엇을 해주나요#

Widgetbook 이라는 전시장 앱(app/kobic_widgetbook/)에 UI 부품을 등록해 줍니다
부품을 성격별로 세 칸으로 나눠 정리합니다 — 일반 부품([Component]), 화면 단위([Feature]), 색상·글꼴 같은 기초 요소([Foundation])
같은 부품을 여러 기기 크기(아이폰·아이패드·데스크톱)와 테마(라이트/다크), 언어(한국어·영어·일본어 등)로 바꿔 가며 볼 수 있게 설정해 줍니다
실제 데이터 없이도 화면이 채워져 보이도록 가짜 데이터(Mock)를 끼워 줍니다

어떻게 쓰나요#

# 전시장 앱을 브라우저(Chrome)로 실행해서 직접 둘러보기
flutter run -t lib/main.dart -d chrome

# 부품을 새로 등록·수정한 뒤 전시장에 반영(코드 자동 생성)
cd app/kobic_widgetbook  & &   dart run build_runner build --delete-conflicting-outputs

# 웹용으로 빌드(공유·배포용)
flutter build web -t lib/main.dart

명령 자체는 /shared:widgetbook 로 실행하며, 부품 이름(component_name)만 있으면 됩니다. 분류(category)와 경로(path)는 선택 사항이라 비워 두면 일반 부품으로 등록됩니다.

안에서 무슨 일이 벌어지나요#

전시장 앱의 기본 골격(진입점, 기기 크기·테마·언어 선택 메뉴)을 준비합니다.
보여 줄 부품에 "전시 표시(@UseCase)"를 붙여, 어느 칸(일반/화면/기초)에 진열할지 정합니다.
한 부품의 여러 상태(기본·비활성·로딩 등)를 나란히 늘어놓아 비교하기 쉽게 묶습니다.
화면 단위 부품은 실제 데이터 대신 가짜 데이터를 넣어 깨지지 않게 채웁니다.
코드 자동 생성을 돌려 전시장에 새 부품을 반영하고, 여러 기기 크기에서 잘 보이는지 점검합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role#

Manages component catalog using Widgetbook.

@UseCase annotation-based component showcase
Addon configuration (Viewport, Theme, Slang)
Component, Feature, Foundation structure
Mock object setup

Activation Conditions#

/shared:widgetbook Activated when command is invoked
Invoked during component catalog and UseCase writing

Parameters#

Parameter	Required	Description
`component_name`	✅	Component name (PascalCase)
`category`	❌	`component`, `feature`, `foundation` (default: `component`)
`path`	❌	Path within Widgetbook

Package Structure#

app/kobic_widgetbook/
├── lib/
│   ├── main.dart                     # 앱 진입점
│   ├── main.directories.g.dart       # 자동 생성
│   ├── add_on/                       # 커스텀 Addon
│   │   ├── add_on.dart
│   │   ├── slang_addon.dart
│   │   ├── view_ports.dart
│   │   └── widgetbook_group.dart
│   ├── component/                    # UI 컴포넌트
│   │   ├── component.dart
│   │   ├── widget_book_button.dart
│   │   ├── widget_book_input.dart
│   │   └── widget_book_card.dart
│   ├── feature/                      # Feature 컴포넌트
│   │   ├── feature.dart
│   │   ├── widget_book_home.dart
│   │   └── widget_book_profile.dart
│   └── foundation/                   # 기초 요소
│       ├── foundation.dart
│       ├── widget_book_colors.dart
│       └── widget_book_typography.dart
└── pubspec.yaml

Import Order (Required)#

// 1. Flutter standard
import 'package:flutter/material.dart' as material;

// 2. Widgetbook package
import 'package:widgetbook/widgetbook.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart';

// 3. UI Kit (CoUI)
import 'package:coui_flutter/coui_flutter.dart';

// 4. Internal modules
import 'add_on/add_on.dart';
import 'main.directories.g.dart';

Core Patterns#

1. Main App Setup#

import 'package:flutter/material.dart' as material;
import 'package:i10n/i10n.dart';
import 'package:resources/resources.dart';
import 'package:widgetbook/widgetbook.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart';

import 'add_on/add_on.dart';
import 'main.directories.g.dart';

/// Widgetbook 앱 진입점
@App()
class WidgetbookApp extends material.StatelessWidget {
  /// WidgetbookApp 생성자
  const WidgetbookApp({super.key});

  @override
  material.Widget build(material.BuildContext context) {
    return Widgetbook.material(
      // 초기 라우트
      initialRoute: '/StorePage',

      // 자동 생성된 디렉토리
      directories: directories,

      // Addon 구성
      addons: [
        // 뷰포트 선택
        ViewportAddon(Viewports.all),

        // 위젯 인스펙터
        InspectorAddon(),

        // 다국어 지원
        SlangAddon(
          locales: AppLocaleUtils.supportedLocales,
          localeNames: {
            const material.Locale('en'): 'English',
            const material.Locale('ko'): '한국어',
            const material.Locale('ja'): '日本語',
            // ... 추가 로케일
          },
        ),

        // 테마 선택
        MaterialThemeAddon(
          themes: [
            WidgetbookTheme(
              name: 'Light',
              data: AppTheme.light,
            ),
            WidgetbookTheme(
              name: 'Dark',
              data: AppTheme.dark,
            ),
          ],
        ),

        // 정렬 옵션
        AlignmentAddon(initialAlignment: material.Alignment.topLeft),

        // 텍스트 스케일
        TextScaleAddon(initialScale: 1),

        // SafeArea 래퍼
        BuilderAddon(
          name: 'SafeArea',
          builder: (context, child) => material.SafeArea(child: child),
        ),
      ],
    );
  }
}

/// 앱 메인 함수
void main() {
  material.runApp(const WidgetbookApp());
}

2. UseCase Annotation Pattern#

import 'package:coui_flutter/coui_flutter.dart';
import 'package:flutter/material.dart' as material;
import 'package:widgetbook_annotation/widgetbook_annotation.dart';

import 'add_on/widgetbook_group.dart';

/// Button 컴포넌트 UseCase
@UseCase(
  name: 'Button',
  type: Button,
  path: '[Component]',
)
material.Widget buildWidgetbookButtonUseCase(material.BuildContext context) {
  return WidgetbookGroup(
    label: 'Unibook Button',
    children: [
      // Primary Button
      WidgetbookButton(
        label: 'Primary Button',
        button: CoButton(
          variant: CoreButtonVariant.primary,
          onPressed: () {},
          child: const Text('Primary'),
        ),
      ),

      // Secondary Button
      WidgetbookButton(
        label: 'Secondary Button',
        button: CoButton(
          variant: CoreButtonVariant.secondary,
          onPressed: () {},
          child: const Text('Secondary'),
        ),
      ),

      // Outlined Button
      WidgetbookButton(
        label: 'Outlined Button',
        button: CoButton(
          variant: CoreButtonVariant.outline,
          onPressed: () {},
          child: const Text('Outlined'),
        ),
      ),

      // Disabled Button
      WidgetbookButton(
        label: 'Disabled Button',
        button: CoButton(
          variant: CoreButtonVariant.primary,
          onPressed: null,
          child: const Text('Disabled'),
        ),
      ),

      // Loading Button
      WidgetbookButton(
        label: 'Loading Button',
        button: CoButton(
          variant: CoreButtonVariant.primary,
          onPressed: () {},
          child: const Text('Loading'),
        ),
      ),
    ],
  );
}

3. WidgetbookGroup Helper#

import 'package:flutter/material.dart' as material;

/// Widgetbook 그룹 컨테이너
class WidgetbookGroup extends material.StatelessWidget {
  /// WidgetbookGroup 생성자
  const WidgetbookGroup({
    required this.label,
    required this.children,
    super.key,
  });

  /// 그룹 라벨
  final String label;

  /// 자식 위젯들
  final List<material.Widget> children;

  @override
  material.Widget build(material.BuildContext context) {
    return material.SingleChildScrollView(
      padding: const material.EdgeInsets.all(16),
      child: material.Column(
        crossAxisAlignment: material.CrossAxisAlignment.start,
        children: [
          material.Text(
            label,
            style: const material.TextStyle(
              fontSize: 24,
              fontWeight: material.FontWeight.bold,
            ),
          ),
          const material.SizedBox(height: 16),
          ...children.map((child) => material.Padding(
                padding: const material.EdgeInsets.only(bottom: 16),
                child: child,
              )),
        ],
      ),
    );
  }
}

/// Widgetbook 버튼 항목
class WidgetbookButton extends material.StatelessWidget {
  /// WidgetbookButton 생성자
  const WidgetbookButton({
    required this.label,
    required this.button,
    super.key,
  });

  /// 버튼 라벨
  final String label;

  /// 버튼 위젯
  final material.Widget button;

  @override
  material.Widget build(material.BuildContext context) {
    return material.Column(
      crossAxisAlignment: material.CrossAxisAlignment.start,
      children: [
        material.Text(
          label,
          style: const material.TextStyle(
            fontSize: 14,
            color: material.Colors.grey,
          ),
        ),
        const material.SizedBox(height: 8),
        button,
      ],
    );
  }
}

4. Slang Addon#

import 'package:flutter/material.dart' as material;
import 'package:i10n/i10n.dart';
import 'package:widgetbook/widgetbook.dart';

/// Slang 다국어 Addon
class SlangAddon extends WidgetbookAddon<material.Locale> {
  /// SlangAddon 생성자
  SlangAddon({
    required this.locales,
    required this.localeNames,
    material.Locale? initialLocale,
  }) : super(
          name: 'Locale',
          initialSetting: initialLocale ?? locales.first,
        );

  /// 지원 로케일 목록
  final List<material.Locale> locales;

  /// 로케일별 표시 이름
  final Map<material.Locale, String> localeNames;

  @override
  List<Field> get fields => [
        ListField<material.Locale>(
          name: 'Locale',
          values: locales,
          initialValue: initialSetting,
          labelBuilder: (locale) =>
              localeNames[locale] ?? locale.languageCode,
        ),
      ];

  @override
  material.Locale valueFromQueryGroup(Map<String, String> group) {
    final localeCode = group['Locale'];
    return locales.firstWhere(
      (locale) => locale.languageCode == localeCode,
      orElse: () => locales.first,
    );
  }

  @override
  material.Widget buildUseCase(
    material.BuildContext context,
    material.Widget child,
    material.Locale setting,
  ) {
    return TranslationProvider(
      child: material.Builder(
        builder: (context) {
          // 로케일 변경
          LocaleSettings.setLocale(
            AppLocale.values.firstWhere(
              (l) => l.languageCode == setting.languageCode,
              orElse: () => AppLocale.en,
            ),
          );
          return child;
        },
      ),
    );
  }
}

5. Viewports Definition#

import 'package:widgetbook/widgetbook.dart';

/// 뷰포트 정의
abstract final class Viewports {
  /// 모든 뷰포트
  static const List<Device> all = [
    // 모바일
    Device.phone(name: 'iPhone SE', resolution: Resolution(width: 375, height: 667)),
    Device.phone(name: 'iPhone 14', resolution: Resolution(width: 390, height: 844)),
    Device.phone(name: 'iPhone 14 Pro Max', resolution: Resolution(width: 430, height: 932)),
    Device.phone(name: 'Android Small', resolution: Resolution(width: 360, height: 640)),
    Device.phone(name: 'Android Large', resolution: Resolution(width: 412, height: 915)),

    // 태블릿
    Device.tablet(name: 'iPad Mini', resolution: Resolution(width: 744, height: 1133)),
    Device.tablet(name: 'iPad Pro 11"', resolution: Resolution(width: 834, height: 1194)),
    Device.tablet(name: 'iPad Pro 12.9"', resolution: Resolution(width: 1024, height: 1366)),

    // 데스크톱
    Device.desktop(name: 'Desktop HD', resolution: Resolution(width: 1280, height: 720)),
    Device.desktop(name: 'Desktop FHD', resolution: Resolution(width: 1920, height: 1080)),
    Device.desktop(name: 'Desktop 4K', resolution: Resolution(width: 3840, height: 2160)),
  ];

  /// 모바일 뷰포트만
  static const List<Device> mobile = [
    Device.phone(name: 'iPhone SE', resolution: Resolution(width: 375, height: 667)),
    Device.phone(name: 'iPhone 14', resolution: Resolution(width: 390, height: 844)),
    Device.phone(name: 'Android', resolution: Resolution(width: 412, height: 915)),
  ];

  /// 태블릿 뷰포트만
  static const List<Device> tablet = [
    Device.tablet(name: 'iPad Mini', resolution: Resolution(width: 744, height: 1133)),
    Device.tablet(name: 'iPad Pro', resolution: Resolution(width: 1024, height: 1366)),
  ];
}

6. Feature UseCase Example#

import 'package:feature_home/feature_home.dart';
import 'package:flutter/material.dart' as material;
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart';

/// Home 페이지 UseCase
@UseCase(
  name: 'HomePage',
  type: HomePage,
  path: '[Feature]/Home',
)
material.Widget buildWidgetbookHomePageUseCase(material.BuildContext context) {
  return BlocProvider(
    create: (_) => MockHomeBloC(),
    child: const HomePage(),
  );
}

/// Mock Home BLoC
class MockHomeBloC extends Cubit<HomeState> {
  MockHomeBloC()
      : super(const HomeLoaded(
          items: [
            HomeItem(id: 1, title: 'Item 1'),
            HomeItem(id: 2, title: 'Item 2'),
            HomeItem(id: 3, title: 'Item 3'),
          ],
        ));
}

7. Foundation UseCase Example#

import 'package:flutter/material.dart' as material;
import 'package:resources/resources.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart';

/// Colors UseCase
@UseCase(
  name: 'Colors',
  type: material.ColorScheme,
  path: '[Foundation]',
)
material.Widget buildWidgetbookColorsUseCase(material.BuildContext context) {
  final colorScheme = material.Theme.of(context).colorScheme;

  return material.SingleChildScrollView(
    padding: const material.EdgeInsets.all(16),
    child: material.Column(
      crossAxisAlignment: material.CrossAxisAlignment.start,
      children: [
        _ColorTile(name: 'Primary', color: colorScheme.primary),
        _ColorTile(name: 'On Primary', color: colorScheme.onPrimary),
        _ColorTile(name: 'Secondary', color: colorScheme.secondary),
        _ColorTile(name: 'On Secondary', color: colorScheme.onSecondary),
        _ColorTile(name: 'Surface', color: colorScheme.surface),
        _ColorTile(name: 'On Surface', color: colorScheme.onSurface),
        _ColorTile(name: 'Error', color: colorScheme.error),
        _ColorTile(name: 'On Error', color: colorScheme.onError),
      ],
    ),
  );
}

class _ColorTile extends material.StatelessWidget {
  const _ColorTile({required this.name, required this.color});

  final String name;
  final material.Color color;

  @override
  material.Widget build(material.BuildContext context) {
    return material.Padding(
      padding: const material.EdgeInsets.only(bottom: 8),
      child: material.Row(
        children: [
          material.Container(
            width: 48,
            height: 48,
            decoration: material.BoxDecoration(
              color: color,
              borderRadius: material.BorderRadius.circular(8),
              border: material.Border.all(color: material.Colors.grey),
            ),
          ),
          const material.SizedBox(width: 16),
          material.Text(name),
        ],
      ),
    );
  }
}

Build Commands#

# Run Widgetbook
flutter run -t lib/main.dart -d chrome

# Code generation
cd app/kobic_widgetbook  & &   dart run build_runner build --delete-conflicting-outputs

# Web build
flutter build web -t lib/main.dart

Reference Files#

app/kobic_widgetbook/lib/main.dart
app/kobic_widgetbook/lib/add_on/slang_addon.dart
app/kobic_widgetbook/lib/add_on/view_ports.dart
app/kobic_widgetbook/lib/component/widget_book_button.dart

Checklist#

@App() Annotation Apply
@UseCase Annotation Writing
Maintain path consistency ([Component], [Feature], [Foundation])
Configure Addons (Viewport, Theme, Slang)
Set up Mock objects (BLoC, Repository)
Execute build_runner
Test across various viewports