3단계: UI - 인터페이스 및 프로토타입 설계

UI는 Agent App Factory 파이프라인의 3단계로, PRD의 기능 설명을 명확한 인터페이스 구조(UI Schema)와 미리보기 가능한 프로토타입으로 변환합니다. 이 단계는 최종 애플리케이션의 외관과 인터랙션 경험을 결정하며, 제품 요구사항과 기술 구현을 연결하는 핵심 다리 역할을 합니다.

이 챕터를 완료하면 다음을 할 수 있습니다

PRD를 표준에 맞는 ui.schema.yaml 파일로 변환
ui-ux-pro-max 스킬을 사용하여 전문 디자인 시스템(스타일, 색상, 폰트) 생성
브라우저에서 미리보기 가능한 프로토타입(HTML + CSS + JS) 생성
UI Agent의 책임 경계 이해(디자인 측면, 기술 구현 미포함)
일반적인 AI 디자인 함정(예: 보라색 그라데이션, Inter 폰트 남용) 회피

현재 당신이 직면한 문제

명확한 PRD가 있지만 인터페이스 디자인을 어떻게 시작할지 모를 수 있습니다:

"PRD는 작성했지만 적합한 UI 스타일이 떠오르지 않는다" (디자인 시스템 지식 부족)
"어떤 색상, 폰트, 레이아웃을 사용해야 할지 모른다" (개인적인 미적 감각보다 전문 규범에 의존 필요)
"디자인한 프로토타입이 PRD와 일치하지 않는다" (인터페이스 구조가 기능 요구사항과 분리)
"디자인이 너무 못생기거나 화려해서 제품 포지셔닝에 맞지 않을까 걱정한다" (업계 디자인 경험 부족)

이러한 디자인 맹목은 이후 Code 단계에서 명확한 시각적 규범이 부족하게 만들어, 최종적으로 생성된 애플리케이션이 외관이 혼란스럽고 인터랙션이 일관되지 않게 만듭니다.

언제 사용하는가

PRD가 이미 완료되고 다음 조건을 충족할 때:

명확한 PRD 문서 (사용자 스토리, 기능 목록, 비목표 포함)
아직 인터페이스 디자인을 시작하지 않음 (UI는 첫 번째 디자인 단계)
기술 스택을 아직 결정하지 않음 (기술 구현 세부사항은 Tech 단계)
디자인 범위를 제어하고 과도 디자인 회피 (UI 단계는 3페이지 이내로 제한)

🎒 시작 전 준비

전제 조건

UI 단계를 시작하기 전에 다음을 확인하세요:

✅ PRD 단계가 완료되었고, artifacts/prd/prd.md가 생성되었습니다.
✅ ui-ux-pro-max 플러그인이 설치되었습니다. (추천 방법: factory init 실행 시 자동 설치)
✅ 7단계 파이프라인 개요를 이해했습니다.
✅ AI 어시스턴트를 준비했습니다. (Claude Code 추천)

핵심 접근 방식

UI 단계란 무엇인가?

UI 단계는 제품 요구사항과 기술 구현을 연결하는 다리로, 유일한 책임은 PRD의 기능 설명을 인터페이스 구조와 시각적 규범으로 변환하는 것입니다.

프론트엔드 개발이 아님

UI Agent는 프론트엔드 개발 엔지니어가 아니며, React 컴포넌트나 CSS 코드를 작성하지 않습니다. 그의 임무는:

PRD의 기능 요구사항 분석
인터페이스 정보 아키텍처 결정(페이지 및 컴포넌트)
디자인 시스템 생성(색상, 폰트, 간격, 모서리 둥글게)
미리보기 가능한 프로토타입 생성(HTML + CSS + JS)

그는 "어떤 프레임워크로 구현할지"가 아닌 "어떻게 생겼을지"를 결정합니다.

왜 디자인 시스템이 필요한가?

디자인 시스템이 없는 집 인테리어를 상상해 보세요:

❌ 디자인 시스템 없음: 거실은 미니멀 스타일, 침실은 레트로 스타일, 주방은 인더스트리얼 스타일로 전체적으로 혼란
✅ 디자인 시스템 있음: 전체 집이 통일된 색조, 통일된 스타일, 통일된 소재로 조화로움

UI 단계는 ui-ux-pro-max 스킬을 통해 이러한 "전체 집 인테리어 가이드"를 생성하여, 이후 Code 단계에서 생성되는 모든 인터페이스가 통일된 시각적 규범을 따르도록 보장합니다.

출력 파일 구조

