반응형 웹: 모바일 우선, 모든 스택, 검증 완료
목표는 선택한 다섯 개 기기 너비가 아닌 모든 너비에서 작동하는 레이아웃을 만드는 것입니다.
버그는 그 사이에 숨어 있습니다: 412px, 905px, max-width: 767px와 min-width: 769px가
모두 적용되지 않는 단 1픽셀 지점에도 존재합니다. 따라서 이 스킬은 항상 함께 수행되는 두 부분으로 구성됩니다:
- 모바일 우선으로 구축: 레이아웃이 스스로 적응하고 적은 중단점(breakpoint)만 필요하도록 작성합니다.
- 증명:
scripts/check_responsive.py를 실행하여 페이지를 렌더링하고 모든 너비에서 레이아웃을 측정합니다. 한두 장의 스크린샷으로 "괜찮아 보인다"는 증명이 아닙니다. 완료되었다는 것은 검사기가 0 에러를 보고하는 것을 의미합니다.
검사기는 렌더링된 페이지(DOM 박스와 계산된 스타일)만 보므로 CSS가 어떻게 작성되었는지는 신경 쓰지 않습니다. 이것이 바로 어떤 기술 스택에서도 작동하는 이유입니다.
0. 프로젝트를 먼저 읽으세요
CSS를 작성하기 전에 잠시 다음을 확인하세요:
- 여기서 스타일이 어떻게 작성되는지: Tailwind (
tailwind.config.*또는 CSS 내@theme), Bootstrap/SCSS 변수, CSS 모듈, styled-components/emotion, Vue/Svelte 스코프 스타일, 일반 CSS 파일. 동일한 시스템과 동일한 토큰을 사용하여 새 코드를 작성하세요. 두 번째 스타일 시스템은 유지보수 버그입니다. - **기존 중단점(breakpoint)**을 찾아 재사용하세요. 콘텐츠가 필요하지 않은 한 새로 만들지 마세요.
- 페이지를 보는 방법: 정적
.html파일, 또는 개발 서버 (npm run dev,php artisan serve,python manage.py runserver,rails s,dotnet watch...). 검사기를 위한 URL 또는 파일 경로가 필요합니다.
references/stacks.md는 일반적인 스택에 대한 모바일 우선 문법과 중단점 위치를 보여줍니다.
1. 모바일 우선으로 구축
가장 작은 화면을 위한 기본 스타일을 미디어 쿼리 없이 작성하세요. 공간이 커짐에 따라 min-width 쿼리를 사용하여 레이아웃을 추가하세요.
폰은 가장 간단한 CSS를 받고, 콘텐츠는 자연스럽게 쌓이며, 각 중단점은 항상 추가만 합니다.
데스크톱 우선 방식(데스크톱을 작성한 다음 max-width로 패치)은 패치 사이에 간격을 남깁니다. 이 간격이 대부분의 반응형 버그가 발생하는 지점입니다.
코드베이스가 이미 데스크톱 우선이라면 다시 작성하지 마세요. 새로 추가하거나 변경하는 부분만 그 규칙 안에서 모바일 우선으로 작성하고, 검사기가 찾는 문제를 수정하세요.
중단점 없이도 적응하는 레이아웃을 선호하세요
- 그리드:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)). 공간이 허용하는 대로 열이 나타나며, 320px에서 오버플로우가 없습니다(min(100%, …)부분이 이를 방지합니다). - 줄바꿈이 필요한 행:
display: flex; flex-wrap: wrap; gap: …와 적절한flex-basis를 사용하세요. - 크기:
width: 640px대신width: 100%; max-width: 40rem.clamp(min, preferred, max)를 사용한 유동적인 타입과 간격. - 사이드바 대 메인 컬럼처럼 너비가 다른 슬롯에 나타나는 컴포넌트: 컨테이너 쿼리 (
container-type: inline-size+@container)를 사용하여 창 너비가 아닌 해당 슬롯에 반응하도록 하세요. - 콘텐츠가 깨지는 지점에 중단점을 추가하세요(창을 좁혀서 무언가 잘못 보일 때까지). 기기 너비가 아닙니다.
알려진 레이아웃 파괴 요소. 작성할 때 각각 확인하세요.
| 파괴 요소 | 깨지는 이유 | 대신 사용할 것 |
|---|---|---|
컨테이너에 고정 width/min-width (px) | 320px 폰보다 넓음 | max-width + width:100%, %, fr, minmax() |
| 긴 콘텐츠가 있는 flex/grid 자식 | 자식의 기본값이 min-width: auto여서 줄어들지 않음 | 자식에 min-width: 0 (또는 minmax(0,1fr)) |
| 긴 단어, URL, 이메일, 코드 | 줄바꿈 기회 없음 | 텍스트 컨테이너에 overflow-wrap: anywhere |
버튼/라벨/네비게이션의 white-space: nowrap | 텍스트가 줄바꿈되지 않아 너비가 밀려남 | 줄바꿈 허용하거나 min-width:0 + title 속성과 함께 말줄임표 사용 |
| 이미지, 비디오, iframe, 임베드 | 고유 너비가 화면보다 큼 | max-width:100%; height:auto; 임베드는 aspect-ratio |
| 테이블 | 열이 콘텐츠보다 작게 줄어들 수 없음 | overflow-x:auto 컨테이너로 감싸거나 작은 화면에서 행 쌓기 |
pre/code 블록 | 공백 유지 | 블록에 overflow-x:auto |
100vw | 스크롤바를 포함하여 데스크톱에서 약 15px 너무 넓음 | 100% (또는 진정한 전체 너비가 필요할 때만 100dvw를 주의해서 사용) |
텍스트가 있는 박스의 고정 height | 폰에서 텍스트가 더 많은 줄로 감싸져 넘치거나 잘림 | min-height 또는 높이 없음 |
| 콘텐츠의 절대 위치 지정 | 공간을 차지하지 않음; 다른 너비에서 충돌 | 일반 흐름/그리드; 장식에만 절대 위치 사용 |
height: 100vh 히어로 | 모바일 브라우저 바와 짧은 가로 모드 화면에서 잘림 | min-height: 100svh (이전 브라우저를 위한 100vh 폴백 포함) |
증상을 절대 숨기지 마세요
- 수평 스크롤을 막기 위해
html/body에overflow-x: hidden을 사용하지 마세요. 콘텐츠가 여전히 잘려 있는 동안 버그를 숨기고(position: sticky도 깨뜨립니다). 너무 넓은 요소를 찾으세요. 검사기는 이 마스킹을clipped-offscreen으로 보고합니다. user-scalable=no또는maximum-scale=1을 사용하지 마세요. 줌 차단은 접근성 위반입니다(WCAG 1.4.4).- 레이아웃을 위한 JavaScript 너비 확인 또는 사용자 에이전트 감지를 사용하지 마세요. CSS 미디어/컨테이너 쿼리가 깜빡임 없이 수행합니다. JS는 동작(
matchMedia)에는 괜찮지만 레이아웃에는 사용하지 마세요. - 테스트를 통과시키기 위해 검사기를 변경하지 마세요(
--min올리기, 오류를 사라지게 하기 위해 무시 항목 추가).
터치, 입력, 뷰포트
- 모든 페이지 head에
<meta name="viewport" content="width=device-width, initial-scale=1">. - 탭 대상은 최소 24x24px 이상(WCAG 2.2 AA). 터치 스크린의 버튼과 아이콘 컨트롤은 44x44px를 목표로 하고, 이웃 간에 공간을 유지하세요.
- 호버 전용 UI(콘텐츠를 표시하는 메뉴, 툴팁)는
@media (hover: hover)와 탭 대안이 필요합니다. - 폰에서 양식 필드
font-size: 16px이상, 그렇지 않으면 iOS Safari가 포커스 시 확대합니다. 적절한type,inputmode,autocomplete를 사용하세요. - 짧은 가로 모드 폰(높이 320–430px)은 실제로 존재합니다. 고정 헤더와 쿠키 배너가 화면의 약 1/3 이상을 덮지 않도록 하세요. 짧은 높이에서는 접거나 줄이세요(
@media (max-height: 500px)). - 노치 장치:
viewport-fit=cover와 함께env(safe-area-inset-*)패딩만 사용하세요.
타이포그래피, 미디어, 네비게이션, 콘텐츠
- 타입에는
rem, 제목에는clamp(), 줄 길이 제한(max-width: 65ch정도), 단위 없는 line-height. - 이미지: 사진에는
srcset/sizes, 레이아웃 이동 방지를 위한width/height속성 또는aspect-ratio, 박스 비율이 이미지와 다를 때는object-fit: cover(그렇지 않으면 늘어납니다). - 네비게이션: 작은 화면에서는 메뉴를 여는
aria-expanded/aria-controls가 있는 실제<button>을 사용하세요. 링크가 실제로 맞는 너비부터 인라인 링크를 표시하세요. - 콘텐츠 동등성 유지: 맞추기 어렵다고 모바일에서 콘텐츠를 삭제하지 마세요. 재정렬, 축약 또는 접으세요.
references/patterns.md에는 이러한 각 요소(그리드, 네비게이션, 테이블, 양식, 히어로, 카드, 미디어)에 대한 복사 가능한 CSS가 있습니다.
2. 검증: 검사기 실행
일회성 설정(Python 3.9+):
pip install playwright
python -m playwright install chromium
렌더링된 페이지에 대해 실행하세요. 개발 서버가 있으면 먼저 시작하세요.
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # 정적 파일
- 여러 페이지: 여러 URL을 전달하세요. 변경한 모든 페이지나 경로와 공유 레이아웃(헤더/푸터)을 사용하는 하나의 페이지를 확인하세요.
- 늦게 렌더링되는 SPA:
--wait-for "#app main". 로그인된 페이지:--storage-state state.json. - 수정 중 빠른 반복:
--quick(~5–10초). 작업 완료를 말하기 전에 전체 실행을 하세요(~20–40초/페이지). - 종료 코드: 0 = 오류 없음, 1 = 오류 발견됨(
--strict사용 시 경고 포함), 2 = 실행 불가.
동작 방식: 320→1920px를 10px 단계로 스윕하고, 일반적인 기기 너비와 페이지 자체 CSS에서 발견된 모든 중단점의 양쪽을 추가로 검사합니다. 실제 모바일 에뮬레이션(터치, 메타 뷰포트)으로 주요 너비를 다시 로드하고 네 개의 짧은 가로 모드 폰을 확인합니다. 각 너비에서 다음을 측정합니다:
| 오류 (수정 필수) | 의미 |
|---|---|
horizontal-overflow | 페이지가 옆으로 스크롤됨; 튀어나온 요소와 강제로 넓게 만드는 원인을 알려줌 |
clipped-offscreen | 콘텐츠가 화면 가장자리에서 잘림(종종 body의 overflow-x:hidden에 의해 숨겨짐) |
occluded-target | 링크/버튼이 다른 요소에 의해 가려짐(또는 모든 스크롤 위치에서 고정된 바에 의해) |
small-target | 탭 대상이 24px 미만이고 이웃에 비좁음 |
text-spill / text-clipped | 텍스트가 박스를 벗어남 / 고정 크기 + overflow:hidden에 의해 잘림 |
text-overlap | 관련 없는 두 블록의 텍스트가 서로 위에 그려짐 |
distorted-media | 이미지/비디오가 늘어남(박스 비율 ≠ 자연 비율, object-fit 없음) |
viewport-meta, layout-viewport | 뷰포트 메타태그 누락/줌 차단; 폰이 데스크톱 너비로 렌더링됨 |
경고 (수정하거나 그렇지 않은 이유 설명): touch-target (<44px 컨트롤, 터치 너비에서), small-text (<12px, 폰에서), input-zoom (<16px 입력), fixed-coverage (고정/스티키 바가 짧은 화면의 35% 초과).
보고서(report.md, report.json)는 결과를 다음과 같이 그룹화합니다:
1. **horizontal-overflow** at 320-610px; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- worst: 296 px past right edge at 320px
- clues: stays exactly 600px wide at every failing width: a fixed width - use max-width/%/fr/minmax instead
- close-up: responsive-report/closeups/01-horizontal-overflow-320.png
clues 줄은 진단입니다. CSS를 열기 전에 읽으세요.
3. 수정 루프
- 가장 작은 실패 너비부터 수정하세요. 모바일이 기본이며, 이를 수정하면 나머지도 해결되는 경우가 많습니다.
- 단서가 가리키는 근본 원인을 프로젝트가 사용하는 소스(Tailwind 클래스, SCSS 부분, styled component)에서 수정하세요. 일회성 재정의가 아닙니다.
references/checks.md에는 각 검사에 대한 원인과 수정 방법이 나와 있습니다. - 다시 실행(
--quick)하고, 반복한 다음, 전체 실행을 하세요. 오류가 0개이고 모든 경고가 수정되었거나 이유가 설명될 때까지 멈추지 마세요. - 의도적으로 규칙을 위반하는 경우(장식적인 모양이 화면 밖으로 삐져나감, 히어로 콜라주에서 의도적인 겹침) 해당 요소에
data-responsive-ignore="text-overlap"(공백으로 구분된 검사 이름)을 표시하고 코드에 이유를 주석으로 추가하세요. 녹색 실행을 얻기 위해 실제 콘텐츠를 무시하는 것은 테스트하지 않는 것과 같습니다.
4. 살펴보세요
검사기는 측정 가능하게 깨진 것을 찾습니다. 측정할 수 없는 문제도 있습니다: 어색한 줄 바꿈(버튼에 고립된 단어 하나), 외로운 마지막 그리드 항목, 1920px+에서 거대한 빈 거터, 피사체를 자르는 이미지 크롭, 기술적으로는 괜찮지만 사용하기 어려운 메뉴. 실행 시 저장된 스크린샷(screens/320.png, 375, 768, 1024, 1440 및 closeups/)을 열어서 확인하세요. 이미지를 볼 수 없으면 시각적 검토를 주장하는 대신 보고서에 그 사실을 명시하세요.
사용자에게 시각적 문제를 보고할 때는 클래스 이름이 아닌 요소가 무엇이고 어디에 있는지 설명하세요("제품 사진의 가격 배지", "메뉴 그리드의 두 번째 카드"). 사용자는 DOM 선택자를 읽지 않습니다. 선택자는 코드를 찾기 위한 자신의 메모에 남겨두세요.
5. 감사 전용 요청
사용자가 사이트를 확인하거나 감사해 달라고 요청하는 경우(수정은 아님), 코드를 건드리기 전에 먼저 전체 검사기를 실행하고 심각도와 너비 범위별로 그룹화된 결과를 스크린샷과 함께 보고하세요. 범위가 큰 경우 수정하기 전에 물어보세요.
6. 검증된 내용을 사용자에게 알리세요
짧고 사실적인 요약으로 마무리하세요:
- 변경한 사항(파일, 컴포넌트);
- 테스트한 항목: 페이지,
N 너비 320–1920px, 가로 모드 폰; 검사기 결과(0 errors, 1 warning); - 각 남아 있는 경고와 그 이유;
- 스크린샷 위치;
- 검증되지 않은 항목. 검사기는 Chromium만 사용하므로 Safari/Firefox 특성, 실제 기기 키보드, 텍스트 전용 200% 확대/축소, RTL, 저장 상태 없이 로그인된 페이지는 별도로 테스트하지 않는 한 포함되지 않습니다.
참고 파일
references/patterns.md: 일반적인 빌딩 블록에 대한 복사 가능한 모바일 우선 CSS. 새 레이아웃이나 컴포넌트를 구축할 때 읽으세요.references/stacks.md: Tailwind, Bootstrap, SCSS, CSS 모듈, CSS-in-JS, MUI/Chakra, Vue/Svelte/Angular, 서버 템플릿에서 모바일 우선 및 중단점이 어떻게 보이는지, 그리고 각각을 검사기용으로 어떻게 제공하는지.references/checks.md: 각 검사기 결과에 대한 일반적인 원인, 수정 방법 및 알려진 오탐지. 결과의 원인이 명확하지 않을 때 읽으세요.scripts/selftest/run_selftest.py: 검사기가 여전히 각 버그 유형(14개 픽스처)을 잡는지 증명합니다. 검사기를 편집한 후 실행하세요.