에이전트가 UI를 못생기게 만드는 이유, 그리고 해결 방법

AI 코딩 에이전트는 이제 웬만한 CRUD 화면은 순식간에 만들어낸다. 문제는 "작동하는 화면"과 "좋아 보이는 화면" 사이에 여전히 큰 간격이 있다는 점이다. 기능은 맞는데 이상하게 촌스럽고, 정렬은 맞는데 제품처럼 보이지 않고, 컴포넌트는 많은데 전체 인상은 산만하다. 왜 그럴까. 이유는 꽤 단순하다. 대부분의 에이전트는 코드를 많이 학습했지만, 좋은 디자인의 취향을 구조화해서 학습하지는 못했기 때문이다.

에이전트는 왜 이렇게 자주 못생긴 UI를 만들까

LLM은 HTML, CSS, React 코드를 엄청나게 많이 봤다. 그래서 버튼을 만들고, 카드 레이아웃을 만들고, 다크모드를 토글하는 일은 잘한다. 하지만 그 능력은 "구현 능력"이지 "심미적 판단 능력"과는 다르다. 보통 에이전트가 만든 UI가 못생겨지는 이유는 아래와 같다.

1. 시각적 취향이 아니라 코드 패턴을 재조합한다

모델은 자주 등장한 구조를 평균적으로 섞어낸다. 그래서 결과물이 안전하고 평범해진다. 더 나쁘게는, 서로 다른 미학이 한 화면에서 충돌한다.

• radius는 둥근데 타이포는 각지고
• 카드 그림자는 무거운데 색상은 미니멀하고
• CTA는 네온인데 나머지는 엔터프라이즈 회색톤이고

이런 식의 불일치는 "못 만든 코드"의 문제가 아니라 "정해진 미학이 없는 상태에서 조합했다"는 신호다.

2. 좋은 UI를 구성하는 단위를 모른다

사람 디자이너는 화면을 볼 때 단순히 버튼, 카드, 인풋만 보지 않는다. 더 상위의 레벨에서 판단한다.

• 이 제품의 visual thesis가 무엇인가
• 이 화면은 얼마나 조밀해야 하는가
• radius는 날카로운가, 부드러운가
• hierarchy는 타이포로 만들 것인가, spacing으로 만들 것인가
• accent color는 어디에만 허용할 것인가

하지만 많은 프롬프트는 에이전트에게 이렇게 말한다. 예쁜 SaaS 대시보드를 만들어줘.!! 이건 너무 추상적이다. "예쁜"이라는 단어는 미학적 기준을 전혀 주지 않는다.

3. 참조 이미지가 있어도 구조화되지 않으면 흉내만 낸다

스크린샷 몇 장을 보여주면 에이전트는 어느 정도 비슷한 분위기를 흉내 낼 수 있다. 하지만 그게 반복 가능하고 확장 가능한 시스템으로 이어지지는 않는다. 결국 첫 화면은 비슷해 보여도 다음 화면부터 무너진다.

• 제목 크기가 흔들리고
• 간격 체계가 사라지고
• 버튼 스타일이 늘어나고
• 라이트/다크 토큰이 뒤섞인다

즉, 참조가 있어도 "규칙"으로 바꾸지 못하면 유지되지 않는다.

그래서 필요한 건 취향의 구조화다

이 지점에서 흥미로운 접근이 나온다. Refero Styles는 좋은 제품 디자인을 그냥 모아두지 않는다. 각 스타일을 에이전트가 이해할 수 있는 규칙 집합으로 추출한다. 

• 한 줄짜리 visual thesis
• theme
• color tokens
• typography scale
• spacing / radius / shadow
• component rules
• Do / Don't

이게 중요한 이유는, 에이전트가 드디어 "분위기"를 직접 학습하는 대신 "규칙화된 취향"을 실행할 수 있게 되기 때문이다. 좋은 디자인을 만드는 데 필요한 것은 더 많은 CSS 트릭이 아니다. 더 명확한 취향과 더 엄격한 제약이다.

스크린샷이 아니라 DESIGN.md를 넘겨야 한다

