CLAUDE.md '디자인 시스템' 섹션 신규:
- 쇼케이스(/design-system.html)를 단일 진실 공급원으로 명시
- 공통 컴포넌트 목록 (Button/Input/Select/PageContainer/PageHeader/Badge 등)
- 카탈로그 API 사용 패턴 (getAlertLevelIntent/Label 등)
- CSS 작성 6대 규칙 (인라인 색상 금지, 하드코딩 Tailwind 색상 금지,
className override 정책, 시맨틱 토큰 우선, !important 절대 금지,
vendor prefix 수동 대응)
- 페이지 작성 표준 템플릿
- 접근성 (WCAG 2.1 Level A) 필수 사항
- 변경 사이클 (쇼케이스 → 카탈로그 → 컴포넌트 → 자동 반영)
- 금지 패턴 체크리스트
RELEASE-NOTES.md [Unreleased]에 디자인 시스템 SSOT 작업 항목 추가:
- 쇼케이스 페이지 + 신규 공통 컴포넌트 + 중앙 레지스트리
- 35+ feature 페이지 마이그레이션
- Badge intent 팔레트 테마 분리
- 접근성 전수 처리 (Select TypeScript 강제 등)
이슈: "Select element must have an accessible name" — 스크린 리더가 용도를
인지할 수 없어 WCAG 2.1 Level A 위반.
수정:
- Select 공통 컴포넌트 타입을 union으로 강제
- aria-label | aria-labelledby | title 중 하나는 TypeScript 컴파일 타임에 필수
- 누락 시 tsc 단계에서 즉시 실패 → 회귀 방지
- 네이티브 <select> 5곳 aria-label 추가:
- admin/SystemConfig: 대분류 필터
- detection/RealVesselAnalysis: 해역 필터
- detection/RealGearGroups: 그룹 유형 필터
- detection/ChinaFishing: 관심영역 선택
- detection/GearIdentification: SelectField에 label prop 추가
- 쇼케이스 FormSection Select 샘플에 aria-label 추가
이제 모든 Select 사용처가 접근 이름을 가지며,
향후 신규 Select 사용 시 tsc가 누락을 차단함.
- MonitoringDashboard: 표준 PageHeader
- MapControl: demo 배지
- RiskMap: 수집 중 배지 + secondary Button 2개 액션
- Dashboard: PageContainer 래핑 (커스텀 DEFCON 헤더는 유지)
- LiveMapView: PageContainer fullBleed + flex 레이아웃 유지
- VesselDetail: PageContainer fullBleed + -m-4 해킹 제거
- TransferDetection: PageHeader 적용
Phase B 전체 완료. 실제 프론트엔드의 모든 주요 페이지가 쇼케이스 기준
공통 컴포넌트(PageContainer/PageHeader/Button/Select/Badge)를 사용한다.
카탈로그/variant 변경 시 쇼케이스와 실 페이지 동시 반영됨.
최종 통계:
- 7개 batch에서 총 30+ 파일 마이그레이션
- PageContainer 도입률: ~100% (SPA 메인 라우트 기준)
- PageHeader 도입률: ~95%
- 신규 Button 컴포넌트 도입: admin/enforcement/parent-inference 등 주요 액션
빌드 검증:
- tsc ✅, eslint ✅ (경고만), vite build ✅
- EnforcementHistory/EventList/EnforcementPlan: primary Button 액션
- EventList: Select 공통 컴포넌트로 등급 필터 치환
- AIAlert/ShipAgent/MobileService: PageContainer + PageHeader(demo)
- PatrolRoute/FleetOptimization: primary Button 액션 2개씩
Phase B-3 완료. 총 10개 파일.
Phase A: 쇼케이스의 카탈로그/variant 정보를 중앙 상수로 끌어올림
- shared/constants/catalogRegistry.ts 신규
- 19+ 카탈로그의 id/showcaseId/titleKo/titleEn/description/source/items를
단일 레지스트리로 통합 관리
- 새 카탈로그 추가 = 레지스트리에 1줄 추가로 쇼케이스 자동 노출
- CATALOG_REGISTRY + getCatalogById()
- lib/theme/variantMeta.ts 신규
- BADGE_INTENT_META: 8 intent의 titleKo/titleEn/description
- BUTTON_VARIANT_META: 5 variant의 titleKo/titleEn/description
- BADGE_INTENT_ORDER/SIZE_ORDER, BUTTON_VARIANT_ORDER/SIZE_ORDER
- 쇼케이스 섹션 리팩토링 — 하드코딩 제거
- CatalogSection: CATALOG_REGISTRY 자동 열거 (CATALOGS 배열 삭제)
- BadgeSection: BADGE_INTENT_META에서 의미 가이드 + titleKo 참조
- ButtonSection: BUTTON_VARIANT_META에서 의미 가이드 + titleKo 참조
효과:
- 카탈로그의 라벨/색상/intent 변경 시 쇼케이스와 실 페이지 동시 반영
- Badge/Button의 variant 의미가 variantMeta 한 곳에서 관리됨
- 쇼케이스 섹션에 분산돼 있던 하드코딩 제거 (INTENT_USAGE, VARIANT_USAGE 등)
다음 단계: 실 페이지를 PageContainer/PageHeader/Button/Input으로 마이그레이션
- badgeVariants 다크 팔레트를 classes 기반 4종 카탈로그와 동일 패턴으로 통일
- 이전: dark:bg-X-400 dark:text-slate-900 dark:border-X-600 (솔리드)
- 이후: dark:bg-X-500/20 dark:text-X-400 dark:border-X-500/30 (translucent)
- 라이트 팔레트는 그대로 유지 (이미 통일되어 있음)
- CatalogSection: 각 카탈로그 항목을 [code / 한글 배지 / 영문 배지] 3열 행으로 렌더
- 한글/영문 라벨 두 버전을 한눈에 비교 검토 가능
- 추적 ID Trk는 행 전체를 감싸서 호버/복사 동작
변경:
- badgeVariants 8 intent 모두 라이트/다크 팔레트 분리
- 다크: 밝은 솔리드 배경(-400) + slate-900 글자 + 강한 보더(-600)
- 라이트: 파스텔 배경(-100) + 진한 글자(-900) + 소프트 보더(-300)
- base에서 text-on-bright 제거 (intent별로 관리)
- classes 기반 카탈로그 4종에 dark: 변형 추가로 라이트 모드 대응:
- eventStatuses: bg-red-100 text-red-800 dark:bg-red-500/20 dark:text-red-400
- enforcementResults: 동일 패턴 (red/purple/yellow/green)
- patrolStatuses: border 포함 (7 상태)
- enforcementActions: classes 필드 신규 추가 (기존에 없어서 fallback grey로 떨어져
라이트 모드에서 글자 안 보이던 원인)
- CatalogSection fallback classes도 dark: 변형 추가 (안전장치)
- enforcementActions에 getEnforcementActionClasses() 헬퍼 신규
빌드 검증:
- tsc ✅, vite build ✅
- CSS 확인: .dark\:bg-red-400:is(.dark *) 컴파일 정상
- 모든 feature 페이지의 Badge className 패턴을 intent/size prop으로 변환
- 컬러풀 액션 버튼 (bg-*-500/600/700 + text-heading) -> text-on-vivid
- 검색/필터 버튼 배경 bg-blue-400 + text-on-bright (밝은 배경 위 검정)
- ROLE_COLORS 4곳 중복 제거 (MainLayout/UserRoleAssignDialog/
PermissionsPanel/AccessControl) -> getRoleBadgeStyle 공통 호출
- PermissionsPanel 역할 생성/수정에 ColorPicker 통합
- MainLayout: PagePagination + scroll page state 제거 (데이터 페이지네이션 혼동)
- Dashboard RiskBar 단위 버그 수정 (0~100 정수 처리)
- ReportManagement, TransferDetection p-5 space-y-4 padding 복구
- EnforcementHistory 그리드 minmax 적용으로 컬럼 잘림 해소
- timeline 시간 formatDateTime 적용 (ISO T 구분자 처리)
- 각 feature 페이지가 공통 카탈로그 API (getXxxIntent/Label/Classes) 사용
- auth_role.color_hex VARCHAR(7) 컬럼 추가 (Flyway V017)
- 빌트인 5개 역할 기본 색상 시드 (ADMIN/OPERATOR/ANALYST/FIELD/VIEWER)
- Role 엔티티 + RoleCreate/UpdateRequest DTO + RoleManagementService
- PermTreeController 응답에 colorHex 필드 포함
