coastdigitalgroup/coastai-skills

목차(ToC) 시스템

목적

목차(ToC) 시스템은 단일 페이지 또는 문서의 구조를 반영하는 페이지 내 탐색 메뉴를 설계하기 위한 방법론을 제공합니다. 긴 형식의 콘텐츠에서 발생하는 '스크롤 피로' 문제를 해결하여 페이지 계층 구조에 대한 지속적인 시각적 지도를 제공함으로써 사용자가 현재 컨텍스트를 이해하고 특정 섹션으로 즉시 이동할 수 있도록 합니다.

사용 사례

• 문서화 및 기술 가이드: 헤더와 하위 헤더의 깊은 계층 구조를 탐색합니다.
• 장문의 기사 및 블로그 게시물: 2,000단어 이상의 에디토리얼 콘텐츠에 로드맵을 제공합니다.
• 복잡한 랜딩 페이지: 사용자가 기능, 가격, FAQ 섹션 사이를 빠르게 이동할 수 있도록 돕습니다.
• 법률 및 정책 페이지: 복잡한 조항과 번호가 매겨진 섹션을 탐색합니다.
• 리소스 허브: 단일 페이지에 긴 링크 또는 도구 목록을 구성합니다.

사용하지 말아야 할 경우

• 짧은 콘텐츠(<3개 섹션): 페이지 전체를 두 번의 스크롤로 훑어볼 수 있다면, ToC는 불필요한 시각적 잡음을 추가합니다.
• 기본 사이트 탐색: 다른 페이지로 이동하기 위해 ToC를 사용하지 마십시오. 대신 site-navigation-system을 사용하십시오.
• 선형 마법사(Linear Wizards): 사용자가 고정된 순서를 따라야 하는 단계별 프로세스에는 step-progress-system을 사용하십시오.
• 미니멀리스트 마케팅: 방해 요소 없이 단일하고 끊김 없는 내러티브 흐름을 목표로 하는 경우에는 사용하지 마십시오.

입력

1. 제목 계층 구조: 페이지의 <h2>부터 <h4> 태그까지의 맵입니다.
2. 레이아웃 컨텍스트: 사용 가능한 가로 공간(사이드바 vs. 인라인).
3. 스크롤 컨테이너: 스크롤이 바디(body)에서 발생하는지, 특정 오버플로우 컨테이너에서 발생하는지 여부입니다.
4. 브랜드 토큰: 디자인 시스템의 간격, 타이포그래피 및 '활성' 상태 색상입니다.

출력

1. ToC 구성 요소 명세: 목록 항목, 들여쓰기 수준 및 '활성' 표시기에 대한 시각적 정의입니다.
2. 스크롤-스파이 청사진: 사용자가 스크롤할 때 '활성' 상태가 업데이트되는 방식에 대한 로직입니다.
3. 반응형 적응 맵: ToC가 데스크톱 사이드바에서 모바일 유틸리티(예: 고정 헤더 또는 하단 드로어)로 변환되는 방식입니다.
4. 길찾기 명세: 부드러운 스크롤 동작 및 포커스 관리에 대한 정의입니다.

워크플로우

1. 문서 개요 감사

제목 구조를 추출합니다. 깔끔한 ToC는 논리적인 h1 -> h2 -> h3 진행에 의존합니다.

• 기본 수준: 일반적으로 <h2> 태그에서 파생됩니다.
• 보조 수준: <h3> 태그에서 파생됩니다(들여쓰기).
• 3차 수준: 문서가 예외적으로 조밀하지 않은 한 ToC에 거의 표시되지 않습니다. 기본적으로 접는 것을 고려하십시오.

2. 레이아웃 패턴 선택

페이지 레이아웃에 따라 공간 배열을 선택합니다.

• 고정 사이드바(오른쪽/왼쪽): 넓은 화면(데스크톱)에 가장 적합합니다. 지도를 항상 볼 수 있습니다.
• 인라인 요약: 기사 상단에 배치합니다. '고정'이 필요하지 않은 모바일 또는 중간 길이 콘텐츠에 가장 적합합니다.
• 고정 헤더/플로팅 바: 히어로 영역을 스크롤한 후에만 나타나는 최소화된 버전입니다.

3. 시각적 계층 구조(수준) 설정

visual-hierarchy-system을 적용하여 깊이를 나타냅니다.

• 들여쓰기: 일관된 가로 패딩(예: 수준당 --space-s)을 사용하여 부모-자식 관계를 표시합니다.
• 타이포그래피: 기본 수준(h2)에 비해 하위 수준(h3)에는 더 작은 글꼴 크기 또는 음영 처리된 색상을 사용합니다.
• 표시기: 목록의 왼쪽/오른쪽에 세로 '진행선'을 사용하여 항목을 시각적으로 연결합니다.

