Communitygithub.com

SamuelChien/mega-skills-collection

웹 접근성 패턴: WCAG 2.2 준수를 위한 ARIA, 키보드 내비게이션, 스크린 리더 및 테스트 방법

mega-skills-collection란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor, Codex 등)가 웹 개발 과정에서 WCAG 2.2 접근성 기준을 준수하는 코드를 생성하도록 돕습니다. 시맨틱 HTML, ARIA 패턴, 키보드 내비게이션, 폼 접근성, 색상 대비 등 핵심 접근성 영역에 대한 구체적인 코드 예제와 가이드라인을 제공합니다. React 및 TypeScript 환경에서의 접근성 컴포넌트 구현(모달, 탭, 키보드 이벤트 핸들러)을 다루며, 실무에서 자주 발생하는 안티 패턴과 체크리스트도 포함되어 있습니다. 이 스킬을 통해 AI 에이전트는 접근성에 최적화된 UI 컴포넌트를 자동 생성하고, 개발자에게 실시간 피드백을 제공할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SamuelChien/mega-skills-collection/tree/HEAD/accessibility-wcag

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

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

문서

접근성 & WCAG

시맨틱 HTML

<!-- 의미 있는 요소를 제네릭 div 대신 사용 -->
<header>
  <nav aria-label="주 내비게이션">
    <ul>
      <li><a href="/" aria-current="page">홈</a></li>
      <li><a href="/products">제품</a></li>
      <li><a href="/about">소개</a></li>
    </ul>
  </nav>
</header>

<main>
  <article>
    <h1>제품 상세</h1>
    <section aria-labelledby="specs-heading">
      <h2 id="specs-heading">사양</h2>
      <dl>
        <dt>무게</dt>
        <dd>1.2 kg</dd>
        <dt>크기</dt>
        <dd>30 x 20 x 10 cm</dd>
      </dl>
    </section>
  </article>
</main>

<footer>
  <p>&copy; 2024 회사명</p>
</footer>

랜드마크에는 <div> 대신 <nav>, <main>, <article>, <section>, <aside>를 사용하세요. 스크린 리더는 이 요소들을 사용하여 페이지를 탐색합니다.

ARIA 패턴

function Modal({ isOpen, onClose, title, children }) {
  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      onKeyDown={(e) => e.key === "Escape" && onClose()}
    >
      <h2 id="modal-title">{title}</h2>
      <div>{children}</div>
      <button onClick={onClose} aria-label="대화상자 닫기">
        <XIcon aria-hidden="true" />
      </button>
    </div>
  );
}

function Tabs({ tabs, activeIndex, onChange }) {
  return (
    <div>
      <div role="tablist" aria-label="설정 섹션">
        {tabs.map((tab, i) => (
          <button
            key={tab.id}
            role="tab"
            id={`tab-${tab.id}`}
            aria-selected={i === activeIndex}
            aria-controls={`panel-${tab.id}`}
            tabIndex={i === activeIndex ? 0 : -1}
            onClick={() => onChange(i)}
            onKeyDown={(e) => handleArrowKeys(e, i, tabs.length, onChange)}
          >
            {tab.label}
          </button>
        ))}
      </div>
      {tabs.map((tab, i) => (
        <div
          key={tab.id}
          role="tabpanel"
          id={`panel-${tab.id}`}
          aria-labelledby={`tab-${tab.id}`}
          hidden={i !== activeIndex}
          tabIndex={0}
        >
          {tab.content}
        </div>
      ))}
    </div>
  );
}

키보드 내비게이션

function handleArrowKeys(
  event: React.KeyboardEvent,
  currentIndex: number,
  totalItems: number,
  onSelect: (index: number) => void
) {
  let newIndex = currentIndex;

  switch (event.key) {
    case "ArrowRight":
    case "ArrowDown":
      newIndex = (currentIndex + 1) % totalItems;
      break;
    case "ArrowLeft":
    case "ArrowUp":
      newIndex = (currentIndex - 1 + totalItems) % totalItems;
      break;
    case "Home":
      newIndex = 0;
      break;
    case "End":
      newIndex = totalItems - 1;
      break;
    default:
      return;
  }

  event.preventDefault();
  onSelect(newIndex);
}

모든 대화형 요소는 키보드로 접근 가능해야 합니다. Tab으로 초점 이동, Enter/Space으로 활성화, 화살표 키로 컴포넌트 내 탐색을 수행합니다.

폼 접근성

function SignupForm() {
  return (
    <form aria-labelledby="form-title" noValidate>
      <h2 id="form-title">계정 만들기</h2>

      <div>
        <label htmlFor="email">이메일 주소</label>
        <input
          id="email"
          type="email"
          required
          aria-required="true"
          aria-describedby="email-hint email-error"
          aria-invalid={hasError ? "true" : undefined}
        />
        <p id="email-hint">이메일을 절대 공유하지 않습니다.</p>
        {hasError && (
          <p id="email-error" role="alert">
            유효한 이메일 주소를 입력해 주세요.
          </p>
        )}
      </div>

      <button type="submit">계정 만들기</button>
    </form>
  );
}

색상과 대비

:root {
  --text-primary: #1a1a1a;      /* 흰색 배경에서 15.3:1 */
  --text-secondary: #595959;    /* 흰색 배경에서 7.0:1 */
  --text-on-primary: #ffffff;   /* 브랜드 색상에서 4.5:1 보장 */
  --border-focus: #0066cc;      /* 가시적 포커스 링 */
}

*:focus-visible {
  outline: 3px solid var(--border-focus);
  outline-offset: 2px;
}

