TK-FB-Project/개발 log/2026-01-20-ui-standardization-phase1.md

UI 표준화 Phase 1: 네비게이션/헤더 통일 - 2026-01-20

배경

페이지마다 서로 다른 헤더 구현 방식과 하드코딩된 색상 값으로 인해 일관성이 부족했습니다:

• dashboard.html과 work/report-view.html이 각각 독립적인 헤더 코드 보유
• 색상 값이 하드코딩되어 있어 변경 시 여러 곳 수정 필요
• CSS 변수 시스템이 있지만 활용도 낮음
• 새 페이지 작성 시 참고할 표준 템플릿 부재

목표

1. ✅ 하늘색 계열 primary 색상으로 통일
2. ✅ Navbar 컴포넌트에 CSS 변수 적용
3. ✅ 인라인 헤더를 navbar 컴포넌트로 교체
4. ✅ 4가지 표준 레이아웃 템플릿 생성
5. ✅ CODING_GUIDE.md 업데이트

---

변경 내용

1. Design System 색상 변수 업데이트

파일: web-ui/css/design-system.css

기존 파란색 primary 색상을 하늘색 계열로 변경:

/* 변경 전 (파란색) */
--primary-400: #42a5f5
--primary-500: #2196f3
--primary-600: #1e88e5

/* 변경 후 (하늘색) */
--primary-400: #38bdf8  /* 밝은 하늘색 */
--primary-500: #0ea5e9  /* 기본 하늘색 */
--primary-600: #0284c7  /* 진한 하늘색 */

