운영·배포 가이드 (검토용 개정안)

이 문서는 장기 운영 목표도 포함한다. 현재 UI/CENTER compiled dist build/export, JSON Default/partial과 공개 URL Loader/Apply, Designer JSON Preview, npm run build:themes 독립 artifact 산출이 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 Theme Admin, 실제 CDN/pipeline은 미구현이다. 테스트 ZIP은 포함 dist와 로컬 workspace를 사용하며 Registry 접근·publish는 필수가 아니다. 아래 @company/ui는 목표명이며 현재 패키지는 @hm-design/ui다. 이번 단계의 실제 배포/캐시/롤백은 Theme delivery를 따른다. MVP 수동 운영과 향후 자동화를 구분한다.

단일 HMDesignSystem Git 저장소에서 컴포넌트 소스·기본 CSS, Storybook, Theme 초안을 함께 관리한다. Git 커밋, 패키지 릴리스, Theme Publish는 서로 다른 단계다. 소스에 CSS/JSON을 수정하거나 Storybook을 빌드하는 것만으로 사용 중인 앱에 변경이 전달되지 않는다.

같은 저장소의 변경	실제 배포 산출물	앱 반영
컴포넌트 구현·selector·기본 CSS·Token 계약	새 `@company/ui` 버전	개발팀이 의존성 업데이트·통합 검증·앱 배포
이미 지원하는 Semantic Token 값	검증·승인된 불변 Theme 버전과 API/CDN 활성 포인터	연동된 Loader가 다음 진입·새로고침에서 가져와 적용; 앱 재배포 없음
Storybook Story·내부 문서·Manager 스타일	내부 Storybook 빌드	검수 환경 갱신; 서비스 앱 반영 경로가 아님

패키지와 Theme은 같은 Git 변경 이력을 추적하되 각자 버전·검증·승인·롤백을 기록한다. CI를 도입하면 변경 파일별로 관련 검증을 선택하고, Publish는 별도 승인 단계에서 실행한다. Theme 초안을 저장소에 두더라도 승인되지 않은 값을 운영 URL에 자동 공개하지 않는다.

1. 두 배포 경로

컴포넌트·계약 변경

요구사항·영향 분석 → Design System 코드/Story 변경 → 검수·PR
→ @company/ui 버전 릴리스 → 서비스 앱 의존성 업데이트
→ 앱 통합 확인 → DEV → STG → PROD

DOM, 공개 props/variant/state, interaction, 접근성, 기본 CSS의 selector·상태·레이아웃 규칙, 새 Semantic Token·스키마는 이 경로를 따른다. shadcn upstream 업데이트도 Design System 저장소에서 검토한 뒤 이 경로로 반영한다. 패키지 버전과 앱별 적용 버전을 기록한다. 서비스는 패키지 새 버전을 자동 수용하지 않고 앱 테스트·배포를 거쳐 사용한다.

기존 Theme 값 변경

Draft 값 수정 → 실제 @company/ui Storybook Preview → 자동 검증
→ 디자인/운영 승인 → 불변 Theme 버전 생성 → STG 확인
→ 운영 활성 포인터 전환 → API/CDN 제공 → 앱 새 진입·새로고침 시 로드

이 경로는 이미 배포된 앱이 지원하는 Semantic Token의 값에 한정한다. Theme Loader가 API/CDN을 읽도록 연동된 앱에서는 앱/패키지 재배포 없이 다음 진입·새로고침에 반영한다. Theme을 발행하기 위해 Storybook이나 앱을 다시 빌드하지 않는다. Storybook은 Preview 환경이며 Publish 권한과 분리한다.

2. Publish 전 검증 게이트

게이트	확인 사항	실패 시
계약 검증	`schemaVersion`, themeId, Token allowlist, 필드/값 타입, 단위·범위	Publish 중단
호환성	운영 중인 앱의 `@company/ui`/계약 버전이 모든 발행 키를 지원	앱 업데이트 선행 또는 값 범위 축소
UI Preview	실제 컴포넌트의 대표 상태와 대비·가독성, 잘림·넘침	Draft 수정 후 재검수
환경 검증	STG에서 앱이 문서를 받아 적용하고 장애 시 기본값 사용	PROD 활성화 보류
승인·기록	변경 요청, 변경 전후 값, 검수 결과, 승인자, 예정 시각·영향 범위	기록 완료 전 보류

값 검증은 클라이언트와 Publish 서버 양쪽에서 수행한다. 클라이언트 검증은 오래된 앱과 잘못 배포된 문서로부터 UI를 보호하고, 서버 검증은 잘못된 Theme 발행을 막는다. 자동 검증을 통과해도 색 대비나 UI 안전성이 자동으로 보장되는 것은 아니다.

3. 버전, 활성화, 캐시

