Open Design → Flutter 앱으로 디자인 워크플로우 가이드

 

https://github.com/nexu-io/open-design

 

이 문서는 **Open Design(OD)**에서 선택한 **디자인 시스템(DESIGN.md)**과 시각 시안을 기준으로, Flutter로 TODO 앱을 만들 때의 실무 워크플로우를 예시로 정리합니다.

---

1. 이 가이드가 가정하는 것

항목가정

OD	저장소 루트에서 npm install 후 npm run dev:all로 데몬·웹 UI 기동
에이전트	Claude Code / Cursor Agent 등 로컬 CLI(또는 Anthropic API BYOK)
Flutter	안정 채널, Dart 3.x, Material 3(useMaterial3: true) 기본
제품	iOS/Android(또는 단일 플랫폼) TODO: 추가·완료 토글·삭제·필터, 1차 저장은 메모리 → shared_preferences

중요: OD가 내보내는 산출물은 보통 **HTML <artifact>**입니다. Flutter에는 그대로 붙일 수 없으므로, 연동의 축은 다음 두 가지로 나눕니다.

1. DESIGN.md — 색·타이포·간격·무드의 단일 출처(진실 공급원).
2. 시안 HTML + 스크린샷 — 레이아웃·위계·컴포넌트 배치의 시각 레퍼런스.

Flutter 쪽에서는 이 둘을 ThemeData / ColorScheme / TextTheme / 앱 전용 간격 상수로 옮겨 구현합니다.

---

2. 전체 흐름 한눈에

[OD] 디자인 시스템 선택 + 스킬 + 브리프 → 질문폼·5방향 → HTML 시안·저장
        ↓
[복사] DESIGN.md → Flutter 레포 docs/ (또는 lib/theme/design_spec.md)
     시안 HTML·스크린샷 → reference/ (참고만, 에셋 번들에 넣지 않아도 됨)
        ↓
[Flutter] flutter create → AppTheme 반영 → 화면 위젯·상태·로컬 저장
        ↓
[반복] 같은 DESIGN.md로 OD에서 UI만 재시안 → Theme/위젯 국소 수정

---

3. Phase A — Open Design에서 TODO 레퍼런스 UI 만들기

3.1 기동

cd /path/to/open-design
npm install
npm run dev:all

브라우저: http://localhost:5173

3.2 스킬·디자인 시스템 선택

설정예시 선택이유

Skill	mobile-app	OD에 포함된 모바일 프레임·터치 UI에 가까운 스타터(없으면 web-prototype로도 가능)
Design system	제품에 맞는 항목 또는 커스텀 DESIGN.md	Flutter ThemeData로 같은 팔레트·타이포를 맞출 기준

3.3 첫 브리프 예시(Flutter 이관을 염두에 둔 프롬프트)

OD는 여전히 HTML을 출력합니다. 다만 토큰은 DESIGN.md에 맞추고, Flutter에서 옮기기 쉽게 명시적 색·폰트·간격을 HTML에 박아 달라고 요청하면 이후 매핑이 쉽습니다.

Flutter로 구현할 단일 화면 TODO 앱의 참고용 UI를 HTML 한 파일로 만들어 줘.
(나중에 Material 3 ThemeData로 옮길 예정이니 색은 hex, 폰트는 웹폰트로 명시해 줘.)

기능(클라이언트 UI만):
- 상단: Large title 느낌의 "Tasks" + 부제 한 줄
- TextField + FAB 또는 주 버튼으로 새 할 일 추가
- 필터: Segmented / Chip 스타일로 전체·진행 중·완료
- 리스트: Checkbox 또는 완료 토글, 제목, 삭제(또는 스와이프 힌트)
- 완료 항목: 취소선, Secondary 색 대비
- 하단 요약: "N items left"

디자인:
- 현재 활성 디자인 시스템(DESIGN.md)의 팔레트·타이포·간격을 :root CSS 변수로 반영
- 터치 타깃 최소 48dp에 해당할 만한 패딩(모바일 기준)
- 스크롤 가능한 리스트 영역 명확히