에이전트에게 디자인 레퍼런스를 줄 때 가장 좋은 포맷은 이미지 묶음이 아니라 DESIGN.md이다. 이 문서에는 최소한 아래와 같은 내용이  있어야 한다.

1. Visual thesis

한 줄로 이 UI의 인상을 규정한다. 이 한 줄이 없으면 나머지 결정이 흔들린다.

• Warm ivory software studio
• Architectural blueprint on white marble
• Deep canvas with fuchsia signal

2. Token system

색, 글자, 간격, 반경, 그림자에 대한 선택지를 제한한다. 핵심은 "많이 주는 것"이 아니라 "적게 허용하는 것"이다. 좋은 디자인 시스템은 자유를 늘리는 문서가 아니라, 나쁜 선택을 줄이는 문서다.

• neutral palette 5~7단계
• accent color 1개
• radius 2종류 내외
• type scale 몇 단계
• spacing scale 고정

3. Component rules

버튼, 카드, 인풋, 테이블이 각자 어떻게 보여야 하는지보다 더 중요한 건, 서로 어떤 family resemblance를 가져야 하는지다. 

• input과 button은 같은 radius family를 쓴다
• card는 shadow보다 border로 정의한다
• primary CTA는 한 화면에 하나만 둔다

이런 규칙이 없으면 컴포넌트는 각각 그럴듯해도 전체는 산만해진다.

4. Do / Don't

개인적으로 이 섹션이 제일 중요하다. 에이전트는 무엇을 해야 하는지보다 무엇을 하지 말아야 하는지를 알 때 훨씬 안정적으로 동작한다.

예를 들면:

• 모든 카드를 shadow로 띄우지 말 것
• 보라색 그라디언트를 습관처럼 넣지 말 것
• accent를 여러 개 경쟁시키지 말 것
• 정보 위계를 전부 font-size로만 해결하지 말 것

이런 금지 규칙이 결과물의 평균을 크게 올린다.

실제 사용 예시

1. 먼저 제품과 비슷한 레퍼런스 스타일을 찾는다.
2. 그 스타일의 핵심을 DESIGN.md로 정리한다.
3. Claude Project나 코딩 에이전트의 작업 컨텍스트에 이 문서를 넣는다.
4. UI 작업을 시작할 때마다 에이전트가 먼저 visual thesis와 token selection을 선언하게 한다.
5. 구현 후에는 self-critique checklist로 스스로 검수하게 한다.

이 흐름의 좋은 점은, 에이전트가 막연히 "예쁜 UI"를 만들려 하지 않고 "정해진 취향을 유지하는 UI"를 만들게 된다는 것이다.

중요한 건 창의성보다 일관성이다

많은 사람이 디자인 문제를 창의성 문제로 생각한다. 하지만 제품 UI에서 더 자주 망가지는 지점은 창의성이 부족해서가 아니라, 일관성이 부족해서다. 에이전트는 원래 평균으로 수렴하는 경향이 있다. 그래서 아무 제약이 없으면 대체로 무난하지만 싱거운 UI를 만든다. 반대로 잘 설계된 제약을 주면 훨씬 좋은 결과를 낸다. 결국 우리가 해야 할 일은 에이전트에게 "더 자유롭게 만들어"라고 말하는 게 아니다. <<이 제품은 이런 인상을 가져야 하고, 이 색과 이 타이포와 이 간격 체계 안에서만 움직일 것!!>> 과 같은 구체적인 실행 명령을 줘야 한다. 해당 명령을 바탕으로 실행된다면 에이전트는 장식 생성기가 아니라, 취향을 실행하는 시스템이 된다.

마무리

AI 에이전트가 못생긴 UI를 만드는 이유는 아직 디자인을 충분히 "본 적이 없어서"가 아니다. 좋은 디자인을 실행 가능한 규칙으로 "정리받지 못해서"다. 좋은 UI는 화려한 영감보다, 좋은 취향의 반복에서 나온다. 에이전트에게도 그 반복 가능한 취향을 넘겨줘야 한다. 더 많은 프롬프트 수식어를 붙이지 말고, 더 많은 스크린샷을 던지기만 하지 말고, 더 명시적인 DESIGN.md를 제공하자~!

