기여 가이드 | CoUI

기여 가이드

Core에서 Flutter·Web·Figma까지 CoUI를 개선하는 첫걸음

CoUI 자체를 처음 고치시나요? 공통 정의를 수정하고, Flutter·Web·Figma에서 확인한 뒤, 팀과 소비 프로젝트에 전달하는 순서로 시작하세요.

저장소를 처음 연 분은 CONTRIBUTING.md, 한국어 단계별 실습은 기여자 가이드를 읽습니다. 아래 저장소 링크는 접근 권한이 필요합니다. 애플리케이션에서 CoUI를 사용하는 방법은 설치입니다.

처음부터 따라가기#

순서	안내	결과
1	환경 설정과 첫 실행	로컬 Web/Flutter 프리뷰 실행
2	구조와 용어	Core·resolver·widget·builder 역할 이해
3	첫 변경: Badge	기본값 하나를 양 플랫폼과 Figma까지 추적
4	검증과 문제 해결	변경별 검사와 결과 증거
5	Figma 플러그인	export·build·Import·Generate
6	호환성과 업그레이드	API 예고, 릴리스와 소비자 갱신

구조 한눈에 보기#

packages/coui_core     공통 토큰 · Contract · Style · Theme
    ├── coui_flutter  resolver → Flutter widget
    ├── coui_web      resolver → Jaspr / DOM
    └── exporter     JSON → tools/figma-token-sync → Figma

docs_core             공유 문서 · 예제 · 코드 스니펫 · 카탈로그
    ├── docs_site     Jaspr 문서 사이트
    └── app/docs_app  네이티브 Flutter 문서 앱
app/coui_widgetbook   Flutter 컴포넌트 실험실

Contract는 사용할 수 있는 입력, Style은 외형과 기본값, Theme은 공통 override입니다. Resolver는 이를 플랫폼 값으로 바꾸고 Widget은 그 결과를 그립니다. Figma는 export 데이터를 builder가 읽어 생성합니다. 기본값 수정이 자동으로 Figma 문서를 다시 그려 주지는 않습니다.

기여의 기본 순서#

이슈에 현재/기대 동작과 영향받는 플랫폼을 적습니다.
작업 브랜치를 만들고 공유 원본 및 양 플랫폼의 처리 경로를 확인합니다.
코드와 테스트를 수정하고, 실행 예제와 복사용 스니펫을 함께 갱신합니다.
디자인 표현이 바뀌면 Figma export/build 후 Import/Generate 결과를 확인합니다.
변경 범위의 검사·시각/동작 증거·필요한 마이그레이션을 남기고 PR을 올립니다.

브랜치, 네이밍, 토큰, API 대칭, 검증, deprecation의 원문은 엔지니어링 규칙 인덱스에 있습니다. 실행 위치와 예상 결과가 포함된 명령은 위 단계별 가이드에서 관리합니다.

접근과 제안#

저장소는 현재 비공개이므로 clone과 소스 열람에 접근 권한이 필요합니다. 공개 전 제안은 cody@cocode.im으로 보내주세요. 버그를 알려주실 때는 사용 중인 태그/커밋, 플랫폼, 재현 단계, 기대 결과를 함께 적어 주시면 도움이 됩니다.

디자인 파일 위치와 사용은 Figma 라이브러리, 디자인 근거 문서는 디자인 소스를 참고하세요.