홈 화면(`/` 경로) UI 개선 #166

krsy0411 · 2026-01-27T09:00:59Z

- contributor-component.ts: GitHub API를 활용한 기여자 프로필 표시 Web Component 구현 - index.ts: 새로운 contributor-component 등록 - home.md: 기여자 섹션에 custom-contributor 컴포넌트 통합 기여자 정보를 동적으로 표시하여 커뮤니티 활동을 시각화합니다. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 로고 이미지와 텍스트 간격 조정 (gap-2 → gap-1) - 시각적 균형감 향상 및 모던한 레이아웃 적용 사용자 경험 개선을 위한 미세 조정입니다. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 불필요한 정규식 처리 제거 - marked.js의 기본 렌더링 로직 활용 - 코드 가독성 및 유지보수성 향상 커스텀 토크나이저가 컴포넌트 처리를 담당하므로 중복 로직을 제거했습니다. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- public/trouble-shooting/: Claude Code 사용 중 발생한 문제와 해결 과정 문서화 - .claude/agents/: modern-ux-designer, troubleshooting-doc-writer 에이전트 정의 - .claude/commands/: design, trouble-shooting 커스텀 명령어 추가 개발 과정에서 겪은 실제 이슈와 해결책을 공유하여 팀 생산성을 높입니다. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- getElement(): null-safe DOM 접근 함수 추가 - requireElement(): 필수 요소 접근 함수 추가 (없으면 에러) - 타입 안정성 강화 및 명확한 에러 메시지 제공 - 런타임 에러 방지를 위한 방어적 프로그래밍 기반 마련 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- page-config.ts 모듈 추가 - getPageType(): URL 해시 기반 페이지 타입 결정 - getPageConfig(): 페이지 타입별 UI 설정 제공 - getCurrentPageConfig(): 현재 페이지 설정 반환 - Single Source of Truth 패턴으로 페이지 타입 로직 중앙화 - 순수 함수로 구성하여 테스트 용이성 확보 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- ui-manager.ts 모듈 추가 - toggleUIElements(): 페이지 설정 기반 UI 제어 - sidebar, aside-toc, content 레이아웃 관리 - 랜딩 페이지는 navigation/TOC 숨김 및 full-width 레이아웃 - DOM 조작 로직을 별도 모듈로 분리하여 관심사 분리 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

breadcrumb.ts: - DOM 유틸리티 사용으로 타입 안정성 강화 - 홈 페이지 체크 조건부 로직 제거 - null-safe 처리 및 방어적 프로그래밍 - JSDoc으로 호출 책임 명시 table-contents.ts: - DOM 유틸리티 적용 - 필수 요소 존재 확인 로직 추가 - early return 패턴으로 가독성 향상 - JSDoc으로 호출 제약사항 문서화 load_md.ts: - getCurrentPageConfig()로 페이지 타입 결정 - requireElement()로 필수 요소 접근 - 타입 안정성 강화 각 모듈의 단일 책임 명확화 및 제어 흐름을 main.ts로 이동 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- initializePage() 오케스트레이터 함수 추가 - 페이지 설정 기반 조건부 초기화 구현 - toggleUIElements()로 UI 요소 표시/숨김 제어 - 루트 경로(/)에서 home.md를 랜딩 페이지로 렌더링 - breadcrumb, TOC, navigation이 랜딩 페이지에서 숨겨짐 - 제어의 역전(IoC) 패턴으로 main.ts가 초기화 흐름 관리 - 단일 책임 원칙 준수 및 확장 가능한 아키텍처 구현 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

홈 화면에서 사용할 링크 카드 Web Component를 추가합니다. - 아이콘(book, github, chat), 제목, 설명 표시 - 외부 링크 자동 감지 및 처리 (target="_blank") - Tailwind CSS 기반 모던 디자인 - 다크모드 지원 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

기여자 카드에 username이 없을 때 "기여하기" 안내 카드를 표시하는 빈 카드 모드를 추가합니다. - + 아이콘과 "기여하기" 텍스트 표시 - 점선 테두리 스타일 - GitHub 기여 가이드 링크 연결 - 호버 시 스케일 및 테두리 색상 변경 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

