기여 가이드 | CoUI
LogoCoUI

기여 가이드

CoUI 기여 방법

기여 가이드#

프로젝트 구조#

coui/
├── packages/
│   ├── coui_core/          # 공유 계약 및 유틸리티 (platform-neutral)
│   ├── coui_flutter/       # Flutter 위젯 구현
│   └── coui_web/           # Jaspr Web 컴포넌트 구현
├── docs_core/               # docs_site(Jaspr)와 docs_app(네이티브 Flutter)이 공유하는
│                             # 문서 코어 — 컴포넌트 카탈로그·프리뷰·예제/코드 레지스트리·
│                             # content/**.md. 두 소비자가 같은 파일을 읽는 단일 출처다.
├── docs_site/               # 문서 사이트 (Jaspr, 이 사이트를 빌드)
├── app/
│   ├── docs_app/            # CoUI 문서를 네이티브 Flutter 로 여는 docs_site 의 쌍둥이 앱
│   └── coui_widgetbook/     # 컴포넌트/테마 시연용 Widgetbook 앱
└── pubspec.yaml             # 루트 pubspec (melos workspace)

저장소 접근 안내

CoUI 저장소는 공개 준비 중이며 현재는 비공개입니다. 아래 절차는 공개 이후 그대로 동작하며, 그전까지는 저장소 접근 권한이 있어야 클론할 수 있습니다.

외부 기여를 받기 시작하는 시점은 공개와 함께 안내드립니다. 그전에 제안하실 내용이 있으면 cody@cocode.im 으로 보내주세요 — 반영하고 크레딧을 남깁니다.

개발 환경 설정#

# 레포 클론
git clone https://github.com/coco-de/coui.git
cd coui

# 의존성 설치
dart pub get
cd packages/coui_flutter && flutter pub get && cd ../..
cd packages/coui_web && dart pub get && cd ../..

# 문서 사이트 로컬 실행
cd docs_site
dart pub get
jaspr serve

컴포넌트 추가 규칙#

모든 chrome / dimensional 값은 coui_core의 단일 CoreXxxStyle 슬롯을 거쳐 양 플랫폼 resolver(resolveXxx → ResolvedXxx)가 굽고, 위젯은 그 결과만 읽는다(render-only) — {Name}Theme/styleValue()/ComponentTheme.maybeOf 같은 예전 패턴, Web의 Styling interface + Style 클래스 패턴은 폐기됐다.

1. coui_core — 플랫폼 무관 계약#

packages/coui_core/lib/src/component/contracts/{name}/:

  1. {name}_contract.dart — CoreXxxContract<W> (widget 타입만 generic)
  2. {name}_style.dart — CoreXxxStyle(merge/copyWith/==/hashCode 필수) + static const default* + variant 별 default가 있으면 defaultsByVariant
  3. {name}_theme.dart — CoreXxxTheme(style/variantStyles 두 슬롯만)
  4. {name}_variant.dart — variant enum이 있으면 (static const defaultVariant)
  5. coui_core.dart barrel export 추가

2. Flutter 컴포넌트#

packages/coui_flutter/lib/src/components/{category}/{name}/:

  1. {name}_style.dart — resolveXxx(context, {...}) + ResolvedXxx (paint-ready 값: Color/EdgeInsets/BorderRadius/TextStyle 등)
  2. {name}.dart — implements CoreXxxContract<Widget>, resolveXxx를 한 번 호출해 resolved.X만 읽고 렌더(render-only)
  3. coui_flutter.dart barrel export 추가

3. Web 컴포넌트#

packages/coui_web/lib/src/components/{category}/{name}/:

  1. {name}_style.dart — resolveXxx(context, {...}) + ResolvedXxx (implements WebResolvedChrome, chrome은 WebElementChrome 슬롯) + build{Slot}ClassName/build{Slot}InlineStyles top-level 순수 함수
  2. {name}.dart — implements CoreXxxContract<Component>, 단일 styled DOM root면 UiComponent(stateless) / UiStatefulComponent(state 필요) 상속, resolved.{slot}.className/.inlineStyles만 읽음(render-only)
  3. coui_web.dart barrel export 추가

4. 검증#

dart analyze + dcm analyze 0 issues, Flutter/Web 양쪽 implements 필드가 대칭인지, 위젯이 resolved.X만 읽고 theme/merge를 직접 하지 않는지 확인한다.

코드 품질#

# DCM 분석
dcm analyze packages/coui_flutter/lib --reporter=console
dcm analyze packages/coui_web/lib --reporter=console

# Dart 분석
dart analyze packages/coui_flutter
dart analyze packages/coui_web

PR 규칙#

  • 브랜치: feat/{component-name}, fix/{description}
  • 커밋: Conventional Commits (feat:, fix:, chore:)
  • 리뷰: DCM 0 issues, Dart analyzer 0 issues 필수