UI 단계는 세 개의 파일을 생성합니다:

파일	내용	역할
ui.schema.yaml	디자인 시스템 설정 + 페이지 구조 정의	Tech 단계에서 이 파일을 읽어 데이터 모델 설계, Code 단계에서 이 파일을 읽어 인터페이스 생성
preview.web/index.html	브라우저에서 미리보기 가능한 프로토타입	미리 인터페이스 효과를 확인하고 디자인이 예상에 부합하는지 검증
design-system.md (선택 사항)	지속 가능한 디자인 시스템 문서	디자인 결정을 기록하고 향후 조정을 용이하게 함

따라하기

1단계: PRD 완료 확인

UI 단계를 시작하기 전에 artifacts/prd/prd.md가 존재하고 내용이 완전한지 확인하세요.

체크포인트 ✅:

대상 사용자가 명확한가요?
- ✅ 구체적인 페르소나(나이/직업/기술 능력)가 있음
- ❌ 모호함: "모두"
핵심 기능이 나열되었나요?
- ✅ 3-7개의 핵심 기능이 있음
- ❌ 너무 많거나 너무 적음
비목표가 충분한가요?
- ✅ 최소 3개의 수행하지 않는 기능이 나열됨
- ❌ 누락되거나 너무 적음

PRD가 불완전한 경우

먼저 PRD 단계로 돌아가 수정하고, 디자인에 명확한 입력이 있는지 확인하세요.

2단계: 파이프라인을 UI 단계로 시작

Factory 프로젝트 디렉터리에서 다음을 실행하세요:

bash

# PRD 단계에서 계속(PRD 단계가 방금 완료된 경우)
factory continue

# 또는 ui에서 시작하도록 직접 지정
factory run ui

CLI는 현재 상태와 사용 가능한 단계를 표시합니다.

3단계: AI 어시스턴트가 UI Agent 정의 읽기

AI 어시스턴트(예: Claude Code)는 자동으로 agents/ui.agent.md를 읽고 그의 책임과 제약 조건을 이해합니다.

Agent 책임

UI Agent는 다음만 수행할 수 있습니다:

artifacts/prd/prd.md 읽기
artifacts/ui/ 쓰기
ui-ux-pro-max 스킬을 사용하여 디자인 시스템 생성
3페이지 이내의 프로토타입 생성

다음은 수행할 수 없습니다:

다른 파일 읽기
다른 디렉터리 쓰기
기술 스택 결정(이는 Tech 단계)
AI 기본 스타일 사용(보라색 그라데이션, Inter 폰트)

4단계: ui-ux-pro-max 디자인 시스템 강제 사용(핵심 단계)

이것은 UI 단계의 핵심 단계입니다. AI 어시스턴트는 디자인 방향이 명확하다고 생각하더라도 먼저 ui-ux-pro-max 스킬을 호출해야 합니다.

ui-ux-pro-max 스킬의 역할:

디자인 시스템 자동 추천: 제품 유형, 업계 분야에 따라 최적의 스타일 자동 매칭
67가지 UI 스타일 제공: 미니멀리즘부터 네오 브루탈리즘까지
96가지 컬러 팔레트 제공: 업계 및 스타일별 사전 디자인
57가지 폰트 조합 제공: 일반적인 AI 스타일(Inter, Roboto) 회피
100가지 업계 추론 규칙 적용: 디자인이 제품 포지셔닝에 부합하도록 보장

AI 어시스턴트는 다음을 수행합니다:

PRD에서 핵심 정보 추출: 제품 유형, 업계 분야, 대상 사용자
ui-ux-pro-max 스킬을 호출하여 완전한 디자인 시스템 추천 획득
추천된 디자인 시스템을 ui.schema.yaml 및 프로토타입에 적용

이 단계를 건너뛰면 거부됨

Sisyphus 스케줄러는 ui-ux-pro-max 스킬을 사용했는지 검증합니다. 사용하지 않은 경우 UI Agent가 생성한 산출물이 거부되며 다시 실행해야 합니다.

디자인 시스템에는 무엇이 포함되어 있나요??

yaml