Refero Styles — Design Systems for AI Agents

 

아래는 해당 사이트를 바탕으로 작성한 DESIGN.md 초안이다. (참고용!)

DESIGN.md

이 문서는 Claude 프로젝트에서 일관되고 보기 좋은 UI를 만들기 위한 디자인 실행 규칙이다. 목표는 "대충 그럴듯한 UI"가 아니라, 하나의 명확한 시각적 취향을 가진 인터페이스를 만들게 하는 것이다.

이 문서는 Refero Styles의 구조를 참고해 작성했다. 특히 스타일을 단순 참고 이미지가 아니라 다음 형식으로 추출한다는 점을 반영했다.

• 한 줄짜리 visual thesis
• 색상/타이포/간격/반경 같은 design token
• 주요 컴포넌트의 역할과 표현 규칙
• 명시적인 Do / Don't

Core Principle

항상 먼저 "이 UI가 어떤 제품처럼 보여야 하는가?"를 정한다. 화면을 만들기 전에 아래 5가지를 먼저 고정한다.

1. Visual thesis 한 줄
2. Theme: light 또는 dark
3. Accent color 하나
4. Typography hierarchy 하나
5. Surface / border / radius 규칙 하나

한 화면 안에서 여러 미학을 섞지 않는다. 깔끔한 B2B 제품이면 끝까지 절제하고, 에디토리얼/브랜드 중심 제품이면 끝까지 밀도와 개성을 유지한다.

Default Taste

기본값은 "정제된 소프트웨어 인터페이스"다.

• 불필요한 장식보다 정보 구조를 우선한다.
• 강조 색은 1개만 강하게 사용한다.
• 회색 스케일을 충분히 활용해 위계를 만든다.
• 그림자보다는 border, contrast, spacing으로 계층을 만든다.
• 카드, 입력창, 버튼은 같은 shape language를 공유해야 한다.

이 기본값은 shadcn/ui, Cursor, Grafbase, Mercury처럼 "정교하지만 과장되지 않은 제품 UI"에 가깝다.

Design Workflow

새 화면을 설계할 때는 반드시 아래 순서를 따른다.

1. 화면 목적을 한 문장으로 요약한다.
2. 사용자의 가장 중요한 행동을 하나만 정한다.
3. visual thesis를 한 줄로 쓴다.
4. 아래 token system에서 색/타이포/간격/반경을 선택한다.
5. 페이지 전체 레이아웃을 먼저 잡고, 컴포넌트는 나중에 채운다.
6. 마지막에 Do / Don't 체크리스트로 결과를 검수한다.

출력 전에 스스로 확인한다.

• CTA가 한눈에 보이는가
• 정보 위계가 색이 아니라 크기와 간격으로도 드러나는가
• border radius가 섞여서 어색하지 않은가
• 회색, 테두리, 그림자 사용량이 과하지 않은가
• "예쁜 척하는 템플릿"이 아니라 제품 같아 보이는가

Visual Thesis Format

각 UI 작업은 반드시 아래 형식의 내부 메모로 시작한다.

Visual thesis: Warm ivory product studio with precise typography and restrained orange accents.
Theme: light
Personality: calm, exact, premium, technical
Primary action emphasis: high
Density: compact | comfortable

이 메모는 최종 산출물에 그대로 노출하지 않아도 되지만, 설계의 기준점으로 반드시 유지한다.

Token System

토큰은 화면마다 새로 발명하지 말고 아래 체계 안에서 선택한다.

Colors

기본 원칙:

• Neutral scale 5~7단계
• Accent color 1개
• Semantic colors는 success / warning / danger 정도만

권장 light neutral scale:

• --bg: #fcfcf9
• --surface: #ffffff
• --surface-muted: #f3f3ef
• --border: #e4e4de
• --text: #171717
• --text-muted: #6b6b6b
• --text-subtle: #8a8a8a

권장 dark neutral scale:

• --bg: #0d0d0f
• --surface: #151519
• --surface-muted: #1d1d22
• --border: #2a2a31
• --text: #f5f5f3
• --text-muted: #b4b4b0
• --text-subtle: #8d8d92

accent 사용 규칙:

