스크린샷과 디자인으로 프론트엔드 개선하기

말로 설명하기 어려운 UI 문제는 화면으로 보여주면 된다

프론트엔드 작업을 하다 보면 이상하게 설명하기 어려운 순간이 옵니다. 버튼 색이 나쁜 것은 아닌데 어딘가 약해 보이고, 카드 간격은 맞춘 것 같은데 화면이 답답하며, 모바일에서는 메뉴가 버튼을 살짝 가립니다. 코드는 분명 동작하지만 사용자가 보는 화면은 아직 제품처럼 느껴지지 않습니다.

예전에는 이런 문제를 해결하려면 디자이너가 주석을 달고, 개발자가 다시 CSS를 고치고, 브라우저에서 확인한 뒤, 또 캡처해서 공유해야 했습니다. 하지만 Codex를 쓰면 이 반복이 훨씬 짧아집니다. 이제 Codex에게 코드만 보여주는 것이 아니라, 스크린샷, 손그림, 레퍼런스 이미지, 실행 중인 앱 화면까지 함께 보여줄 수 있기 때문입니다.

OpenAI의 Codex 프론트엔드 활용 사례에서도 스크린샷, 짧은 디자인 브리프, 레퍼런스를 함께 제공하면 Codex가 기존 프로젝트의 패턴을 유지하면서 반응형 UI를 구현할 수 있다고 설명합니다.¹ 핵심은 단순합니다. Codex에게 "이렇게 생긴 화면을 원한다"는 시각적 기준과 "우리 프로젝트에서는 이런 컴포넌트와 규칙을 써야 한다"는 코드 기준을 동시에 주는 것입니다.

이 장에서는 Codex를 프론트엔드 디자이너처럼 쓰는 법을 배웁니다. 정확히 말하면, Codex에게 디자인 감각을 전부 맡기는 것이 아니라 화면을 함께 보며 고치는 파트너로 활용하는 방법입니다. 초보자에게 특히 좋은 이유는, CSS 용어를 몰라도 "여기 여백이 이상해요", "이 버튼이 잘 안 보여요", "모바일에서 이 카드가 너무 좁아요"처럼 눈에 보이는 문제를 그대로 전달할 수 있기 때문입니다.

첫 결과물은 초안일 뿐이다

Codex에게 "랜딩 페이지를 예쁘게 만들어줘"라고 요청하면 꽤 그럴듯한 화면이 나올 수 있습니다. 하지만 첫 결과물이 바로 최종 UI가 되는 경우는 드뭅니다. AI가 만든 초안은 기능적으로는 맞아도 시각적으로는 아쉬운 부분이 남기 쉽습니다. 카드 간격이 조금씩 다르거나, 제목과 본문 사이의 위계가 약하거나, 데스크톱에서는 괜찮은데 모바일에서 레이아웃이 무너질 수 있습니다.

여기서 중요한 태도는 "Codex가 디자인을 못한다"가 아니라 "Codex도 화면을 보고 반복해야 잘한다"입니다. 사람 개발자도 처음 작성한 CSS가 완벽하지 않습니다. 브라우저를 열고, 크기를 줄이고, 실제 데이터를 넣어 보고, 이상한 부분을 고칩니다. Codex도 마찬가지입니다. 이미지를 입력으로 받고, 로컬 앱을 실행해 화면을 확인하고, 다시 스크린샷을 비교하게 하면 결과가 크게 좋아집니다.

프론트엔드 작업의 완료 기준은 코드가 생성되었는지가 아니라 사용자가 보는 화면이 의도와 맞는지입니다. 따라서 이 장에서 사용할 기본 루프는 다음과 같습니다.

1. 기준이 되는 이미지나 스크린샷을 준비한다.

2. Codex에게 기존 코드베이스의 컴포넌트, 색상, 간격 규칙을 유지하라고 지시한다.

3. 로컬 앱을 실행하고 artifact preview나 내장 브라우저에서 실제 화면을 확인한다.

4. 스크린샷, 영역 지목, 주석으로 문제를 구체적으로 알려 준다.

5. 수정 후 데스크톱, 태블릿, 모바일 화면에서 다시 검증한다.

이 루프를 익히면 "디자인을 어떻게 말로 설명하지?"라는 부담이 줄어듭니다. 화면을 보여주고, 눈에 보이는 기준으로 고치면 됩니다.

준비물: 이미지 하나보다 맥락 묶음이 더 강하다

Codex에게 이미지를 하나만 던지고 "이렇게 만들어줘"라고 말할 수도 있습니다. 하지만 좋은 결과를 원한다면 이미지와 함께 짧은 설명을 붙여야 합니다. 이미지는 시각적 기준을 주고, 설명은 구현 방향과 제약 조건을 알려 줍니다.

가장 좋은 입력 묶음은 보통 다음 네 가지로 구성됩니다.

• 현재 앱 스크린샷: 지금 무엇이 문제인지 보여 주는 이미지

• 목표 레퍼런스: 어떤 느낌이나 구조로 개선하고 싶은지 보여 주는 이미지

• 짧은 디자인 브리프: 사용 목적, 주요 사용자, 강조해야 할 요소를 설명한 문장

• 구현 제약: 기존 컴포넌트, 색상 토큰, Tailwind 설정, 라우트, 접근성 기준 같은 프로젝트 규칙

예를 들어 지난 장들에서 만든 미니 SaaS 앱의 대시보드를 개선한다고 해 봅시다. 현재 화면은 기능은 있지만 카드가 밋밋하고, CTA 버튼이 눈에 띄지 않으며, 모바일에서 프로젝트 목록이 너무 좁게 보입니다. 이때 Codex에게 이렇게 요청할 수 있습니다.

첨부한 current-dashboard.png는 현재 화면이고, reference-dashboard.png는 원하는 밀도와 카드 스타일의 참고 이미지입니다.

