좋은 인터페이스를 만드는 에이전트 스킬 모음

Jakub Krehel의 skills는 좋은 인터페이스를 만들고 검토하는 기준을 8개의 Agent Skill로 나눈 저장소다. 접근성부터 제품 문구까지 다루는 6개 도메인 스킬에, 전체 화면을 종합 검토하는 better-interface와 코드 변경분을 추적하는 interface-review를 더했다.

Claude Code 플러그인으로 한꺼번에 설치하거나 npx skills add jakubkrehel/skills로 원하는 스킬만 고를 수 있다. Claude Code, Codex와 그 밖의 에이전트에서 쓰는 문서 패키지임.

여섯 분야가 각자 규칙을 소유함

저장소는 같은 문제를 여러 스킬이 중복 판단하지 않도록 규칙의 소유권부터 정한다.

better-accessibility — 시맨틱 HTML, 키보드·포커스, 폼, 스크린리더
better-layout — 그룹과 정렬, 간격, 반응형 구조, RTL 레이아웃
better-writing — 용어와 목소리, 버튼, 오류, 빈 상태 문구
better-typography — 글꼴, 위계, 줄바꿈, 구두점, 양방향 텍스트
better-colors — 색상 표기, 팔레트, 색역, 실제 조합의 대비 측정
better-ui — 표면, 아이콘, 모션처럼 상호작용이 성립한 뒤의 시각적 마감

예를 들어 접근성 스킬이 어떤 대비 기준이 필요한지 판단하면, 색상 스킬이 실제 전경색과 배경색 조합을 측정하고 수정한다. 제목의 의미 구조는 접근성이 맡고, 화면에서 크기와 굵기가 어떻게 보이는지는 타이포그래피가 맡음. 경계가 겹칠 때 어느 스킬이 최종 판단하는지를 먼저 고정한 구조다.

종합 리뷰는 체크리스트 여섯 장을 이어 붙이지 않음

better-interface의 첫 문장은 “강한 인터페이스는 여섯 개의 독립된 감사를 한데 묶은 것이 아니다”라는 주장이다. 그래서 리뷰는 취향을 말하기 전에 범위와 검증 방식을 결정한다.

quick은 실제로 도달한 주 경로를 보고 HIGH와 MEDIUM만 최대 5건 보고함
full은 빈 화면·로딩·오류·좁은 화면까지 살피고 LOW를 포함해 최대 15건 보고함
프레임워크, 스타일링 방식, 컴포넌트 라이브러리, 토큰, 지원 뷰포트와 프로젝트 내부 지침을 먼저 확인함
접근성 → 레이아웃 → 문구 → 타이포그래피 → 색상 → UI 순서로 검토함
소스 파일이 있으면 모든 지적에 파일과 줄을 붙이고, 파일이 없는 화면은 정확한 화면·컴포넌트를 지목함. 현재 구현과 바꿀 구현, 사용자에게 생기는 문제도 함께 적음

사용자 영향이 큰 문제는 발생한 범위가 작아 보여도 즉시 HIGH다. 이름 없는 아이콘 버튼, 보이지 않는 키보드 포커스, 포인터로만 가능한 경로, prefers-reduced-motion을 무시하는 모션, 320px 또는 200% 확대에서 잘리는 콘텐츠, 실패한 텍스트 대비, 색만으로 전달하는 상태, 확인·되돌리기·구별되는 표현이 모두 없는 파괴적 동작이 여기에 들어감.

같은 원인에서 나온 문제는 여러 건으로 부풀리지 않고 하나로 묶는다. 반대로 검토했지만 문제로 채택하지 않은 후보도 Considered but Rejected에 남긴다. 근거가 부족하거나 현재 구현이 프로젝트 규칙 안에서 방어 가능한 선택이었다는 사실까지 리뷰 결과에 포함하는 셈이다.

diff가 아니라 바뀐 화면을 따라감

2026년 8월 6일 추가된 interface-review는 커밋되지 않은 변경, 현재 브랜치, 풀 리퀘스트를 대상으로 한다. 핵심 문장은 **“diff는 화면이 아니다”**임. 바뀐 파일은 검토 대상 자체가 아니라 어떤 화면이 영향을 받았는지 찾는 출발점이다.

대상이 명시되지 않으면 기본 브랜치와의 merge base부터 확인한다. 브랜치에 쌓인 커밋이 있으면 그 범위와 커밋되지 않은 작업을 함께 보고, 그다음에야 작업 트리만 본다. 사소한 로컬 수정 한 건 때문에 여러 커밋의 변경이 리뷰 범위에서 사라지는 일을 막기 위한 순서다.