• 기본 accent는 1개만 쓴다.
• CTA, active state, selected state, 핵심 링크에만 사용한다.
• 넓은 면적을 전부 accent로 칠하지 않는다.
• accent가 강하면 나머지 UI는 반드시 더 차분해야 한다.

권장 accent 예시:

• --accent-blue: #4f46e5
• --accent-orange: #f54e00
• --accent-green: #0ea567
• --accent-violet: #8a53e1

Typography

원칙:

• 폰트는 최대 2개까지
• display / heading / body / caption 위계를 명확히
• body는 읽기 우선, display는 캐릭터 우선

권장 폰트 조합:

• Sans: Inter, Geist, Söhne 계열 분위기
• Mono: IBM Plex Mono, Geist Mono

권장 타입 스케일:

• --text-display: 44px / 1.0 / 600
• --text-h1: 32px / 1.1 / 600
• --text-h2: 24px / 1.2 / 600
• --text-h3: 18px / 1.3 / 600
• --text-body: 14px / 1.5 / 400
• --text-small: 12px / 1.45 / 500

세부 규칙:

• 큰 제목은 약간의 negative letter-spacing을 허용한다.
• body text는 지나치게 작게 만들지 않는다.
• 한 화면에서 font-weight를 너무 많이 섞지 않는다.
• 카드 안의 제목과 보조 설명은 크기보다 명도 차이로 분리하는 편이 낫다.

Spacing

간격은 임의값보다 스케일을 따른다.

• 4, 8, 12, 16, 20, 24, 32, 40, 56, 72, 88

원칙:

• 컴포넌트 내부 간격은 작고 일정하게
• 섹션 간 간격은 확실히 크게
• 더 중요한 블록일수록 padding으로 존재감을 만든다

권장 규칙:

• input / button height: 36~44px
• card padding: 16~24px
• section gap: 56~88px
• grid gap: 16~24px

Shape

radius는 제품의 성격을 결정한다. 한 화면에서 2종류 정도만 쓴다.

• 6px: 날카롭고 도구적인 느낌
• 10px: 현대적이고 균형 잡힌 기본값
• 14px: 부드럽고 제품 친화적
• 9999px: pill 버튼, badge

권장 규칙:

• button / input / select는 같은 radius family를 공유한다.
• card radius는 input보다 같거나 조금 크게 한다.
• rounded-full은 정말 의도적인 요소에만 사용한다.

Elevation

shadow는 최소화한다.

• 우선순위는 spacing > border > contrast > shadow
• light UI에서는 1px border 위주
• dark UI에서는 투명도 낮은 outline과 muted surface 차이 위주

권장 shadow:

--shadow-soft: 0 1px 2px rgba(0, 0, 0, 0.06);
--shadow-card: 0 0 0 1px rgba(0, 0, 0, 0.06);
--shadow-dark-card: 0 0 0 1px rgba(255, 255, 255, 0.06);

Layout Rules

레이아웃은 "예쁜 컴포넌트 나열"이 아니라 읽히는 정보 구조여야 한다.

Page Composition

• hero는 메시지, 행동, 증거 순으로 쌓는다.
• dashboard는 제목, 현재 상태, 주요 행동, 상세 데이터 순으로 쌓는다.
• form은 1차 행동과 보조 행동을 멀리 떨어뜨리지 않는다.
• marketing page라도 섹션마다 역할이 명확해야 한다.

Width

• 텍스트 중심 페이지: 640~760px
• 일반 제품 페이지: 960~1200px
• 데이터 밀도 높은 페이지: 1280px까지 허용

Rhythm

• 좁은 카드 여러 개보다, 덩어리감 있는 그룹을 선호한다.
• 구분선이 많아지면 정보 구조가 아니라 피로만 남는다.
• 레이아웃 리듬은 left alignment + consistent spacing으로 만든다.

Component Rules

컴포넌트는 유행하는 모양이 아니라 역할 중심으로 설계한다.

Button

• Primary button은 가장 강한 contrast를 가져야 한다.
• Secondary button은 ghost 또는 outline으로 두되 존재감은 충분해야 한다.
• 한 화면에 primary style이 여러 종류 존재하면 안 된다.
• icon button은 주변 텍스트 버튼과 무게가 맞아야 한다.

