coastdigitalgroup/coastai-skills

이미지 갤러리 및 라이트박스 시스템

목적

이미지 갤러리 및 라이트박스 시스템은 웹에서 미디어 컬렉션을 효과적으로 보여주기 위한 엄격한 설계 방법론을 제공합니다. 이 시스템은 이미지나 비디오 그룹을 정적 그리드(갤러리)로 표현하고, 해당 자산이 시선을 사로잡는 방해 요소 없는 전체화면 오버레이(라이트박스)로 전환되는 방식을 구조화합니다. 이 시스템을 통해 시각적 포트폴리오, 전자상거래 제품 확대, 사례 연구 등이 높은 반응성을 유지하고, 깊이 있는 접근성(WCAG AA)을 준수하며, 터치 스와이프 제스처, 키보드 컨트롤 및 포커스 트랩을 통해 다양한 장치를 지원할 수 있습니다.

사용 사례

• 사진, 삽화, 건축 디자인 또는 사례 연구를 선보이는 포트폴리오 사이트
• 대규모 세부 이미지 탐색이 필요한 전자상거래 제품 상세 페이지(PDP)
• 기사가 대화형 사진 갤러리를 포함하는 콘텐츠 중심 미디어 사이트
• 이벤트 사진이나 후기 로그를 표시하는 이벤트 페이지 및 마케팅 랜딩 페이지
• 고해상도 인테리어 및 외부 투어를 제공하는 부동산 웹사이트

사용하면 안 되는 경우

• 단일 배경 또는 인라인 미디어: 확대 또는 캐러셀 형태의 상호 작용이 필요하지 않은 독립형 비그룹 배경 이미지나 간단한 인라인 다이어그램
• 데이터 중심 대시보드 보기: 전체화면 오버레이가 작업 공간을 방해하는 구조화된 데이터 포인트(예: 테이블 또는 차트) 정렬 또는 분석이 주요 작업인 경우. data-table-ui-system 대신 사용
• 복잡한 문서 또는 PDF: 사용자가 여러 페이지로 된 텍스트 문서를 읽어야 하는 경우, 라이트박스는 시각적 미디어에 최적화되어 있으며 읽기 중심의 자산에는 적합하지 않음
• 독립적인 컨텍스트 모달: 대화 상자에 양식 입력, 설정 또는 풍부한 대화형 애플리케이션이 포함된 경우. overlay-and-dialog-system 또는 settings-interface-system 대신 사용

입력

1. 미디어 인벤토리: 고해상도 원본 자산과 이에 상응하는 저해상도 또는 압축된 썸네일 변형
2. 컨텍스트 메타데이터: 제목, 설명, 저작권 정보, 캡션 및 필요한 접근성 대체(alt) 텍스트
3. 반응형 간격 규칙: 사이트의 확립된 responsive-grid-system 및 fluid-spacing-system을 기반으로 하는 대상 그리드 간격, 여백 및 레이아웃 열 규칙
4. 대화형 대비 팔레트: 제어 오버레이, 닫기 버튼 및 페이지 매김 도트에 대한 접근 가능한 텍스트 및 아이콘 색상 사양(WCAG 4.5:1 최소 대비 충족)

출력

1. 갤러리 그리드 명세: 정의된 열 레이아웃, 이미지 종횡비, 호버 상태 및 초점점 보존 규칙
2. 라이트박스 아나토미 청사진: 전체화면 오버레이 구조, 컨트롤(이전, 다음, 닫기), 캡션 위치 및 썸네일 스트립 레이아웃 상세 설명
3. 제스처 및 키보드 명세: 키보드 이벤트, 탭/터치 영역 및 드래그/스와이프 동작을 매핑하는 완전한 상호 작용 매트릭스
4. 접근성 랜드마크 맵: 논리적 역할(dialog, group), 레이블(aria-label), 포커스 트래핑 규칙 및 실시간 상태 알림

워크플로우

1. 갤러리 그리드 기반 구축

기본 페이지 갤러리를 구조화하여 스캔 효율성과 화면 공간 활용도의 균형을 맞춥니다:

• 종횡비 표준화: 균일한 종횡비(예: 1:1 정사각형 또는 4:3 표준)를 사용하여 갤러리 썸네일을 그룹화하여 질서 정연한 리듬을 만듭니다. CSS aspect-ratio 속성을 사용하여 레이아웃 점프를 방지합니다.
• 간격 및 거터: 그리드 간격에 fluid-spacing-system 토큰(일반적으로 --space-s 또는 --space-m)을 사용합니다.
• 호버/포커스 어포던스: interactive-state-system 규칙을 적용합니다. 사용자가 썸네일에 호버하거나 포커스할 때 미묘한 시각적 변화(예: 확대/축소, 부드러운 오버레이 대비, 사용자 지정 검색/확대/축소 커서)를 트리거하여 항목을 클릭할 수 있음을 알립니다.
• 시맨틱 HTML: 목록 래퍼(<ul> / <li>)를 사용하여 갤러리를 구조화하고, 키보드 접근성을 보장하기 위해 썸네일을 button 요소(또는 인덱싱/딥 링킹이 필요한 경우 링크)로 표시합니다.

