Communitygithub.com

coastdigitalgroup/coastai-skills

사이트 수준의 오류 상태 및 시스템 상태(404, 500, 유지보수, 오프라인)를 처리하는 체계적인 프레임워크를 설계하여 사용자 신뢰를 유지하고 명확한 복구 경로를 제공합니다.

coastai-skills란 무엇인가요?

이 스킬은 웹사이트에서 발생할 수 있는 시스템 수준의 오류 상태(404, 500, 유지보수, 오프라인 등)를 설계하기 위한 방법론을 제공합니다. 폼 검증이나 컨텍스트 배너와는 달리 전체 페이지 또는 사이트 전체의 상태를 처리하며, 실패가 발생했을 때 명확성, 공감, 그리고 뚜렷한 '탈출구'를 통해 사용자 신뢰를 유지하고 이탈을 방지하는 데 중점을 둡니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 환경에서 사용할 수 있도록 설계되었으며, 오류 유형 분류, 복구 경로 설정, 시각적 계층 구조 설계, '사람 우선' 메시징 규칙 적용, 반응형 적응 계획 수립 등의 단계별 워크플로를 제시합니다. 이 프레임워크는 404/403과 같은 경미한 오류부터 500과 같은 심각한 오류, 의도적인 유지보수, 네트워크 단절 등 다양한 시나리오를 다루며, 각 상황에 맞는 최적의 사용자 경험을 제공하는 것을 목표로 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/error-and-status-system

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

오류 및 상태 시스템

목적

오류 및 상태 시스템은 웹사이트의 '불행한 경로(unhappy paths)'—즉, 시스템 수준에서 무언가 잘못되었을 때의 순간—를 설계하기 위한 방법론을 제공합니다. 폼 수준의 검증이나 컨텍스트 배너와 달리, 이 시스템은 전체 페이지 또는 사이트 전체 상태를 처리합니다. 이는 실패가 명확성, 공감, 그리고 명확한 '탈출구'와 함께 전달되도록 하여, 기술적 문제 발생 시 사용자의 불만과 이탈을 방지합니다.

사용 사례

  • 404 찾을 수 없음: 사용자가 존재하지 않는 URL로 이동했을 때.
  • 500 서버 오류: 중요한 백엔드 오류로 페이지를 로드할 수 없을 때.
  • 유지보수 모드: 사이트가 업데이트를 위해 의도적으로 오프라인 상태일 때.
  • 오프라인 상태: 웹 애플리케이션에서 사용자의 연결이 끊어졌을 때.
  • 액세스 거부 (403): 사용자에게 특정 리소스에 대한 권한이 없을 때.

사용하지 말아야 할 경우

  • 폼 검증: 필드 수준 오류는 form-design-system을 사용하세요.
  • 컨텍스트 알림: 비차단 업데이트나 사소한 오류는 banner-and-alert-system을 사용하세요.
  • 빈 목록: 페이지가 올바르게 로드되었지만 데이터가 없을 때는 empty-state-system을 사용하세요.
  • 로딩 상태: 표준 콘텐츠 로딩 시 skeleton-state-system을 사용하세요.

입력

  1. 오류 유형: 클라이언트 오류(4xx), 서버 오류(5xx), 또는 시스템 상태(유지보수)인가?
  2. 기술 컨텍스트: 시스템이 민감한 데이터를 노출하지 않고 왜 실패했는지 설명할 수 있는가?
  3. 복구 경로: 사용자에게 가장 가능성 높은 다음 단계는 무엇인가?
  4. 브랜드 톤: 브랜드의 목소리가 유머러스한가, 전문적인가, 엄격히 기술적인가?
  5. 시스템 제약 조건: 오프라인 상태에서 특정 로컬 우선 작업을 지원해야 하는가?

출력

  1. 상태 페이지 구조: 오류 메시지, 시각적 앵커, 복구 작업에 대한 정의된 레이아웃.
  2. 메시징 계층 구조: 헤드라인(무슨 일이 일어났는지)과 설명(다음에 무엇을 해야 하는지)에 대한 표준.
  3. 복구 청사진: 특정 오류에 맞춰진 링크, 검색 입력, 또는 도움말 리소스의 맵.
  4. 오프라인 UI 사양: 연결이 끊어졌을 때 인터페이스가 어떻게 변경되어야 하는지에 대한 규칙.

워크플로

1. 실패 심각도 분류

오류의 영향을 결정합니다:

  • 낮음 (404/403): 하나의 URL에 국한됩니다. 사이트는 정상입니다. 리다이렉션에 초점을 맞춥니다.
  • 높음 (500): 시스템 전체 또는 페이지 중단입니다. 사이트에 문제가 있습니다. 안심과 지원에 초점을 맞춥니다.
  • 시스템적 (유지보수): 의도적인 다운타임입니다. 기대치 관리에 초점을 맞춥니다 (예: "오후 2시에 복귀").
  • 연결 (오프라인): 환경적 오류입니다. 상태 보존에 초점을 맞춥니다 (예: "변경 사항이 로컬에 저장되었습니다").

2. 복구 경로 설정