헤더와 푸터의 색상 스키마를 화이트 베이스로 변경하고 네비게이션 스타일을 개선합니다. Header: - 배경을 white/gray 기반으로 변경 (글래스모피즘 효과) - 로고 그라디언트 제거, 솔리드 컬러 적용 - 네비게이션 active 상태를 rounded pill 스타일로 개선 - 부드러운 그림자와 보더 추가 Footer: - 배경을 white/gray 기반으로 변경 - GitHub 링크에 아이콘 추가 - 레이아웃 간소화 및 정리 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Markdown 콘텐츠 스타일이 Web Components에 적용되지 않도록 Direct Child Combinator를 사용하여 CSS 충돌을 해결합니다. - 모든 선택자를 #content > 형태로 변경 - Web Components가 자동으로 격리됨 - 마크다운 콘텐츠만 스타일 적용 - animate-pulse-slow 유틸리티 추가 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

홈 페이지를 Hero 섹션, 커뮤니티 섹션, 기여자 섹션으로 재구성하고 새로운 링크 카드 컴포넌트를 적용합니다. - 제목 그라디언트 제거, 솔리드 컬러 사용 - home-link-card-component로 버튼 교체 - 컴팩트한 레이아웃으로 조정 - contributor-component에 빈 카드 모드 적용 - modern-ux-designer 에이전트에 그라디언트 금지 규칙 추가 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- content_style.css에서 사용되는 파란색(#007bff)을 border에 적용 - 흰색 배경에서 카드 구분이 명확하도록 개선 - 호버 시 더 진한 파란색(#0056b3) 적용 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 커스텀 토크나이저를 모든 웹 컴포넌트 지원으로 확장 - card-component, button-component, home-link-card-component 모두 처리 - SUPPORTED_COMPONENTS 배열로 관리하여 확장 용이 - 테스트 코드 구조 개선 - 하나의 테스트는 하나의 검증만 수행하도록 리팩토링 - it.each()를 사용한 동적 입력값 테스트 도입 - 웹 컴포넌트별 독립적인 테스트 케이스 작성 - 비동기 처리 안정화 - waitForComponentRender() 헬퍼 함수 추가 (50ms) - connectedCallback 실행 완료 보장 - 테스트 커버리지 확대 - card-component: 2개 케이스 - button-component: 3개 케이스 - home-link-card-component: 2개 케이스 추가 - 마크다운 파싱: 일반 텍스트, 혼합 렌더링 검증 결과: 22개 테스트 모두 통과, CI 환경 검증 완료 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

이 PR은 홈 화면(/ 경로)의 UI를 개선하는 작업입니다. 랜딩 페이지와 문서 페이지를 구분하는 페이지 설정 시스템을 도입하고, 새로운 웹 컴포넌트를 추가하며, 마크다운 렌더링 로직을 단순화했습니다.

Changes:

페이지 타입 관리 시스템 추가 (page-config, ui-manager, dom utils)
새로운 웹 컴포넌트 추가 (home-link-card, contributor)
마크다운 렌더링 로직 단순화 및 UI 컴포넌트 개선
테스트 업데이트 및 트러블슈팅 문서 추가

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/scripts/page-config.ts	페이지 타입(landing/documentation) 결정 및 UI 설정 관리를 위한 새 모듈
src/scripts/ui-manager.ts	페이지 설정에 따른 UI 요소 표시/숨김 제어 모듈
src/scripts/utils/dom.ts	타입 안전한 DOM 접근 유틸리티 함수
src/scripts/main.ts	Application Insights 제거, 페이지 초기화 로직 통합
src/scripts/load_md.ts	마크다운 렌더링 로직 단순화, SUPPORTED_COMPONENTS 목록 추가
src/scripts/components/home-link-card-component.ts	홈 화면 링크 카드 웹 컴포넌트 추가
src/scripts/components/contributor-component.ts	기여자 프로필 카드 웹 컴포넌트 추가
src/scripts/components/header-component.ts	헤더 디자인 개선 (모던한 UI로 변경)
src/scripts/components/footer-component.ts	푸터 디자인 개선
src/scripts/table-contents.ts	방어적 프로그래밍 추가 (null 체크)
src/scripts/breadcrumb.ts	방어적 프로그래밍 추가 (null 체크)
src/styles/content_style.css	직접 자식 셀렉터(>)로 변경하여 웹 컴포넌트와 스타일 분리
src/styles/style.css	pulse-slow 애니메이션 추가
tests/markdown.test.ts	새 컴포넌트에 대한 테스트 추가, it.each 사용으로 개선
public/docs/home.md	새로운 랜딩 페이지 콘텐츠
public/trouble-shooting/*	개발 과정의 문제 해결 과정을 문서화
.claude/*	Claude AI 에이전트 및 명령어 설정 추가

src/scripts/main.ts

src/scripts/load_md.ts

src/scripts/components/home-link-card-component.ts

src/scripts/ui-manager.ts

src/scripts/components/home-link-card-component.ts

src/styles/content_style.css

src/scripts/components/contributor-component.ts

Copilot · 2026-01-27T10:03:29Z

src/scripts/page-config.ts

+/**
+ * 페이지 타입 및 설정 관리 모듈
+ *
+ * 책임:
+ * - URL 해시로부터 페이지 타입 결정
+ * - 페이지 타입별 UI 설정 제공
+ * - 중앙 집중식 페이지 타입 관리 (Single Source of Truth)
+ */
+
+export type PageType = 'landing' | 'documentation';
+
+export interface PageConfig {
+  type: PageType;
+  showBreadcrumb: boolean;
+  showTableOfContents: boolean;
+  showNavigation: boolean;
+}
+
+/**
+ * URL 해시로부터 페이지 타입을 결정합니다.
+ *
+ * @param hash - window.location.hash 값
+ * @returns 페이지 타입 ('landing' | 'documentation')
+ *
+ * @example
+ * getPageType('') // 'landing'
+ * getPageType('#/') // 'landing'
+ * getPageType('#/home') // 'landing'
+ * getPageType('#/guides/docker-overview') // 'documentation'
+ */
+export const getPageType = (hash: string): PageType => {
+  const normalizedHash = hash.replace(/^#?\/?/, ''); // #, / 제거
+
+  // 빈 해시 또는 'home'인 경우 랜딩 페이지로 판단
+  return normalizedHash === '' || normalizedHash === 'home'
+    ? 'landing'
+    : 'documentation';
+};
+
+/**
+ * 페이지 타입에 따른 UI 설정을 반환합니다.
+ *
+ * @param pageType - 페이지 타입
+ * @returns 페이지별 UI 설정
+ *
+ * @example
+ * const config = getPageConfig('landing');
+ * console.log(config.showBreadcrumb); // false
+ */
+export const getPageConfig = (pageType: PageType): PageConfig => {
+  const configs: Record<PageType, PageConfig> = {
+    landing: {
+      type: 'landing',
+      showBreadcrumb: false,
+      showTableOfContents: false,
+      showNavigation: false,
+    },
+    documentation: {
+      type: 'documentation',
+      showBreadcrumb: true,
+      showTableOfContents: true,
+      showNavigation: true,
+    },
+  };
+
+  return configs[pageType];
+};
+
+/**
+ * 현재 URL의 페이지 설정을 반환합니다.
+ * getPageType과 getPageConfig를 조합한 헬퍼 함수입니다.
+ *
+ * @returns 현재 페이지의 UI 설정
+ *
+ * @example
+ * const config = getCurrentPageConfig();
+ * if (config.showBreadcrumb) {
+ *   initializeBreadcrumb();
+ * }
+ */
+export const getCurrentPageConfig = (): PageConfig => {
+  return getPageConfig(getPageType(window.location.hash));
+};


새로 추가된 page-config.ts, ui-manager.ts, utils/dom.ts 모듈에 대한 테스트가 없습니다. 이 모듈들은 페이지 타입 결정, UI 요소 제어 등 핵심 로직을 담당하므로, 단위 테스트를 추가하여 안정성을 보장하는 것이 좋습니다. 특히 page-config의 getPageType 함수는 다양한 해시 값에 대한 테스트가 필요합니다.

src/styles/style.css

코드 리뷰 피드백을 반영하여 테스트 코드를 전면 개선했습니다. ## 주요 개선사항 ### 1. 컴포넌트 팩토리 패턴 도입 - tests/helpers/component-factory.ts 추가 - 목 컴포넌트 생성 로직을 팩토리 패턴으로 추상화 - 코드 중복 제거: 236줄 → 150줄 (36% 감소) - 새 컴포넌트 추가 시 COMPONENT_CONFIGS만 수정 (Open/Closed Principle) ### 2. 전역 상태 관리 개선 - tests/helpers/test-environment.ts 추가 - setupTestEnvironment()로 JSDOM 환경 설정 - afterAll() cleanup으로 전역 상태 복원 - 테스트 격리성 보장 ### 3. 테스트 데이터 분리 - tests/fixtures/component-test-data.ts 추가 - 테스트 로직과 데이터 분리 (Single Responsibility) - as const로 불변성 보장 - 테스트 데이터 재사용 가능 ### 4. 타입 안정성 개선 - tests/types/global.d.ts 추가 - JSDOM 환경 전역 타입 정의 - 타입 안정성 향상 ### 5. 에지 케이스 테스트 추가 - 속성 값이 없는 컴포넌트 렌더링 검증 ## 개선 효과 - 코드 가독성 향상: 선언적 구조로 테스트 의도 명확화 - 유지보수성 향상: 새 컴포넌트 추가 시 설정만 추가 - 확장성 향상: 팩토리 패턴으로 유연한 구조 - 안정성 향상: 타입 안정성 및 cleanup 로직 추가 테스트 결과: 23개 테스트 모두 통과 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

오늘 작업 세션에서 얻은 학습 내용을 바탕으로 에이전트 가이드라인 개선 ## modern-ux-designer.md 업데이트 ### 색상 선택 가이드라인 추가 - 시각적 피로도를 고려한 색상 선택 원칙 - 높은 채도 색상 회피 (#007bff → #6B9AC4) - 40-70% 채도의 부드러운 색상 팔레트 권장 - 기존 스타일과의 일관성 유지 - 문서 사이트를 위한 전문적이고 차분한 톤 선택 ## qa-tester.md 업데이트 ### 핵심 테스트 규칙 추가 1. 하나의 테스트 = 하나의 검증 원칙 2. it.each()를 활용한 데이터 드리븐 테스트 3. AAA 패턴 (Arrange, Act, Assert) 4. 테스트 데이터 분리 (fixtures) 5. 팩토리 패턴을 통한 목 객체 생성 ### 테스트 코드 리뷰 가이드라인 추가 - 테스트 구조 및 명확성 기준 - 데이터 드리븐 테스트 기법 - 테스트 독립성 및 격리성 - 코드 조직화 (helpers, fixtures, types) - 테스트 품질 지표 적용 배경: 테스트 코드 리팩토링 작업을 통해 학습한 베스트 프랙티스 반영 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

CI 환경에서 발생한 테스트 실패 문제와 전면 리팩토링 과정을 문서화 ## 추가된 문서 ### 2026-01-27-test-code-refactoring-architecture.md **문제**: CI 테스트 2개 실패 - card-component와 button-component 렌더링 검증 실패 - 혼합 컴포넌트 HTML 내용 검증 실패 **원인**: 1. 커스텀 토크나이저가 card-component만 처리 2. 테스트 코드 236줄 중 83줄 중복 3. 전역 상태 cleanup 로직 없음 4. 하나의 테스트가 여러 검증 수행 **해결**: - 커스텀 토크나이저 확장 (모든 컴포넌트 지원) - 컴포넌트 팩토리 패턴 도입 - 테스트 환경 추상화 및 cleanup - 테스트 데이터 분리 (fixtures) - 타입 안정성 개선 **결과**: - 코드 36% 감소 (236줄 → 150줄) - 테스트 100% 통과 (23개) - 중복 코드 완전 제거 ## 문서 특징 - Before/After 코드 비교 - 아키텍처 패턴 설명 (팩토리, 의존성 주입) - SOLID 원칙 및 테스트 베스트 프랙티스 - 새 컴포넌트 추가 가이드 - 적용 가능한 프로젝트 유형 안내 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

웹 컴포넌트에서 사용자 입력 및 속성값에 대한 XSS 공격을 방지하기 위해 escapeHtml() 메서드를 추가하고 적용함. 또한 링크 내부의 h3 태그를 div로 변경하여 의미론적으로 올바른 HTML 구조를 유지함. - contributor-component: username, role 속성값 이스케이프 처리 - home-link-card-component: title, description 속성값 이스케이프 처리 - 링크 내부의 h3 태그를 div로 변경 (접근성 및 의미론 개선) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

contributor-component 임포트를 추가하여 컴포넌트가 정상적으로 등록되도록 보장하고, Application Insights 모니터링을 복원함. 또한 UI 매니저의 classList 관리 로직을 개선하여 클래스 누적을 방지함. - main.ts: contributor-component 임포트 추가 - main.ts: Application Insights 초기화 및 페이지 뷰 추적 복원 - ui-manager.ts: content 영역의 classList를 명시적으로 초기화하여 클래스 누적 방지 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

코드 리뷰 시 보안, 의미론적 HTML, 데드 코드 제거 등의 항목을 체크할 수 있도록 에이전트 가이드라인을 확장함. 프로젝트별 베스트 프랙티스 섹션을 추가하여 일관된 코드 품질을 유지할 수 있도록 개선함. - 보안 검토 항목 추가: XSS 방지, 입력 검증, HTML 이스케이프 - 의미론적 HTML 검증: 헤딩 태그 중첩 방지, 접근성 고려 - classList 관리 패턴: 클래스 누적 방지를 위한 명시적 초기화 - 컴포넌트 임포트 일관성: main.ts에서 명시적 임포트 패턴 - 데드 코드 제거 가이드라인: 번들 크기 최적화를 위한 미사용 코드 검색 및 제거 - 모니터링 코드 보존: Application Insights 등 텔레메트리 코드 유지 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

코드베이스 전체에서 사용되지 않는 pulse-slow 애니메이션 및 관련 유틸리티 클래스를 제거하여 번들 크기를 최적화함. - @Keyframes pulse-slow 제거 - .animate-pulse-slow 유틸리티 클래스 제거 - 코드베이스 검색 결과 해당 클래스가 사용되지 않음을 확인 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

krsy0411 and others added 16 commits January 23, 2026 19:40

[UI] 헤더 로고 디자인 개선

d6ea659

- 로고 이미지와 텍스트 간격 조정 (gap-2 → gap-1) - 시각적 균형감 향상 및 모던한 레이아웃 적용 사용자 경험 개선을 위한 미세 조정입니다. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Merge branch 'main' into krsy0411-feat/home

0a39738

krsy0411 added the ui UI 작업 관련 label Jan 27, 2026

krsy0411 self-assigned this Jan 27, 2026

krsy0411 and others added 2 commits January 27, 2026 18:02

prettier:write 명령어 실행

fb6dbd9

krsy0411 requested a review from Copilot January 27, 2026 09:46

Copilot started reviewing on behalf of krsy0411 January 27, 2026 09:46 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

krsy0411 and others added 7 commits January 27, 2026 19:07

krsy0411 merged commit a99c5f0 into docker-ko:main Jan 27, 2026
1 check passed

krsy0411 deleted the krsy0411-feat/home branch January 27, 2026 14:56

krsy0411 linked an issue Jan 27, 2026 that may be closed by this pull request

[UI] 홈 화면 UI 작업 #152

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

홈 화면(`/` 경로) UI 개선 #166

홈 화면(`/` 경로) UI 개선 #166

Uh oh!

krsy0411 commented Jan 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 27, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

홈 화면(/ 경로) UI 개선 #166

홈 화면(/ 경로) UI 개선 #166

Uh oh!

Conversation

krsy0411 commented Jan 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

홈 화면(`/` 경로) UI 개선 #166

홈 화면(`/` 경로) UI 개선 #166