flutter-ui

Convert Figma designs to Flutter UI components (CoUI design system)

항목	내용
Invoke	/flutter:ui
Aliases	/ui, /21, /coui
Category	kobic-development
Complexity	moderate
MCP Servers	magic, figma, serena

/flutter:ui — 피그마 디자인을 화면 코드로#

한마디로#

디자이너가 그린 피그마 디자인을 보고, 그대로 작동하는 앱 화면 코드(Flutter)로 옮겨주는 도구입니다. 도면(피그마)을 건네면 우리 회사 표준 부품(CoUI)으로 실제 화면을 조립해 주는 셈이에요.

누가·언제 쓰나요#

디자이너가 만든 피그마 화면·컴포넌트를 실제 앱 화면으로 만들어야 할 때
우리 회사 디자인 시스템(CoUI)에 맞춰 버튼·카드·입력창 같은 UI를 새로 만들 때
빠르게 /ui, /21, /coui 같은 짧은 별칭으로 호출하고 싶을 때

무엇을 해주나요#

피그마 화면을 분석해 우리 표준 부품(CoUI 위젯)으로 바꾼 화면 코드(Widget 파일) 를 만들어 줍니다.
색상·글자·간격을 임의로 정하지 않고 회사 디자인 토큰(정해진 색·글꼴·여백 규칙)에 맞춥니다.
만든 컴포넌트를 해당 기능 폴더에 배치하고, 컴포넌트 카탈로그(Widgetbook UseCase) 와 테스트 파일까지 함께 만들어 줍니다.

어떻게 쓰나요#

# 버튼 컴포넌트 만들기
/flutter-ui button --name SubmitButton --feature common

# 피그마 카드 디자인을 변환하기 (--figma-node 로 피그마 노드 지정)
/flutter-ui card --figma-node 12:345 --name ProductCard --feature store

# 화면 전체를 변환하기
/flutter-ui page --figma-node 1:100 --name HomePage --feature home

component_type(필수): 만들 종류 — button, card, form, page 등
--figma-node: 변환할 피그마 노드 ID (예: 12:345)
--name: 컴포넌트 이름 (예: ProductCard)
--feature: 어느 기능 모듈에 넣을지 (예: home, store)

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

피그마 분석 — 지정한 피그마 노드의 구조·색상·텍스트를 읽어 들입니다.
부품 매칭 — 피그마 요소를 우리 표준 부품(CoUI 위젯)과 색상·글꼴 규칙에 1:1로 연결합니다.
화면 코드 생성 — 연결한 내용을 바탕으로 실제 Flutter 화면 코드를 만들고, 화면 크기에 맞게 반응형으로 구성합니다.
프로젝트에 통합 — 만든 코드를 기능 폴더에 넣고, 컴포넌트 카탈로그와 테스트 파일까지 함께 정리합니다.

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

Triggers#

When converting Figma frames/components to Flutter
CoUI design system based UI development
When using /ui, /21 keywords

Context Trigger Pattern#

/flutter-ui {component_type} [--options]

Parameters#

Parameter	Required	Description	Example
`component_type`	✅	Component type	`button`, `card`, `form`, `page`
`--figma-node`	❌	Figma node ID	`12:345`
`--name`	❌	Component name	`ProductCard`
`--feature`	❌	Feature module	`home`, `store`

Execution Flow#

┌─────────────────────────────────────────┐
│  1. Figma 노드 분석 (MCP: figma)           │
├─────────────────────────────────────────┤
│  • get_selection / get_node_info        │
│  • extract_tailwind                     │
│  • scan_text_nodes                      │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│  2. CoUI 컴포넌트 매핑                    │
├─────────────────────────────────────────┤
│  • Figma 클래스 → CoUI 위젯 (Co < X > )      │
│  • 색상 변수 → appColors / colorScheme  │
│  • 타이포그래피 → context.textStyles    │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│  3. Flutter 코드 생성 (MCP: magic)       │
├─────────────────────────────────────────┤
│  • 21st_magic_component_builder         │
│  • Widget 구조 생성                      │
│  • 반응형 레이아웃 적용                   │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│  4. 프로젝트 통합                         │
├─────────────────────────────────────────┤
│  • Feature 위젯 디렉토리에 배치           │
│  • Generate Widgetbook UseCase              │
│  • 테스트 파일 생성                       │
└─────────────────────────────────────────┘