목표:
미니 SaaS 대시보드 첫 화면을 더 명확하고 사용하기 쉽게 개선해 주세요.

제약:
- 기존 React 컴포넌트 구조와 라우팅은 유지하세요.
- src/components/ui 안의 Button, Card, Badge 컴포넌트를 우선 사용하세요.
- tailwind.config.ts에 정의된 색상과 간격 토큰을 벗어나지 마세요.
- 새로운 UI 라이브러리는 추가하지 마세요.
- 데스크톱에서는 3열 카드, 태블릿에서는 2열, 모바일에서는 1열로 전환하세요.

완료 기준:
- 카드 간격은 데스크톱 기준 24px로 통일합니다.
- 주요 CTA 버튼은 배경과 대비가 충분해야 합니다.
- 모바일 375px 폭에서 가로 스크롤이 없어야 합니다.
- npm run build가 성공해야 합니다.

이 프롬프트의 핵심은 "레퍼런스처럼 만들어줘"에서 멈추지 않는다는 점입니다. 현재 코드베이스를 존중하라고 했고, 어떤 컴포넌트를 써야 하는지 알려 주었고, 반응형 기준과 완료 조건도 제시했습니다. 이렇게 해야 Codex가 예쁜 새 세계를 따로 만드는 것이 아니라, 기존 앱 안에서 자연스럽게 개선합니다.

CLI에서 이미지 입력 사용하기

Codex CLI를 쓰고 있다면 이미지 파일을 명시적으로 첨부하는 방식이 가장 안정적입니다. 공식 CLI 문서에서도 스크린샷이나 디자인 스펙을 프롬프트와 함께 첨부해 Codex가 읽도록 할 수 있다고 설명합니다.² 터미널에서는 보통 --image 또는 짧게 -i 옵션을 사용합니다.

codex -i ./screens/current-dashboard.png \
  "이 화면의 레이아웃 문제를 찾아 주세요. 특히 카드 간격, CTA 버튼 대비, 모바일 반응형 관점에서 개선안을 제안해 주세요."

현재 화면과 목표 화면을 비교하고 싶다면 이미지를 여러 장 붙입니다.

codex -i ./screens/current-dashboard.png -i ./screens/reference-dashboard.png \
  "첫 번째 이미지는 현재 구현, 두 번째 이미지는 목표 레퍼런스입니다. 기존 컴포넌트와 Tailwind 토큰을 유지하면서 차이를 줄이도록 수정해 주세요."

초보자가 자주 하는 실수는 이미지 파일 경로만 문장 안에 적고 Codex가 알아서 열어 보기를 기대하는 것입니다. 환경에 따라 가능할 때도 있지만, 안정적인 방법은 명시적으로 첨부하는 것입니다. 특히 UI 비교처럼 이미지 자체가 중요한 작업에서는 -i 옵션을 습관처럼 쓰는 편이 좋습니다.

이미지를 첨부한 뒤에는 바로 코드를 수정하라고 하기보다, 먼저 관찰 결과를 말하게 하는 것도 좋습니다.

codex -i ./screens/current.png -i ./screens/target.png \
  "두 화면을 비교해서 레이아웃, 간격, 타이포그래피, 색상 대비, 반응형 관점의 차이를 목록으로 정리하세요. 아직 코드는 수정하지 마세요."

이렇게 한 번 멈추면 Codex가 무엇을 보고 있는지 확인할 수 있습니다. 관찰이 맞으면 그다음에 "좋습니다. 위 차이 중 1번부터 4번까지 수정하세요"라고 진행하면 됩니다. 관찰이 틀렸다면 바로 고쳐 줄 수 있습니다. UI 작업에서는 이 작은 확인 단계가 시간을 많이 줄여 줍니다.

App의 내장 브라우저로 화면에 직접 주석 달기

Codex App을 사용한다면 내장 브라우저가 매우 유용합니다. 내장 브라우저는 스레드 안에서 나와 Codex가 같은 렌더링 화면을 보도록 해 주며, 웹 앱을 만들거나 디버깅할 때 페이지를 미리 보고 시각적 코멘트를 붙일 수 있습니다.³

이 기능은 프론트엔드 작업에서 특히 강력합니다. 터미널에서는 "두 번째 카드 오른쪽 여백이 이상하다"라고 설명해야 하지만, 내장 브라우저에서는 그 카드 영역을 직접 선택하고 주석을 남길 수 있습니다. 말로 설명하기 어려운 UI 문제가 위치 정보와 함께 Codex에게 전달되는 셈입니다.

흐름은 어렵지 않습니다. 먼저 로컬 개발 서버를 실행합니다.

npm run dev

그다음 Codex App의 내장 브라우저에서 http://localhost:3000/dashboard 같은 로컬 URL을 엽니다. 화면을 보면서 문제가 있는 영역에 주석을 답니다. 예를 들어 이런 코멘트가 가능합니다.

이 카드의 오른쪽 여백이 왼쪽보다 좁아 보입니다. 카드 내부 padding을 좌우 동일하게 맞추고, 숫자 영역은 오른쪽 정렬을 유지해 주세요.

모바일 화면에서 햄버거 메뉴가 CTA 버튼을 가립니다. 메뉴가 열릴 때 버튼 아래로 밀리거나, 메뉴 레이어가 전체 너비를 차지하도록 수정해 주세요.

이 제목은 두 줄로 줄바꿈되면서 의미가 끊깁니다. 375px 화면에서는 "프로젝트를" 뒤에서 줄바꿈되도록 max-width나 문구 길이를 조정해 주세요.

주석을 남긴 뒤에는 스레드에 이렇게 요청합니다.

내장 브라우저에 남긴 주석을 처리해 주세요. 레이아웃 구조는 크게 바꾸지 말고, 지적한 여백과 모바일 메뉴 겹침 문제만 수정해 주세요. 수정 후 데스크톱 1440px, 모바일 375px에서 다시 확인해 주세요.