4. 스크롤-스파이(활성) 상태 설계

ToC는 사용자의 뷰포트와 동기화되어야 합니다.

• 활성 링크: 현재 뷰포트 상단에 있는 섹션에 해당하는 링크를 강조 표시합니다.
• '활성선' 효과: 세로선을 사용하는 경우 마커가 활성 항목의 위치로 슬라이드하도록 애니메이션을 적용합니다.
• 피드백 지연: 활성 상태가 빠르게(<100ms) 업데이트되지만 헤더 사이를 스크롤할 때 깜박임을 방지하기 위해 약간의 버퍼를 포함해야 합니다.

5. 반응형 길찾기 계획

사이드바는 일반적으로 모바일에서 사라집니다. 대안을 제공하십시오.

• 모바일 ToC 트리거: 드로어를 여는 화면 상단 또는 하단의 고정 버튼(예: "이 섹션에서")입니다.
• 점진적 공개(Progressive Reveal): 현재 <h2>만 고정 막대에 표시하고, 전체 목록을 확장할 수 있는 쉐브론을 제공합니다.

결정 규칙

• '3단계' 제한: ToC에 3단계 이상의 깊이를 표시하지 마십시오. 콘텐츠가 더 깊다면, h2와 h3에만 초점을 맞추도록 ToC를 단순화하십시오.
• 아이콘보다 들여쓰기: 계층 구조를 표시하기 위해 글머리 기호나 아이콘보다는 들여쓰기를 사용하십시오. 아이콘은 조밀한 텍스트 목록을 복잡하게 만들 수 있습니다.
• 활성 상태 고유성: ToC에서 한 번에 하나의 항목만 '활성' 상태여야 합니다.
• 고정 임계값: ToC는 페이지 로드 시 즉시가 아니라 뷰포트 상단에 도달했을 때만 고정(스티키)되어야 합니다.
• 클릭하여 이동(Click to Jump): ToC 링크를 클릭하면 방향 감각 상실을 방지하기 위해 '부드러운 스크롤(Smooth Scrolling)'을 사용해야 하며, 공유 가능성을 위해 URL 해시(#section-id)를 반드시 업데이트해야 합니다.

제약 조건

• 접근성: ToC는 aria-label="Table of contents"와 함께 <nav>로 감싸야 합니다. 활성 링크는 aria-current="true"(또는 aria-current="location")를 사용해야 합니다. 링크를 탭으로 이동할 때 포커스 링이 보이는지 확인하십시오.
• 대비: 활성 및 비활성 상태는 WCAG AA(4.5:1) 요구 사항을 충족해야 합니다.
• 반응성: 모바일에서 ToC는 기본 텍스트 콘텐츠와 겹쳐서는 안 됩니다. 드로어 또는 토글 가능한 섹션을 사용하십시오.
• 콘텐츠 동기화: ToC의 링크 텍스트는 제목 텍스트와 정확히 일치하거나(또는 명확하게 인식 가능한 축약 버전)이어야 합니다.

일반적인 실패 패턴

• '부실' 상태: 스크롤-스파이 트리거 포인트가 너무 높거나 낮게 설정되어 ToC가 잘못된 섹션을 강조 표시하는 경우입니다.
• 콘텐츠 가리기: 고정된 ToC가 사용자가 읽을 수 있도록 도와야 하는 텍스트를 가리는 경우입니다.
• 깊이 과부하: 모든 h4와 h5를 표시하여 ToC가 뷰포트보다 길어지고 자체 스크롤바가 필요한 경우입니다(중첩 스크롤바 피하기).
• ID 누락: 제목에 일치하는 id 속성이 없어 링크가 작동하지 않는 경우입니다.
• 뒤로 가기 버튼 고장: URL 해시를 업데이트하지 않고 섹션으로 이동하여 사용자가 브라우저의 '뒤로' 버튼을 사용하여 ToC로 돌아오지 못하게 하는 경우입니다.

검증 기준

• h2와 h3 수준 간에 명확한 시각적 계층 구조(들여쓰기)가 존재해야 합니다.
• 스크롤-스파이가 사용자가 스크롤할 때 활성 섹션을 올바르게 강조 표시해야 합니다.
• 링크를 클릭하면 올바른 섹션으로 부드러운 스크롤이 트리거되어야 합니다.
• ToC 링크를 클릭하면 URL 해시가 업데이트되어야 합니다.
• ToC는 <nav aria-label="Table of contents"> 랜드마크로 감싸져야 합니다.
• 활성 상태는 aria-current를 통해 접근 가능해야 합니다.
• 모바일 전용 길찾기 패턴(예: 드로어 또는 고정 막대)이 정의되어야 합니다.
• 계층 구조의 3단계 이상이 표시되지 않아야 합니다.