design_system:
  style: "Glassmorphism"           # 선택한 스타일(예: 글래스모피즘, 미니멀리즘)
  colors:
    primary: "#2563eb"             # 주 색상(주요 작업에 사용)
    secondary: "#64748b"           # 보조 색상
    success: "#10b981"             # 성공 색상
    warning: "#f59e0b"             # 경고 색상
    error: "#ef4444"               # 오류 색상
    background: "#ffffff"          # 배경 색상
    surface: "#f8fafc"            # 서피스 색상
    text:
      primary: "#1e293b"           # 주 텍스트
      secondary: "#64748b"         # 보조 텍스트
  typography:
    font_family:
      headings: "DM Sans"          # 제목 폰트(Inter 회피)
      body: "DM Sans"              # 본문 폰트
    font_size:
      base: 16
      lg: 18
      xl: 20
      2xl: 24
  spacing:
    unit: 8                        # 간격 기준(8px 그리드)
  border_radius:
    md: 8
    lg: 12
  effects:
    hover_transition: "200ms"      # hover 전환 시간
    blur: "backdrop-blur-md"       # 글라스 효과

5단계: 인터페이스 구조 설계

AI 어시스턴트는 PRD의 기능 요구사항에 따라 인터페이스 정보 아키텍처(페이지 및 컴포넌트)를 설계합니다.

인터페이스 구조 예시 (ui.schema.yaml에서 가져옴):

yaml

pages:
  - id: home
    title: "홈"
    type: list
    description: "모든 프로젝트 목록 표시"
    components:
      - type: header
        content: "내 앱"
      - type: list
        source: "api/items"
        item_layout:
          - type: text
            field: "title"
            style: "heading"
          - type: text
            field: "description"
            style: "body"
        actions:
          - type: "navigate"
            target: "detail"
            params: ["id"]

  - id: detail
    title: "상세"
    type: detail
    params:
      - name: "id"
        type: "number"

  - id: create
    title: "생성"
    type: form
    fields:
      - name: "title"
        type: "text"
        label: "제목"
        required: true
    submit:
      action: "post"
      endpoint: "/api/items"
      on_success: "navigate:home"

페이지 유형:

list: 목록 페이지(예: 홈, 검색 결과)
detail: 상세 페이지(예: 프로젝트 상세 보기)
form: 폼 페이지(예: 생성, 편집)

6단계: 미리보기 프로토타입 생성

AI 어시스턴트는 HTML + CSS + JS를 사용하여 미리보기 가능한 프로토타입을 생성하고 핵심 인터랙션 흐름을 보여줍니다.

프로토타입 특징:

네이티브 기술 사용(프레임워크 의존 없음)
디자인 시스템 추천 색상, 폰트, 효과 적용
모든 클릭 가능한 요소에 hover 상태 및 cursor-pointer가 있음
모바일 우선 디자인(375px 및 768px에서 반응형 정상 작동)
SVG 아이콘 사용(Heroicons/Lucide), emoji 사용 안 함

미리보기 방법: 브라우저에서 artifacts/ui/preview.web/index.html을 열면 프로토타입을 볼 수 있습니다.

7단계: UI 출력 확인

UI Agent가 완료되면 출력 파일을 확인해야 합니다.

체크포인트 ✅:

ui.schema.yaml이 존재하는가?
- ✅ 파일이 artifacts/ui/ 디렉터리에 있음
- ❌ 누락되거나 경로가 잘못됨
디자인 시스템이 ui-ux-pro-max 스킬을 사용했는가?
- ✅ 출력이나 schema에서 명확하게 설명됨
- ❌ 자체적으로 선택한 디자인 시스템
페이지 수가 3페이지 이내인가?
- ✅ 1-3페이지(MVP는 핵심 기능에 집중)
- ❌ 3페이지 초과
프로토타입이 브라우저에서 열리는가?
- ✅ 브라우저에서 preview.web/index.html을 열면 정상적으로 표시됨
- ❌ 열리지 않거나 오류 표시
AI 기본 스타일을 피했는가?
- ✅ 보라색/분홍색 그라데이션이 없음
- ✅ Inter 폰트를 사용하지 않음
- ✅ SVG 아이콘 사용(emoji 사용 안 함)
- ❌ 위 AI 스타일이 나타남
모든 클릭 가능한 요소에 인터랙션 피드백이 있는가?
- ✅ cursor-pointer 및 hover 상태가 있음
- ✅ 전환이 매끄러움(150-300ms)
- ❌ 인터랙션 표시 없음 또는 즉시 변경

8단계: 계속, 재시도 또는 일시중지 선택

확인 후 CLI는 옵션을 표시합니다:

bash

작업을 선택하세요:
[1] 계속(Tech 단계로 진행)
[2] 재시도(UI 다시 생성)
[3] 일시중지(나중에 계속)

먼저 프로토타입 미리보기 추천