여기서 중요한 말은 "문제만 수정해 주세요"입니다. Codex는 친절해서 주변 코드까지 정리하려 할 때가 있습니다. 시각적 수정은 범위가 넓어지기 쉬우므로, 한 번에 고칠 범위를 작게 유지해야 합니다.

artifact preview로 결과물을 바로 확인하기

Codex App의 작업 공간에는 생성된 산출물이나 미리보기를 확인하는 흐름이 포함되어 있습니다. App의 artifact viewer는 PDF, 스프레드시트, 문서, 프레젠테이션 같은 비코드 산출물을 앱 안에서 확인할 수 있게 해 주며, 작업 사이드바는 에이전트의 계획, 참고한 소스, 생성한 산출물을 보여 주는 방식으로 발전했습니다.⁴ 프론트엔드 작업에서는 이 개념을 "코드를 만들고 바로 결과를 본다"는 미리보기 습관으로 이해하면 됩니다.

예를 들어 Codex가 온보딩 페이지용 일러스트를 생성하거나, 랜딩 페이지 시안을 HTML로 만들거나, 차트가 포함된 리포트 화면을 구성했다면 결과물을 외부 앱으로 일일이 열지 않고 작업 흐름 안에서 확인할 수 있습니다. 초보자에게 이 점은 큽니다. 코드 파일만 보면 무엇이 바뀌었는지 감이 잘 오지 않지만, 미리보기 화면을 보면 "아, 이 버튼이 여기로 갔구나" 하고 바로 이해할 수 있습니다.

artifact preview를 쓸 때는 Codex에게 미리보기 기준도 함께 요청하세요.

수정이 끝나면 미리보기에서 다음을 확인해 주세요.

- /dashboard 페이지가 정상 렌더링되는지
- 프로젝트 카드 3개가 데스크톱에서 한 줄에 배치되는지
- 모바일 폭에서 카드가 1열로 쌓이는지
- CTA 버튼이 접힌 메뉴나 카드 텍스트와 겹치지 않는지
- 콘솔 오류가 없는지

이런 요청은 단순히 "실행해 봐"보다 훨씬 좋습니다. Codex가 무엇을 봐야 하는지 명확해지기 때문입니다.

"예쁘게" 대신 관찰 가능한 기준으로 말하기

프론트엔드 프롬프트에서 가장 위험한 단어는 "예쁘게"입니다. 사람에게도 애매한 말은 Codex에게도 애매합니다. 예쁘다는 말 안에는 간격, 색상, 대비, 정렬, 타이포그래피, 여백, 그림자, 애니메이션이 모두 섞여 있습니다. Codex는 그중 무엇을 우선해야 할지 추측해야 합니다.

대신 화면에서 직접 확인할 수 있는 기준으로 말해야 합니다. 예를 들어 다음 두 요청을 비교해 봅시다.

나쁜 요청:
대시보드를 더 예쁘게 고쳐줘.

좋은 요청:
대시보드 카드 사이 간격을 24px로 통일하고, 카드 내부 padding은 20px 이상으로 맞춰 주세요. 주요 CTA 버튼은 현재보다 대비가 강한 primary 색상을 사용하고, 헤더 높이는 72px에서 56px 정도로 줄여 첫 화면에서 카드가 더 많이 보이게 해 주세요. 모바일 375px에서는 모든 카드가 1열로 쌓이고 가로 스크롤이 없어야 합니다.

좋은 요청은 검증 가능합니다. 결과 화면을 보고 카드 간격이 24px인지, CTA 대비가 좋아졌는지, 헤더가 줄었는지, 모바일에서 1열인지 확인할 수 있습니다. Codex가 작업 후 스스로 검증하기도 쉽습니다.

초보자는 다음 표현을 자주 활용하면 좋습니다.

• 간격: "카드 사이 gap을 24px로", "섹션 위아래 padding을 64px로", "모바일에서는 32px로 줄여 주세요"

• 정렬: "아이콘과 텍스트를 수직 중앙 정렬", "가격 숫자는 오른쪽 정렬", "CTA 버튼은 카드 하단에 고정"

• 반응형: "1024px 이상 3열, 768px 이상 2열, 640px 미만 1열", "모바일에서 가로 스크롤 금지"

• 타이포그래피: "제목은 2줄을 넘지 않게", "본문 line-height를 1.6으로", "보조 설명은 14px로 낮추되 대비는 유지"

• 상호작용: "hover 시 그림자만 살짝 강화", "focus-visible outline 유지", "메뉴 열림 상태에서 Escape로 닫기"

이렇게 말하면 디자인 피드백이 감상이 아니라 작업 단위가 됩니다. 작업 단위가 되면 Codex가 수정하기 쉽고, 우리가 리뷰하기도 쉽습니다.

실전 예제 1: 할 일 앱의 빈 화면 개선하기

이전 실습에서 만든 할 일 관리 앱을 떠올려 봅시다. 기능은 잘 작동하지만, 처음 접속했을 때 할 일이 없으면 화면이 너무 비어 보일 수 있습니다. 이런 빈 상태는 초보 프로젝트에서 자주 놓치는 UI입니다.

먼저 현재 빈 화면을 캡처합니다. 파일 이름을 todo-empty-current.png로 저장했다고 가정하겠습니다. 그리고 손으로 간단히 그린 목표 화면도 준비합니다. 가운데에는 작은 체크 아이콘, 그 아래에는 "아직 할 일이 없어요", 설명 문구, "첫 할 일 추가하기" 버튼이 있는 구조입니다. 손그림이어도 괜찮습니다. Codex는 완성된 디자인 파일만 읽는 것이 아니라, 시각적 의도를 파악하는 데 도움을 받을 수 있습니다.

프롬프트는 이렇게 작성합니다.

첨부한 첫 번째 이미지는 현재 할 일 앱의 빈 화면이고, 두 번째 이미지는 손으로 그린 목표 레이아웃입니다.

