비즈니스 로직을 유지하며 기존 프로젝트 UI와 투박한 흐름 개선하기
새 데모를 처음부터 만드는 일은 쉽습니다. API 계약, 폼 검증, URL 상태를 망가뜨리지 않고 실제 프로덕션 앱을 개선하는 것은 어렵습니다. 신뢰할 수 있는 UI 개선은 먼저 비즈니스 불변 조건을 고정하고 문제에 맞는 개선 깊이를 선택하며 클릭 수를 세어 흐름을 검증합니다. 그다음 대표 화면에서 DESIGN.md를 추출해 변경 사항을 앱 전체에 적용합니다.
핵심 요점
- API 페이로드, 경로 매개변수, 권한 확인, 그대로 유지해야 할 폼 핸들러 등 양보할 수 없는 비즈니스 동작을 먼저 나열하세요.
- 문제에 개선 깊이를 맞추세요. 1단계는 시각적 소음 정리, 2단계는 레이아웃과 누락된 상태 업그레이드, 3단계는 투박한 다단계 흐름 재구성입니다.
- 실제 작업을 수행하며 클릭 수를 세어 사용성 개선을 측정하세요. 모달을 여섯 번 클릭하는 과정을 두 번의 직접 행동으로 줄이는 것이 단순한 외형 변경보다 낫습니다.
- 대표 페이지가 리뷰를 통과하면 토큰, 타이포그래피, 간격을 DESIGN.md에 기록해 관련 페이지의 일관성을 유지하세요.
npx github:oil-oil/oil-cli install oil-ui-pro먼저 한 화면에서 기본 방향 보드와 인위적인 요소 정리를 시도하려면 npx skills add oil-oil/oil-ui를 실행해 무료 Skill을 설치하세요.
UI 개선의 세 단계: 변경 범위 선택하기
“이 페이지를 더 보기 좋게 해 줘” 같은 모호한 프롬프트가 컴포넌트 props를 엉망으로 만들거나 작동하던 필터를 삭제할 수 있기 때문에 팀은 코딩 Agent가 프로덕션 뷰를 건드리는 것을 망설이곤 합니다. Oil UI, 특히 Oil UI Pro의 기존 프로젝트 워크플로에서는 개선을 명시적인 세 단계로 구분합니다.
| 단계 | 사용 시점 | 변경 사항 | 그대로 유지하는 부분 |
|---|---|---|---|
| 1단계: 시각적 소음 정리 | 흐름은 작동하지만 테두리, 글꼴 크기, 간격, 색상이 어수선하거나 낡음 | 타이포그래피 크기, 테두리 제거, 정렬, 색상 절제, 카드 정리 | DOM 구조, 경로, 상태 hooks, 모든 상호작용 흐름 |
| 2단계: 레이아웃 및 상태 업그레이드 | 시각 위계가 평평하고 주요 행동이 묻혀 있거나 로딩/빈/오류 상태가 없음 | 섹션 위계, 다중 열 비율, 반응형 중단점, 완전한 UI 상태 | 백엔드 API 계약, 비즈니스 로직, 페이지 간 네비게이션 |
| 3단계: 투박한 흐름 재구성 및 DESIGN.md 추출 | 사용자가 기본 작업을 끝내기 위해 중첩 모달이나 분절된 화면을 거침 | 단계 통합, 인라인 편집, 대표 화면 리디자인, 저장소 전체 DESIGN.md | 기반 도메인 모델과 데이터 무결성 규칙 |
실제 애플리케이션을 안전하게 개선하는 네 단계
갤러리의 MOQI 같은 계약 검토 앱, Relay 같은 스프린트 트래커, Post 같은 이메일 클라이언트, Pinch Checkout 같은 결제 흐름 중 무엇을 개선하든 통제된 순서를 따르세요.
현재 화면을 캡처하고 주석이 달린 진단 실행
Agent가 먼저 실행 중인 페이지의 스크린샷을 찍고 번호를 매긴 시각·상호작용 결함을 나열하게 하세요. 예를 들어 머리글에서 경쟁하는 같은 강조색 버튼 세 개, 1280px에서 잘리는 12열 표, 오류 시 표시되는 원시 alert 상자입니다.
먼저 대표 화면 하나 개선
한꺼번에 스무 개의 경로를 건드리지 마세요. 사용자가 가장 오래 머무는 화면 하나를 선택하고 실제 데이터로 개선 방향 2~3개를 비교한 다음 하나를 확정하세요.
전체 사용자 작업을 수행하고 클릭 수 계산
브라우저에서 필터링, 제출, 검증 오류 발생과 복구를 포함한 실제 흐름을 클릭하고 입력하세요. 빈도 높은 작업의 단계가 이전보다 줄었는지 확인하세요.
DESIGN.md를 추출하고 관련 페이지에 적용
대표 화면이 시각 리뷰를 통과하면 Agent가 표면 팔레트, 타입 스케일, 표 밀도, 상투적 요소 방지 규칙을 DESIGN.md에 작성하게 하세요. 그다음 그 명세를 나머지 앱에 적용하세요.
기존 화면 개선 프롬프트 템플릿
Claude Code, Codex, Cursor에서 애플리케이션 로직을 보호하면서 실제 뷰를 업그레이드할 때 이 구조를 사용하세요.
Oil UI를 사용해 이 프로젝트의 [경로 또는 컴포넌트 경로, 예: app/billing/page.tsx]을 개선해 줘.
- 엄격히 유지할 동작: 기존 [데이터 쿼리, URL 필터 매개변수, 폼 검증 규칙, 제출/데이터 추출 핸들러]를 모두 그대로 유지해 줘. 도메인 필드를 제거하지 마.
- 해결할 현재 문제: [예: 모든 섹션이 동일한 테두리 카드처럼 보임, 표 열이 어색하게 줄 바꿈됨, 필터 결과 없음 및 결제 실패 상태가 없음].
- 개선 단계: [1단계 소음 정리 / 2단계 레이아웃 및 상태 업그레이드 / 3단계 흐름 재구성 및 DESIGN.md 추출 중 선택].
현재 실제 화면을 캡처하고 진단하는 것으로 시작하고 방향을 제안한 다음 완성된 페이지를 1440×900과 390×844에서 확인해 줘.유지할 동작을 첫 번째 항목에 나열하면 의도하지 않은 회귀를 예방할 수 있습니다.
작동하는 갤러리 사례와 프롬프트
1440px 또는 390px의 실제 데모를 열어 모델과 프롬프트가 최종 인터페이스를 어떻게 형성했는지 살펴 보세요.
MOQI
AI 계약 검토 웹사이트
사내 법무팀을 위한 AI 계약 검토 제품의 웹사이트를 만드세요. 홈페이지를 구현하세요.
작품과 프롬프트 살펴 보기 →
Relay
프로젝트 및 스프린트 관리
제품: 20–200인 소프트웨어 팀을 위한 작업 및 스프린트 관리 도구 Relay입니다. 메인 작업 공간을 만드세요(1440×900). - 왼쪽 네비게이션에는 팀, 프로젝트, 내 작업, 받은편지함을 배치하세요. 중앙에는 현재 스프린트를 작업 목록이나 보드로 표시하세요. 작업에는 ID, 제목, 상태, 우선순위, 담당자 아바타, 예상치가 있습니다. 실제 소프트웨어 개발 작업처럼 들리는 이름의 작업 20~30개 등 현실적인 데이터를 충분히 사용하세요. - 느낌: 하루 8시간 사용하는 전문 도구처럼 어둡고 정교하며 밀도 높게 만드세요. 행은 콤팩트하게 유지하고 키보드 단축키를 전체에서 볼 수 있게 하며 상태 아이콘은 일관되고 알아보기 쉽게 하세요. - 키보드 명령 팔레트를 기억에 남게 만드세요. 단축키로 열고 몇 글자만 입력해 이동하거나 상태를 바꾸거나 담당자를 지정할 수 있어야 합니다. 쿼리를 입력 중인 열린 상태를 캡처하세요. - 작업 상세 사이드바가 열린 상태도 캡처하세요.
작품과 프롬프트 살펴 보기 →
Post
이메일 클라이언트
제품: 하루에 수백 통의 이메일을 처리하는 사람들을 위한 이메일 클라이언트 Post입니다. 메인 인터페이스를 만드세요(1440×900). 받은편지함, 열어 본 이메일, 빠른 답장을 포함하고 업무 서신, 청구서, 알림이 섞인 현실적인 이메일 내용을 사용하세요. 받은편지함을 비우는 경험에 독특한 감각을 부여하세요. 예를 들어 처리한 이메일이 즉시 밀려 나가고 개수가 줄어들 수 있습니다. 비어 있는 받은편지함 상태의 스크린샷도 캡처하세요.
작품과 프롬프트 살펴 보기 →
Pinch 결제
이커머스 결제 모듈
독립 디자이너 브랜드 온라인 스토어의 결제 모듈을 만드세요(데스크톱 1440×900, 결제 패널을 중앙에 배치). 쇼핑 목록, 배송 주소, 결제 수단, 주문 확인을 포함합니다. 각 단계가 부드럽게 이어져야 하며 모든 입력에 입력 중, 유효하지 않음, 완료 상태가 명확히 나타나야 합니다. 주문 완료는 체크 표시만 보여 주는 데 그치지 않고 즐거운 느낌을 전달하세요. 양식 작성, 유효성 검사 오류, 주문 성공의 세 가지 상태를 캡처하세요.
작품과 프롬프트 살펴 보기 →Oil UI Pro의 전체 기존 프로젝트 개선 도구 모음
Oil UI Pro에는 주석이 달린 단일 페이지 스크린샷 진단, 3단계 개선 워크플로, 클릭 수를 센 작업 점검, 여러 페이지 일관성을 위한 DESIGN.md 추출이 포함됩니다.
npx github:oil-oil/oil-cli install oil-ui-pro자주 묻는 질문
전역 CSS 토큰을 먼저 정의해야 하나요, 아니면 실제 화면 하나를 먼저 개선해야 하나요?
대표 화면 하나를 먼저 개선하세요. 실제 상황과 동떨어져 작성한 추상적인 토큰 파일은 실제 표 밀도와 폼 상태를 만나면 유지되기 어렵습니다. 실제 데이터로 대표 화면 하나를 완성하면 DESIGN.md로 정확한 토큰을 추출하기 쉽습니다.
서드파티 위젯을 다시 작성하지 않고 레거시 앱을 점진적으로 개선할 수 있나요?
네. 1단계나 2단계 작업에서는 복잡한 포함 위젯을 교체할 준비가 될 때까지 그대로 두고 페이지 그리드, 타이포그래피, 간격, 주변 상태를 재구성할 수 있습니다.
리디자인이 실제로 사용성을 개선했는지 어떻게 확인하나요?
두 가지를 확인하세요. 먼저 텍스트를 흐리게 해 주요 행동과 예외 상태가 구조적으로 돋보이는지 확인합니다. 다음으로 브라우저에서 주요 사용자 작업을 완료하고 클릭 수, 스크롤 탐색, 오류 복구가 이전보다 빨라졌는지 확인하세요.
추출한 DESIGN.md는 어디에 두어야 하나요?
저장소 루트나 docs/ 디렉터리에 보관하세요. 사용자나 팀원이 Claude Code, Codex, Cursor에서 새 기능을 만들 때 Agent에 DESIGN.md를 가리키면 새 화면이 확립된 시스템과 일치하게 됩니다.