/* 새로 추가 */
--header-gradient: linear-gradient(135deg, #0ea5e9 0%, #38bdf8 50%, #7dd3fc 100%);

2. Navbar 컴포넌트 CSS 변수 적용

파일: web-ui/components/navbar.html

모든 하드코딩된 스타일 값을 CSS 변수로 변경:

기존 하드코딩	변경 후 CSS 변수
linear-gradient(135deg, #0ea5e9...)	var(--header-gradient)
color: white	var(--text-inverse)
padding: 1rem 1.5rem	var(--space-4) var(--space-6)
font-size: 1.5rem	var(--text-2xl)
font-weight: 700	var(--font-bold)
border-radius: 9999px	var(--radius-full)
background: #90caf9	var(--primary-200)
color: #0d47a1	var(--primary-900)

변경 라인: 약 50개 이상의 스타일 속성 업데이트

3. 인라인 헤더 제거 및 컴포넌트 적용

dashboard.html

변경 전 (50줄의 인라인 헤더 코드):

<header class="dashboard-header">
  <div class="header-content">
    <!-- 50줄의 헤더 코드 -->
  </div>
</header>

변경 후 (2줄):

<!-- 네비게이션 헤더 -->
<div id="navbar-container"></div>

<!-- 스크립트 -->
<script src="/js/load-navbar.js"></script>

work/report-view.html

동일한 방식으로 인라인 헤더 제거 및 컴포넌트 적용:

• 54줄 → 2줄로 축소
• 오래된 프로필 메뉴 링크 자동 수정 (navbar 컴포넌트 사용)

4. 표준 레이아웃 템플릿 생성

디렉토리: web-ui/templates/

새로 생성된 파일:

templates/
├── README.md                   # 템플릿 사용 가이드
├── dashboard-layout.html       # 대시보드용 템플릿
├── work-layout.html           # 작업 페이지용 템플릿
├── admin-layout.html          # 관리자 페이지용 템플릿
└── simple-layout.html         # 프로필/설정용 템플릿

템플릿별 특징

dashboard-layout.html:

• 빠른 작업 섹션 포함
• 여러 콘텐츠 카드 지원
• 푸터 포함
• 토스트 알림 영역

work-layout.html:

• 페이지 제목 섹션
• 검색/필터 영역
• 작업 콘텐츠 카드
• 로딩 스피너
• 모달 예시 코드

admin-layout.html:

• 뒤로가기 버튼 헤더
• 탭 네비게이션
• 데이터 테이블 레이아웃
• 체크박스 일괄 선택
• 페이지네이션
• 확인 모달

simple-layout.html:

• 중앙 정렬 (최대 800px)
• 폼 요소 스타일링
• 정보 표시 리스트
• 반응형 레이아웃
• 완전한 폼 예시

5. CODING_GUIDE.md 업데이트

파일: CODING_GUIDE.md

새로 추가된 섹션:

• 표준 컴포넌트: Navbar 사용법, CSS 변수 시스템
• CSS 변수 시스템: 주요 변수 목록 및 사용 예시
• 페이지 레이아웃 템플릿: 4가지 템플릿 소개 및 사용법

---

테스트 결과

자동 테스트 (curl)

✓ Dashboard: 200
✓ Navbar container found in dashboard.html
✓ Work Report View: 200
✓ Navbar container found in work/report-view.html
✓ Navbar Component: 200
✓ Navbar component loads correctly
✓ Sky blue color variables found in design-system.css
✓ Templates README: 200
✓ Templates directory accessible
✓ Navbar component uses CSS variables

파일 변경 통계

파일	상태	변경 내용
design-system.css	수정	+2줄 (color variables)
navbar.html	수정	~50개 속성 CSS 변수화
dashboard.html	수정	-48줄 (헤더 제거) +2줄 (컴포넌트)
work/report-view.html	수정	-52줄 (헤더 제거) +1줄 (스크립트)
CODING_GUIDE.md	수정	+68줄 (새 섹션)
templates/*.html	신규	4개 템플릿 생성
templates/README.md	신규	가이드 문서 생성

총 파일: 8개 (수정 5개, 신규 3개 + 4 templates)

---

혜택 및 개선 사항

코드 중복 제거

• dashboard.html: 50줄 → 2줄 (96% 감소)
• work/report-view.html: 54줄 → 2줄 (96% 감소)
• 총 102줄의 중복 코드 제거

유지보수성 향상

• 헤더 수정 시 navbar.html 한 곳만 수정
• 색상 변경 시 design-system.css 한 곳만 수정
• CSS 변수로 인한 일관성 보장

개발 생산성 향상

• 새 페이지 작성 시 템플릿 복사로 시작
• 표준화된 구조로 코드 리뷰 용이
• 신규 개발자 온보딩 시간 단축

디자인 일관성

• 모든 페이지 동일한 헤더 스타일
• 통일된 색상 체계 (하늘색)
• 일관된 간격 및 타이포그래피

---

향후 계획 (Phase 2-4)

Phase 2: 버튼/카드 컴포넌트 통일 (예정)

• 26개 CSS 파일의 중복된 버튼 스타일 통합
• 카드 컴포넌트 표준화

Phase 3: CSS 파일 구조 개선 (예정)

• 26개 → 8개 CSS 파일로 통합
• 페이지별 CSS를 모듈화

Phase 4: 폰트 시스템 완전 통일 (예정)

• Pretendard로 완전히 통일
• 불필요한 폰트 제거

---

트러블슈팅

문제: 페이지마다 네비게이션 색상이 다름

증상:

• 일부 페이지는 파란색, 일부는 흰색, 일부는 하늘색 네비게이션 표시

원인:

1. CSS 파일에 .dashboard-header 스타일이 중복 정의되어 navbar 컴포넌트 스타일을 덮어씀
2. 일부 페이지에 design-system.css가 누락되어 CSS 변수가 작동하지 않음

해결:

# 1. 중복된 헤더 스타일 제거
- modern-dashboard.css: .dashboard-header 스타일 제거
- project-management.css: .dashboard-header 스타일 제거

# 2. 누락된 design-system.css 추가
- work/report-view.html
- work/analysis.html
- admin/accounts.html

체크리스트 (새 페이지 작성 시):

• <link rel="stylesheet" href="/css/design-system.css"> 최상단에 추가
• <script type="module" src="/js/load-navbar.js"></script> 추가
• <div id="navbar-container"></div> 추가
• CSS 파일에 .dashboard-header 스타일 작성 금지 (navbar.html에서 관리)

---

사용 가이드

기존 페이지 수정 방법

기존 페이지에 인라인 헤더가 있다면:

<!-- 1. 기존 헤더 코드 제거 -->
<!-- <header class="dashboard-header">...</header> -->

<!-- 2. 컴포넌트로 교체 -->
<div id="navbar-container"></div>

<!-- 3. 스크립트 추가 -->
<script src="/js/load-navbar.js"></script>

새 페이지 작성 방법

# 1. 용도에 맞는 템플릿 선택
cd web-ui/templates
ls -la  # 4가지 템플릿 확인

# 2. 템플릿 복사
cp work-layout.html ../pages/work/new-page.html

# 3. 내용 수정
# - <title> 변경
# - 페이지별 CSS/JS 추가
# - 콘텐츠 작성

# 4. 테스트
open http://localhost:20000/pages/work/new-page.html

CSS 변수 사용 예시

/* ❌ 나쁜 예 - 하드코딩 */
.my-button {
  background: #0ea5e9;
  padding: 16px;
  border-radius: 8px;
}

/* ✅ 좋은 예 - CSS 변수 */
.my-button {
  background: var(--primary-500);
  padding: var(--space-4);
  border-radius: var(--radius-md);
}

---

참고 문서

• web-ui/templates/README.md: 템플릿 상세 가이드
• CODING_GUIDE.md: 전체 개발 가이드
• 개발 log/2026-01-20-page-restructure.md: 페이지 구조 개편 로그

---

커밋 정보

• 날짜: 2026-01-20
• 작업자: Claude AI
• Phase: 1 (네비게이션/헤더 통일)
• 영향받는 파일: 8개
• 코드 감소: -102줄 (중복 제거)

---

다음 단계: Phase 2 버튼/카드 컴포넌트 통일 작업 예정