카페 메뉴 웹문서 시스템 - 디자인 안정화 가이드

🚨 중요: 디자인 깨짐 방지를 위한 필수 지침

이 문서는 웹문서 시스템의 디자인 일관성을 유지하고 CSS 충돌을 방지하기 위한 가이드입니다.

1. 문제의 원인

CSS 파일 충돌

  • 여러 CSS 파일이 중복/충돌하며 적용됨
  • 기존 styles.css와 새로운 CSS 파일들 간의 충돌
  • 변환 중단 후 재시작 시 CSS 파일이 중복 추가됨

HTML 구조 불일치

  • HTML 구조가 파일마다 다름
  • container vs wrapper 사용 혼재
  • sidebar vs aside 태그 혼용

2. 즉시 적용 가능한 해결책

A. 단일 통합 CSS 사용 (권장)

# 1. webdoc 폴더로 이동
cd /Users/[개발자]/work/workspace/ai/claude/cafe/cafe_menu/webdoc

# 2. 기존 CSS 백업
mkdir css_backup
cp *.css css_backup/

# 3. 통합 CSS 하나만 사용
# modern.css 사용 권장

B. 안전한 HTML 템플릿 사용

모든 HTML 파일은 다음 구조를 따라야 함:

<!DOCTYPE html>
<html lang="ko">
<head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>페이지 제목 - 카페 메뉴 가이드</title>
 <link rel="stylesheet" href="modern.css">
</head>
<body>
 <header>
 <div class="header-container">
 <div class="logo">☕ CAFE GUIDE</div>
 <nav>
 <!-- 네비게이션 -->
 </nav>
 </div>
 </header>
 
 <div class="layout-container">
 <aside class="sidebar">
 <!-- 사이드바 내용 -->
 </aside>
 
 <main>
 <div class="content-wrapper">
 <div class="content">
 <!-- 메인 콘텐츠 -->
 </div>
 </div>
 </main>
 </div>
 
 <footer>
 <div class="footer-content">
 <p>© 2025 카페 메뉴 가이드. 모든 권리 보유.</p>
 </div>
 </footer>
</body>
</html>

3. 모범 사례

✅ 권장 사항

  • modern.css 단일 파일 사용
  • 일관된 HTML 구조 유지
  • 클래스명 규칙 준수
  • 정기적인 백업

❌ 피해야 할 사항

  • 여러 CSS 파일 동시 링크
  • 인라인 스타일 과도한 사용
  • 구조 변경 시 부분 수정
  • 테스트 없는 대량 변환

변환 작업 체크리스트

긴급 복구 방법

디자인이 깨졌을 때

  1. 백업 파일로 즉시 복구
  2. CSS 링크 확인 (중복 제거)
  3. 브라우저 캐시 삭제
  4. 단계별 재변환 실시

4. 통합 CSS 파일 예제

다음은 충돌을 방지하기 위한 통합 CSS 파일의 예제입니다:

/* unified_style.css - 리셋 및 기본 설정 */
* {
 margin: 0;
 padding: 0;
 box-sizing: border-box;
}

/* 한글 폰트 */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;700&display=swap');

body {
 font-family: 'Noto Sans KR', sans-serif;
 line-height: 1.6;
 color: #333;
}

/* 메인 레이아웃 */
.app-container {
 display: flex;
 min-height: 100vh;
}

/* 사이드바 */
.app-sidebar {
 width: 280px;
 background: #2c3e50;
 color: white;
 padding: 20px;
 overflow-y: auto;
 position: fixed;
 height: 100vh;
}

.app-sidebar h2 {
 margin-bottom: 20px;
 font-size: 1.5rem;
}

.app-sidebar ul {
 list-style: none;
}

.app-sidebar a {
 color: white;
 text-decoration: none;
 display: block;
 padding: 10px;
 margin: 5px 0;
 border-radius: 5px;
 transition: background 0.3s;
}

.app-sidebar a:hover {
 background: rgba(255,255,255,0.1);
}

/* 메인 콘텐츠 */
.app-content {
 margin-left: 280px;
 padding: 40px;
 width: 100%;
 background: #f5f5f5;
}

.content-wrapper {
 max-width: 1000px;
 margin: 0 auto;
 background: white;
 padding: 40px;
 border-radius: 8px;
 box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}

/* 반응형 */
@media (max-width: 768px) {
 .app-container {
 flex-direction: column;
 }
 
 .app-sidebar {
 position: relative;
 width: 100%;
 height: auto;
 }
 
 .app-content {
 margin-left: 0;
 padding: 20px;
 }
}

5. 변환 스크립트 예제

Python을 사용한 일괄 변환 스크립트:

# convert_to_unified.py
import os
from pathlib import Path

def convert_to_unified_style():
 webdoc_dir = Path("/Users/[개발자]/work/workspace/ai/claude/cafe/cafe_menu/webdoc")
 
 for html_file in webdoc_dir.glob("*.html"):
 with open(html_file, 'r', encoding='utf-8') as f:
 content = f.read
 # 모든 CSS 링크 제거
 import re
 content = re.sub(r']*\.css[^>]*>', '', content)
 
 # 통합 CSS만 추가
 content = content.replace(
 '',
 ' 
'
 )
 
 # 클래스명 통일
 content = content.replace('class="container"', 'class="app-container"')
 content = content.replace('class="sidebar"', 'class="app-sidebar"')
 content = content.replace('class="content"', 'class="app-content"')
 
 with open(html_file, 'w', encoding='utf-8') as f:
 f.write(content)

6. 문제 발생 시 복구 방법

# 1. 모든 HTML 파일의 CSS 링크 초기화
find . -name "*.html" -exec sed -i '' '/| 
|' {} \;

7. 권장 작업 순서

  1. 백업 생성

    cp -r webdoc webdoc_backup_$(date +%Y%m%d)

  2. 통합 CSS 생성

    unified_style.css 파일을 생성하고 위의 코드를 저장

  3. 일괄 변환

    모든 HTML 파일을 한 번에 변환 (중간에 중단하지 않기)

  4. 테스트

    • 브라우저 캐시 삭제 (Ctrl+F5)
    • 주요 페이지 5개 이상 확인

  5. 문제 시 롤백

    rm -rf webdoc
cp -r webdoc_backup_0129 webdoc

8. 절대 하지 말아야 할 것

  • ❌ 여러 CSS 파일을 중복으로 링크
  • ❌ 변환 중간에 중단
  • ❌ 부분적으로만 수정
  • ❌ 클래스명을 일관성 없이 사용
  • ❌ 백업 없이 작업

9. 최종 확인 사항

브라우저 콘솔에서 다음 코드를 실행하여 CSS 파일을 확인하세요:

// 브라우저 콘솔에서 실행
Array.from(document.querySelectorAll('link[rel="stylesheet"]')).forEach(link => {
 console.log(link.href);
});
// 결과: unified_style.css 하나만 나와야 함

💡 핵심 요약

디자인 안정성을 위해서는 modern.css 단일 파일을 사용하고, 모든 HTML 파일에서 동일한 구조를 유지하는 것이 가장 중요합니다. 변환 작업 시에는 항상 백업을 먼저 수행하고, 소규모로 테스트한 후 전체에 적용하세요.

중요: 이 가이드를 따르면 디자인 깨짐 없이 안정적인 웹문서 시스템을 유지할 수 있습니다.