2. 전체화면 라이트박스 배경 디자인

라이트박스 배경은 뷰어를 페이지의 나머지 부분과 분리해야 합니다:

• 스크림 레이어: 단색 또는 약간 투명한 배경(예: 95% 불투명도의 #0a0a0a 또는 어두운 배경 블러)을 오버레이하여 주변의 방해 요소를 제거합니다.
• 종횡비 유지: 활성 이미지를 뷰포트의 절대 중앙에 배치합니다. 컨테이너가 max-width: 90vw 및 max-height: 80vh로 동적으로 크기를 조정하여 소스 종횡비를 자르거나 자르지 않고 모든 뷰포트에 맞도록 합니다.
• 로딩 상태: aria-busy="true"로 인식되는 중앙 집중식 시각적 표시기(스피너, 로딩 스켈레톤 또는 진행 링)를 구축하여 사용자가 고해상도 자산이 다운로드 중임을 알 수 있도록 합니다.

3. 탐색 컨트롤 및 캡션 오버레이 설정

데스크톱과 모바일 모두에서 인체 공학을 최적화하도록 오버레이 요소를 배치하고 스타일을 지정합니다:

• 닫기 대상: 닫기 버튼을 오른쪽 상단에 배치합니다. 명확한 시각적 경계가 있어야 하고, 최소 터치 대상 크기 48x48px(WCAG에 따라 44x44px)를 충족해야 하며, 명확한 키보드 포커스 링을 유지해야 합니다.
• 이전 및 다음 화살표: 탐색 화살표를 왼쪽 및 오른쪽 여백에 수직으로 중앙에 배치합니다. 모바일 장치에서는 이러한 화살표를 숨기거나 약간 안쪽으로 배치하여 터치 스와이프 동작에 완전히 집중할 수 있도록 합니다.
• 캡션 및 인덱스 표시기: 시맨틱 캡션과 인덱스(예: "Image 3 of 12")를 컨테이너 하단에 배치합니다. aria-live 컨테이너를 사용하여 인덱스가 업데이트될 때 화면 판독기에 변경 이벤트를 알립니다.
• 썸네일 스트립: 기본 이미지 아래에 스크롤 가능한 작은 썸네일 행을 표시합니다. 두껍고 대비가 높은 테두리와 뚜렷한 :focus 윤곽선으로 활성 항목을 강조 표시합니다.

4. 키보드 및 제스처 메커니즘 연결

라이트박스는 데스크톱 주변기기 및 모바일 제스처 상호 작용을 동등하게 우아하게 처리해야 합니다:

• 키보드 매핑: 키 컨트롤에 대한 즉각적인 지원을 보장합니다. Escape는 라이트박스를 닫고, ArrowRight/ArrowDown은 "다음"을 트리거하며, ArrowLeft/ArrowUp은 "이전"을 트리거합니다.
• 포커스 트래핑: 라이트박스가 열리면 키보드 포커스를 그 안에 가둡니다. 사용자는 배경 페이지로 탭할 수 없어야 합니다. 첫 번째 포커스 요소는 기본 대화 상자 컨테이너 또는 닫기 버튼이어야 합니다.
• 포커스 복원: 라이트박스가 닫히면 트리거한 특정 썸네일 버튼으로 포커스를 즉시 복원합니다.
• 스와이프하여 탐색: 부드러운 왼쪽 및 오른쪽 스와이프 터치스크린 제스처를 지원합니다.
• 스와이프하여 닫기: 기본 모바일 운영 체제 패턴을 복제하여 라이트박스를 빠르게 닫기 위해 수직으로(위 또는 아래로) 드래그하거나 스와이프할 수 있도록 합니다.

5. 접근성 및 문서 개요 마무리

WCAG AA를 준수하는 화면 판독기 환경을 보장하기 위해 고급 ARIA 선언을 적용합니다:

• 역할 및 레이블: 라이트박스 래퍼를 role="dialog", aria-modal="true"로 표시하고 제목/캡션을 참조하는 aria-label 또는 aria-labelledby를 사용하여 레이블을 지정합니다.
• 배경 차폐: 라이트박스가 활성화되면 기본 페이지 래퍼(<main> 또는 #app-root)에 aria-hidden="true"를 적용하여 화면 판독기 검색을 오버레이 내에서만 격리합니다.
• 실시간 업데이트: 이미지 제목/캡션 변경 사항이 aria-live="polite" 영역 내에 배치하거나 참조하여 알려지도록 합니다.

결정 규칙

• 해상도 분할: 갤러리 그리드의 썸네일은 최대 600px 너비 등으로 많이 압축되고 적절한 크기여야 합니다. 라이트박스는 마스터 고해상도 변형을 로드하지만, 모바일 대역폭을 절약하기 위해 주문형(다음 및 이전 슬라이드를 지연 로딩)으로만 로드해야 합니다.
• 키보드 대 터치 우선 순위: 모바일 뷰포트(너비 < 768px)에서는 이미지를 위해 화면 공간을 우선시합니다. 데스크톱 UI 컨트롤(다음/이전 화살표)을 터치 스와이프 제스처를 위해 숨기되 항상 눈에 잘 띄는 "닫기" 버튼은 유지합니다.
• 무한 루프 대 하드 스톱:
  • 크리에이티브 포트폴리오, 사용후기 또는 유연한 스캐닝이 선호되는 제품을 선보일 때는 *무한 루프(캐러셀이 마지막 항목 후에 1로 돌아감)*를 사용합니다.
  • 방향성이 중요한 단계별 순차 자습서, 지침 세트 또는 시간순 타임라인의 경우 *하드 스톱(마지막 항목에서 다음 화살표 비활성화)*를 사용합니다.
• 캡션 대 오버레이 공간: 이미지에 긴 설명이 있는 경우 이미지 자체 위에 오버레이하지 마십시오. 이미지 경계 아래의 전용 하단 막대에 배치하여 텍스트가 수직 화면 공간을 초과할 경우 독립적으로 스크롤될 수 있도록 합니다.
• 데스크톱 커서 어포던스: 데스크톱 커서를 동적으로 변경합니다:
  • 갤러리 썸네일 호버: cursor: zoom-in
  • 활성 라이트박스 이미지(확대 가능): cursor: zoom-in(클릭하면 전체 해상도로 확장되어 커서가 cursor: zoom-out으로 변경되어 패닝 가능)
  • 라이트박스 배경 호버: cursor: pointer(클릭하면 오버레이 닫힘)

제약 조건

• 반응성: 이미지는 라이트박스 내에서 왜곡되거나 종횡비를 잃지 않아야 합니다. 컨테이너는 유연한 뷰포트 단위(vw/vh)와 CSS object-fit: contain을 사용하여 모든 장치 방향에서 화면 경계 내에 엄격하게 유지되어야 합니다.
• 대비 비율: 닫기, 탐색 및 썸네일 대화형 컨트롤은 배경 및 이미지 오버레이에 대해 최소 4.5:1의 대비 비율을 충족해야 합니다.
• 포커스 상태: 모든 활성 탐색 요소에는 가시적인 :focus-visible 링이 있어야 합니다. 포커스 표시기는 경계 상자나 인접 요소에 의해 잘리지 않아야 합니다.
• 터치 대상: 모바일 장치의 탭 대상은 WCAG 2.2 SC 2.5.8(최소 24x24px, 그러나 닫기 및 탐색과 같은 기본 작업의 경우 44x44px를 강력히 권장)을 충족해야 합니다.

일반적인 실패 패턴

• "무한 탭 트랩": 열린 라이트박스에서 배경 페이지로 탭하여 화면 판독기가 보이지 않는 콘텐츠를 읽도록 하고 키보드 탐색을 중단시키는 경우
• "이미지 오버런": 세로 형식의 이미지가 모바일 뷰포트의 상단 또는 하단을 넘어 확장되어 탐색 화살표나 닫기 버튼에 완전히 도달할 수 없게 되는 경우
• 초점점 손실: 절대 중앙 자르기로 인해 정적 갤러리의 썸네일이 핵심 피사체(예: 사람의 머리)를 잘라내는 경우. object-position 또는 사용자 정의 반응형 자르기를 사용하여 해결합니다.
• "죽은 탈출": Escape 키 연결을 잊어버려 키보드 전용 사용자를 모달 오버레이 내에 직관적인 닫기 방법 없이 남겨두는 경우
• 열릴 때 레이아웃 이동: 라이트박스가 열릴 때 브라우저 스크롤바가 사라져 전체 배경 페이지 레이아웃이 떨리거나 옆으로 이동하는 경우. 일치하는 거터 또는 스크롤 잠금 패딩을 추가하여 해결합니다.
• 포커스 복원 없음: 라이트박스를 닫으면 포커스가 사이트맵 상단이나 본문으로 재설정되어 키보드 사용자가 원래 위치로 돌아가기 위해 전체 헤더 탐색을 다시 탭해야 하는 경우

검증 기준

• 갤러리 썸네일이 표준화된 종횡비를 사용하고 명확한 호버/포커스 표시기가 있습니다.
• 활성 라이트박스 이미지가 종횡비를 유지하고 뷰포트 제한(max-width: 90vw 및 max-height: 80vh) 내에 완벽하게 맞습니다.
• 닫기 버튼과 화살표가 배경 레이어에 대해 최소 4.5:1의 대비 비율을 충족합니다.
• 키보드 탐색이 활성화됨: Escape는 닫기, ArrowRight는 다음, ArrowLeft는 이전.
• 라이트박스가 열려 있을 때 포커스가 내부에 고정되고 닫을 때 원래 갤러리 요소로 완벽하게 복원됩니다.
• 터치 제스처가 활성화됨: 왼쪽/오른쪽 스와이프로 탐색, 위/아래 스와이프로 모바일 뷰포트에서 닫기.
• 라이트박스 모달이 활성화되면 기본 페이지 래퍼가 aria-hidden="true"로 표시됩니다.
• 로딩 상태 스피너가 표시되고 고해상도 자산이 로드 중일 때 aria-busy="true"로 표시됩니다.