Impeccable: LLM이 만든 티 나는 UI를 줄이기 위한 프론트엔드 디자인 스킬킷

Impeccable은 AI 코딩 도구가 더 나은 프론트엔드 결과물을 만들도록 유도하는 디자인 스킬 + 명령어 모음입니다. 저장소 설명 그대로 보면, 이 프로젝트는 “1개의 핵심 스킬, 17개의 명령, 그리고 큐레이션된 안티패턴”으로 구성되어 있으며, 목표는 흔한 AI 생성 UI의 전형성을 줄이고 더 완성도 높은 인터페이스를 만들게 하는 것입니다. 작성자는 Paul Bakaus이며, README에서는 Anthropic의 frontend-design 스킬을 기반으로 더 깊은 가이드와 더 많은 제어 수단을 추가한 프로젝트라고 설명합니다. (GitHub)

이 프로젝트가 흥미로운 이유는, 보통 “AI가 UI를 잘 만들게 하려면 모델이 더 똑똑해야 한다”는 방향으로 생각하기 쉬운데, Impeccable은 반대로 모델에게 더 나은 미적 판단 기준과 금지 규칙을 제공하는 방식을 택한다는 점입니다. 즉, 모델 자체를 바꾸는 것이 아니라, 모델이 디자인 결정을 내릴 때 참고할 어휘(vocabulary) 와 검수 프레임워크를 주는 접근입니다. (GitHub)

또한 이 프로젝트는 특정 한 도구 전용이 아닙니다. README와 개발 가이드 기준으로 Cursor, Claude Code, Gemini CLI, Codex CLI를 지원하며, 내부적으로는 풍부한 원본 포맷을 유지한 뒤 각 도구가 이해할 수 있는 형식으로 변환하는 구조를 사용합니다. (GitHub)

 

GitHub - pbakaus/impeccable: The design language that makes your AI harness better at design.

---

왜 이 프로젝트가 등장했을까

Impeccable이 해결하려는 문제는 매우 현실적입니다. README는 오늘날 LLM이 흔히 만들어내는 디자인 실수를 꽤 노골적으로 지적합니다. 예를 들어:

• Inter 같은 너무 흔한 폰트 사용
• 보라/파랑 계열 그라디언트 남용
• 카드 안에 카드가 또 들어가는 구조
• 컬러 배경 위에 흐릿한 회색 텍스트 사용

이런 패턴은 “그럴듯하지만 기억에 남지 않는 AI UI”의 대표적인 징후로 소개됩니다. Impeccable은 바로 이런 편향을 줄이기 위해 등장했습니다. (GitHub)

여기서 중요한 포인트는, 이 프로젝트가 단순히 “예쁜 UI를 만들어라”라고 말하지 않는다는 점입니다. 오히려 무엇을 하지 말아야 하는지를 매우 구체적으로 적습니다. 예를 들어 순수한 검정/흰색을 피하고, 중성색에도 브랜드 톤을 살짝 섞으라고 하며, “다크 모드 + 네온 포인트 + 유리 효과” 같은 너무 익숙한 조합을 경계합니다. 즉, 생성형 모델이 자주 빠지는 평균적 결과를 벗어나게 하기 위한 금지 목록 기반 설계 언어가 핵심입니다. (GitHub)

개발자 관점에서 보면 이건 꽤 실용적입니다. 왜냐하면 실제 제품 개발에서 문제는 “코드를 못 짠다”가 아니라, 빨리 만든 화면이 전부 비슷비슷해 보인다는 데 더 가깝기 때문입니다. Impeccable은 그 지점을 정확히 찌릅니다. 즉, 코드 생성 품질보다 한 단계 위에 있는 디자인 의사결정 품질을 보정하려는 프로젝트라고 볼 수 있습니다. 이 해석은 README의 문제 정의와 스킬 문서의 안티패턴 중심 서술을 종합한 것입니다. (GitHub)

---

핵심 기능

1) frontend-design 스킬: 디자인 판단 기준을 모델에 주입

Impeccable의 중심은 frontend-design 스킬입니다. 이 스킬은 “대담한 미적 방향을 먼저 정하라”고 요구합니다. 목적, 톤, 제약 조건, 차별점까지 먼저 명확히 하라고 지시하고, 그 뒤에야 UI를 구현하게 만듭니다. 즉, 바로 컴포넌트 코드를 뽑는 대신 먼저 디자인 컨셉을 의식적으로 선택하게 유도합니다. (GitHub)