목표:
할 일이 하나도 없을 때 사용자가 다음 행동을 쉽게 이해하도록 빈 상태 UI를 개선해 주세요.

제약:
- 기존 TodoList 컴포넌트 구조는 유지하세요.
- 새 패키지는 설치하지 마세요.
- 기존 버튼 스타일과 색상 토큰을 사용하세요.
- 빈 상태는 화면 중앙에 배치하되, 모바일에서는 위쪽 여백이 너무 커지지 않게 해 주세요.

완료 기준:
- 아이콘, 제목, 설명, CTA 버튼이 세로로 정렬되어야 합니다.
- 제목과 설명 사이 간격은 8px, 설명과 버튼 사이 간격은 20px 정도로 맞춰 주세요.
- 키보드 포커스가 버튼에 명확히 표시되어야 합니다.
- 375px 모바일 화면에서 텍스트가 어색하게 한 글자씩 줄바꿈되지 않아야 합니다.

Codex가 수정한 뒤에는 바로 끝내지 말고 후속 검토를 요청합니다.

로컬 앱을 실행해 빈 상태 화면을 확인하세요. 데스크톱 1440px와 모바일 375px에서 스크린샷을 찍었다고 가정하고, 레이아웃 문제가 남아 있는지 점검해 주세요. 문제가 있으면 최소한의 CSS 변경으로 수정해 주세요.

여기서 빈 화면 개선은 작아 보이지만, 앱의 인상이 크게 달라집니다. 사용자는 데이터가 없는 상태에서도 "앱이 고장 난 것이 아니라 내가 할 일을 추가하면 되는구나"라고 이해합니다.

실전 예제 2: 날씨 대시보드 카드 재배치하기

날씨 대시보드에서는 정보의 우선순위가 중요합니다. 현재 온도, 날씨 상태, 체감 온도, 습도, 풍속, 시간별 예보가 모두 같은 무게로 보이면 사용자는 어디를 봐야 할지 헷갈립니다. 이럴 때는 레퍼런스 이미지가 특히 유용합니다.

예를 들어 깔끔한 날씨 앱 스크린샷을 참고 이미지로 준비했다고 합시다. 단, 그대로 베끼면 안 됩니다. 레이아웃 원칙과 시각적 위계를 참고하되, 우리 앱의 색상과 컴포넌트 규칙으로 다시 구현해야 합니다.

Codex에게는 이렇게 말합니다.

weather-current.png는 현재 구현 화면이고, weather-reference.png는 참고하고 싶은 정보 위계입니다.

목표:
현재 날씨와 시간별 예보의 위계를 더 명확히 만들어 주세요. 레퍼런스 이미지를 그대로 복제하지 말고, 우리 프로젝트의 카드 스타일과 색상 체계를 유지해 주세요.

수정 방향:
- 현재 온도와 날씨 상태를 가장 큰 시각 요소로 배치하세요.
- 습도, 풍속, 체감 온도는 작은 요약 카드 3개로 정리하세요.
- 시간별 예보는 데스크톱에서 가로 카드 리스트, 모바일에서 가로 스크롤 가능한 리스트로 만드세요.
- 카드 간격은 24px, 모바일에서는 16px로 줄이세요.

검증:
- 1440px, 768px, 375px 폭에서 레이아웃을 확인하세요.
- 긴 도시 이름, 예: "San Francisco Downtown"이 들어가도 카드가 깨지지 않아야 합니다.
- 색상 대비가 낮은 텍스트가 있으면 수정하세요.

이 예제에서 좋은 점은 "날씨 앱처럼 예쁘게"가 아니라 정보 구조를 명확히 지정했다는 것입니다. Codex는 이미지에서 분위기와 배치를 참고하고, 텍스트 프롬프트에서 구현 규칙을 따릅니다.

실전 예제 3: 미니 SaaS의 가격표 A/B 테스트하기

디자인에는 정답이 하나만 있는 경우가 많지 않습니다. 특히 가격표, 랜딩 페이지 히어로, 온보딩 화면은 여러 안을 비교해 보는 것이 좋습니다. Codex에게 한 가지 결과만 만들게 하지 말고, 2~3가지 변형을 만든 뒤 기준에 따라 고르게 할 수 있습니다.

미니 SaaS 앱의 가격표를 만든다고 해 봅시다.

/pricing 페이지의 가격표 UI를 개선하려고 합니다.

세 가지 변형을 만들어 비교해 주세요.

A안:
가장 기본적인 3열 카드형 가격표. 가운데 Pro 플랜을 강조합니다.

B안:
왼쪽에는 설명 문구, 오른쪽에는 가격 카드 3개를 배치하는 비대칭 레이아웃입니다.

C안:
월간/연간 토글을 상단에 두고, 카드 내부의 기능 목록 가독성을 가장 우선합니다.

공통 제약:
- 기존 Button, Card, Badge 컴포넌트를 사용하세요.
- 모바일에서는 모든 안이 1열로 쌓여야 합니다.
- 새 UI 라이브러리는 추가하지 마세요.
- 접근성상 버튼과 토글은 키보드로 조작 가능해야 합니다.

각 안을 구현한 뒤 가독성, CTA 명확성, 모바일 안정성 기준으로 비교하고, 가장 좋은 안 하나를 선택해 최종 적용해 주세요.

Codex가 세 가지를 모두 실제 파일로 남기게 할 수도 있지만, 초보자에게는 범위가 커질 수 있습니다. 그래서 처음에는 한 파일 안에서 variant를 나누거나, 별도 브랜치 또는 worktree를 사용하는 편이 안전합니다. 10장에서 배운 worktree를 사용하면 A안, B안, C안을 각각 분리해 비교할 수 있습니다.

A/B 테스트에서 중요한 것은 "내 취향"만으로 고르지 않는 것입니다. 다음 기준을 함께 요청하세요.

