Communitygithub.com

coastdigitalgroup/coastai-skills

아코디언 UI 시스템을 설계하고 구현하여 구조적 무결성, 시각적 어포던스, 다양한 콘텐츠 밀도 및 기기에서의 접근성을 보장합니다.

coastai-skills란 무엇인가요?

이 스킬은 아코디언 UI 컴포넌트를 체계적으로 설계하고 구현하는 방법을 제공합니다. 아코디언은 사용자가 고수준 정보를 훑어보고 세부 내용을 선택적으로 열어볼 수 있게 하는 점진적 공개 패턴입니다. FAQ, 모바일 메뉴, 복잡한 양식 등에 적합하며, 작은 콘텐츠 볼륨이나 중요한 안내 사항에는 사용하지 말아야 합니다. 이 스킬은 콘텐츠 구조, 시각적 어포던스, 상호작용 로직, 반응형 전략, 접근성(ARIA, 키보드 내비게이션, WCAG 2.2 터치 타겟)을 정의합니다. Chevron 규칙, 첫 번째 항목 열기 규칙 등 의사 결정 규칙과 함께 흔한 실패 패턴(미스터리 미트 트리거, 콘텐츠 점프 등)을 다루어 실무에 바로 적용할 수 있는 가이드를 제공합니다.

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

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

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

문서

아코디언 UI 시스템

목적

Accordion UI System 스킬은 아코디언(클릭하면 관련 콘텐츠를 펼쳐 보여주는 쌓인 헤더)을 설계하고 구성하는 방법론을 제공합니다. 이 패턴은 점진적 공개에 필수적이며, 사용자가 개괄적인 정보를 훑어보고 필요한 세부 사항을 선택적으로 볼 수 있게 합니다. 체계적인 접근 방식은 중요한 정보를 숨기거나 접근성 장벽을 만들지 않으면서 인지 부하를 줄여줍니다.

사용 사례

  • FAQ 섹션: 질문과 답변 목록을 스캔 가능한 목록으로 구성.
  • 모바일 메뉴: 보조 내비게이션 항목을 접어서 수직 공간 절약.
  • 복잡한 양식: 관련 입력 필드를 그룹화하여 관리 가능한 토글 섹션으로 구성.
  • 제품 상세 정보: 전자상거래 페이지에서 기술 사양, 배송 정보, 리뷰를 숨김.
  • 필터링: 검색 사이드바에서 여러 패싯 그룹 관리.

사용하지 말아야 할 경우

  • 소량의 콘텐츠: 전체 콘텐츠가 짧다면 클릭 뒤에 숨기는 것은 불필요한 상호작용 비용을 추가.
  • 중요 안내: 사용자가 진행하기 위해 반드시 읽어야 하는 정보(예: 법적 경고, '방법' 단계)는 숨기지 않음.
  • 검색 중심 페이지: 사용자가 브라우저 '찾기'(Cmd/Ctrl+F)를 자주 사용해야 하는 경우; 기본적으로 숨겨진 아코디언 콘텐츠는 검색되지 않는 경우가 많음.
  • 단일 항목 공개: 토글할 콘텐츠가 하나뿐이면 '더 보기' 링크나 단일 공개 컴포넌트를 사용.

입력

  1. 콘텐츠 인벤토리: 헤더와 그에 해당하는 확장 콘텐츠 목록.
  2. 확장 로직: 한 번에 하나만 열 수 있는지(단독), 아니면 여러 개를 열 수 있는지.
  3. 트리거 컨텍스트: 아코디언이 위치할 곳(예: 본문 영역, 사이드바, 모바일 드로어).
  4. 기존 시스템: 상위 디자인 시스템의 유동적 간격 및 타이포그래피 스케일.

출력

  1. 아코디언 구성 요소 명세: 헤더, 아이콘, 패널, 간격에 대한 시각적 정의.
  2. 상호작용 명세: 확장, 포커스 상태, 전환에 대한 동작.
  3. 접근성 청사진: ARIA 역할, 상태, 키보드 매핑.
  4. 반응형 전략: 아코디언이 좁은 뷰포트에 적응하는 규칙.

워크플로우

1. 콘텐츠 구조 정의

아코디언 항목의 표준 부분을 정의합니다:

  • 헤더(트리거): 제목을 포함한 클릭 가능한 영역.
  • 아이콘(어포던스): 일반적으로 확장 가능성을 나타내는 쉐브론 또는 플러스/마이너스 기호.
  • 패널: 숨겨진 콘텐츠를 담는 컨테이너.
  • 그룹: 여러 항목 간의 관계를 관리하는 상위 컨테이너.

2. 시각적 어포던스 설정

visual-hierarchy-system을 적용하여 아코디언이 인식 가능하도록 합니다:

  • 상태 표시기: 열렸을 때 회전하거나 변경되는 아이콘(쉐브론) 사용.
  • 구분: fluid-spacing-system의 테두리, 배경색 변화, 또는 수직 간격을 사용하여 항목 구분.
  • 헤더: 헤더 텍스트가 상호작용 가능해 보이도록 함(굵은 글씨체나 다른 색상).