이 스킬은 특히 다음 원칙들이 강합니다.

• 타입 스케일과 계층을 분명히 둘 것
• 색상은 OKLCH 같은 현대적 컬러 시스템을 활용할 것
• 레이아웃은 대칭과 반복만 고집하지 말고 리듬을 만들 것
• 애니메이션은 transform/opacity 중심으로 다룰 것
• 모바일은 기능을 잘라내는 것이 아니라 맥락에 맞게 적응시킬 것
• UX 카피는 군더더기 없이 쓸 것

이건 단순 취향 가이드가 아니라, 실제 구현 방식까지 포함하는 실전용 프롬프트 설계 문서에 가깝습니다. (GitHub)

2) 7개의 레퍼런스 문서: 분야별 세부 규칙 제공

README 기준으로 이 프로젝트는 7개의 도메인별 레퍼런스를 제공합니다.

• typography
• color-and-contrast
• spatial-design
• motion-design
• interaction-design
• responsive-design
• ux-writing (GitHub)

예를 들어 typography 레퍼런스는 단순히 “폰트를 잘 고르라” 수준이 아닙니다. line-height를 수직 리듬의 기준 단위로 삼으라거나, body text는 16px 미만으로 가지 말라거나, clamp() 기반 fluid type을 어디에 쓰고 어디엔 쓰지 말아야 하는지까지 제시합니다. 심지어 OpenType 기능과 fallback font metric 조정 같은 꽤 디테일한 항목도 다룹니다. (GitHub)

이 말은 곧, Impeccable이 “한두 개의 예쁜 예시를 흉내 내는 툴”이 아니라, 모델이 디자인 결정을 할 때 참고하는 룰북을 제공하는 시스템이라는 뜻입니다. (GitHub)

3) 17개의 명령어: 생성 이후를 다루는 후처리 워크플로우

README에는 /audit, /critique, /normalize, /polish, /distill, /clarify, /optimize, /harden, /animate, /colorize, /bolder, /quieter, /delight, /extract, /adapt, /onboard, /teach-impeccable의 17개 명령이 정리되어 있습니다. (GitHub)

이 중 특히 중요한 것은 /audit과 /teach-impeccable입니다.

/audit은 접근성, 성능, 테마 일관성, 반응형, 그리고 “AI 티 나는 안티패턴”까지 점검하는 진단 명령입니다. 흥미로운 점은 이 명령이 수정하지 않고 문서화만 하라고 명시한다는 것입니다. 즉, 이것은 리팩터링 명령이 아니라 품질 점검기입니다. 결과물도 심각도, 위치, 영향, 권장 해결책, 다음에 어떤 명령을 쓰면 좋을지까지 구조화해서 보고하도록 설계돼 있습니다. (GitHub)

/teach-impeccable은 프로젝트의 코드베이스를 먼저 탐색하고, 부족한 부분만 사용자에게 질문한 뒤, 그 결과를 CLAUDE.md의 ## Design Context 섹션에 기록하도록 되어 있습니다. 다시 말해 일회성 명령이 아니라, 프로젝트 고유의 디자인 컨텍스트를 장기 기억처럼 설정하는 부트스트랩 단계에 가깝습니다. (GitHub)

---

이 프로젝트의 진짜 강점

개인적으로 이 저장소의 강점은 “디자인 감각” 자체보다도, 그 감각을 재사용 가능한 명령 체계로 분해했다는 점입니다.

보통 AI로 UI를 만들면 이런 흐름이 됩니다.

1. 화면 하나 생성
2. 마음에 안 드는 점이 보임
3. “좀 더 세련되게”, “좀 더 미니멀하게” 같은 모호한 요청 반복
4. 결과가 랜덤하게 출렁임

Impeccable은 이 과정을 다음처럼 바꿉니다.

1. 기본 설계 원칙을 스킬로 주입
2. /teach-impeccable로 프로젝트 컨텍스트 고정
3. /audit로 문제 유형 진단
4. /normalize, /polish, /quieter, /bolder 등 목적별 명령으로 수정

즉, 추상적인 감상평을 명시적 조작(command vocabulary) 으로 바꾸는 것이 핵심입니다. README의 “The vocabulary you didn’t know you needed”라는 문구가 정확히 이 지점을 가리킵니다. (GitHub)

---

프로젝트 구조

