Communitygithub.com

ComeOnOliver/skillshub

UI 컴포넌트의 WCAG 준수 여부, ARIA 속성, 키보드 탐색 및 스크린 리더 지원 여부를 검토합니다. 프론트엔드 컴포넌트를 구축하거나 사용자가 접근성 개선을 요청할 때 사용하세요.

skillshub란 무엇인가요?

Accessibility Auditor는 웹 애플리케이션의 접근성(WCAG 2.1 Level AA)을 감사하고 개선점을 제안하는 AI 에이전트 스킬입니다. UI 컴포넌트를 빌드하거나 검토할 때, 사용자가 접근성 개선을 요청할 때, 혹은 사전 감사를 준비할 때 유용합니다. 'accessibility', 'a11y', 'WCAG', 'screen reader', 'keyboard navigation' 키워드가 언급되면 자동으로 활성화됩니다. 이 스킬은 시맨틱 HTML 체크, 올바른 ARIA 속성 사용법, 키보드 탐색 지원, 대체 텍스트, 색상 대비, 폼 라벨링, 제목 구조, 동적 콘텐츠 알림, 스크린 리더 테스트 기법 등 12개 영역의 상세 지침을 제공합니다. 또한 Lighthouse, axe-core, pa11y 같은 자동화 도구 실행 명령어와 테스트 코드 예제를 포함하여 실무에서 바로 적용할 수 있도록 설계되었습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/crazydubya/accessibility-auditor

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

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

미리보기

스킬 README에서

skillshub preview
skillshub preview
skillshub preview

문서

접근성 감사 도구

웹 애플리케이션의 접근성(WCAG 2.1 Level AA) 준수 여부를 감사하고 개선점을 제안합니다.

사용 시기

  • UI 컴포넌트를 빌드하거나 검토할 때
  • 사용자가 접근성 개선을 요청할 때
  • 접근성 감사 준비 중일 때
  • 사용자가 "접근성", "a11y", "WCAG", "스크린 리더", "키보드 탐색"을 언급할 때

지침

1. 시맨틱 HTML 체크

적절한 HTML 요소 사용:

<!-- 나쁨 -->
<div onclick="submit()">제출</div>

<!-- 좋음 -->
<button onclick="submit()">제출</button>

시맨틱 구조:

  • <header>, <nav>, <main>, <footer>
  • <article>, <section>, <aside>
  • <h1> ~ <h6> 올바른 계층 구조로
  • 액션에는 <button>, 탐색에는 <a>

2. ARIA 속성

ARIA 사용 시기:

  • 사용자 정의 위젯 (탭, 아코디언, 모달)
  • 동적 콘텐츠 업데이트
  • 복잡한 상호작용
  • 시맨틱 HTML만으로 부족할 때

일반적인 ARIA 속성:

<!-- 랜드마크 역할 -->
<nav role="navigation" aria-label="메인">

<!-- 위젯 역할 -->
<div role="button" tabindex="0" aria-pressed="false">

<!-- 라이브 리전 -->
<div role="alert" aria-live="assertive">오류가 발생했습니다</div>

<!-- 레이블 및 설명 -->
<button aria-label="대화상자 닫기">×</button>
<input aria-describedby="비밀번호-도움말" />

ARIA의 첫 번째 규칙: 시맨틱 HTML로 해결된다면 ARIA를 사용하지 마세요

3. 키보드 탐색

모든 대화형 요소는 키보드로 접근 가능해야 합니다:

// 사용자 정의 요소에 키보드 지원 추가
<div
  role="button"
  tabindex="0"
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick();
    }
  }}
>
  클릭하세요
</div>

탭 순서:

  • 사용자 정의 대화형 요소에는 tabindex="0" 사용
  • tabindex > 0은 피하세요 (혼란스러운 탭 순서 유발)
  • 프로그래매틱 포커스 전용으로 tabindex="-1" 사용

포커스 관리:

  • 시각적 포커스 표시기
  • 모달 내 포커스 트래핑
  • 대화상자 닫을 때 포커스 반환
  • 주요 콘텐츠로 건너뛰기 링크

4. 대체 텍스트 및 이미지

정보 제공 이미지:

<img src="chart.png" alt="3분기 매출 25% 증가" />

장식용 이미지:

<img src="decoration.png" alt="" />
<!-- 또는 -->
<img src="decoration.png" role="presentation" />

복잡한 이미지:

<figure>
  <img src="complex-chart.png" alt="분기별 매출 차트" />
  <figcaption>
    차트 데이터에 대한 상세 설명...
  </figcaption>
</figure>

5. 색상 및 대비

대비 비율 (WCAG AA):

  • 일반 텍스트: 최소 4.5:1
  • 큰 텍스트(18pt 이상): 최소 3:1
  • UI 컴포넌트: 최소 3:1