출력은 반드시 하나의 <artifact> 태그 안에 완전한 HTML 문서로만.

3.4 질문 폼·시각 방향

• 제품이 iOS 휴먼 인터페이스에 더 가깝다면 폼에서 톤을 명시하고, Flutter는 Cupertino 위젯 혼합도 가능합니다. 이 가이드는 Material 3 기준 설명을 유지합니다.
• 5가지 시각 방향 선택 시, Flutter 레포 README에 방향 이름과 선택 날짜를 적어 두면 테마 되돌리기가 쉽습니다.

3.5 결과물 저장

• Save to disk로 .od/artifacts/.../index.html 저장.
• 스크린샷(프리뷰 캡처)을 함께 보관하면 Flutter 구현 후 픽셀 단위가 아닌 위계·여백 비교에 유리합니다.

---

4. Phase B — Flutter 프로젝트 생성

OD 저장소와 별도 경로에 앱 레포를 둡니다.

cd ~/projects
flutter create todo_app --org com.example
cd todo_app
flutter run

pubspec.yaml에 이후 단계에서 사용합니다.

dependencies:
  shared_preferences: ^2.2.0

flutter pub get

(상태 관리는 처음엔 StatefulWidget만으로도 충분합니다. 팀에서 Riverpod 등을 쓰면 그에 맞춰 분리하면 됩니다.)

---

5. Phase C — 디자인 시스템을 Flutter 테마로 연동

5.1 DESIGN.md를 레포에 두기

todo_app/
  docs/
    DESIGN.md        # OD design-systems/<id>/DESIGN.md 를 복사

규칙 예: 색·타이포·라운드·간격은 DESIGN.md를 벗어나지 않는다.

5.2 HTML 시안 → Flutter 매핑 표 (개념)

OD / HTMLFlutter

:root / --color-primary 등	ColorScheme.primary, ColorScheme.surface, …
본문/제목 폰트 패밀리·크기	TextTheme의 titleLarge, bodyMedium 등
8px 그리드·섹션 간격	EdgeInsets, SizedBox(height: …), 또는 AppSpacing 클래스 상수
모서리 반경	ThemeData.cardTheme.shape, RoundedRectangleBorder(borderRadius: …)

ColorScheme.fromSeed(seedColor: Color(0xFF...))로 한 번에 잡고, DESIGN.md의 보조색·서피스가 시드만으로 부족하면 copyWith로 세밀 조정합니다.

5.3 테마 파일 예시(새 파일)

lib/theme/app_theme.dart를 두고 MaterialApp의 theme에 연결합니다.

import 'package:flutter/material.dart';

class AppTheme {
  AppTheme._();

  /// DESIGN.md의 primary 색을 시드로 (hex는 문서에서 복사)
  static ThemeData light(Color seed) {
    final scheme = ColorScheme.fromSeed(
      seedColor: seed,
      brightness: Brightness.light,
    );
    return ThemeData(
      useMaterial3: true,
      colorScheme: scheme,
      textTheme: _textTheme(scheme),
      visualDensity: VisualDensity.adaptivePlatformDensity,
    );
  }

  static TextTheme _textTheme(ColorScheme scheme) {
    const font = 'Noto Sans'; // DESIGN.md에 맞게 변경; pubspec fonts 항목 필요
    return TextTheme(
      titleLarge: TextStyle(
        fontFamily: font,
        fontWeight: FontWeight.w600,
        fontSize: 28,
        color: scheme.onSurface,
      ),
      bodyMedium: TextStyle(
        fontFamily: font,
        fontSize: 16,
        color: scheme.onSurface,
      ),
    );
  }
}

main.dart에서는 예를 들어:

theme: AppTheme.light(const Color(0xFF6750A4)),

실제 시드 색은 DESIGN.md의 Primary를 사용합니다. 커스텀 폰트는 pubspec.yaml의 fonts:에 등록해야 합니다.