3. 상호작용 로직 정의

동작 패턴을 선택합니다:

  • 단독 열림: 하나의 항목을 열면 다른 항목이 자동으로 닫힘. 집중도와 페이지 길이 축소에 가장 좋음.
  • 다중 열림: 여러 항목이 열린 상태로 유지 가능. 섹션 간 정보를 비교해야 할 때 가장 좋음.
  • 기본 상태: 첫 번째 항목을 기본으로 열어 기능을 알릴지 결정.

4. 간격 및 콘텐츠 최적화

내부에 fluid-spacing-system을 적용합니다:

  • 헤더 패딩: 터치 타겟이 최소 24x24px(WCAG 2.2 SC 2.5.8 최소)인지 확인; 레이아웃이 허락하는 경우 편안한 터치 사용을 위해 44x44px 선호.
  • 패널 패딩: 헤더와 콘텐츠 간의 명확한 관계를 만들도록 내부 패딩 사용.
  • 전환: 콘텐츠가 나타날 때의 '점프'를 부드럽게 하기 위해 미묘한 높이 또는 불투명도 전환(200-300ms) 사용.

5. 접근성 및 반응형 확인

  • 키보드: 사용자는 ARIA APG 아코디언 패턴에 따라 Tab 키로 헤더로 이동하고 Enter/Space로 토글할 수 있어야 함.
  • ARIA: 각 트리거를 제목 요소(<h3><button aria-expanded="true/false" aria-controls="panel-id">...</button></h3>)로 감싸고, 패널에 role="region"을 부여하고 aria-labelledby로 트리거를 가리키게 함(패널에 중요한 콘텐츠가 있는 경우).
  • 모바일: 긴 헤더가 깔끔하게 줄 바꿈되고 아이콘과 겹치지 않도록 함.

의사 결정 규칙

  • 쉐브론 규칙: 항상 헤더 오른쪽에 시각적 표시기(쉐브론 같은)를 포함. 닫힐 때는 아래쪽, 열릴 때는 위쪽을 가리켜야 함.
  • 첫 번째 항목 규칙: 가장 중요하거나 가장 많이 요청되는 정보를 포함하는 경우 기본적으로 첫 번째 아코디언 항목을 열어둠.
  • 텍스트 자르기 금지: 아코디언 헤더를 자르지 않음. 제목이 길면 여러 줄로 줄 바꿈하여 명확성 보장.
  • 정렬: 확장/축소 트리거 아이콘을 일관되게 유지(보통 오른쪽 끝에 정렬)하여 예측 가능한 스캔 경로를 만듦.

제약 조건

  • 접근성: 헤더는 키보드 접근을 위해 <button>을 포함한 시맨틱 제목 태그(H2-H4)를 사용해야 하며, WCAG 2.2 SC 2.5.8 최소 타겟 크기(24x24px)를 충족.
  • 반응형: 아코디언 너비는 유동적(부모의 100%)이어야 함. 패널 콘텐츠는 완전히 반응형이어야 함.
  • 계층 구조: 아코디언 헤더는 페이지의 H1보다 시각적으로 더 두드러져서는 안 됨.

일반적인 실패 패턴

  • 미스터리 미트 트리거: 클릭 가능하다는 것을 알 수 없는 평범한 텍스트처럼 보이는 아코디언 헤더.
  • 콘텐츠 점프: 사용자의 스크롤 위치를 혼란스럽게 하는 빠르고 갑작스러운 전환.
  • 포커스 상태 누락: 키보드 사용자를 위한 가시적 포커스 링을 디자인하지 않음.
  • 과밀한 패널: 패널 내부에 너무 많은 복잡한 상호작용 콘텐츠(다른 아코디언 등)를 넣어 '중첩 인셉션'을 초래.
  • 접근 불가능한 ARIA: aria-expanded 상태를 프로그래밍 방식으로 업데이트하지 않음.

검증 기준

  • 모든 아코디언 항목에 명확한 시각적 표시기(예: 쉐브론)가 있음.
  • 헤더가 키보드 접근 가능(버튼 기반)하며 가시적 포커스 상태가 있음.
  • aria-expanded와 aria-controls가 올바르게 정의됨.
  • 내부 간격이 유동적 간격 시스템을 따름.
  • 단독/다중 열림 로직이 콘텐츠 유형에 적절함.
  • 아코디언이 레이아웃을 깨지 않고 부드럽게 전환됨.
  • 터치 타겟이 WCAG 2.2 최소 24x24px(44x44px 권장)을 충족함.

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 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 specify a systematic dark theme framework, establishing rules for elevation-based surface colors, desaturated brand accents, text legibility, and media adaptation to ensure an accessible, low-fatigue experience.

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.

관련 스킬