Cursor로 만든 웹사이트 디자인을 고치기 전에 코드부터 고쳤습니다

Claude Design에 들어가기 전, 코드부터 정리한 이유

소개

4개월 전 Cursor로 만든 숙소 홈페이지가 로컬에 있습니다. 아직 배포 전입니다.

디자인이 계속 마음에 걸렸습니다. 딱히 어디가 틀렸다고 말하긴 어려운데, 단순하고 세련되지 않은 느낌이었습니다. 레퍼런스로 MUJI HOTEL 사이트를 정해두고 있었습니다.

원래 계획은 이랬습니다.

레퍼런스 사이트에서 Claude Code로 디자인 시스템을 뽑아 → Claude Design에 업로드 → 디자인 개선

그런데 이 순서를 검토하다가 뒤집는 게 낫다는 결론이 났습니다.

레퍼런스에서 뽑은 디자인 시스템은 남의 집 치수입니다. 내 사이트의 컴포넌트 구조와 어긋나면 나중에 코드로 되돌릴 때 반영이 아니라 재작성이 됩니다. 그래서 내 코드베이스를 먼저 정리하고, 레퍼런스는 그 위에 얹는 참고자료로 쓰기로 했습니다.

결과적으로 이번 1주차는 Claude Design에 들어가기 전 준비 작업이 됐습니다.

진행 방법

사용 도구: Claude 채팅(전략·판단) + Claude Code(실제 코드 작업)

채팅에서 무엇을 할지 결정하고, 그 결정을 프롬프트로 만들어 Claude Code에 넘기는 방식으로 진행했습니다.

1단계 — 코드 감사

디자인을 손대기 전에 현재 상태부터 알아야 했습니다. 코드는 수정하지 말고 조사만 시켰습니다.

이 프로젝트의 스타일링 방식을 조사해줘. 코드는 수정하지 말고
STYLE-AUDIT.md 파일로 정리만 해줘.

1. 어떤 CSS 방식을 쓰는지 (Tailwind / 순수 CSS / CSS 모듈 등)
2. 색상 값이 총 몇 종류이고, 어디에 하드코딩돼 있는지
3. 글꼴 크기와 굵기가 각각 몇 종류인지
4. 여백(margin/padding) 값이 몇 종류인지
5. 반복해서 쓰이는 UI 컴포넌트 목록
6. 페이지 목록과 각 페이지의 섹션 구조

결과가 예상보다 심각했습니다.

그리고 조용한 오작동이 발견됐습니다.

var(--space-lg, 32px)   /* 32px 의도 → 실제 48px 적용 */
var(--space-xl, 48px)   /* 48px 의도 → 실제 80px 적용 */

존재하지 않는 토큰을 참조하거나, 폴백값이 실제 토큰값과 달랐습니다. 화면이 헐렁해 보이던 이유의 일부는 취향 문제가 아니라 버그였습니다. 글꼴 굵기 700도 폰트를 안 불러온 상태라 브라우저가 가짜 볼드로 합성하고 있었습니다.

2단계 — 오작동 수정

여기서 중요한 원칙을 하나 정했습니다. 이번 작업은 화면을 바꾸지 않는다. 코드가 의도대로 작동하게만 만든다.

STYLE-AUDIT.md의 다음 문제만 수정해줘. 다른 건 절대 건드리지 마.
작업 전에 새 git 브랜치를 만들어줘.

원칙: 이번 작업은 화면 모양을 바꾸는 게 목적이 아니다.
코드가 의도대로 작동하게 만드는 게 목적이다.
따라서 폴백 숫자를 실제 적용값에 맞춘다. 반대로 하지 마.