• 사용자가 가장 먼저 보게 되는 플랜이 명확한가

• 무료 또는 저가 플랜과 추천 플랜의 차이가 쉽게 이해되는가

• 모바일에서 CTA 버튼이 너무 아래로 밀리지 않는가

• 긴 기능 설명이 들어가도 카드 높이가 지나치게 불균형하지 않은가

• 키보드 탐색과 포커스 표시가 유지되는가

이런 기준이 있으면 Codex의 비교 의견도 더 쓸모 있어집니다.

이미지 입력은 최종 정답이 아니라 시각적 기준이다

스크린샷이나 레퍼런스 이미지를 사용할 때 꼭 기억해야 할 점이 있습니다. 이미지는 최종 정답이 아니라 기준입니다. 특히 웹 UI는 화면 크기, 데이터 길이, 사용자 설정, 브라우저 차이에 따라 달라집니다. 한 장의 이미지와 완전히 같은 픽셀을 만들려고 하면 오히려 반응형과 접근성을 망칠 수 있습니다.

예를 들어 레퍼런스 이미지에서는 제목이 한 줄이지만, 실제 한국어 문구는 두 줄이 될 수 있습니다. 레퍼런스에서는 카드가 3개지만, 실제 서비스에서는 카드가 7개일 수 있습니다. 이미지에서는 버튼에 마우스가 올라간 상태가 보이지 않지만, 실제 앱에서는 hover, active, disabled, loading 상태가 필요합니다.

따라서 Codex에게 이렇게 말하는 습관을 들이세요.

이 이미지를 픽셀 단위의 절대 정답으로 보지 말고, 레이아웃 구조와 시각적 위계의 기준으로 사용하세요. 실제 구현에서는 우리 프로젝트의 컴포넌트, 접근성 기준, 반응형 규칙을 우선하세요.

고충실도 UI를 목표로 할 때는 순서도 중요합니다. 처음부터 모든 화면 크기를 완벽하게 맞추려 하지 말고, 기준 viewport 하나를 먼저 잡습니다. 예를 들어 데스크톱 1440px 화면을 먼저 목표에 가깝게 만든 뒤, 태블릿과 모바일을 다듬습니다. 고충실도 UI 재현을 목표로 하는 ui-from-image 같은 Codex skill도 먼저 기준 화면을 맞추고, 그다음 반응형을 검증하는 방식을 강조합니다.⁵

실무적으로는 다음 순서가 좋습니다.

1. 데스크톱 기준 화면에서 큰 레이아웃과 위계를 맞춘다.

2. 같은 크기의 스크린샷을 찍어 레퍼런스와 비교한다.

3. 간격, 타이포그래피, 색상, 아이콘 누락을 수정한다.

4. 태블릿과 모바일로 줄이며 깨지는 지점을 찾는다.

5. hover, focus, loading, empty, error 상태를 확인한다.

이 과정을 거치면 "비슷한데 어딘가 어색한 UI"에서 "실제로 사용할 수 있는 UI"로 넘어갈 수 있습니다.

디자인 브리프는 짧고 구체적으로 쓴다

이미지만으로는 알 수 없는 정보가 많습니다. 이 화면이 누구를 위한 것인지, 무엇을 가장 강조해야 하는지, 브랜드가 차분한지 활기찬지, 사용자가 초보자인지 전문가인지 이미지만 보고는 확실히 알기 어렵습니다. 그래서 짧은 디자인 브리프가 필요합니다.

디자인 브리프는 길 필요가 없습니다. 오히려 초보자는 5문장 안팎으로 쓰는 것이 좋습니다.

이 앱은 1인 창업자가 고객 프로젝트를 관리하는 미니 SaaS입니다. 사용자는 개발자가 아니므로 화면은 복잡하지 않아야 합니다. 첫 화면에서는 "오늘 처리할 일"과 "최근 프로젝트 상태"가 가장 잘 보여야 합니다. 브랜드 느낌은 신뢰감 있고 차분해야 하며, 과한 그라데이션이나 애니메이션은 피합니다. 모바일에서도 핵심 CTA인 "새 프로젝트 만들기"가 쉽게 보여야 합니다.

이 정도면 Codex가 판단할 기준이 생깁니다. "차분한 SaaS"라는 방향, "비개발자 사용자"라는 난이도, "오늘 처리할 일"과 "최근 프로젝트 상태"라는 우선순위, "새 프로젝트 만들기"라는 핵심 행동이 모두 들어 있습니다.

여기에 구현 제약을 붙이면 더 강해집니다.

구현 제약:
- Next.js App Router 구조를 유지하세요.
- Tailwind CSS 유틸리티를 사용하세요.
- 기존 Card, Button, Input 컴포넌트를 재사용하세요.
- 색상은 brand, muted, accent 토큰 안에서만 사용하세요.
- framer-motion 같은 새 애니메이션 라이브러리는 추가하지 마세요.

브리프는 Codex가 마음대로 "멋진 화면"을 만들지 못하게 막는 안전장치입니다. 동시에 우리가 무엇을 원하는지 스스로 정리하는 도구이기도 합니다.

시각 피드백을 잘 주는 법

Codex와 UI를 고칠 때 피드백은 짧아도 됩니다. 다만 위치와 기준이 있어야 합니다. "전체적으로 별로예요"는 Codex에게 도움이 되지 않습니다. "히어로 제목과 CTA 사이가 너무 멀어서 첫 화면에서 버튼이 아래로 밀립니다"는 좋은 피드백입니다.

나쁜 피드백과 좋은 피드백을 비교해 보겠습니다.

나쁜 피드백:
카드가 좀 이상해.

좋은 피드백:
두 번째 카드의 제목과 설명 사이 간격이 첫 번째 카드보다 넓어 보입니다. 모든 카드에서 제목 아래 margin을 8px로 통일해 주세요.

나쁜 피드백:
모바일이 깨져.