CoUI Design System#

Color Mapping#

// Figma Variable → Flutter (context.theme.colorScheme / context.appColors)
base-100     → colorScheme.base100
base-200     → colorScheme.base200
base-300     → colorScheme.base300
primary      → colorScheme.primary
secondary    → colorScheme.secondary
neutral-*    → context.appColors.neutralN

Component Mapping#

Figma	Flutter/CoUI	Notes
btn	`CoButton(variant: ...)`	no `Button.primary()`
card	`CoCard`
input	`CoInput(type: ...)` / `CoTextField` (labelled)	no `FormTextField`
modal	`CoDialog`
drawer	`CoDrawer`
navbar	`AppBar` (in `Scaffold(headers: [...])`)	no `CoAppBar`
avatar	`CoAvatar`
badge	`CoBadge(variant: ...)`	no `PrimaryBadge`
tabs	`TabList` + `Tab`	no `CoTabBar`
icon	`CoIcon(CoLucideIcons.x)`	no `HeroIcon`
spacing	`CoGap.spaceN()` / `CoGap(gapStyle: CoreGapStyle(...))`	no `Gap.s*`, no `CoGap(size: CoreSpace.spaceN)` (v0.92)

Typography#

// Figma text style → context.textStyles.<size><weight>
headline-lg  → context.textStyles.xlBold
headline-md  → context.textStyles.lgBold
body-lg      → context.textStyles.baseNormal
body-md      → context.textStyles.smNormal
label-lg     → context.textStyles.smSemibold

Output Template#

import 'package:core/core.dart';

/// {component_name} widget
///
/// Figma: {figma_node_link}
class {ComponentName} extends StatelessWidget {
  const {ComponentName}({
    required this.title,
    this.onTap,
    super.key,
  });

  final String title;
  final VoidCallback? onTap;

  @override
  Widget build(BuildContext context) {
    // CoUI Co<X> 위젯으로 구성 (CoButton / CoBadge / CoCard / CoGap / CoIcon)
    return CoButton(
      onPressed: onTap,
      child: Text(title, style: context.textStyles.baseSemibold),
    );
  }
}

Widgetbook UseCase#

@UseCase(name: 'Default', type: {ComponentName})
Widget buildDefault(BuildContext context) {
  return const {ComponentName}(
    title: 'Sample Title',
  );
}

MCP Integration#

Phase	MCP Server	Tool
Figma analysis	figma	get_node_info, extract_tailwind
UI generation	magic	21st_magic_component_builder
Code search	serena	find_symbol, search_for_pattern

Core Rules#

Prefer const constructor
super.key always last parameter
Break into small reusable units

Styling#

No hardcoded colors -> use context.theme.colorScheme.* / context.appColors.*
Typography -> context.textStyles.<size><weight> (no Text().lg.bold chaining)
Spacing -> CoGap.spaceN() / CoGap(gapStyle: CoreGapStyle(...)) (no Gap.s* / Spacing.s* / Insets.* / CoGap(size: CoreSpace.spaceN) v0.92)
withOpacity() prohibited -> use withValues(alpha:)
No magic numbers -> use design tokens (CoreSpace)

Responsive#

Utilize LayoutBuilder or MediaQuery
Minimum touch target 48x48

Examples#

Button Component Creation#

/flutter-ui button --name SubmitButton --feature common

Figma Card Conversion#

/flutter-ui card --figma-node 12:345 --name ProductCard --feature store

Full Page Conversion#

/flutter-ui page --figma-node 1:100 --name HomePage --feature home

References#

Detailed implementation: .claude/agents/flutter-ui.md
CoUI components: package/coui/
Color system: package/resources/lib/src/core/theme/