AI 어시스턴트에서 확인하기 전에 먼저 브라우저에서 프로토타입을 열어 디자인이 예상에 부합하는지 확인하세요. 일단 Tech 단계로 진입하면 디자인 수정 비용이 더 높습니다.

함정 주의

함정 1: ui-ux-pro-max 스킬을 사용하지 않음

오류 예시:

AI 어시스턴트가 글래스모피즘 스타일, 파란색 컬러 스킴을 자체적으로 선택

결과: Sisyphus 스케줄러가 산출물을 거부하고 다시 실행을 요구합니다.

권장 사항:

AI 어시스턴트는 반드시 먼저 ui-ux-pro-max 스킬을 호출하여 추천된 디자인 시스템을 획득해야 함

함정 2: AI 기본 스타일 사용

오류 예시:

보라색/분홍색 그라데이션 배경
Inter 또는 Roboto 폰트
emoji를 UI 아이콘으로 사용

결과: 디자인이 전문적이지 않고 AI 생성으로 쉽게 식별되어 제품 이미지에 영향을 줍니다.

권장 사항:

ui-ux-pro-max가 추천하는 57가지 폰트 조합에서 선택
SVG 아이콘 라이브러리 사용(Heroicons/Lucide)
그라데이션 및 네온 색상 남용 회피

함정 3: 페이지 수가 3페이지 초과

오류 예시:

5페이지 생성: 홈, 상세, 생성, 편집, 설정

결과: MVP 범위가 통제 불능 상태가 되고 Tech 및 Code 단계의 작업량이 크게 증가합니다.

권장 사항: 1-3페이지로 제한하고 핵심 사용 경로에 집중하세요.

함정 4: 프로토타입에 인터랙션 피드백 부족

오류 예시:

버튼에 hover 상태가 없고, 링크에 cursor-pointer가 없음

결과: 사용자 경험이 좋지 않고 프로토타입이 현실적이지 않습니다.

권장 사항: 모든 클릭 가능한 요소에 cursor-pointer 및 hover 상태 추가(150-300ms 전환).

함정 5: 밝은 모드 대비율 부족

오류 예시:

글라스 카드 배경색 bg-white/10(너무 투명), 텍스트 색상 #94A3B8(너무 밝음)

결과: 밝은 모드에서 콘텐츠가 보이지 않고 접근성 기준에 부합하지 않습니다.

권장 사항:

글라스 카드 밝은 모드에서는 bg-white/80 이상 사용
텍스트 대비율 >= 4.5:1(WCAG AA 기준)

함정 6: 프로토타입과 schema 불일치

오류 예시:

schema에는 2페이지가 정의되어 있는데 프로토타입에는 3페이지가 표시됨

결과: Tech 및 Code 단계가 혼란스러워지며 어느 것을 따라야 할지 모릅니다.

권장 사항: 프로토타입과 schema가 완전히 일치하는지 확인하고, 페이지 수와 컴포넌트 구조가 반드시 대응되도록 하세요.

챕터 요약

UI 단계의 핵심은 디자인 시스템입니다:

입력: 명확한 PRD 문서(artifacts/prd/prd.md)
과정: AI 어시스턴트가 ui-ux-pro-max 스킬을 통해 전문 디자인 시스템 생성
출력: ui.schema.yaml(디자인 시스템 + 인터페이스 구조) + preview.web/index.html(미리보기 가능한 프로토타입)
검증: 디자인 시스템이 전문적인지, 프로토타입이 미리보기 가능한지, AI 기본 스타일을 피했는지 확인

핵심 원칙

❌ 하지 말 것: 기술 스택 결정, 프론트엔드 코드 작성, AI 기본 스타일 사용
✅ 할 것: 디자인 시스템 생성, 인터페이스 구조 설계, 미리보기 가능한 프로토타입 생성

다음 챕터 미리보기

다음 챕터에서는 **4단계: Tech - 기술 아키텍처 설계**를 학습합니다.
다음을 배우게 됩니다:
PRD와 UI Schema를 기반으로 기술 아키텍처를 설계하는 방법
적합한 기술 스택 선택 방법(Express + Prisma + React Native)
최소 실행 가능한 데이터 모델 설계 방법(Prisma Schema)
Tech 단계에서 UI 구현 세부사항을 다루지 않는 이유

부록: 소스 코드 참조

클릭하여 소스 코드 위치 확인

업데이트 날짜: 2026-01-29

기능	파일 경로	행 번호
UI Agent 정의	`agents/ui.agent.md`	1-98
UI 스킬	`skills/ui/skill.md`	1-430
파이프라인 정의(UI 단계)	`pipeline.yaml`	34-47
스케줄러 정의	`agents/orchestrator.checkpoint.md`	1-100+