Input / Select

• 배경색과 border 대비는 명확해야 한다.
• placeholder는 너무 흐리지 말고, 실제 값과 충분히 구분되게 한다.
• helper text와 error text는 body보다 한 단계 작게 둔다.

Card

• 카드는 "섹션"이지 장식이 아니다.
• 카드가 많다면 색이 아니라 구조와 제목으로 구분한다.
• 카드 안의 padding은 절대 아끼지 않는다.

Table / Data List

• 줄무늬보다 spacing과 alignment를 우선한다.
• 숫자는 탭처럼 정렬되고, 라벨은 짧고 선명해야 한다.
• 보조 정보는 muted text로 처리하되 읽히지 않을 정도로 약하게 만들지 않는다.

Navigation

• 현재 위치는 배경색이나 굵기 변화로 명확히 보여준다.
• 사이드바는 과하게 장식하지 않는다.
• top nav는 정보보다 행동 중심으로 압축한다.

Content Style

좋은 UI는 시각만이 아니라 문장 톤도 정돈되어야 한다.

• 제목은 짧고 단정하게
• 설명은 친절하되 장황하지 않게
• 버튼 라벨은 동사 중심으로
• empty state는 건조한 시스템 문장보다 맥락을 주는 문장으로

예시:

• 나쁨: Submit
• 좋음: Create API Key
• 나쁨: No data
• 좋음: No invoices yet

Do

• 한 화면마다 분명한 visual thesis를 유지한다.
• accent color는 적게 쓰고 정확하게 쓴다.
• hierarchy는 크기, 명도, 간격으로 만든다.
• neutral palette를 충분히 세분화해 정보 밀도를 처리한다.
• radius, border, spacing을 시스템처럼 반복한다.
• 실제 제품처럼 보이게 하되, 템플릿처럼 보이지 않게 만든다.
• 레퍼런스가 필요하면 먼저 비슷한 성격의 실서비스 UI를 찾아 구조를 학습한다.

Don't

• 보라색 그라디언트와 유리효과를 습관처럼 넣지 않는다.
• 모든 카드를 shadow로 띄우지 않는다.
• CTA를 여러 색으로 경쟁시키지 않는다.
• 12가지 radius와 6가지 gray를 제멋대로 섞지 않는다.
• 정보 위계를 전부 font-size 차이로만 해결하지 않는다.
• dribbble 스타일 장식이 제품 usability를 이기게 두지 않는다.
• "AI가 만든 것 같은 UI" 느낌이 나면 무조건 한 단계 더 단순화한다.

Self-Critique Checklist

결과물을 내기 전에 아래를 반드시 점검한다.

1. 이 화면은 한 문장으로 어떤 미학인지 설명 가능한가
2. CTA는 하나로 읽히는가
3. 회색 단계가 충분히 정리되어 있는가
4. 제목, 본문, 보조 정보의 위계가 명확한가
5. radius와 spacing이 반복 가능한 규칙을 갖는가
6. 카드와 섹션이 정말 필요한 만큼만 존재하는가
7. 이 UI는 "멋있어 보이는 데모"가 아니라 "실제 제품"처럼 보이는가

Output Contract For Claude

UI를 설계하거나 구현할 때는 가능하면 아래 형식으로 사고하고 출력한다.

## Design Direction
- Visual thesis: ...
- Theme: light/dark
- Accent: ...
- Density: compact/comfortable

## Tokens
- Background:
- Surface:
- Border:
- Text:
- Accent:
- Radius:
- Shadow:

## UI Decisions
- Why this hierarchy works
- Why this CTA treatment works
- Why this layout matches the product

최종 사용자에게 항상 이 구조를 노출할 필요는 없지만, 내부적으로는 이 수준의 명시성을 유지해야 한다.

Final Instruction

UI를 만들 때 "요소를 추가하는 능력"보다 "취향을 일관되게 유지하는 능력"을 더 중요하게 본다.

좋은 디자인은 화려함이 아니라 선택의 일관성에서 나온다.
애매하면 더 꾸미지 말고, 더 정리한다.