# UI Audit Method

> UI 코드베이스를 인상이 아니라 숫자로 감사하는 방법. 지표를 세는 grep의 함정, 실제 렌더로 검증하는 절차, 배율 때문에 없는 버그가 보이는 스크린샷 함정, 그리고 판정을 기록해 같은 논의가 반복되지 않게 하는 베이스라인 구조를 다룬다. "UI 감사", "디자인 점검", "이 UI 측정해줘", UI audit, design audit, 레이아웃이 깨져 보인다는 요청에 사용. 무엇을 좋은 디자인으로 볼지는 정하지 않는다 — 그건 프로젝트 베이스라인이 정한다.

- Skill: `rhino-ty/ui-audit-method-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rhino-ty/ui-audit-method-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rhino-ty/ui-audit-method-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: rhino-ty (https://skillmd.com/u/rhino-ty)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rhino-ty/ui-audit-method-2

---


# UI 감사 방법론

이 스킬은 **무엇이 좋은 UI인지 말하지 않는다.** 어떻게 재고, 어떻게 검증하고,
어떻게 기록하는지만 다룬다. 무엇을 문제로 볼지는 프로젝트가 정한다.

원칙은 하나다 — **인상으로 말하지 마라.** "좀 AI 같네요"는 보고가 아니다.
`rounded-xl 25회`가 보고다.

## 두 가지 실패 모드

작업 전에 이것부터 읽어라.

1. **없는 문제를 만들어낸다.** 깨끗한 항목까지 지적해서 고칠 것을 지어낸다.
   어떤 지표가 0이면 그건 빈칸이 아니라 **지켜야 할 상태**다
2. **이미 내린 판정을 잊는다.** 지난번에 "확인함, 문제 아님"으로 끝낸 항목이
   다음 감사에 또 올라온다. 그래서 판정을 파일에 적는다

## 베이스라인이 먼저다

이 스킬 혼자서는 절반만 동작한다. 무엇이 정상인지 모르는 채로 숫자만 뽑게 된다.

```
<프로젝트>/.claude/ui-baseline.md
```

없으면 `../../references/BASELINE-TEMPLATE.md`를 복사해서 채운다. 담기는 것은 넷이다.

- **이 앱의 정체** — 웹인가 데스크탑인가, 뷰포트가 고정인가, 테마가 몇 개인가
- **건드리면 안 되는 것** — 팔레트, 프레임워크 관례, 프로젝트 규칙이 정한 것
- **지표 목록** — 이 프로젝트가 무엇을 세기로 했는지, 그리고 감사 시점 → 현재 값.
  **"현재" 열이 회귀 감지선이다**
- **판정 기록** — "확인했고 문제 아님"으로 끝낸 항목, 근거, 재점화 조건

지표를 고르는 건 프로젝트의 몫이다. 이 스킬은 고르는 법이 아니라 **세는 법**을 준다.

## 1. 대상 파일 확인

명령이 무엇을 훑는지부터 정한다. 프레임워크마다 UI가 사는 확장자가 다르다.

```bash
for e in svelte vue jsx tsx astro html css scss; do
  n=$(git ls-files "*.$e" | wc -l); [ "$n" -gt 0 ] && echo "  .$e $n개"