좋은 피드백:
375px 모바일 화면에서 상단 메뉴가 열릴 때 "새 프로젝트 만들기" 버튼 위를 덮습니다. 메뉴가 열리면 버튼을 아래로 밀거나, 메뉴를 별도 전체 너비 패널로 표시해 겹침을 없애 주세요.

나쁜 피드백:
버튼이 안 예뻐.

좋은 피드백:
주요 CTA 버튼이 배경 카드와 대비가 약합니다. primary 배경색을 사용하고, hover 상태에서는 한 단계 어두운 색으로 바꿔 주세요. disabled 상태의 대비도 너무 낮지 않게 확인해 주세요.

내장 브라우저에서 주석을 달 수 있다면 이런 피드백은 더 쉬워집니다. 문제가 있는 영역을 직접 찍고, 그 위에 짧게 쓰면 됩니다. UI 작업에서는 위치 정보가 절반의 설명입니다.

이미지 생성으로 임시 에셋 만들기

프론트엔드 작업에서 코드만큼 자주 막히는 것이 이미지 자산입니다. 랜딩 페이지에는 배너가 필요하고, 온보딩에는 일러스트가 필요하며, 상품 목록에는 임시 제품 이미지가 필요합니다. 실제 브랜드 촬영이나 전문 디자인 전에는 임시 자산이 있어야 레이아웃을 제대로 볼 수 있습니다.

최근 Codex는 스크린샷과 코드, 이미지 생성을 같은 흐름 안에서 활용하는 방향으로 확장되었습니다. OpenAI는 Codex가 이미지 생성과 반복을 활용해 제품 콘셉트, 프론트엔드 디자인, 목업, 게임 비주얼을 만드는 데 도움이 된다고 소개했습니다.⁶ 최신 환경에서는 Codex CLI에서도 이미지 첨부와 이미지 생성·편집을 프론트엔드 흐름에 결합하는 방향으로 발전하고 있습니다.²

예를 들어 미니 SaaS 랜딩 페이지에 임시 히어로 이미지를 만들고 싶다면 이렇게 요청할 수 있습니다.

$imagegen
미니 SaaS 랜딩 페이지에 사용할 임시 히어로 이미지를 만들어 주세요.

스타일:
- 차분한 B2B SaaS 느낌
- 밝은 배경, 부드러운 그림자
- 프로젝트 카드, 체크리스트, 작은 차트가 떠 있는 추상 대시보드 일러스트
- 브랜드 컬러는 teal 계열
- 실제 로고나 유명 서비스 UI는 포함하지 마세요

출력 후:
- public/images/hero-dashboard.png로 저장해 주세요.
- HeroSection 컴포넌트에 연결해 주세요.
- alt 텍스트도 함께 작성해 주세요.

제품 이미지 플레이스홀더가 필요하면 이렇게 말할 수 있습니다.

$imagegen
프로젝트 관리 앱의 기능 카드에 넣을 3개의 작은 일러스트를 만들어 주세요.

1. 작업 자동 정리
2. 팀 협업
3. 진행 상황 리포트

조건:
- 같은 스타일과 색상 팔레트를 유지
- 512x512 정사각형
- 배경은 밝고 단순하게
- 텍스트는 이미지 안에 넣지 말기
- 결과 파일은 public/images/features/ 폴더에 저장

단, 생성 이미지는 "서비스에 바로 넣어도 되는 최종 자산"이 아닙니다. 실제 서비스에 적용하기 전에는 반드시 점검해야 합니다.

• 해상도: 고해상도 화면에서 흐릿하지 않은가

• 저작권과 브랜드 적합성: 특정 브랜드, 캐릭터, 로고를 닮지 않았는가

• 파일 용량: 웹 성능을 해치지 않도록 압축했는가

• 대체 텍스트: 스크린 리더 사용자를 위한 alt 설명이 있는가

• 의미 적합성: 장식 이미지인지, 정보를 전달하는 이미지인지 구분했는가

특히 브랜드 핵심 이미지나 광고 소재라면 전문 디자이너의 검토를 거치는 것이 좋습니다. Codex의 이미지 생성은 빠른 프로토타이핑과 임시 자산 제작에는 강력하지만, 브랜드를 대표하는 최종 비주얼을 무조건 대신해 주는 도구는 아닙니다.

스크린샷 비교로 UI 차이 찾기

시각적 개선에서 가장 확실한 방법 중 하나는 전후 스크린샷을 나란히 비교하는 것입니다. 사람 눈으로 비교해도 되고, Codex에게 두 이미지를 함께 주고 차이를 설명하게 해도 됩니다.

예를 들어 수정 전 화면을 before.png, 수정 후 화면을 after.png로 저장했다면 이렇게 요청합니다.

codex -i ./screens/before.png -i ./screens/after.png \
  "두 이미지를 비교해 주세요. 레이아웃, 간격, 타이포그래피, 색상 대비, 모바일 안정성 관점에서 좋아진 점과 아직 남은 문제를 구분해서 정리하세요. 코드 수정은 아직 하지 마세요."

그다음 Codex의 비교가 맞는지 확인하고 수정에 들어갑니다.

좋습니다. 남은 문제 중 1번 카드 간격, 2번 CTA 대비, 4번 모바일 줄바꿈만 수정해 주세요. 다른 구조 변경은 하지 마세요.

이렇게 하면 Codex가 한 번에 너무 많은 것을 바꾸는 일을 줄일 수 있습니다. UI 작업에서는 변경 범위를 좁히는 것이 품질 관리의 핵심입니다.

고충실도 재현이 필요할 때는 같은 크기의 스크린샷을 비교해야 합니다. 기준 이미지는 1440px인데 구현 이미지는 1280px이면 차이가 커 보일 수밖에 없습니다. Codex에게도 viewport를 명확히 지시하세요.