저장소 루트에는 api, public, scripts, server, tests, source/skills 같은 디렉터리와 함께 .claude/skills도 존재합니다. 공개 문서만으로 각 디렉터리의 세부 역할이 완전히 설명되지는 않지만, 적어도 이 저장소가 단순 프롬프트 모음집을 넘어서 빌드/배포/테스트 및 웹 배포 자산까지 포함하고 있다는 점은 확인할 수 있습니다. (GitHub)

개발 가이드에 따르면 핵심 아키텍처는 다음과 같습니다.

• source/ 아래에 풍부한 원본 포맷 유지
• 각 AI 도구에 맞게 dist/로 변환
• Cursor는 제한된 포맷으로 다운그레이드
• Claude Code, Gemini CLI, Codex는 richer metadata 유지 (GitHub)

이를 구조적으로 그리면 대략 이렇습니다.

이 구조의 좋은 점은 최저 공통 분모에 맞추지 않는다는 데 있습니다. 개발 가이드는 Cursor가 frontmatter나 argument 지원이 약한 반면, Claude Code·Gemini·Codex는 더 풍부한 메타데이터를 지원한다고 설명합니다. 그래서 원본은 풍부하게 유지하고, 각 플랫폼으로 갈 때 필요한 수준만큼 변환합니다. (GitHub)

---

개발자 관점에서 본 설계 포인트

1) “프롬프트”가 아니라 “도메인 모델”에 가깝다

이 프로젝트는 얼핏 보면 프롬프트 모음 같지만, 실제로는 다음 세 가지 층을 가집니다.

1. 공통 디자인 원칙 (frontend-design)
2. 세부 참조 지식 (typography, motion, responsive ...)
3. 작업 단위 명령 (/audit, /polish, /adapt ...)

이렇게 나뉘어 있기 때문에, 단순히 “예쁘게 만들어”보다 훨씬 안정적으로 동작할 가능성이 높습니다. 특히 “무엇을 하지 말아야 하는지”가 시스템적으로 들어가 있다는 점이 인상적입니다. 이 평가는 스킬 문서와 README의 구조를 바탕으로 한 분석입니다. (GitHub)

2) 디자인 결과를 후처리 가능한 파이프라인으로 본다

/audit가 수정 대신 보고서를 생성하도록 설계된 부분은 매우 중요합니다. 이는 생성형 결과를 한 번에 완벽하게 만들려 하지 않고, 진단 → 수정 → 정리의 파이프라인으로 다루겠다는 뜻입니다. 프론트엔드 팀의 실제 리뷰 프로세스와 닮아 있습니다. (GitHub)

3) “브랜드/맥락”을 프로젝트 로컬 컨텍스트로 저장한다

/teach-impeccable이 CLAUDE.md에 Design Context를 기록하는 설계는 꽤 실무적입니다. 많은 AI 생성 결과가 흔들리는 이유는 세션마다 미감과 우선순위가 바뀌기 때문인데, 이 프로젝트는 그걸 지속 설정값으로 다루려 합니다. (GitHub)

---

실제 사용 방법

README 기준 설치 방법은 매우 단순합니다. 생성된 번들을 각 도구의 설정 디렉터리에 복사하면 됩니다. 예를 들어 Claude Code는 다음처럼 설치합니다. (GitHub)

# 프로젝트 전용
cp -r dist/claude-code/.claude your-project/

# 전역 설치
cp -r dist/claude-code/.claude/* ~/.claude/

Cursor, Gemini CLI, Codex CLI도 비슷한 방식으로 설치합니다. Cursor는 Nightly 채널과 Agent Skills 설정이 필요하고, Gemini CLI는 preview 버전과 Skills 활성화가 필요하다고 README에 적혀 있습니다. (GitHub)

설치 후에는 이런 식으로 사용할 수 있습니다.

/audit
/normalize
/polish
/distill

특정 영역만 대상으로 줄 수도 있습니다.

/audit header
/polish checkout-form

Codex CLI는 문법이 조금 달라 /prompts:audit, /prompts:polish 형태를 쓴다고 README가 설명합니다. (GitHub)

---

이런 식으로 활용하면 좋다

실무에서 가장 자연스러운 사용 흐름은 아마 이런 형태일 겁니다.

1단계: 프로젝트 컨텍스트 세팅

/teach-impeccable

이 단계에서 AI는 코드베이스를 먼저 살피고, 부족한 정보만 물어본 뒤, 디자인 원칙을 프로젝트 문서에 기록합니다. (GitHub)

2단계: 초기 UI 생성

일반적인 프롬프트나 기존 작업 흐름으로 화면을 만듭니다.

사용자 대시보드의 메인 홈 화면을 만들어줘.
최근 활동, KPI, 빠른 액션, 알림을 포함해줘.

3단계: 품질 진단

/audit dashboard-home

이 명령은 접근성, 반응형, 성능, 안티패턴을 점검한 보고서를 만들어 줄 것입니다. (GitHub)

4단계: 목적별 후처리

/normalize dashboard-home
/polish dashboard-home
/quieter dashboard-home

이런 식으로 결과를 좁혀가면 “막연한 재시도”보다 훨씬 통제된 개선이 가능합니다. README의 명령 체계상 이런 워크플로우가 가장 자연스럽습니다. (GitHub)

---

인상적이었던 세부 규칙 몇 가지

Typography 레퍼런스에서 특히 좋았던 포인트 몇 가지를 뽑아보면 이렇습니다. (GitHub)

/* fluid type 예시 */
.hero-title {
  font-size: clamp(2rem, 5vw + 1rem, 4.5rem);
}