done
```

아래 예시는 `*.svelte`다. 결과에 맞춰 `--include`를 바꿔 쓴다.

## 2. 세는 법 — 그리고 세 가지 함정

지표가 무엇이든 아래 함정은 똑같이 걸린다. **실제로 오측정이 나온 사례들이다.**

### 함정 1 — 부분집합만 세고 전체라고 믿는다

크기·형태로 필터를 걸면 같은 문제의 다른 형태를 통째로 놓친다.

```bash
grep -rn "text-[45]xl" src --include=*.svelte    # 큰 것만 → 9건
# 전수 조사 → 85건. 버튼 레이블과 상태 표시에 박힌 것이 전부 빠져 있었다
```

**정량 지표를 만들 때는 먼저 필터 없이 전수를 세고, 그다음에 분류하라.**

### 함정 2 — 정규식이 템플릿 문법을 먹는다

```bash
grep -rn "#[0-9a-fA-F]\{3,8\}"    src --include=*.svelte   # 14건 (오탐)
grep -rn "#[0-9a-fA-F]\{3,8\}\b"  src --include=*.svelte   # 2건 (실제)
```

`\b`가 없으면 Svelte의 `{#each}`가 `#eac`로 걸린다. Vue의 `#default`,
JSX의 `#region` 주석도 같은 방식으로 샌다. **경계를 명시하라.**

### 함정 3 — 정상인 것까지 긁는다

```bash
grep -rn "\[[0-9]*px\]"       src --include=*.svelte   # 11건 — 레이아웃 치수 포함
grep -rn "text-\[[0-9]*px\]"  src --include=*.svelte   # 7건 — 폰트만
```

`w-[260px]` 같은 치수는 고정 크기 앱에서 정상이다. **무엇이 정상인지 모르면
지표가 아니라 소음을 센다.** 그래서 베이스라인이 먼저다.

### 옵션 접미사를 놓치지 않기

```bash
grep -rho  "rounded-[a-z0-9]*"      src --include=*.svelte | sort -u   # 4종
grep -rhoE "rounded(-[a-z0-9]+)?"   src --include=*.svelte | sort -u   # 5종
```

접미사 없는 형태(`rounded`, `border`, `shadow`)를 잡으려면 `-E`와 `?`가 필요하다.

### 투명도·수식어 변형을 합산하지 않기

```bash
grep -rhoE "bg-accent/?[0-9]*" src --include=*.svelte | grep -c '^bg-accent$'
```

`bg-accent/80` 같은 변형까지 세면 21이 39가 된다. 호버 전용 클래스도 마찬가지다 —
평상시 화면에 안 보이는 것을 노출량에 넣으면 과다로 오판한다.

## 3. 렌더로 검증 (레이아웃·색이 걸릴 때만)

클래스 이름만 세는 감사면 건너뛴다. 레이아웃이 의심되거나 색이 실제로
적용되는지 확인해야 하면 `../../references/RENDER-VERIFICATION.md`를 따른다.

거기 든 핵심 하나만 먼저 말하면 — **스크린샷을 근거로 레이아웃 버그를
주장하지 마라.** OS 배율이 100%가 아닌 화면에서 창 크기대로 캡처하면 오른쪽이
잘려서 없는 오버플로가 보인다. 실제로 그렇게 오보한 사례가 있다.

> **스크린샷과 측정값이 어긋나면 측정값을 믿어라.**
> 같은 코드가 브라우저에서 멀쩡한데 앱에서만 깨져 보이면 관측을 의심한다.

## 4. 보고

파일:줄 번호와 **고칠 코드**까지 낸다. "개선하세요" 같은 말은 쓰지 마라.

```
src/components/Card.tsx:63    transition-all
  → 색만 바뀌는 자리다. transition-colors
```

베이스라인의 "현재" 열과 대조해서 **나아졌는지 나빠졌는지**를 말한다.
절대값만 나열하면 판단할 근거가 없다.

## 5. 수정

**승인 없이 고치지 마라.** 사용자가 "고쳐"라고 하면 그때 편집한다.

한 커밋에 한 종류만. 반경 통일이면 반경만, 전환이면 전환만. 섞으면
되돌리기가 불가능해진다.

일괄 치환이 위험한 경우를 항상 확인하라 — 같은 클래스가 다른 이유로 쓰이는
자리가 있다. 예를 들어 `transition-all` 12건 중 5건이 진행바였고, 거기에
`transition-colors`를 걸었으면 애니메이션이 사라졌을 것이다.

수정 후 그 프로젝트의 타입 검사·빌드를 돌리고, **베이스라인의 "현재" 열을
갱신한다.** 그게 다음 감사의 기준선이다.

## 6. 판정을 기록한다

"확인했고 문제 아님"으로 끝낸 항목은 **근거와 재점화 조건까지** 베이스라인에
적는다. 안 적으면 다음 감사에 똑같이 올라온다.

```markdown
| 액센트 사용 | 77회 | 문제 없음 | 불투명 bg-accent가 21회 초과 시 |
```

근거는 숫자로 쓴다. "괜찮아 보임"이 아니라 "77회 중 27회가 호버 전용이라
평상시 노출은 50회".

## 이슈가 없으면

짧게 끝내라. 실패 모드 1번을 기억할 것.