coastdigitalgroup/coastai-skills

온보딩 투어 시스템

목적

온보딩 투어 시스템 스킬은 다중 단계 가이드 제품 워크스루를 구조화, 스타일링 및 조정하기 위한 포괄적인 설계 방법론을 제공합니다. 처음 온보딩하거나 주요 기능 출 시 사용자의 인지 부하를 줄이기 위해 설계되었으며, 핵심 인터페이스 요소를 시각적으로 분리하고 순차적이고 관련성 높은 컨텍스트를 제공하여 사용자를 능동적이고 성공적인 상태로 안내합니다. 이 시스템은 예측 가능하고 접근 가능하며 사용자 제어 가능한 페이싱을 설정하여 혼란스럽고 혼잡하거나 지나치게 방해가 되는 투어를 방지합니다.

사용 사례

• 최초 사용자 온보딩: 복잡한 SaaS 애플리케이션의 핵심 워크플로우를 통해 새로 등록한 사용자를 안내하여 활성화를 유도합니다.
• 신규 기능 홍보: 기존 사용자에게 새롭게 출시된 고가치 도구나 인터페이스 요소를 강조하고 설명합니다.
• UI 재디자인 적응: 주요 인터페이스 스타일 변경 또는 재구성 후 기존 사용자가 익숙한 도구를 찾을 수 있도록 지원합니다.
• 복잡한 단계별 데이터 입력 투어: 초기 설정(예: 첫 번째 자동화 규칙 설정) 중 다면적인 대시보드 패널을 통해 사용자를 안내합니다.

사용하지 말아야 할 경우

• 자명한 인터페이스: 작업이 더 명확한 레이아웃, 더 나은 레이블 또는 직관적인 아이콘을 통해 단순화될 수 있다면, 나쁜 UX를 투어로 가리기보다 먼저 핵심 UI를 개선하세요.
• 반복적인 마이크로 태스크: 잦은 워크플로우를 팝업으로 방해하지 마세요. 정기적인 도움을 위해서는 tooltip-and-hint-system 또는 인라인 도우미 텍스트를 사용하세요.
• 모바일 전용 또는 저해상도 인터페이스: 다중 단계 앵커 팝오버 투어는 많은 화면 공간을 소비하며 모바일 장치에서 잘리거나 겹치기 쉽습니다. 대신 전체 화면 카드나 통합 가능한 인라인 단계를 사용하세요.
• 중요 오류 또는 트랜잭션 피드백: 즉각적인 시스템 피드백 또는 오류의 경우 banner-and-alert-system 또는 toast-and-snackbar-system을 사용하세요.

입력

1. 정보 아키텍처 및 컨텍스트: 투어가 실행될 특정 페이지 레이아웃, 대시보드 섹션 또는 UI 좌표.
2. 앵커 요소 인벤토리: 각 단계에서 강조 표시해야 하는 특정 대상 버튼, 입력, 테이블 또는 탐색 링크.
3. 온보딩 이정표( "이유" ): 온보딩을 완료하고 활성화를 보장하는 데 필요한 최소 핵심 작업.
4. 장치 중단점: responsive-grid-system의 지침을 사용하여 투어가 렌더링되어야 하는 반응형 대상 뷰포트.

출력

1. 배경 및 마스크 사양: 대상 요소를 시각적으로 분리하고 인터페이스의 나머지 부분을 어둡게 하여 사용자의 주의를 집중시킵니다.
2. 팝오버(투어 카드) 구성 사양: 투어 버블에 대한 상세 구조 청사진(화살표, 본문 텍스트, 단계 표시기, 건너뛰기/다음/뒤로 버튼, 닫기 컨트롤).
3. 시퀀스 및 흐름 로직: 단계별 경로 매핑, 진행 모델(엄격한 선형 대 사용자 주도) 및 세션 지속성.
4. 반응형 전략 및 모바일 대체: 고정 앵커 팝오버가 안전하게 맞지 않는 작은 화면을 위한 적응 규칙.
5. 접근성 랜드마크 및 상호작용 사양: 전체 ARIA 사양, 키보드 탐색 맵 및 포커스 트래핑 동작.