영향 범위도 한 단계 넓힌다.

바뀐 컴포넌트의 직접 소비자를 기본 한 홉 추적함
디자인 토큰·테마·공용 프리미티브는 두 홉까지 확장함
검토 가능한 소비자는 라우트·레이아웃 진입점, 가져다 쓰는 파일 수(importer count), 같은 패키지·기능과의 근접성 순으로 최대 5개까지 고르고, 제외한 수를 밝힘
추가된 줄뿐 아니라 삭제된 줄도 읽음

삭제된 aria-label, <button>, :focus-visible, prefers-reduced-motion, 논리적 CSS 속성, 줄바꿈 설정, 색상 토큰, 사용자 문구는 회귀의 단서가 된다. 다만 삭제 자체를 곧바로 결함으로 부르지는 않는다. 네이티브 요소나 동등한 포커스 링처럼 대체 구현이 있는지 확인하고, 발견 사항을 Introduced, Regression, Pre-existing으로 나눔.

리뷰 중 원래 작업 트리를 바꾸지 않는 것도 원칙이다. 풀 리퀘스트는 ref를 가져와 읽고, 화면 실행이 필요할 때만 별도 worktree를 만든다. checkout, switch, stash로 작성자가 열어둔 파일을 움직이지 않음.

숫자를 박되 적용 조건도 함께 둠

도메인 스킬은 “더 세심하게” 같은 말 대신 구현 가능한 수치를 준다. 동시에 프로젝트의 기존 토큰과 스타일링 체계를 먼저 따르도록 제한함.

중첩된 모서리는 바깥 반지름 = 안쪽 반지름 + 패딩으로 맞춤
모션은 브라우저에서 10% 속도로 재생해 어색한 상태를 찾음
자주 쓰지 않는 등장 애니메이션은 의미 단위로 나눠 약 100ms 간격으로 배치함
버튼을 누를 때는 scale(0.96)을 쓰되, 고빈도 동작에는 커스텀 애니메이션을 넣지 않음
긴 본문 한 줄은 약 60~75자로 제한하고, 모바일 입력 글자는 16px을 유지함
그룹 사이 간격은 그룹 안 간격의 최소 2배로 둠. 점진적으로 가린 콘텐츠에 기존 안내가 없다면 다음 항목을 16~32px 내보이거나 별도 펼침 컨트롤을 둠
터치 표적은 WCAG 2.5.8의 24×24 CSS px 기준이나 간격·동등 컨트롤·인라인·사용자 에이전트·필수성 예외를 따름. 가능하면 터치에서 44×44px을 목표로 함
파괴적 버튼은 OK나 Yes 대신 Delete project처럼 결과를 동사로 명시함

정확한 값이 항상 새 규칙을 강제한다는 뜻은 아니다. 기존 프로젝트가 Hex 토큰을 쓰면 고립된 수정 하나 때문에 OKLCH를 들이지 않고, 이미 정한 밀도나 모션 언어가 있으면 먼저 보존한다. 요구사항과 휴리스틱의 처방 강도를 다르게 두려는 시도다.

아직 검증된 리뷰 엔진은 아님

이 저장소는 SKILL.md와 참고 문서, 플러그인 메타데이터로 구성된 문서 전용 프로젝트다. 자체 빌드·린트·테스트 도구가 없고, 리뷰 전후의 사용성이나 접근성 결함 감소, 여러 실행 사이의 판정 일관성을 비교한 결과도 제시하지 않는다.

GitHub 문서와 소개 페이지 사이에도 차이가 있다. README는 8개 스킬을 안내하지만, 공식 소개 페이지는 2026년 8월 9일 기준 새 interface-review를 제외한 7개 섹션만 보여준다. 설치 가능한 플러그인 버전은 1.1.0이고 별도 GitHub Release는 아직 없다.

crit의 관점

이 모음의 강점은 디자인 취향을 많이 적었다는 데보다 누가 판단하고, 무엇을 근거로, 어디까지 검토할지를 리뷰 계약으로 만든 데 있다. 다만 에이전트가 실제 화면·키보드 경로·대비값을 확인하지 않으면 정교한 문서는 근거 없는 확신을 더 잘 포장할 수도 있다. 같은 변경을 여러 에이전트가 검토했을 때 지적이 얼마나 재현되는지, 각 지적 중 실행 가능한 증거가 붙은 비율이 얼마인지가 다음 검증 기준임.