모든 오류 페이지에는 '탈출구'가 있어야 합니다:

  • '홈' 버튼: 절대 최소 요구 사항입니다.
  • 스마트 제안: 404의 경우 인기 페이지 링크나 검색 창을 제공합니다.
  • '새로고침' 트리거: 5xx 오류의 경우 요청을 재시도할 수 있는 눈에 띄는 방법을 제공합니다.
  • 지원 링크: 지속적인 문제의 경우 도움말 센터나 상태 페이지로의 직접 경로를 제공합니다.

3. 시각적 구조 설계

오류 보기에 visual-hierarchy-system을 적용합니다:

  • 시각적 앵커: 브랜드에 맞는 일러스트레이션이나 아이콘을 사용하여 실패의 충격을 완화합니다.
  • 명확한 헤드라인: 상태 코드("404 오류") 대신 '인간적인' 헤드라인(예: "페이지를 찾을 수 없습니다")을 사용합니다.
  • 미묘한 메타데이터: 기술 코드(예: 오류 ID: 12345)는 작고 대비가 낮게 유지하여 사용자가 아닌 지원 팀을 대상으로 합니다.

4. '사람 우선' 메시징 규칙 적용

사용자를 소외시키는 기술 전문 용어를 피합니다:

  • 나쁨: "500 내부 서버 오류: 피어에 의해 연결이 재설정되었습니다."
  • 좋음: "저희 쪽에서 문제가 발생했습니다. 지금 수정 중입니다."
  • 나쁨: "404 리소스를 찾을 수 없습니다."
  • 좋음: "이 페이지가 잘못된 길로 접어든 것 같습니다."

5. 반응형 적응 계획

  • 전체 페이지 vs. 모달: 오류가 전체 뷰포트를 차지해야 하는지(404/500의 경우 표준) 아니면 고정 배너로 표시되어야 하는지(오프라인 상태의 경우 일반적) 결정합니다.
  • 중앙 정렬 레이아웃: 중앙 정렬 콘텐츠는 스캔 노력을 최소화하고 사용자 여정의 '일시 중지'를 강조하므로 오류 페이지에 종종 가장 좋습니다.

결정 규칙

  • '직접 경로' 규칙: 오류 페이지가 막다른 길이 되어서는 안 됩니다. 특정 제안이 없으면 항상 '홈으로 돌아가기' 및 '검색' 옵션을 포함합니다.
  • 404 시 검색: 사이트에 100페이지 이상이 있는 경우 404 페이지에는 반드시 검색 창이 포함되어야 합니다.
  • 유지보수 투명성: 유지보수 모드인 경우 항상 예상 복귀 시간 또는 상태 페이지 링크를 제공합니다.
  • 오프라인 지속성: 오프라인 상태일 때 데이터 손실을 방지하기 위해 기능하지 않는 작업(예: '제출' 버튼)을 시각적으로 '회색 처리'하거나 비활성화합니다.

제약 조건

  • 접근성: 오류 페이지는 익숙한 길 찾기를 제공하기 위해 가능한 경우 사이트의 글로벌 탐색 및 바닥글을 유지해야 합니다. 동적 상태 변경(예: 오프라인 전환)의 경우 aria-live="assertive" 영역을 사용하여 변경 사항을 즉시 알립니다.
  • 반응형: 오류 페이지는 가능한 한 탄력적이어야 합니다. 시스템이 이미 어려움을 겪고 있을 경우 로드에 실패할 수 있는 무거운 에셋은 피합니다.
  • 브랜딩: 오류 페이지는 사이트의 일부처럼 보여야 하며, 일반적인 브라우저나 서버 기본 페이지처럼 보이지 않아야 합니다.

일반적인 실패 패턴

  • '막다른 길': 링크가 없는 404 페이지로, 사용자가 브라우저의 뒤로 가기 버튼을 사용하거나 떠나도록 강제합니다.
  • '전문 용어의 벽': 원시 스택 추적이나 데이터베이스 오류를 표시하여 사용자를 혼란스럽게 하고 잠재적으로 보안 정보를 유출합니다.
  • '비난 게임': 사용자가 잘못했다는 인상을 주는 메시지(예: "잘못된 URL을 입력했습니다") 대신 검색 실패에 대한 책임을 수용합니다.
  • 스타일 불일치: 사이트의 나머지 부분과 다른 글꼴/색상을 사용하여 오류 페이지가 손상되었거나 악의적으로 보이게 만듭니다.

검증 기준

  • 모든 오류 상태(404, 500 등)에는 명확하고 사람이 읽을 수 있는 헤드라인이 있습니다.
  • 최소한 하나의 기본 복구 작업(예: '홈으로 돌아가기')이 있습니다.
  • 404 페이지의 경우 검색 창이나 인기 링크가 제공됩니다.
  • 기술 메타데이터(오류 ID)는 존재하지만 계층 구조에서 하위에 배치됩니다.
  • 연결 상태 변경(오프라인)은 ARIA 라이브 영역을 통해 알려집니다.
  • 시각적 스타일은 핵심 브랜드/디자인 시스템과 일관성을 유지합니다.
  • 유지보수 페이지는 '예상 복귀 시간' 또는 '상태 페이지' 링크를 제공합니다.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

관련 스킬