워크플로우

1. 단계 시퀀스 정의(행복 경로)

• 투어 시퀀스를 3~5단계로 제한합니다(밀러의 법칙). 그 이상은 이탈률이 높아집니다.
• 각 단계를 단순한 레이블이 아닌 적극적인 혜택에 초점을 맞춥니다. (예: "이것은 설정 메뉴입니다" 대신 "팀의 워크플로우에 맞게 작업 공간을 여기서 사용자 정의하세요"라고 작성).
• 마지막 단계에는 사용자를 능동적이고 생산적인 상태로 남게 하는 명확하고 실행 가능한 CTA(클릭 유도 문안)가 있어야 합니다.

2. 배경 마스크 및 격리(초점) 설계

• 어두운 반투명 배경 오버레이(보통 50-70% 불투명도의 #000000)를 사용하여 배경 소음을 차단하고 시선을 집중시킵니다.
• 활성 앵커 요소 주위에 "격리 마스크"(SVG 경로 컷아웃 또는 CSS clip-path / box-shadow 사용)를 만듭니다.
• 강조 표시된 앵커 주위에 4px~8px 패딩 버퍼를 유지하여 마스크가 요소 경계에 너무 밀착되지 않도록 합니다.

3. 팝오버(투어 카드) 계층 구축

• 앵커 정렬: 강조 표시된 요소 옆에 팝오버를 동적으로 배치합니다. 작은 방향 화살표/포인터를 사용하여 카드를 앵커에 시각적으로 연결합니다.
• 구성 요소 해부학:
  • 헤더: 표준 닫기 버튼('X')과 진행 표시기(예: "2/4 단계")를 포함합니다.
  • 본문: 굵고 간결한 제목과 최대 2문장의 설명 텍스트를 사용합니다.
  • 액션 바: "건너뛰기" 링크를 왼쪽 정렬하고 탐색 버튼을 오른쪽 정렬합니다. "다음"(또는 "알겠습니다")은 기본 CTA 스타일을 사용하고 "뒤로"는 저대비 3차 스타일을 사용합니다.

4. 접근성 코딩(키보드 및 스크린 리더 동등성)

• 포커스 트래핑: 투어 단계가 활성화되면 키보드 포커스(Tab 키)가 투어 팝오버 내에 갇혀 키보드 사용자가 배경 항목을 탐색하지 못하도록 해야 합니다.
• ARIA 연결: 팝오버 컨테이너가 role="dialog" 또는 role="alertdialog"와 함께 aria-modal="false"를 사용하도록 합니다(보조 기술이 배경 요소가 여전히 존재함을 알 수 있도록). 팝오버 제목을 aria-labelledby로 연결하고 설명을 aria-describedby로 연결합니다.
• 키보드 단축키: 키보드 탐색 지원: Escape는 투어 해제/건너뛰기, ArrowRight는 "다음", ArrowLeft는 "뒤로".

5. 모바일 적응 전략 매핑

• 뷰포트가 768px(태블릿/모바일)보다 작으면 고정 팝오버에서 하단 시트 드로어 또는 중앙 정렬, 비앵커 모달로 전환합니다. 이렇게 하면 카드가 화면 밖으로 밀리거나 중요한 요소를 덮는 것을 방지합니다.
• 모바일에서는 배경 마스크를 비활성화하거나 단순화하여 모바일 스크롤로 인한 클리핑 오류를 방지합니다.

결정 규칙

• 선형 투어 대 사용자 주도 작업 목록:
  • 단계 A가 단계 B보다 반드시 선행되어야 하는 엄격한 최초 설정 시퀀스에는 선형 투어를 사용합니다.
  • 작업을 어떤 순서로든 완료할 수 있는 경우 **대화형 진행 위젯(작업 목록)**을 사용하여 사용자가 자신의 속도에 맞춰 작업을 선택할 수 있도록 합니다.
• 트리거 조건:
  • 최초 실행 시 또는 명시적인 업데이트 후에만 자동으로 트리거합니다.
  • 일반 방문 시 기존 사용자에게 투어를 자동 트리거하지 마십시오.
• 앵커 위치 재정의:
  • 기본값: 앵커의 "하단 중앙" 또는 "오른쪽 중앙"에 팝오버를 배치합니다.
  • 충돌 규칙: 앵커가 화면 가장자리 근처에 있으면 팝오버 배치를 반전시켜 잘림을 방지합니다(예: "오른쪽"에서 "왼쪽"으로). 앵커가 숨겨져 있으면(축소된 패널 내부) 팝오버를 렌더링하기 전에 프로그래밍 방식으로 패널을 확장합니다.
• "건너뛰기" 기능:
  • 모든 단계에 항상 표시되는 "투어 건너뛰기" 또는 "해제" 작업을 제공합니다. 사용자에게 탈출구 없이 투어를 완료하도록 강요하면 좌절감을 유발합니다.

제약 조건

• 접근성(WCAG 2.2):
  • 투어 카드 내 텍스트 대비는 WCAG AA(최소 4.5:1)를 충족해야 합니다.
  • 대화형 버튼에는 고대비 시각적 포커스 링(outline)이 있어야 합니다.
  • 다음/뒤로 버튼의 터치 대상은 최소 44x44px(권장)이거나 24x24px 최소(WCAG 2.2 SC 2.5.8)를 충족해야 합니다.
  • 배경 컷아웃 내부의 대화형 앵커는 포커스 가능해야 합니다.
• 레이아웃 이동 관리:
  • 배경, 컷아웃 마스크 및 팝오버의 표시는 기존 레이아웃 요소를 이동시켜서는 안 됩니다. 문서 뷰포트를 기준으로 position: absolute 또는 position: fixed를 사용합니다.
• Z-인덱스 정렬:
  • 배경 및 투어 카드는 토스트와 같은 최상위 유틸리티 알림 아래에 위치해야 합니다(예: 배경 z-index 900, 팝오버 z-index 910). 이렇게 하면 우선순위가 높은 시스템 알림이 여전히 통과할 수 있습니다.

일반적인 실패 패턴

• "무한 투어" 함정: 5단계가 넘는 투어로 인해 사용자가 즉시 이탈합니다.
• "이중 포커스" 충돌: 이미 활성 모달이 있는 페이지에서 투어를 자동 시작하여 중첩된 오버레이와 갇힌 입력을 만듭니다.
• 블라인드 앵커 강조: 화면 밖으로 스크롤되거나 축소된 요소를 강조 표시하여 화살표가 빈 공간을 가리키게 합니다.
• 도달할 수 없는 배경 작업: 사용자가 마스킹된 요소에 입력해야 하지만 배경으로 입력 또는 마우스 클릭을 차단합니다.
• 모바일 버블 압착: 모바일에서 고정 버블이 읽을 수 없는 너비로 줄어들어 단어가 어색하게 끊어집니다.

검증 기준

• 투어가 엄격히 3~5단계로 제한됩니다.
• 모든 단계에 명확하게 레이블이 지정되고 표시되는 "건너뛰기" 또는 닫기 옵션이 있습니다.
• 활성 단계 동안 키보드 탭 포커스가 팝오버 내에 갇힙니다.
• "다음"을 누르면 포커스가 다음 투어 카드(또는 새로 강조 표시된 요소)로 부드럽게 이동합니다.
• ARIA 속성(role="dialog", aria-modal, aria-describedby)이 올바르게 구성됩니다.
• 팝오버 충돌 처리가 정의됩니다(화면 가장자리 근처에서 자동으로 위치 반전).
• 모바일 뷰포트는 고정 팝오버에서 중앙 모달 또는 지속적인 하단 시트로 자연스럽게 전환됩니다.
• 격리된 앵커 주위에 4~8px 패딩 버퍼가 유지되어 테두리 잘림을 방지합니다.
• 모든 버튼의 활성 및 호버 상태가 WCAG AA(4.5:1 대비)를 충족합니다.