1. 미정의 토큰 교체
   var(--border-color, #e8e4de) → var(--divider)
   var(--color-accent, #b5936a) → var(--accent-wood)
   var(--space-2xl, ...) → var(--space-xl)

2. 폴백값 불일치 수정 (폴백 숫자만 고친다)
   var(--space-lg, 32px) → var(--space-lg, 48px)
   var(--space-xl, 48px) → var(--space-xl, 80px)
   var(--space-sm, 12px) → var(--space-sm, 16px)
   var(--bg-warm-gray, #f5f2ed) → var(--bg-warm-gray, #F5F3F0)

3. 근사색 통합 (전부 전역 토큰 참조로 교체)
   #e8e4de, #eae6e0 → var(--divider)
   #f5f2ed → var(--bg-warm-gray)
   #b5936a → var(--accent-wood)
   #999 → var(--text-secondary)

4. 11개 페이지 전부의 Google Fonts link에 wght 700 추가

완료 후 무엇을 몇 곳 바꿨는지 표로 보고해줘.

구분선 색이 3종, 웜그레이 배경이 2종, 액센트 색이 2종으로 갈라져 있던 걸 하나로 합쳤습니다.

3단계 — 레퍼런스 비교

MUJI HOTEL 사이트와 내 사이트를 나란히 놓고 봤습니다. 결론은 이랬습니다.

무인양품이 세련돼 보이는 건 색이나 글꼴 때문이 아니라 덜어냈기 때문입니다.

여기서 개선 방향 세 가지가 나왔습니다.

1. 사진 키우기 — 집을 파는 사이트인데 사진이 화면의 1/3도 안 됐습니다

2. 줄바꿈·폭 정리 — 오른쪽에 자리가 남는데 글이 일찍 줄바꿈되고 있었습니다

3. 테두리 걷어내기 — 선으로 가두는 대신 여백으로 구분

4단계 — 한 페이지에서 먼저 실험

11개 페이지를 한꺼번에 바꾸지 않고 Reviews 페이지 하나로 시험했습니다.

reviews.html 한 페이지만 실험해보자. 다른 파일은 절대 건드리지 마.

목표: 테두리 상자를 걷어내고 여백으로 구분하기

reviews.html의 <style> 블록에서 아래 요소들의
border(테두리)와 border-radius(둥근 모서리)를 제거해줘.

- .platform-card
- .multilingual-card
- .review-card
- .read-more-box

대신 요소들 사이 간격(gap)을 지금의 2배로 늘려줘.
배경색과 글자는 건드리지 마.

한 번에 안 됐습니다. 테두리는 지웠는데 카드의 흰 배경이 남아 회색 바탕 위에 흰 사각형으로 여전히 상자처럼 보였습니다. 배경까지 지우니 그제야 정리됐습니다.

반대로 4열 평점 영역은 배경을 지우니 너무 뭉쳐 보였습니다. 여기는 세로 구분선을 넣어 해결했습니다.

열과 열 사이에 세로 구분선을 넣어줘.

- 첫 번째 열을 뺀 나머지 열의 왼쪽에 1px 세로선
- 선 색은 var(--divider)
- 선과 글자가 붙지 않게 왼쪽 안쪽 여백을 충분히 줘

모바일(768px 미만)에서는 세로선을 없애줘.
좁은 화면에서는 열이 위아래로 쌓이니까 세로선이 어색해진다.

5단계 — 메인 페이지 적용

검증된 방식을 메인에 적용했습니다. 순서가 중요했습니다. 사진 → 폭 → 테두리 순입니다. 사진 크기가 정해져야 주변 여백이 정해지기 때문입니다.

ALT

집을 위한 흰색과 검정색 웹사이트 디자인

6단계 — 규칙 문서화

같은 작업을 남은 7개 페이지에 반복해야 하는데, 매번 프롬프트를 새로 쓰는 건 비효율적이었습니다. 검증된 규칙을 DESIGN-RULES.md 한 파일로 정리했습니다.

DESIGN-RULES.md를 읽고 배치 1을 진행해줘.

대상: about.html, faq.html, location.html
이 세 파일만 수정한다. 다른 파일은 절대 건드리지 마.

문서의 규칙을 그대로 적용하되,
"6. 절대 건드리지 않을 것"을 반드시 지켜줘.

작업 후 페이지별로 무엇을 바꿨는지 표로 알려줘.

문서 안에는 대원칙 한 줄을 맨 위에 넣었습니다. 작업 중 판단이 애매할 때 돌아올 자리입니다.

선으로 가두지 말고 여백으로 구분한다.

결과와 배운 점

배운 점 1 — 디자인 문제인 줄 알았는데 버그였다

"세련되지 않다"고 느낀 것 중 상당 부분이 취향 문제가 아니었습니다. 의도한 여백이 32px인데 실제로는 48px이 적용되고, 굵기 700이 가짜 볼드로 그려지고, 구분선 색이 세 가지로 갈라져 있었습니다.

감각으로 판단하기 전에 코드가 의도대로 돌아가는지부터 확인해야 합니다. 그리고 이걸 확인하는 데 AI가 아주 유용합니다. 사람이 2,618줄 CSS를 눈으로 훑어서 이런 걸 찾아내긴 어렵습니다.

배운 점 2 — "수정하지 말고 조사만 해줘"

가장 자주 쓴 문장입니다. AI에게 바로 고치라고 하면 어디를 왜 고쳤는지 따라가기 어렵습니다.

조사 → 보고 → 판단 → 수정으로 나누니 통제가 됐습니다. 특히 코드를 잘 모르는 상태에서 이 순서가 중요했습니다. 조사 결과를 보고 내가 판단할 수 있었습니다.

배운 점 3 — 한 페이지 먼저, 그다음 배치로

처음부터 11개 페이지를 한꺼번에 바꿨다면 되돌리기 어려웠을 겁니다. 한 페이지로 시험하고, 방식이 검증된 뒤에 규칙 문서를 만들고, 그다음 3~4개씩 묶어 적용하는 순서가 안전했습니다.

커밋도 작업 단위로 쪼갰습니다. 잘못되면 그 지점으로만 돌아가면 됩니다.

시행착오

AI 진단이 틀린 적이 두 번 있었습니다.

한 번은 제가 캡처 이미지의 여백을 콘텐츠 여백으로 착각해 "레이아웃이 왼쪽으로 쏠렸다"고 판단했습니다. Claude Code가 브라우저에서 실측해보니 좌우가 정확히 대칭이었습니다. 다행히 "고치기 전에 원인부터 찾아줘"라고 지시해둔 덕에 멀쩡한 코드를 건드리지 않았습니다.

또 한 번은 코드 구조만 보고 "홈 섹션을 8개에서 4~5개로 줄여야 한다"고 판단했습니다. 실제 화면을 캡처해서 보니 문제는 섹션 수가 아니라 사진 크기였습니다. 화면을 안 보고 코드만 보면 틀립니다.

지시하지 않은 파일이 수정된 적도 있었습니다. 스타일 작업인데 구조화 데이터 파일(schema.js)의 문구가 바뀌어 있었습니다. 커밋 전에 git status로 확인하지 않았다면 그냥 들어갔을 겁니다.

이미지 47장(196MB)을 커밋할 뻔했습니다. git에 한 번 들어가면 나중에 최적화해도 히스토리 용량은 안 줄어듭니다. 스타일 파일만 골라 담아 넘겼습니다.

도움이 필요한 부분

Claude Design을 아직 안 써봤습니다. 코드베이스를 연결해 디자인 시스템을 자동 생성하는 기능을 다음 주에 시도할 예정인데, 실제로 어느 정도 정확한지 궁금합니다. 써보신 분 경험이 있으면 듣고 싶습니다.

앞으로의 계획

여기까지 마친 뒤 배포할 계획입니다.

도움 받은 글

• Introducing Claude Design by Anthropic Labs — 코드베이스 기반 디자인 시스템 자동 생성, 웹 캡처, Claude Code 핸드오프 기능 확인

• MUJI HOTEL — 레퍼런스 사이트