Impeccable(임페커블, "흠잡을 데 없는")은 Claude Code·Cursor·Codex 같은 AI 코딩 하니스(harness)에 설치하는 프런트엔드 디자인 전용 스킬 패키지입니다. AI에게 "디자인을 잘하는 법"을 가르치는 지침서 + 검사기라고 보면 됩니다.
핵심 구성은 세 덩어리입니다. ① 스킬 1개(SKILL.src.md에 Color·Typography·Layout·Motion·Interaction 섹션 인라인 통합 + interaction-design.md 별도 파일), ② 명령 23개(polish·audit·critique·distill 등 AI와 공유하는 디자인 어휘), ③ 결정론적 안티패턴 규칙 44개 (AI slop 26개 + 일반 품질 18개). CLI와 브라우저 확장은 이 규칙들을 LLM 없이, API 키 없이 돌립니다.
만든 사람은 Paul Bakaus — jQuery UI·Famo.us 등으로 알려진 웹 인터랙션/성능 분야 베테랑 개발자입니다. 2026년 6월 기준 GitHub 스타 28k, 포크 1.5k. npm 패키지 impeccable v2.3.2, 스킬 릴리스 v3.5.0.
AI에게 "랜딩 페이지 만들어줘"라고 하면, 학습 데이터에 가장 많았던 모양 — Inter 폰트, 보라→파랑 그라데이션, 카드 속 카드, 제목마다 둥근 사각 아이콘 타일 — 으로 수렴합니다. 누가 봐도 "AI가 만들었네" 싶은 결과물이죠.
Impeccable은 두 가지로 이를 막습니다. 아트 디렉터 역할(스킬 + 명령)은 작업 전에 "이런 식으로 디자인하라"고 가이드하고, 맞춤법 검사기 역할(CLI 디텍터)은 작업 후 "여기 AI 티 나는 패턴이 있다"고 코드를 스캔해 잡아냅니다.
2025~2026년은 "AI에게 코딩을 시키는" 시대가 본격화된 시기입니다. 그런데 기능은 그럴듯해도 디자인은 죄다 비슷비슷한 SaaS 템플릿으로 나오는 게 공통 불만이었습니다. Impeccable은 이 "AI slop" 문제를 정면으로 겨냥해 입소문을 탔습니다.
Impeccable은 Anthropic이 공개한 최초의 디자인 스킬 frontend-design에서 출발했습니다(README.md 'Why Impeccable?' 섹션에 명시). 하지만 원조는 가이드 한 장 수준이라, 같은 모델·같은 데이터로 학습된 AI들이 결국 똑같은 몇 가지 "tell(티)"로 수렴하는 걸 막지 못했습니다.
① SKILL.src.md에 통합된 Color·Typography·Layout·Motion·Interaction 디자인 지식을 깊게 주입하고, ② 23개 명령으로 사람과 AI가 같은 디자인 어휘를 쓰게 하며, ③ 44개 결정론적 규칙(slop 26 + quality 18)으로 결과물을 코드 레벨에서 검사합니다. 게다가 11개 이상의 AI 하니스에 한 번에 설치됩니다.
| 비교 항목 | Impeccable | frontend-design (원조) | 일반 ESLint/Stylelint |
|---|---|---|---|
| 목적 | AI 디자인 품질 + 안티패턴 | AI 디자인 가이드 | 코드 문법/스타일 |
| 디자인 지식 | 7개 도메인 레퍼런스 | 단일 가이드 | 없음 |
| 공유 어휘(명령) | 23개 | 없음 | 없음 |
| 자동 검출 | 44개 결정론적 규칙 (slop 26 + quality 18) | 없음 | 문법 위주 |
| LLM/API 키 | 디텍터는 불필요 | 해당 없음 | 불필요 |
| 설치 대상 | 11+ 하니스 | Claude 위주 | 빌드 도구 |
ESLint가 "코드 문법이 틀렸다"를 잡는다면, Impeccable은 "디자인이 촌스럽다 / AI 티가 난다"를 잡습니다. 둘 다 규칙 기반 정적 검사지만, 검사 대상이 로직이 아니라 시각적 취향과 UX라는 점이 다릅니다.
Impeccable은 코드 프로젝트라기보다 "콘텐츠(스킬) + 그걸 배포·검증하는 도구 체인"에 가깝습니다. 그래서 스택도 네 층으로 나뉩니다.
| 구성 | 역할 |
|---|---|
| SKILL.src.md | 스킬의 본체이자 라우터. YAML frontmatter(name·description·allowed-tools) + 디자인 규칙 + 명령 라우팅 표. Color·Typography·Layout·Motion·Interaction 섹션 인라인 통합 |
| reference/ (도메인 파일) | interaction-design.md (별도 파일로 유일하게 존재). 나머지 도메인(typography·color·spatial·motion·responsive·ux-writing)은 SKILL.src.md에 인라인 통합됨 |
| reference/ (명령 23종) | craft·shape·audit·polish 등 각 명령의 실행 절차서. 호출 시에만 읽힘(lazy load) |
| reference/brand.md · product.md | "디자인이 곧 제품" vs "디자인이 제품을 보조" 두 레지스터(register) |
| Agent Skills 스펙 | agentskills.io 표준 frontmatter 준수 + 하니스별 확장 필드 |
| 기술 | 역할 |
|---|---|
| scripts/build.js | 단일 소스(SKILL.src.md)를 11개 하니스 포맷으로 컴파일하는 트랜스포머 |
| Bun | 빌드/테스트 러너 (bun run build, bun test) |
| archiver | 하니스별 + 통합(universal) ZIP 번들 생성 |
| Biome | JS 린팅/포매팅 (biome.json) |
| placeholder 치환 | {{model}}·{{scripts_path}} 등을 하니스별 값으로 컴파일 타임 치환 |
| 기술 | 역할 |
|---|---|
| htmlparser2 + domutils | HTML을 DOM 트리로 파싱 (정적 분석) |
| css-tree + css-select | CSS 파싱 + 셀렉터 매칭으로 스타일 규칙 검사 |
| marked | 마크다운 처리 |
| puppeteer (optional) | URL 스캔 시에만 — 실제 브라우저로 렌더해 레이아웃/대비 검사 |
| registry/antipatterns.mjs | 모든 규칙의 단일 진실원(배열). 빌드가 여기서 규칙 수를 자동 집계 |
| 기술 | 역할 |
|---|---|
| Astro 6 | 정적 사이트 생성 (콘텐츠 컬렉션 기반 사례 페이지·문서) |
| Cloudflare Pages + Functions | 호스팅 + 다운로드 API(functions/api/download) |
| Wrangler | Cloudflare 배포 CLI |
| motion / @paper-design/shaders | 사이트 모션·셰이더 데모 |
| kinpaku 테마 | 다크 래커 + 골드 악센트 — 빌드가 기본값 회귀를 막는 가드까지 둠 |
핵심은 "한 번 쓰고 어디든 컴파일"입니다. 디자이너/메인테이너는 SKILL.src.md 하나만 고치고, 빌드가 Claude Code·Cursor·Gemini CLI·Codex·Copilot·Kiro·OpenCode·Pi·Qoder·Trae·Rovo Dev 각각의 디렉토리 규칙과 frontmatter 지원 범위에 맞춰 결과물을 찍어냅니다(자세한 호환 표는 HARNESSES.md).
규칙은 category로 "slop(AI 티)"와 "quality(일반 품질·접근성)"를 구분하고, 일부는 gated(gpt/gemini)로 묶여 해당 모델 결과를 검사할 때만 켜집니다. 각 규칙은 skillSection·skillGuideline 필드로 스킬이 가르치는 지침과 1:1로 연결됩니다 — "검출"과 "교육"이 같은 출처를 공유하는 구조입니다.
스킬을 하니스마다 따로 관리하지 않고, 소스 1벌을 빌드가 11개 포맷으로 변환합니다. 새 하니스가 등장해도 트랜스포머에 규칙 한 줄만 추가하면 됩니다. 프런트엔드의 "디자인 토큰 → 플랫폼별 산출물" 발상과 같습니다.
SKILL.md는 얇은 라우터로 두고, 명령별·도메인별 상세는 reference/<name>.md로 분리해 필요할 때만 읽습니다. 컨텍스트 토큰을 아끼면서도 깊은 지식을 제공하는, Agent Skills의 정석 패턴입니다.
측정 가능한 건 결정론적 코드 규칙 44개(slop 26 + quality 18)로 API 키 없이 빠르게 잡습니다. 객관적 규칙 기반 검사를 CI에서도 돌릴 수 있게 만든 설계입니다.
같은 규칙도 맥락에 따라 다르게 적용해야 합니다. 랜딩·캠페인처럼 "디자인이 곧 제품"이면 brand.md, 대시보드·툴처럼 "디자인이 제품을 보조"하면 product.md를 로드해 기본값을 조정합니다.
빌드가 자기 웹사이트·README를 validateProse(em 대시·마케팅 buzzword 금지)와 validateTheme(kinpaku 기본값 가드)로 스캔합니다. 규칙 위반이 있으면 빌드를 실패시킵니다. "디자인 잘하자"고 말하는 도구가 스스로 그 규칙을 지키도록 강제하는 셈입니다.
Impeccable은 agentskills.io 표준을 정석대로 따른 좋은 교본입니다. SKILL.md의 frontmatter(name·description·allowed-tools·user-invocable), reference/ 분리, placeholder 치환을 실제 동작하는 형태로 볼 수 있습니다.
내 프로젝트용 미니 스킬을 하나 만들어 보세요. description을 잘 쓰는 게 핵심입니다 — Impeccable의 description은 "언제 이 스킬을 써야 하는가"를 한 문단으로 촘촘히 나열합니다. 이게 AI가 스킬을 올바르게 트리거하게 하는 비결입니다.
LLM 없이 HTML/CSS를 파싱해 규칙을 검사하는 방법을 배웁니다. registry/antipatterns.mjs의 규칙 객체 스키마(id·category·severity·gated)와 rules/checks.mjs의 검사 함수가 어떻게 분리됐는지 보면, "데이터(규칙)와 로직(엔진)의 분리"가 한눈에 들어옵니다.
npx impeccable detect <내-사이트-url> --json을 돌려 결과 JSON을 뜯어보고, antipatterns 배열에 나만의 규칙 1개(예: "버튼 높이 36px 미만 금지")를 추가해 보세요.
"단일 소스 → N개 타깃" 빌드는 디자인 토큰, 모노레포, i18n 등 어디서나 재등장하는 패턴입니다. scripts/lib/transformers/가 provider별 차이(디렉토리명, 지원 frontmatter 필드)를 어떻게 데이터로 추상화했는지 학습 가치가 큽니다.
코드를 안 봐도, skill/SKILL.src.md의 Color·Typography·Layout·Motion·Interaction 섹션과 reference/interaction-design.md를 정독해도 프런트엔드 디자인 실력이 오릅니다. OKLCH 색 공간, 모듈러 타입 스케일(≥1.25 비율), 지수 감속 이징, text-wrap: balance/pretty, 시맨틱 z-index 스케일, 반응형 repeat(auto-fit, minmax()) 같은 실전 규칙이 "왜"와 함께 정리돼 있습니다.
이 규칙들은 AI를 위한 것이지만 사람에게도 그대로 적용됩니다. "회색 글씨를 색 배경에 쓰지 마라", "카드 속 카드 금지", "cream/beige 기본 배경 금지" 같은 건 디자인 입문자가 흔히 저지르는 실수의 체크리스트이기도 합니다.
| 항목 | 요구사항 |
|---|---|
| 런타임 | Node.js ≥ 24 (CLI 사용 시). 스킬만 쓰면 Node 불필요 |
| AI 하니스 | Claude Code / Cursor / Gemini CLI / Codex / Copilot / Kiro / OpenCode / Pi / Qoder / Trae / Rovo Dev 중 하나 |
| URL 스캔 | puppeteer(선택 의존성) — 디렉토리/파일 스캔만 할 거면 불필요 |
| API 키 | 디텍터·CLI는 불필요. 스킬의 LLM 비평은 하니스의 모델을 사용 |
| 라이선스 | Apache 2.0 (상업적 사용·수정 자유, 특허 보호 조항 포함) |
# 방법 1 (권장): 하니스 자동 감지 후 설치
npx impeccable install
# 방법 2: Git 서브모듈 또는 ZIP 다운로드 (impeccable.style)
# → 사이트에서 하니스별 ZIP을 받아 프로젝트에 압축 해제
# 방법 3: 레포에서 직접 복사 (README 기재 경로 사용)
# → README의 Option 3 참조 (하니스별 경로 상이)npx impeccable detect src/ # 디렉토리 스캔
npx impeccable detect index.html # 단일 파일
npx impeccable detect https://example.com # URL (puppeteer)
npx impeccable detect --fast --json . # 정규식만, JSON 출력(CI용)아무 정적 사이트나 골라 npx impeccable detect <url>을 돌려보세요. slop/quality로 분류된 findings를 읽고, 각 규칙이 skillGuideline에서 무엇을 가리키는지 매칭해 봅니다. "내 사이트가 AI 티가 나나?"를 객관적으로 확인하는 첫걸음입니다.
Claude Code/Cursor에 스킬을 깔고 /impeccable critique → /impeccable polish 순으로 기존 컴포넌트를 손봐 보세요. 비평 → 수정 흐름에서 AI의 결과가 어떻게 달라지는지, before/after를 직접 비교합니다.
registry/antipatterns.mjs에 규칙 객체를 추가하고 rules/checks.mjs에 검사 로직을 붙여, 테스트(tests/detect-antipatterns.test.js)를 통과시켜 보세요. "규칙 데이터 + 엔진 + 테스트"의 3박자 구조를 체득하게 됩니다.
impeccable detect --json을 GitHub Actions에 붙여, PR에서 slop 규칙 위반이 N개 이상이면 빌드를 실패시키는 워크플로를 작성하세요. "디자인 품질을 CI로 강제"하는 실전 파이프라인을 경험합니다.
scripts/lib/transformers/를 분석해, 아직 지원되지 않는 가상의 하니스(예: 내 사내 도구)용 provider 설정을 추가하고 bun run build로 산출물이 정상 생성되는지 확인하세요. 단일 소스 → 다중 타깃 빌드의 내부를 완전히 이해하게 됩니다.
| 주차 | 주제 | 학습 내용 / 실습 |
|---|---|---|
| 1주차 | 디자인 기본기 | skill/reference의 typography·color·spatial 정독. OKLCH·모듈러 스케일·대비(4.5:1) 직접 적용해 작은 랜딩 1장 제작 |
| 2주차 | 모션·인터랙션·반응형 | motion·interaction·responsive 레퍼런스 + prefers-reduced-motion, 지수 이징, container query 실습 |
| 3주차 | Agent Skills | agentskills.io 스펙 학습 → 내 도메인용 스킬 제작. description·reference 분리·placeholder 익히기 |
| 4주차 | 정적 분석 도구 제작 | htmlparser2·css-tree로 미니 린터 만들기 → impeccable 디텍터 구조와 비교, 규칙 1개 기여(PR) |
코드부터 보지 말고 reference 문서 → 명령 사용 → 디텍터 코드 순서를 권합니다. "무엇이 좋은 디자인인가"를 먼저 알아야, 디텍터가 "왜 이걸 잡는지"가 이해됩니다.