---

6. Phase D — Cursor/에이전트용 Flutter 이관 프롬프트 예시

Flutter 레포 루트에서:

@docs/DESIGN.md 와 reference/todo_od_preview.html (실제 경로로 바꿀 것) 을 참고해서
Material 3 TODO 화면을 구현해 줘.

요구사항:
- lib/theme/app_theme.dart 의 ColorScheme/TextTheme가 DESIGN.md의 팔레트·타이포와 일치하도록 조정
- lib/features/todo/todo_page.dart 에서: 입력, 필터(전체/진행/완료), ListView.builder, 삭제
- 완료 항목은 TextDecoration.lineThrough + Theme의 onSurfaceVariant
- 최소 터치 영역 48 이상
- 상태는 우선 StatefulWidget; Todo 모델은 immutable 클래스로
- 이후 shared_preferences로 직렬화할 수 있도록 Todo 리스트를 List<Todo>로 분리

---

7. Phase E — 추천 디렉터리 구조(예시)

todo_app/
├── docs/
│   └── DESIGN.md
├── reference/                    # git에 넣어도 되고 로컬만이어도 됨
│   ├── todo_od_artifact.html
│   └── preview.png
├── lib/
│   ├── main.dart
│   ├── theme/
│   │   └── app_theme.dart
│   ├── features/
│   │   └── todo/
│   │       ├── todo_page.dart
│   │       ├── todo_model.dart
│   │       └── todo_storage.dart   # shared_preferences 래퍼
│   └── widgets/
│       └── todo_tile.dart
└── README.md

---

8. Phase F — 상태와 저장(권장 순서)

1. Todo 모델 — id, title, completed (필요 시 priority 등).
2. TodoPage + setState — 필터·CRUD.
3. todo_storage.dart — List<Todo> ↔ JSON 문자열 ↔ shared_preferences.
4. 로딩 순서 — initState에서 비동기 로드 후 setState.

OD 단계에서는 저장소 없이 UI만 맞추고, Flutter에서 로직을 얹는 패턴이 Next 가이드와 동일합니다.

---

9. 반복 워크플로우(디자인 시스템 유지)

• **OD에서 항상 같은 DESIGN.md**를 선택한다.
• 라벨·카드 레이아웃만 바꿀 때: OD에 짧은 브리프로 HTML만 재생성 → 스크린샷 비교 → Flutter에서 위젯·테마 일부만 수정.

이렇게 하면 디자인 시스템 문서는 고정하고 화면 실험만 OD에서 하는 흐름이 유지됩니다.

---

10. 자주 하는 실수와 대응

문제대응

HTML 시안과 Flutter 색이 다름	DESIGN.md의 hex를 기준으로 Color(...)를 다시 맞춤. 시안 HTML은 참고용
폰트가 안 맞음	pubspec.yaml에 폰트 등록 여부 확인. 시스템 폰트만 쓸 경우 DESIGN.md와의 차이를 문서화
OD mobile-app 스킬이 웹 프레임 위에만 있음	시안은 토큰·비율이 중요; 기기 프리뷰는 시뮬레이터에서 최종 검증
테마가 위젯 곳곳에 하드코딩	Theme.of(context).colorScheme, textTheme만 사용하도록 리뷰 규칙화

 

---

12. 요약

1. OD에서 DESIGN.md + 디자인 시스템을 고정하고, TODO 화면 HTML 시안을 만든다.
2. DESIGN.md를 Flutter 레포에 복사해 계약으로 삼는다.
3. ThemeData로 토큰을 코드화하고, 시안은 레이아웃·위계 참고용으로 쓴다.
4. 기능·저장은 Flutter에서 표준 구조로 얹고, 변경 시 같은 DS로 OD만 재실행해 차이를 줄인다.

Flutter에는 OD HTML을 그대로 임베드할 수 없으므로, 연동의 핵심은 DESIGN.md → ThemeData/스타일 상수이고, HTML은 레퍼런스입니다.