핵심 제약 조건:

ui-ux-pro-max 스킬 강제 사용: ui.agent.md:33, 53-54
AI 스타일 컬러 금지: ui.agent.md:36
emoji 아이콘 금지: ui.agent.md:37
cursor-pointer 및 hover 상태 필수 추가: ui.agent.md:38
프로토타입 페이지 3페이지 이내: ui.agent.md:34
네이티브 HTML/CSS/JS 사용: ui.agent.md:35

종료 조건(pipeline.yaml:43-47):

ui.schema.yaml 존재
페이지 수 3페이지 이내
미리보기 페이지가 브라우저에서 열릴 수 있음
Agent가 ui-ux-pro-max 스킬을 사용하여 디자인 시스템 생성

UI 스킬 내용 프레임워크:

사고 프레임워크: 목적, 톤, 차별화, 정보 아키텍처
디자인 시스템 생성 워크플로우: 요구사항 분석 → 디자인 시스템 생성 → 보조 검색 → 기술 스택 가이드 획득
67가지 UI 스타일: 미니멀리즘, 뉴모피즘, 글래스모피즘, 브루탈리즘 등
업계 추론 규칙: 100가지 규칙, 제품 유형별 디자인 시스템 자동 추천
디자인 시스템 가이드: 색상 체계, 타이포그래피 시스템, 간격 시스템, 컴포넌트 규범
전달 전 검사 목록: 시각적 품질, 인터랙션, 밝은/어두운 모드, 레이아웃, 접근성
결정 원칙: 목표 주도, 모바일 우선, 접근성, 간결 제한, 미리보기 일치, 도구 우선
하지 말 것(NEVER): AI 스타일 폰트/컬러, emoji 아이콘, 낮은 대비율, 3페이지 초과 등

3단계: UI - 인터페이스 및 프로토타입 설계 ​

이 챕터를 완료하면 다음을 할 수 있습니다 ​

현재 당신이 직면한 문제 ​

언제 사용하는가 ​

🎒 시작 전 준비 ​

핵심 접근 방식 ​

UI 단계란 무엇인가? ​

왜 디자인 시스템이 필요한가? ​

출력 파일 구조 ​

따라하기 ​

1단계: PRD 완료 확인 ​

2단계: 파이프라인을 UI 단계로 시작 ​

3단계: AI 어시스턴트가 UI Agent 정의 읽기 ​

4단계: ui-ux-pro-max 디자인 시스템 강제 사용(핵심 단계) ​

5단계: 인터페이스 구조 설계 ​

6단계: 미리보기 프로토타입 생성 ​

7단계: UI 출력 확인 ​

8단계: 계속, 재시도 또는 일시중지 선택 ​

함정 주의 ​

함정 1: ui-ux-pro-max 스킬을 사용하지 않음 ​

함정 2: AI 기본 스타일 사용 ​

함정 3: 페이지 수가 3페이지 초과 ​

함정 4: 프로토타입에 인터랙션 피드백 부족 ​

함정 5: 밝은 모드 대비율 부족 ​

함정 6: 프로토타입과 schema 불일치 ​

챕터 요약 ​

다음 챕터 미리보기 ​

부록: 소스 코드 참조 ​

3단계: UI - 인터페이스 및 프로토타입 설계

이 챕터를 완료하면 다음을 할 수 있습니다

현재 당신이 직면한 문제

언제 사용하는가

🎒 시작 전 준비

핵심 접근 방식

UI 단계란 무엇인가?

왜 디자인 시스템이 필요한가?

출력 파일 구조

따라하기

1단계: PRD 완료 확인

2단계: 파이프라인을 UI 단계로 시작

3단계: AI 어시스턴트가 UI Agent 정의 읽기

4단계: ui-ux-pro-max 디자인 시스템 강제 사용(핵심 단계)

5단계: 인터페이스 구조 설계

6단계: 미리보기 프로토타입 생성

7단계: UI 출력 확인

8단계: 계속, 재시도 또는 일시중지 선택

함정 주의

함정 1: ui-ux-pro-max 스킬을 사용하지 않음

함정 2: AI 기본 스타일 사용

함정 3: 페이지 수가 3페이지 초과

함정 4: 프로토타입에 인터랙션 피드백 부족

함정 5: 밝은 모드 대비율 부족

함정 6: 프로토타입과 schema 불일치

챕터 요약

다음 챕터 미리보기

부록: 소스 코드 참조