CSS 수정 가이드

이 문서는 스타일 수정 시 어떤 파일을 먼저 봐야 하는지와 충돌 없이 반영하는 순서를 정리합니다. 파일 경로는 모두 파일트리로 보여 주어 실제 저장소 구조를 한 번에 파악할 수 있도록 구성했습니다. 운영 중에는 수정 범위를 최소화하고 책임 파일을 명확히 나누는 것이 핵심입니다.

스타일 파일 역할

스타일은 목적별로 분리되어 있으며, 기능별 책임 파일이 다릅니다. 아래 트리를 기준으로 수정 위치를 먼저 고른 뒤 변경을 시작하면 불필요한 중복 수정을 줄일 수 있습니다.

• docs/
  • src/
    • assets/
      • landing.css
      • migration-checks.css
      • w0-migration/
        • prose.css
        • interactive.css

• landing.css: 랜딩/메인 페이지 중심 스타일
• migration-checks.css: 문서 공통 보정 스타일
• prose.css: 본문 타이포/기본 요소 스타일
• interactive.css: 탭/아코디언/FAQ/디렉티브 인터랙션 스타일

로드 순서

스타일 적용 우선순위는 로드 순서로 결정됩니다. 뒤에서 로드되는 파일이 동일 우선순위 규칙에서 최종 적용됩니다.

• docs/
  • astro.config.mjs
    • customCss (기본)
      • ./src/assets/landing.css
      • ./src/assets/migration-checks.css
      • ./src/assets/w0-migration/prose.css
      • ./src/assets/w0-migration/interactive.css
    • customCss (NO_GRADIENTS)
      • ./src/assets/migration-checks.css
      • ./src/assets/w0-migration/prose.css
      • ./src/assets/w0-migration/interactive.css

수정 대상 선택 규칙

수정 목적에 따라 파일을 나누어 작업하면 충돌이 크게 줄어듭니다. 같은 셀렉터를 여러 파일에서 동시에 수정하는 방식은 지양하는 것이 좋습니다.

• 스타일 수정 목적
  • 인터랙티브 컴포넌트
    • w0-migration/interactive.css
  • 콜아웃/문서 공통 보정
    • migration-checks.css
  • 본문 타이포/기본 문단
    • w0-migration/prose.css
  • 랜딩 전용 화면
    • landing.css

충돌 점검 포인트

전역 간격 규칙과 컴포넌트 내부 규칙이 동시에 적용되면 예상치 못한 여백이 생길 수 있습니다. 변경 후에는 DevTools에서 최종 적용 셀렉터를 확인해, 실제 승자 규칙이 의도한 파일인지 반드시 검증해야 합니다.

• 점검 순서
  • 1. 수정 파일 단일화
  • 2. pnpm run dev 렌더링 확인
  • 3. DevTools Computed/Rules 확인
  • 4. pnpm run build 정적 빌드 확인