Theme 문서는 themeId와 themeVersion으로 식별하는 불변 산출물로 저장한다. 발행 후 내용을 덮어쓰지 않는다.
환경별 활성 포인터(예: STG/PROD)가 버전을 가리킨다. Publish와 rollback은 이 포인터 변경으로 수행한다.
API/CDN은 활성 포인터와 버전 문서를 제공한다. 버전 URL은 오래 캐시할 수 있고, 활성 포인터는 짧은 TTL 또는 재검증 가능한 ETag 정책을 사용한다. 구체 TTL은 운영 요구와 CDN 특성에 맞춰 확정한다.
앱은 새 페이지 진입·새로고침 시 활성 버전을 확인한다. 포인터 전환과 CDN 전파 사이의 지연을 운영 반영 시간에 포함해 기록한다.
@company/ui 버전과 Theme 버전은 별개다. Publish 기록에는 검수한 패키지 버전 및 운영 앱의 최소 지원 계약 버전을 함께 남긴다.

4. Rollback 절차

장애 범위, 현재 활성 Theme 버전, 직전 정상 버전, 영향 앱을 확인한다.
직전 정상 버전의 계약 호환성을 확인하고 운영 활성 포인터를 해당 기존 불변 버전으로 되돌린다.
API/CDN에서 활성 포인터와 문서가 일치하는지 확인한다. 필요한 경우 포인터 캐시를 갱신하고 전파 시간을 관찰한다.
새 페이지 진입·새로고침에서 실제 앱의 시각 결과와 적용 버전을 확인한다. fetch/검증 오류에는 기본 Theme fallback이 동작하는지 확인한다.
사고 기록에 원인, 시작·복구 시각, 영향 범위, 후속 조치를 남긴다. 문제가 있는 버전을 덮어써서 복구하지 않는다.

이미 열려 있는 탭은 초기 운영 정책상 즉시 교체되지 않는다. 즉시 전환이 필요한 서비스가 확인되면 갱신 신호와 탭 동기화를 별도 설계한다. 활성 포인터나 CDN이 일시적으로 실패하면 앱은 검증되지 않은 값을 적용하지 않고 기본 Theme을 유지한다.

5. 단계별 운영 도입

단계	운영 방식	필수 증거
현재 구현	compiled dist build/export 패키지·JSON Theme/URL Loader/Apply·Designer Preview·Theme-only artifact. Registry publish 이력은 ZIP 검증 범위 밖; 운영 CDN Publish 미구현	JSON/Runtime/Default parity/레이아웃 및 URL 실패 fallback 검증
MVP 서비스 도입	구현된 패키지 빌드·로컬 Theme JSON·Storybook Preview를 서비스 앱에 연결하고 수동 검증. Production Publish 없음	동일 패키지 컴포넌트의 override/fallback, 새로고침 확인
운영 기반	Registry, 불변 버전, 검증 API, 승인 기록, 환경별 활성 포인터, API/CDN, 롤백 절차	STG→PROD 발행과 이전 버전 복귀의 실제 앱 검증
운영 확장	Theme Admin, 역할별 권한, 감사 로그, 자동 시각·접근성 검사, 관측	승인·배포·복구 이력과 서비스별 적용 버전 추적

Admin 없이 시작하더라도 Publish를 단순 파일 덮어쓰기나 디자인 툴 자동 직결로 만들지 않는다. 운영 기반 단계에서는 최소한 검증, 불변 버전, 승인, 활성화, 롤백을 갖춘다.

6. 단계별 책임과 산출물

단계	담당과 산출물
Design System 구현	디자인팀이 Token 의도·값, 컴포넌트와 계약 변경, 기본 Theme, Storybook·Preview 검수, `@company/ui` 패키지 버전을 담당
Theme 운영·발행	디자인팀이 서버 검증, 불변 버전 저장, 승인 기록, 환경별 활성화, API/CDN·롤백을 담당
서비스 적용	개발팀이 패키지 업데이트, Theme ID 선택, Loader와 fallback, 앱 통합 검증을 담당

디자인팀은 Design System 구현과 Theme 운영을 함께 수행한다. 표는 조직 분리가 아니라 작업 단계를 구분한다. 같은 사람이 여러 단계를 수행할 수 있으며, 단계마다 변경 내용·검수 결과·승인·반영 버전을 남긴다. 운영 시작 전 각 단계의 실제 담당자와 승인자를 정하고, 디자인 승인만으로 운영 활성화가 자동 실행되는지는 디자인팀의 권한 정책에서 결정한다.

7. 운영 체크리스트

컴포넌트 릴리스

변경이 컴포넌트/API/기본 CSS 규칙/계약 경로인지 분류했다.
관련 Story와 패키지 공개 API를 갱신하고 접근성·주요 상태를 확인했다.
패키지 버전을 발행하고 앱별 업데이트·테스트·배포를 기록했다.
영향 Theme 문서의 스키마/Token 호환성을 확인했다.

Theme Publish

Git의 Theme 초안 변경과 운영 Publish를 구분하고, 기존 Semantic allowlist 값만 발행 대상으로 검증했다.
실제 컴포넌트 Storybook Preview와 STG 앱에서 검수했다.
승인자·변경 내용·호환 패키지 버전·이전 활성 버전을 기록했다.
새 불변 버전을 저장하고 운영 활성 포인터를 전환했다.
API/CDN 응답과 새로고침한 운영 앱의 적용 버전·fallback을 확인했다.
필요 시 이전 버전으로 되돌릴 수 있는 포인터와 절차를 확인했다.

9.5 KiB Raw Blame History