색상에만 의존하지 마세요:

<!-- 나쁨: 색상만 사용 -->
<span style="color: red;">오류</span>

<!-- 좋음: 아이콘 + 색상 -->
<span style="color: red;">
  <svg aria-hidden="true"><!-- 오류 아이콘 --></svg>
  <span class="sr-only">오류: </span>
  잘못된 입력
</span>

6. 폼 및 레이블

모든 입력에는 레이블이 필요합니다:

<!-- 명시적 레이블 -->
<label for="email">이메일</label>
<input id="email" type="email" />

<!-- 암시적 레이블 -->
<label>
  이메일
  <input type="email" />
</label>

<!-- 아이콘 버튼의 aria-label -->
<button aria-label="검색">
  <svg><!-- 검색 아이콘 --></svg>
</button>

오류 메시지:

<input
  id="password"
  aria-invalid="true"
  aria-describedby="password-error"
/>
<div id="password-error" role="alert">
  비밀번호는 최소 8자 이상이어야 합니다
</div>

7. 제목 및 문서 구조

올바른 제목 계층 구조:

<h1>페이지 제목</h1>
  <h2>섹션 1</h2>
    <h3>하위 섹션 1.1</h3>
    <h3>하위 섹션 1.2</h3>
  <h2>섹션 2</h2>

레벨을 건너뛰지 마세요: h1 → h2 → h3 (h1 → h3 안 됨)

8. 동적 콘텐츠

스크린 리더에 업데이트 알림:

<!-- 예의: 사용자 일시 중지까지 대기 -->
<div role="status" aria-live="polite">
  5개의 새 메시지
</div>

<!-- 적극적: 즉시 중단 -->
<div role="alert" aria-live="assertive">
  세션이 1분 후에 만료됩니다
</div>

로딩 상태:

<button aria-busy="true" aria-label="로딩 중...">
  <span aria-hidden="true">로딩</span>
</button>

9. 스크린 리더 테스트

스크린 리더 전용 텍스트:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

장식 요소 숨기기:

<svg aria-hidden="true"><!-- 아이콘 --></svg>

10. 일반적인 문제 확인 사항

누락:

  • 이미지의 대체 텍스트
  • 폼 입력의 레이블
  • 올바른 제목 계층 구조
  • 키보드 포커스 표시기
  • 아이콘 버튼의 ARIA 레이블

부적절:

  • 낮은 대비 텍스트
  • 비시맨틱 마크업 (버튼에 div 사용)
  • 모달 내 포커스 관리 누락
  • 키보드 트랩
  • 자동 재생 미디어

테스트:

  • 키보드 전용 탐색
  • 스크린 리더 (NVDA, JAWS, VoiceOver)
  • 색맹 시뮬레이션
  • 200% 확대
  • 자동화 도구 (axe, Lighthouse)

11. 자동화된 테스트

도구:

# Lighthouse
npx lighthouse https://example.com --only-categories=accessibility

# axe-core
npm install --save-dev @axe-core/cli
npx axe https://example.com

# pa11y
npm install --save-dev pa11y
npx pa11y https://example.com

테스트 코드:

import { axe } from 'jest-axe';

test('접근성 위반이 없어야 함', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

12. WCAG 2.1 Level AA 체크리스트

인지 가능:

  • 비텍스트 콘텐츠에 대한 텍스트 대체
  • 오디오/비디오 자막
  • 적응 가능한 콘텐츠 (시맨틱 마크업)
  • 충분한 색상 대비

운용 가능:

  • 키보드 접근 가능
  • 키보드 트랩 없음
  • 적절한 시간 제한 (조정 가능)
  • 발작 유발 깜빡임 없음
  • 탐색 건너뛰기 링크
  • 설명적인 페이지 제목
  • 포커스 순서가 논리적임
  • 링크 목적을 문맥에서 명확히 알 수 있음

이해 가능:

  • 페이지 언어 지정 (<html lang="en">)
  • 예측 가능한 탐색
  • 입력 도움말 (레이블, 지침, 오류 메시지)

견고:

  • 유효한 HTML
  • 사용자 정의 위젯의 이름, 역할, 값
  • 보조 기술과의 호환성

모범 사례

  • 처음부터 접근성 고려하여 구축
  • 실제 보조 기술로 테스트
  • 시맨틱 HTML 우선, ARIA는 그다음
  • 논리적인 문서 구조 유지
  • 콘텐츠에 여러 접근 방식 제공
  • 키보드 탐색 철저히 테스트
  • 확대/축소 비활성화 금지
  • 랜드마크 및 제목 사용

지원 파일

  • reference/wcag-checklist.md: 전체 WCAG 2.1 AA 체크리스트
  • reference/aria-patterns.md: 일반적인 ARIA 위젯 패턴

Individual skills in this repo

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

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