React나 Next.js로 화면을 만들다 보면 “이 버튼, 접근성은 괜찮을까?”, “폼 입력창에 레이블을 빠뜨린 건 아닐까?” 하는 생각이 드는 순간이 있습니다. 직접 가이드라인 문서를 열어 체크하자니 양이 너무 많고, 그냥 넘어가자니 찜찜합니다.

web-design-guidelines 스킬은 이 상황을 해결합니다. Vercel이 실제 프로덕션 경험을 바탕으로 만든 웹 인터페이스 가이드라인을 에이전트에 심어두면, “이 파일 검토해줘” 한 마디에 접근성부터 다크모드, i18n까지 18개 카테고리를 파일:줄번호 형식으로 바로 돌려줍니다.

이 스리즈 세 번째 편으로, Vercel Labs의 agent-skills 레포에서 가장 넓게 적용되는 스킬을 소개합니다.

web-design-guidelines란?

web-design-guidelines는 Vercel Labs가 공식 배포한 UI 코드 검토 스킬입니다. 2026년 1월 19일 첫 등록 이후 현재 주간 설치 수 243,000회, GitHub Stars 24,800개를 기록하고 있습니다.

이 스킬이 독특한 점은 규칙 목록을 스킬 파일 안에 하드코딩하지 않는다는 것입니다. 실행할 때마다 Vercel의 공개 가이드라인 레포(vercel-labs/web-interface-guidelines)에서 최신 규칙을 가져옵니다. Vercel이 가이드라인을 업데이트하면 스킬을 재설치하지 않아도 자동으로 최신 기준이 적용됩니다.

18개 카테고리, 실전 중심 규칙들

Vercel이 정리한 가이드라인은 디자인 심미성이 아니라 동작하는 UI에 집중합니다.

카테고리	주요 점검 항목
접근성	아이콘 버튼 aria-label, 폼 레이블, 키보드 핸들러
포커스 상태	focus-visible:ring-*, outline-none 금지
폼	autocomplete, 올바른 type, 붙여넣기 차단 금지
애니메이션	prefers-reduced-motion 대응, transition: all 금지
타이포그래피	말줄임표(… vs ...), 곱슬따옴표, 숫자 정렬
이미지	width/height 명시, loading="lazy"
성능	50개 이상 목록 가상화, DOM 레이아웃 읽기 주의
내비게이션	URL에 상태 반영, <Link> 사용, 파괴적 동작 확인 모달
터치 & 인터랙션	touch-action: manipulation, 드래그 중 텍스트 선택 비활성화
다크모드	color-scheme: dark, 네이티브 <select> 색상 명시
국제화	Intl.DateTimeFormat, Intl.NumberFormat, translate="no"
하이드레이션	value/onChange 쌍, SSR/CSR 날짜 불일치 방지

이 스킬이 해결하는 문제

설치 방법

# Claude Code에 설치 (프로젝트 전용)
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code

# 전역 설치 (모든 프로젝트에서 사용)
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a claude-code

-g를 붙이면 한 번 설치로 모든 프로젝트에서 사용할 수 있습니다. UI 작업을 여러 프로젝트에서 하신다면 -g를 권장합니다.

다른 에이전트를 쓰신다면:

# Cursor에 설치
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a cursor

# Codex에 설치
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a codex

# Gemini CLI에 설치
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a antigravity

실전 데모: 컴포넌트 파일 검토

설치 후 Claude Code에서 바로 사용할 수 있습니다.

# 특정 파일 검토
/web-design-guidelines src/components/Button.tsx

# 패턴으로 여러 파일 한꺼번에
/web-design-guidelines src/components/**/*.tsx

# 폴더 전체
/web-design-guidelines src/components/

실제 출력 예시는 이렇습니다.

## src/components/Modal.tsx

src/components/Modal.tsx:8  — missing overscroll-behavior: contain
src/components/Modal.tsx:23 — focus trap not implemented (modal should trap focus)
src/components/Modal.tsx:41 — "..." → "…" (ellipsis character)
src/components/Modal.tsx:55 — aria-live region missing for async status

## src/components/ImageCard.tsx

src/components/ImageCard.tsx:12 — <img> missing width/height (causes CLS)
src/components/ImageCard.tsx:18 — below-fold image missing loading="lazy"

