# im-designer — 디자인 언어 번역기 (Design Language Translator)
> 디자인 경험이 없는 사용자의 모호한 표현("예쁘게", "깔끔하게", "애플처럼", "이 색 말고 다른 색")을 디자이너·개발자·AI 디자인 도구가 **바로 실행할 수 있는 UI/UX 언어**로 번역하는 [Claude Code](https://docs.claude.com/en/docs/claude-code) 스킬.
>
> Translate a non-designer's vague design language into executable UI/UX requests that designers, developers, and AI design tools can act on immediately.
> **참고 (v1.2.0):** 내부 지시문(`SKILL.md`, `references/`)은 **토큰 효율을 위해 영어**로 작성됩니다. **출력은 기본적으로 한국어**(사용자 언어)로 생성됩니다 — 영문은 효율만 위함이며 산출물은 한국어입니다. 영문화로 토큰 소모가 약 절반 감소했습니다.
---
## 왜 필요한가
사용자는 보통 이렇게 말합니다.
- "좀 더 예쁘게 해주세요."
- "깔끔하게 만들어줘."
- "애플처럼 대시보드 만들어줘."
- "채팅 목록에서 활성화된 채팅 색이 바뀌었으면 좋겠어."
이걸 그대로 디자이너나 개발자, AI 도구에 전달하면 **해석이 갈리고 실행이 불가능**합니다. "예쁘게"가 무스 코드인지 아무도 모르니까요.
`im-designer`는 이런 **감각어·직관어를 분해**해서 — 사용자 문제, 관찰 가능한 근거, 대상 컴포넌트, 상태값, 수정 속성, 적용 범위, 접근성 고려가 포함된 **실행 가능한 요청문**으로 바꿉니다.
> **핵심 전환:** "좀 더 예쁘게 해주세요." → "첫 화면에서 핵심 CTA가 묻혀 다음 행동을 파악하기 어렵습니다. CTA 시각적 위계를 높이고 주변 정보량을 줄여 가입 버튼을 먼저 인식하도록 조정해 주세요."
그리고 **비전문가는 텍스트 스펙만으로는 판단하지 못한다**는 점을 전제로, 옵션을 **실제 HTML로 렌더링**해 "눈으로 고르게" 하는 시각화 모드를 제공합니다.
---
## 핵심 기능
1. **감각어 번역** — "예쁘게/깔끔하게/고급스럽게/세련되게/눈에 띄게/부드럽게/덜 복잡하게"를 구체적 디자인 속성(위계·여백·타이포·대비·정보 밀도…)으로 풀어냅니다.
2. **5가지 출력 모드** — 같은 요청을 목적에 맞게: 디자이너용 문장 / AI 디자인 도구용 명령문 / Figma·Penpot 코멘트 / 개발자 구현 힌트 / **체감용 시각화(HTML)**.
3. **모호성 → 시각화·인터뷰로 범위 좁히기** — 요청이 여러 의미로 해석되면 각 해석을 HTML로 나란히 그려 **눈으로 고르게**(option-compare). 요청이 하나의 덩어리("이거 예쁘게")로 해석이 안 갈리면, 한 번에 한 질문, 작은 결정부터 큰 결정 순으로 **구조화 인터뷰**. 렌더 옵션은 **클릭 칩**(✓이 방향 / ✗스킵 / ⊕부분만)으로 반응을 모아 타이핑 없이 최종 요청을 조립합니다.
4. **색 = 토큰 우선(강제)** — 모든 색을 `Primary`/`Secondary`/`Surface` 토큰에서만 선택. 임의 hex 금지. 통일성 최우선.
5. **접근성 기본** — 색상만으로 상태를 구분하지 않고, focus ring을 유지하며, error 메시지는 구체적으로.
6. **블라인드스팟 패스** — 사용자가 **말하지 않은 결정**(다크모드, 빈/에러/로딩/빈데이터 상태, 반응형, 키보드 접근성, 권한, 엣지 데이터)을 능동으로 끌어내, 번역이 조용히 기본값을 상속하지 않게 합니다. 화면 타입×카테고리 매트릭스로 위험도 순위화.
7. **레퍼런스 gotcha** — "토스처럼/애플처럼/노션처럼" 요청 시, 그 브랜드의 시그니처가 **왜 존재하는지(비즈니스 맥락)**와 **다른 제품이 맥락 없이 베끼면 어떻게 잘못되는지**를 경고. 토큰은 빌려도 맥락까지 베끼지 않도록.
---
## 설치
```bash
# 1) 클론
git clone https://github.com/insightflo/im-designer.git ~/Projects/skills/im-designer
# 2) Claude Code 글로벌 스킬 디렉토리에 심볼릭 링크
ln -s ~/Projects/skills/im-designer ~/.claude/skills/im-designer
```
설치 후 새 세션을 시작하면 즉시 사용할 수 있습니다. 원본은 한 곳(`~/Projects/skills/im-designer`)만 편집하면 전역에 반영됩니다.
---
## 사용법
**특별한 명령 없이, 평소처럼 디자인에 대해 말하면 자동 발동합니다.**
```
사용자: 채팅 목록에서 활성화된 채팅은 색상이 변했으면 좋겠어.
사용자: 애플처럼 깔끔한 대시보드 만들어줘.
사용자: 버튼이 좀 더 눌러보고 싶게 보였으면 좋겠어.
사용자: 랜딩페이지 첫 화면이 밋밋하고 뭘 눌러야 할지 모르겠어. 좀 세련되게.
```
### 출력 옵션
- **기본**: 18항목 표준 형식(요청 유형 → 의도 → 대상 → 문제 → 근거 → … → 최종 문장 4종)으로 구조화
- **"짧게 / 코멘트만 / 바로 보낼 문장만"**: 축약 출력
- **"보여줘 / 체감 / 옵션 비교 / 어떻게 달라지는지"**: 시각화 모드(모드 5) — 옵션이나 결과를 HTML로 렌더링
### 시각화 모드 예시
"활성화된 채팅 색 변경" 요청은 3가지로 해석될 수 있습니다. 시각화 모드는 각각을 실제 모습으로 그려 나란히 보여줍니다:
| 옵션 | 방식 | 특징 |
|------|------|------|
| **A (추천)** | 배경 틴트 + 왼쪽 막대 + 굵게 | 색상 외 단서 2개, 가장 명확 |
| B | 배경 틴트만 | 단순하지만 색상에만 의존 |
| C | 왼쪽 강조 막대만 | 절제된 느낌, 색상 외 단서 1개 |
사용자가 눈으로 고르면 그것이 곧 명확한 요청이 됩니다.
---
## 출력 예시 (Before → After)
**❌ 나쁜 요청:** "좀 더 예쁘게 해주세요."
**✅ 번역된 요청:**
> 첫 화면에서 핵심 CTA가 묻혀 사용자가 다음 행동을 빠르게 파악하기 어렵습니다. CTA의 시각적 위계를 높이고, 주변 정보량을 줄여 사용자가 가입 버튼을 먼저 인식하도록 조정해 주세요.
**❌ 나쁜 요청:** "채팅 목록에서 활성화된 채팅 색 바꿔주세요."
**✅ 번역된 요청:**
> ChatListItem의 `selected` 상태가 더 명확히 보이도록 선택된 row 전체의 background-color(`color.primary` 10% tint)를 변경해 주세요. 텍스트 색상은 유지하고, `hover`보다 `selected`가 더 강하게 구분되도록 조정해 주세요. 색상만으로 구분되지 않도록 왼쪽 accent bar 또는 font-weight 차이도 함께 적용해 주세요.
---
## 원칙 (Do / Don't)
**하는 것:**
- 사용자 원문을 보존하고, 가능한 의미를 분해한 뒤 가장 실무적인 방향을 제안
- 색은 항상 토큰(`Primary`/`Secondary`/`Surface`) 기반, 강도는 tint로 파생
- 상태(`selected`/`hover`/`disabled`/`error`…)를 명확히 구분
- 접근성을 기본 점검(색상 외 단서, focus ring 유지, 대비, 라벨)
- 비전문가에게는 텍스트 스펙과 함께 시각화(HTML) 제공
**하지 않는 것:**
- "예쁘게 해주세요" 같은 감상어를 최종 요청문에 그대로 넣기
- 브랜드를 그대로 복제하라고 지시 ("애플처럼" → 애플 화면 복사 X, 디자인 언어로 변환 O)
- 임의 색상코드를 확정값처럼 제안
- 색상만으로 상태를 구분 / focus ring 제거 제안
- 모든 문제를 "색상 변경"으로 해결
---
## 디자인 토큰(기본값)
브랜드 토큰이 없을 때의 출발점. `--c-primary` 하나를 바꾸면 tint·버튼·뱃지가 모두 따라 바뀝니다.
| 토큰 | 예시 값 | 쓰임 |
|------|--------|------|
| `color.primary` | `#2563eb` | 주 액션·포인트·강조(= accent 토큰) |
| `color.primary.tint` | Primary @10% | selected/active 배경 |
| `color.secondary` | `#64748b` | 보조 액션 |
| `surface.app` | `#f4f6f9` | 화면 배경 |
| `surface.base` | `#ffffff` | 카드·기본면 |
| `surface.raised` | `#ffffff` + 그림자 | 떠 있는 카드·모달·패널 |
| `text.primary` | `#1d1d1f` | 본문 |
| `text.secondary` | `#4b5563` | 캡션·보조 텍스트 |
| `text.subtle` | `#6e6e73` | 흐린 설명·플레이스홀더 |
| `border.subtle` | `#e5e7eb` | 구분선 |
---
## 구조
```
im-designer/
├── SKILL.md # 모델용 지시문 (결정 핵심 로직 + 18항목 출력 형식)
├── README.md # 이 파일 (사람용)
├── references/
│ ├── classification-and-output.md # A~E 요청 유형별 구조 + 5 출력 모드 요령
│ ├── dictionaries.md # 감각어 사전 + 컴포넌트/상태/속성 어휘
│ ├── rules.md # 레퍼런스 해석 + 색상(토큰 우선) + 우선순위 + 접근성
│ ├── visualization.md # 모드 5 시각화: 원칙 + 재사용 HTML 골격
│ └── examples.md # 완성 예시 3종 + bad/good 쌍
└── evals/
└── evals.json # 평가 케이스 4종
```
**Progressive disclosure**: SKILL.md(222줄)에는 결정에 필요한 핵심만, 무거운 디테일은 `references/`에 분리 — 단순 요청은 SKILL.md만으로 처리하고, 필요할 때만 해당 reference를 읽습니다.
---
## 요청 유형 (5가지)
| 유형 | 예 |
|------|-----|
| **A. UX 피드백** | "전체적으로 복잡해", "첫 화면에서 뭘 해야 할지 모르겠어" |
| **B. 컴포넌트 수정** | "활성화된 채팅 색 바꿔줘", "버튼이 눌러보고 싶게 보여야 해" |
| **C. 시각 스타일 번역** | "깔끔하게", "고급스럽게", "세련되게", "부드럽게" |
| **D. 레퍼런스 해석** | "애플처럼", "토스처럼", "노션처럼", "stripe 느낌으로" |
| **E. 접근성/사용성 보정** | "잘 안 보여", "선택된 건지 모르겠어", "비활성화된 건지 헷갈려" |
---
## 라이선스
MIT — 자유롭게 사용·수정·배포하세요.
---
## 기여
이 스킬은 "비전문가도 디자인을 정확히 소통할 수 있게" 만드는 게 목표입니다. 새로운 감각어 사전 항목, 레퍼런스 해석 예시, 시각화 패턴 제안 모두 환영합니다. PR이나 이슈로 남겨주세요.