localhost:3000/pricing을 1440x900 크기로 캡처하고 reference-pricing-1440.png와 비교하세요. 같은 viewport 기준으로만 차이를 판단해 주세요.

모바일도 마찬가지입니다.

375x812 크기에서 /pricing 화면을 확인하세요. reference-pricing-mobile.png와 비교해 카드 순서, 버튼 위치, 텍스트 줄바꿈 차이를 정리하고 수정해 주세요.

접근성과 성능까지 함께 검증하기

화면이 예뻐 보여도 좋은 프론트엔드라고 할 수는 없습니다. 사용자가 키보드로 이동할 수 있어야 하고, 색상 대비가 충분해야 하며, 모바일에서도 터치하기 쉬워야 합니다. 이미지가 너무 크면 로딩이 느려지고, 포커스 표시를 없애면 키보드 사용자가 길을 잃습니다.

시각적 수정이 끝나면 Codex에게 검증 루프를 요청하세요.

UI 수정이 끝났으니 검증을 진행해 주세요.

확인할 항목:
- Lighthouse 성능과 접근성 점수 확인
- 주요 텍스트와 버튼의 색상 대비 확인
- Tab 키로 헤더, 메뉴, CTA, 폼 요소를 순서대로 탐색할 수 있는지 확인
- focus-visible 스타일이 보이는지 확인
- 모바일 375px, 태블릿 768px, 데스크톱 1440px에서 레이아웃 확인
- 콘솔 오류와 hydration 오류 확인

문제가 발견되면 스크린샷 기준으로 설명하고, 최소 변경으로 수정해 주세요.

여기서 Lighthouse는 웹 페이지의 성능, 접근성, SEO 등을 점검하는 도구입니다. 초보자는 점수를 절대적인 성적표로만 보지 말고, "어디를 더 확인해야 하는지 알려 주는 체크리스트"로 이해하면 됩니다.

접근성에서 특히 자주 놓치는 부분은 포커스 표시입니다. CSS를 예쁘게 만들다 보면 outline: none을 넣고 끝내는 경우가 있습니다. 마우스로만 쓰면 문제가 없어 보이지만, 키보드 사용자는 현재 어디에 있는지 알 수 없습니다. Codex에게 다음처럼 분명히 말하세요.

버튼과 링크의 기본 focus outline을 제거하지 마세요. 디자인상 조정이 필요하면 focus-visible 상태에서 브랜드 색상의 명확한 링을 표시해 주세요.

색상 대비도 자주 확인해야 합니다. 연한 회색 배경 위에 연한 회색 텍스트를 올리면 세련돼 보일 수 있지만 읽기 어렵습니다. Codex에게 "대비가 낮은 텍스트가 있으면 색상 토큰 안에서 조정해 달라"고 요청하면 좋습니다.

초보자를 위한 UI 개선 마스터 프롬프트

아래 프롬프트는 거의 그대로 복사해 사용할 수 있는 기본형입니다. 대괄호 부분만 프로젝트에 맞게 바꾸면 됩니다.

첨부한 이미지를 참고해 [페이지/컴포넌트 이름]의 UI를 개선해 주세요.

이미지 설명:
- current.png: 현재 구현 화면입니다.
- reference.png: 원하는 레이아웃과 시각적 위계의 참고 이미지입니다.

목표:
[사용자가 이 화면에서 해야 하는 핵심 행동]이 더 잘 보이도록 개선합니다.

프로젝트 제약:
- 기존 컴포넌트와 스타일 토큰을 우선 사용하세요.
- 새 UI 라이브러리는 추가하지 마세요.
- 기존 라우팅과 데이터 흐름은 유지하세요.
- 변경 범위는 [수정할 파일/폴더]로 제한하세요.

시각 기준:
- 카드 간격은 데스크톱 24px, 모바일 16px로 맞춥니다.
- 주요 CTA 버튼의 대비를 강화합니다.
- 헤더 높이를 줄여 첫 화면의 정보량을 늘립니다.
- 모바일 375px에서는 1열 레이아웃로 전환합니다.
- 긴 텍스트가 들어가도 줄바꿈이 어색하지 않아야 합니다.

검증:
- npm run build를 실행하세요.
- 데스크톱 1440px, 태블릿 768px, 모바일 375px에서 확인하세요.
- 키보드 Tab 탐색과 focus 표시를 확인하세요.
- 색상 대비가 낮은 요소가 있으면 수정하세요.
- 변경 사항과 남은 한계를 요약해 주세요.

이 프롬프트를 처음부터 완벽하게 채우려고 하지 않아도 됩니다. 중요한 것은 목표, 제약, 시각 기준, 검증을 나누어 말하는 습관입니다. 이 네 가지가 있으면 Codex의 결과가 훨씬 안정적입니다.

작업 범위를 작게 나누는 것이 실력이다

프론트엔드 개선은 욕심내기 쉽습니다. 대시보드 카드 간격을 고치다가 헤더를 바꾸고, 헤더를 바꾸다가 사이드바를 바꾸고, 사이드바를 바꾸다가 라우팅 구조까지 바꾸게 됩니다. Codex는 이런 확장을 더 빠르게 할 수 있기 때문에 오히려 더 조심해야 합니다.

한 번의 작업은 가능하면 하나의 화면, 하나의 문제, 하나의 기준으로 제한하세요. 예를 들어 "가격표 모바일 레이아웃 수정", "대시보드 CTA 대비 강화", "온보딩 빈 상태 추가"처럼 작게 나눕니다. 수정 후 diff를 확인하고, 화면을 확인하고, 커밋합니다.

좋은 작업 단위는 이런 모양입니다.

/pricing 페이지의 모바일 레이아웃만 수정해 주세요. 데스크톱 스타일은 가능한 유지하세요. 375px 화면에서 카드가 1열로 쌓이고, CTA 버튼이 카드 밖으로 넘치지 않게 하는 것이 목표입니다.

나쁜 작업 단위는 이런 모양입니다.