/* 데이터 가독성 */
.data-table {
  font-variant-numeric: tabular-nums;
}

/* body text는 최소 16px 이상 권장 */
body {
  font-size: 1rem; /* 16px 기준 */
  line-height: 1.5;
}

이 프로젝트가 좋은 이유는 단순히 “유행하는 스타일”을 말하지 않고, 이렇게 바로 코드에 반영 가능한 힌트를 준다는 데 있습니다. 특히 font-variant-*, fallback metric 보정, ch 기반 measure 같은 것은 초중급 개발자가 놓치기 쉬운 부분입니다. (GitHub)

---

한계도 있다

물론 이 프로젝트가 만능은 아닙니다.

첫째, Impeccable은 어디까지나 LLM을 더 잘 유도하는 스킬셋이지, 실제 디자이너를 완전히 대체하는 시스템은 아닙니다. 좋은 결과를 얻으려면 여전히 제품 맥락, 사용자, 브랜드 방향 같은 입력이 필요하고, 이 점은 /teach-impeccable 설계에서도 드러납니다. (GitHub)

둘째, “AI 슬롭”을 피하자는 철학이 강하다 보니, 팀의 디자인 시스템이 오히려 매우 보수적이고 표준화되어 있어야 하는 프로젝트에서는 일부 규칙이 과할 수도 있습니다. 예를 들어 너무 독특한 폰트 선택이나 대담한 미적 방향은 SaaS 백오피스나 내부 운영 도구와는 긴장이 생길 수 있습니다. 이 부분은 프로젝트 문서의 의도를 바탕으로 한 해석입니다. (GitHub)

셋째, 저장소 루트에 api, public, server, scripts, tests가 있지만, README만으로는 이 배포/데모 사이트 계층의 전부를 이해하기는 어렵습니다. 따라서 저장소는 꽤 체계적이지만, 처음 보는 사람 입장에서는 “스킬 소스”와 “웹사이트/배포 코드”의 관계를 조금 더 문서화해주면 더 좋겠다는 생각이 듭니다. 이 평가는 저장소 구조와 문서 범위를 비교한 관찰입니다. (GitHub)

---

총평

Impeccable은 “AI가 UI를 만든다”는 이야기에서 한 걸음 더 나아가, AI가 어떤 기준으로 UI를 판단하고 다듬어야 하는가를 정리한 프로젝트입니다. 핵심은 예쁜 샘플을 주는 것이 아니라, 디자인 판단 기준과 금지 규칙, 그리고 후처리 명령 체계를 제공한다는 데 있습니다. (GitHub)

특히 인상적인 부분은 다음입니다.

• 단일 스킬에 7개 참조 문서를 붙여 디자인 지식을 구조화한 점
• /audit 같은 진단형 명령으로 리뷰 프로세스를 모델링한 점
• /teach-impeccable로 프로젝트별 디자인 컨텍스트를 지속화한 점
• 여러 AI 코딩 도구로 변환 가능한 빌드 구조를 갖춘 점 (GitHub)

한 문장으로 정리하면 이렇습니다.

Impeccable은 AI에게 “더 예쁘게 만들어”라고 말하는 대신, “좋은 프론트엔드 디자인이 무엇인지, 그리고 흔한 실패가 무엇인지”를 체계적으로 가르치는 프로젝트다.

 

이어서 실무로 적용하는 방법을 알아보자.

Claude Code에서 Impeccable 적용하기: AI가 만드는 UI 품질을 한 단계 올리는 방법