## src/components/SearchInput.tsx

✓ pass

파일마다 통과(✓ pass) 또는 위반 위치(파일:줄번호)를 정확히 알려줍니다. VS Code에서 클릭하면 해당 줄로 바로 이동할 수 있는 형식입니다.

내부 동작 원리

이 스킬이 독특한 이유는 규칙을 매번 원격에서 가져온다는 점입니다.

1. 사용자가 파일 경로를 제공하면
2. https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
   에서 최신 가이드라인 규칙을 가져옵니다 (WebFetch)
3. 지정한 파일들을 읽습니다
4. 가져온 규칙 전체를 대조합니다
5. file:line 형식으로 결과를 출력합니다

즉, Vercel이 가이드라인을 업데이트하면 스킬을 재설치하지 않아도 다음 실행부터 자동으로 최신 기준이 적용됩니다. 반면 네트워크 없이는 동작하지 않습니다.

허용된 도구

이 스킬이 사용하는 도구는 두 가지입니다. WebFetch로 가이드라인을 가져오고, Read로 파일을 읽습니다. 코드를 자동으로 수정하는 동작은 없습니다. 발견한 문제를 알려주는 역할만 합니다.

이럴 때 쓰세요 / 이럴 때는 안 맞아요

잘 맞는 상황	덜 맞는 상황
PR 머지 전 UI 컴포넌트 최종 점검	접근성 감사 공식 인증이 필요한 경우
새 팀원이 작성한 컴포넌트 코드 리뷰	디자인 심미성·브랜드 일관성 검토
”내가 이 규칙을 놓쳤나?” 빠른 확인	오프라인 환경 (가이드라인 원격 로드 필요)
레거시 코드베이스 일괄 감사	백엔드 API·서버 로직 검토

Vercel Labs의 다른 스킬들

vercel-labs/agent-skills 레포에는 이 스킬 외에도 유용한 스킬이 여럿 있습니다.

# 레포에 있는 스킬 목록 확인
npx skills add vercel-labs/agent-skills --list

이 시리즈에서 이미 다룬 것들:

• vercel-react-best-practices — React·Next.js 성능 최적화 69개 규칙 자동 적용 → 2편 보러 가기
• find-skills — “어떤 스킬이 있어?” 물으면 에이전트가 직접 찾아서 설치 → 1편 보러 가기

다음 편에서 다룰 예정:

• frontend-design (Anthropic 공식) — 프론트엔드 디자인 감각을 에이전트에 주입하는 스킬
• next-best-practices — App Router·캐싱·데이터 패칭 등 Next.js 전용 규칙

자주 묻는 질문 (FAQ)

Q1: web-design-guidelines 스킬은 유료인가요?

npx skills add로 설치되는 스킬 자체는 무료 오픈소스입니다. GitHub에 공개된 텍스트 파일(SKILL.md)을 에이전트에 로드하는 것뿐이라 별도 비용이 없습니다. 스킬이 내부적으로 Vercel의 가이드라인을 가져올 때 사용하는 GitHub Raw 엔드포인트도 무료입니다.

Q2: Claude Code 외에도 쓸 수 있나요?

네. Cursor, Codex (OpenAI), Gemini CLI (Antigravity), GitHub Copilot, Amp, OpenCode, Replit 등 총 41개 에이전트를 공식 지원합니다. -a 옵션으로 설치할 에이전트를 지정하면 됩니다. 여러 에이전트에 동시 설치도 가능합니다.

Q3: 가이드라인이 업데이트되면 스킬도 다시 설치해야 하나요?

아닙니다. 이 스킬은 실행할 때마다 Vercel의 가이드라인 레포에서 최신 규칙을 직접 가져옵니다. 스킬 파일 자체는 “어디서 규칙을 가져오고, 어떻게 출력할지”만 담겨 있습니다. 따라서 Vercel이 규칙을 추가하거나 수정해도 다음 실행부터 자동으로 반영됩니다.

Q4: 파일을 지정하지 않으면 어떻게 되나요?

파일이나 패턴을 인자로 넘기지 않으면 에이전트가 어떤 파일을 검토할지 먼저 물어봅니다. “현재 열려 있는 파일을 검토해줘” 또는 “src/components 폴더 전체”처럼 자연어로 답해도 됩니다.

---