앱 전체 디자인을 최신 SaaS처럼 싹 바꿔줘.

물론 전체 리디자인이 필요할 때도 있습니다. 하지만 그때도 먼저 디자인 브리프를 만들고, 공통 디자인 규칙을 정리하고, 한 화면에 적용해 검증한 뒤 다른 화면으로 확장해야 합니다. 한 번에 모든 화면을 바꾸면 무엇이 좋아졌고 무엇이 깨졌는지 파악하기 어렵습니다.

디자인 규칙을 AGENTS.md에 남기기

좋은 UI 개선을 한 번 만들었다면 그 경험을 프로젝트 기억으로 남겨야 합니다. 11장에서 배운 AGENTS.md는 Codex에게 프로젝트 규칙을 알려 주는 파일입니다. 프론트엔드 디자인 규칙도 여기에 정리할 수 있습니다.

예를 들어 대시보드와 가격표를 다듬은 뒤 이런 내용을 추가할 수 있습니다.

## Frontend design guidelines

- Use existing components from src/components/ui before creating new primitives.
- Keep desktop card gaps at 24px and mobile gaps at 16px unless a screen has a specific reason.
- Primary CTA buttons should use the primary color token and must pass contrast checks.
- Do not remove focus-visible outlines. Use a visible brand-colored focus ring.
- Responsive breakpoints:
  - Desktop: 1024px and above, use multi-column layouts when appropriate.
  - Tablet: 768px to 1023px, prefer 2-column card grids.
  - Mobile: below 640px, use 1-column layouts and avoid horizontal scrolling.
- When implementing from screenshots, match visual hierarchy and spacing while preserving project components and accessibility.

이렇게 해 두면 다음번에 Codex가 새 화면을 만들 때 같은 규칙을 더 잘 따릅니다. 프론트엔드 품질은 한 번의 멋진 화면보다 일관성이 중요합니다. 버튼 모양, 카드 간격, 폰트 크기, 포커스 표시가 화면마다 다르면 앱은 금방 아마추어처럼 보입니다.

문제가 생겼을 때 되돌리는 습관

시각적 수정은 결과를 보기 전까지 성공 여부를 알기 어렵습니다. 그래서 Git 습관이 중요합니다. 10장에서 배운 것처럼 작업 전에는 clean state를 만들고, Codex가 수정한 뒤에는 diff를 봅니다. UI가 마음에 들지 않으면 과감히 되돌릴 수 있어야 합니다.

추천 흐름은 다음과 같습니다.

1. 작업 전 git status로 깨끗한 상태인지 확인한다.

2. UI 수정 작업을 작게 요청한다.

3. Codex가 만든 diff를 파일별로 확인한다.

4. 로컬 브라우저, 내장 브라우저, 스크린샷으로 결과를 확인한다.

5. 마음에 들면 커밋하고, 아니면 일부 파일 또는 전체 변경을 되돌린다.

Codex에게도 이렇게 말할 수 있습니다.

작업을 시작하기 전에 현재 git status를 확인하세요. 수정 후에는 변경 파일 목록과 주요 diff 요약을 알려 주세요. 디자인 수정과 무관한 파일이 바뀌었다면 되돌려 주세요.

초보자일수록 "일단 많이 바꿔 보자"보다 "작게 바꾸고 자주 확인하자"가 안전합니다. Codex는 빠르기 때문에 작은 반복을 여러 번 해도 부담이 적습니다.

이번 장의 핵심 정리

프론트엔드 UI는 코드만으로 완성되지 않습니다. 사용자가 보는 화면을 기준으로 계속 확인해야 합니다. Codex의 이미지 입력, artifact preview, 내장 브라우저, 주석 기능을 활용하면 이 확인 과정을 훨씬 빠르고 구체적으로 만들 수 있습니다.

가장 중요한 원칙은 "말로 애매하게 설명하지 말고 화면으로 보여주기"입니다. 스크린샷, 손그림, 레퍼런스 이미지, 짧은 디자인 브리프를 함께 제공하면 Codex는 우리가 원하는 방향을 더 잘 이해합니다. 단, 이미지를 최종 정답으로 보게 하지 말고 기존 컴포넌트, 색상, 간격, 접근성 규칙 안에서 구현하도록 지시해야 합니다.

그리고 "예쁘게"라는 말 대신 검증 가능한 기준을 주세요. 카드 간격 24px, 모바일 1열 전환, CTA 대비 강화, 헤더 높이 축소, 텍스트 줄바꿈 위치처럼 화면에서 확인할 수 있는 기준이 좋습니다. Codex가 만든 첫 결과물은 초안입니다. 실제 화면을 열고, 주석을 달고, 스크린샷을 비교하고, 다시 수정하는 반복 속에서 UI가 좋아집니다.

마지막으로 시각적 완성도는 접근성과 성능까지 포함합니다. Lighthouse, 색상 대비, 키보드 탐색, 포커스 표시, 모바일/태블릿/데스크톱 뷰를 확인해야 합니다. 보기 좋은 화면에서 멈추지 말고, 실제 사용자가 편하게 쓸 수 있는 화면까지 Codex와 함께 검증하세요.

다음 장에서는 이 흐름을 더 단단하게 만들기 위해 테스트, 디버깅, 리팩토링을 Codex에게 맡기는 방법을 다룹니다. UI를 눈으로 확인했다면, 이제 코드가 계속 안전하게 동작하도록 자동 검증의 기반을 세울 차례입니다.

참고

¹Build responsive front-end designs | Codex use cases

²CLI - Codex | OpenAI Developers

³In-app browser - Codex app | OpenAI Developers

⁴Inside the Codex App Workspace: PR Review Pane, Task Sidebar, and Artifact Viewer in Platform 26.415

⁵GitHub - Ixe1/ui-from-image: Codex skill for recreating high-fidelity UIs from screenshots

⁶Codex for (almost) everything - OpenAI