.error-message {
  color: #d32f2f;
  /* 색상에만 의존하지 말고 아이콘이나 텍스트 접두사 추가 */
}
.error-message::before {
  content: "오류: ";
  font-weight: bold;
}

WCAG AA는 일반 텍스트에 4.5:1, 큰 텍스트(18px 볼드 또는 24px 일반)에 3:1의 대비를 요구합니다.

안티 패턴

  • 클릭 가능한 요소에 button이나 a 대신 div와 span 사용
  • 대체 지표 없이 포커스 아웃라인 제거
  • 정보 전달을 위해 색상에만 의존(빨간색=오류, 초록색=성공)
  • 요소를 이미 라벨링하는 가시 텍스트가 있을 때 aria-label 사용
  • 일시 정지 메커니즘 없이 미디어 자동 재생
  • 키보드 사용자를 위한 건너뛰기 내비게이션 링크 누락

체크리스트

  • 모든 대화형 요소가 키보드로 접근 가능 (Tab, Enter, Escape, 화살표)
  • 시맨틱 HTML 랜드마크 사용 (nav, main, article, section)
  • 이미지에 설명적인 alt 텍스트가 있음 (또는 장식용일 경우 alt="")
  • 색상 대비가 WCAG AA를 충족 (일반 텍스트 4.5:1, 큰 텍스트 3:1)
  • 모든 대화형 요소에서 포커스 표시기가 보임
  • 폼 입력에 연결된 <label> 요소가 있음
  • 오류 메시지가 role="alert"를 통해 스크린 리더에 전달됨
  • 페이지를 스크린 리더(VoiceOver, NVDA)와 키보드만으로 테스트했음

Individual skills in this repo

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

SamuelChien/mega-skills-collection

Security audit, hardening, threat modeling (STRIDE/PASTA), Red/Blue Team, OWASP checks, code review, incident response, and infrastructure security for any project.

SamuelChien/mega-skills-collection

Arquitecto de Soluciones Principal y Consultor Tecnológico de Andru.ia. Diagnostica y traza la hoja de ruta óptima para proyectos de IA en español.

SamuelChien/mega-skills-collection

Ingeniero de Sistemas de Andru.ia. Diseña, redacta y despliega nuevas habilidades (skills) dentro del repositorio siguiendo el Estándar de Diamante.

SamuelChien/mega-skills-collection

Estratega de Inteligencia de Dominio de Andru.ia. Analiza el nicho específico de un proyecto para inyectar conocimientos, regulaciones y estándares únicos del sector. Actívalo tras definir el nicho.

SamuelChien/mega-skills-collection

2D game development principles. Sprites, tilemaps, physics, camera.

SamuelChien/mega-skills-collection

3D game development principles. Rendering, shaders, physics, cameras.

SamuelChien/mega-skills-collection

Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing depth to web experiences.

SamuelChien/mega-skills-collection

Accessibility audit skill for scanning, fixing, and verifying WCAG 2.2 Level A and AA compliance across React, Next.js, Vue, Angular, Svelte, and plain HTML codebases. Use when auditing accessibility, fixing a11y violations, checking color contrast, generating compliance reports, or integrating accessibility checks into CI/CD pipelines.

SamuelChien/mega-skills-collection

Ab Test Analyzer - Auto-activating skill for Data Analytics. Triggers on: ab test analyzer, ab test analyzer Part of the Data Analytics skill category.

SamuelChien/mega-skills-collection

A B Test Config Creator - Auto-activating skill for ML Deployment. Triggers on: a b test config creator, a b test config creator Part of the ML Deployment skill category.

SamuelChien/mega-skills-collection

When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "conversion experiment," "statistical significance," or "test this." For tracking implementation, see analytics-tracking.

SamuelChien/mega-skills-collection

Acceptance Criteria Creator - Auto-activating skill for Enterprise Workflows. Triggers on: acceptance criteria creator, acceptance criteria creator Part of the Enterprise Workflows skill category.

SamuelChien/mega-skills-collection

Use when a coding task should be driven end-to-end from issue intake through implementation, review, deployment, and acceptance verification with minimal human re-intervention.

SamuelChien/mega-skills-collection

Accessibility Audit Runner - Auto-activating skill for Frontend Development. Triggers on: accessibility audit runner, accessibility audit runner Part of the Frontend Development skill category.

SamuelChien/mega-skills-collection

You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance.

SamuelChien/mega-skills-collection

Manage Discord channel access — approve pairings, edit allowlists, set DM/group policy. Use when the user asks to pair, approve someone, check who's allowed, or change policy for the Discord channel.

SamuelChien/mega-skills-collection

Create unified specification packages across Business, Development, and Design teams. Staged elaboration (L0 Vision → L1 Requirements → L2 Team Detail → L3 Acceptance Criteria) to build shared understanding. Does not write code.

SamuelChien/mega-skills-collection

Research a company or person and get actionable sales intel. Works standalone with web search, supercharged when you connect enrichment tools or your CRM. Trigger with "research [company]", "look up [person]", "intel on [prospect]", "who is [name] at [company]", or "tell me about [company]".

SamuelChien/mega-skills-collection

Create forensically sound bit-for-bit disk images using dd and dcfldd while preserving evidence integrity through hash verification.

SamuelChien/mega-skills-collection

Validate messaging consistency across website, GitHub repos, and local documentation generating read-only discrepancy reports. Use when checking content alignment or finding mixed messaging. Trigger with phrases like "check consistency", "validate documentation", or "audit messaging".

관련 스킬