preview-first (미리보기 우선)

preview-first (미리보기 우선)은(는) 무엇을 하나요?

만들기 전에 먼저 보세요. 이 스킬은 애플리케이션 코드를 작성하기 전에 디자인 단계를 삽입합니다. 개발자는 브라우저에서 여러 개의 완전하고 명확히 다른 디자인 방향을 보고, 하나를 선택하면 그 선택은 이후 모든 세션이 따르는 문서화된 계약이 됩니다.

이것은 디자인 스튜디오 단계이지, 웹사이트 생성기가 아닙니다. 이 스킬은 절대 개발자의 애플리케이션 코드를 작성하지 않습니다. 결정과 계약을 생성합니다. 스크립트는 결정론적이며 표준 라이브러리 Python으로 작성되었습니다. 판단(브리프 읽기, 방향 이름 짓기, 카피 작성)은 당신의 몫입니다.

언제 실행하고, 언제 제안할지

개발자가 웹 프로젝트를 시작, 재시작 또는 재설계하려고 할 때 전체 단계를 실행하세요: "X를 위한 랜딩 페이지를 만들어 줘", "프론트엔드 시작", "이 디자인이 마음에 안 들어", "색상과 폰트 골라 줘", 또는 명시적인 /preview-first.

프로젝트에 UI 코드는 있지만 design/DESIGN.md가 없을 때는 한 줄로 제안하세요: "먼저 디자인 방향을 보고 싶으신가요? 현재 모습을 대안들과 함께 보여드릴 수 있습니다." 수락되면 현재 디자인을 방향 중 하나로 가져와(임포트 섹션 참조) 동등한 조건으로 비교합니다.

이미 스타일링된 앱에 대한 작은 편집("버튼 추가", "패딩 수정")에는 절대 실행하지 마세요. design/DESIGN.md가 존재하면 핸드오프 후 단계로 건너뜁니다.

흐름

모든 스크립트는 이 스킬의 scripts/ 디렉토리에 있습니다. python3(또는 프로젝트에서 uv를 사용하는 경우 uv run python3)로 실행하세요. 아래 경로는 프로젝트 루트를 기준으로 합니다.

1. 프로젝트 읽기, 최대 네 가지 질문

묻기 전에 존재하는 것을 먼저 읽으세요: package.json, Tailwind 설정, CSS 커스텀 속성, 로고 SVG, 기존 폰트, README. 발견된 모든 것은 질문이 아닌 제약 조건입니다.

저장소가 답할 수 없는 것만 평범한 언어로, 한 번의 메시지로 물어보세요:

1. 제품은 무엇이며, 누구를 위한 것인지 한 문장으로.
2. 어떻게 느껴져야 하는지 세 단어, 또는 존경하는 사이트 하나.
3. 고정된 것: 브랜드 색상, 로고, 폰트, 라이트 또는 다크 전용.
4. 어떤 종류의 페이지가 가장 중요한지: 마케팅, 앱, 콘텐츠 또는 스토어.

2. 브리프 작성

답변을 정규화하여 .design-preview/brief.json에 저장합니다:

{
  "product": "Ledgerline, 프리랜서 개발자를 위한 인보이싱 도구",
  "audience": "개인 개발자 및 소규모 스튜디오",
  "product_type": "product-type.saas",
  "moods": ["정확한", "차분한", "신뢰할 수 있는"],
  "page_type": "marketing",
  "constraints": {"brand_colors": ["#154d8c"], "fonts": [], "scheme": "both"},
  "admired": ["https://linear.app"],
  "words": {"name": "Ledgerline", "tagline": "git 로그와 일치하는 인보이스"}
}

자유 텍스트를 노드 ID로 매핑하려면 recommend.py --list product-types 및 --list moods를 사용하세요. 알 수 없는 단어도 괜찮습니다. 추천기는 별칭과 토큰 중복을 통해 대체됩니다. product_type의 자유 텍스트도 허용됩니다.

3. 카피 작성 후 1분 이내에 미리보기 열기

먼저 .design-preview/copy.json을 작성하세요. 한 번의 짧은 답변이면 되며, 이것이 초안을 템플릿이 아닌 제품 그 자체로 읽히게 만듭니다. 제품 자체의 명사를 사용하세요: 내비게이션은 제품 섹션이고, 기능은 제품이 하는 일이며, 헤드라인은 사용자가 반복할 주장입니다.

{
  "headline": "501, 크리켓, 라운드 더 클록 실시간 점수",
  "subhead": "Oche가 점수를 관리하니 선수들은 게임에 집중합니다.",
  "lead": "펍 리그 선수와 집에서 친구들과 즐기는 이들을 위해.",
  "cta_primary": "새 게임", "cta_secondary": "재개",
  "nav": ["게임", "선수", "통계", "설정"],
  "features": [{"title": "체크아웃 경로가 포함된 501 및 301", "body": "남은 점수마다 표준 체크아웃 경로를 표시합니다."}],
  "proof": "", "meta": {"city": "리즈", "year": "2026"},
  "footer": "Oche가 점수를 관리합니다."
}

그런 다음 한 명령:

python3 <skill>/scripts/quick_start.py --brief .design-preview/brief.json --copy .design-preview/copy.json --count 5 --open

번들을 추천하고, directions.json을 작성하며, 미리보기를 빌드하고 서버를 시작합니다. 개발자에게 URL을 즉시 제공하세요. --copy를 건너뛰면 브리프 자체의 명사에서 파생된 카피를 사용합니다. 완성된 방향으로 제시하기 전에 이런 상태로 두지 마세요. 개발자가 보는 동안 directions.json(이름, 근거, 레이아웃, 프로그램)을 다듬고 재빌드하세요. 페이지는 같은 URL로 다시 로드됩니다.

모든 미리보기 페이지는 상단 바에 세 개의 생성기를 제공하므로 개발자가 더 많은 것을 얻기 위해 돌아올 필요가 없습니다: 서프라이즈 미(사용되지 않은 스타일, 어울리는 팔레트 및 페어링, 아이디어, 섹션, 프로그램의 무작위 조합으로 구성된 무작위 방향), 변형(현재 보고 있는 방향의 다섯 가지 버전: 동일한 스타일, 다른 팔레트, 페어링, 아이디어 및 프로그램), 그리고 갤러리에서는 모든 스타일 보기(이 브리프에 대한 스타일당 하나의 방향). 각각은 동일한 버튼이 있는 새 초안으로 이동합니다. 터미널: random_direction.py --directions .design-preview/directions.json --build .design-preview [--like B | --all].

3a. 수동 후보 번들

python3 <skill>/scripts/recommend.py --brief .design-preview/brief.json --count 4

각 번들은 스타일, 팔레트, 타입 페어링, 컴포넌트 처리, 모션 패턴, 아이콘 세트 및 812개의 디자인 아이디어(분할 내비게이션 및 실시간 시계, 스페시멘 히어로, 거대 숫자, 필름 그레인, 브래킷 버튼, 콜로폰 푸터와 같은 출처가 명확한 아이디어)로 구성되며, 이를 정당화한 그래프 엣지와 교체 가능한 라이브 대안이 포함됩니다. 다양성이 강제됩니다: 구별되는 스타일 패밀리, 한 온도의 최대 두 팔레트, 한 유형 카테고리의 최대 두 페어링, 팔레트나 페어링이 두 번 사용되지 않음. 기본적으로 35개의 번들이며, 개발자가 더 보기를 요청하면 최대 8개까지 가능합니다. 3개 미만으로 낮추지 마세요. 브리프가 좁은 경우(다크 전용, 하나의 브랜드 색상)에도 말하고 여전히 세 개를 보여주세요.

4. directions.json 작성

번들을 .design-preview/directions.json(스키마는 knowledge/schema.json, files.directions 참조)으로 변환합니다. 각 방향에 대해 스크립트가 할 수 없는 것을 제공하세요:

• name: 스타일이 아닌 아이디어("Ledger", "Greenhouse", "Night shift"). 절대 "Modern" 또는 "Clean"이 아닙니다.
• rationale: 브리프 자체의 단어를 인용하고 이 방향이 브리프에 어떻게 응답하는지 설명하는 한 문단. 하나의 대담한 선택과 조용히 유지되는 것을 언급하세요.
• copy: 브리프의 실제 카피: 헤드라인, 서브헤드, 두 개의 행동 유도 문구, 네 개의 내비게이션 레이블, 제목과 한 문장 설명이 있는 세 개에서 여섯 개의 기능, 정직한 증명 라인(또는 빈 값), 필드 레이블이 있는 폼 제목과 제출 텍스트, 푸터 라인. 문장 케이스, 능동태, 제품 명사, 대시 없음, 이모지 없음, 화살표 없음, "당신이 X이든 Y이든" 없음, 삼단 비교 없음, 로렘 입숨 없음, 가상의 숫자 없음. 카피는 방향의 어조가 실제로 다른 경우를 제외하고 모든 방향에서 동일합니다.
• layout (선택 사항): 섹션 변형을 재정의합니다. 그렇지 않으면 방향의 아이디어와 스타일의 기본값이 선택합니다.
• bundle.ideas (유지 또는 편집): 추천기가 첨부한 아이디어. 제품에 맞지 않는 것은 하나 삭제하고, 브리프나 존경하는 사이트가 요청하면 recommend.py --list ideas에서 하나 추가하세요. 렌더링 훅이 있는 아이디어는 초안을 변경하고, 나머지는 계약서에 포함됩니다.
• copy.numbers 및 copy.stats (선택 사항): 출처가 있는 수치 {value, label, source}. 숫자 히어로와 통계 벽은 이것들이 존재할 때만 렌더링되며, 절대 가상의 수치로 렌더링하지 않습니다.
• copy.meta (선택 사항): {"city": "리스본"} (분할 내비, 콜로폰, 오버레이 시계용).
• 제품 유형은 주제 키트(아트워크 종류, 터미널, 잔고, 일정, 작곡가, 점수판과 같은 주제 컴포넌트 및 제품 명사)를 전달합니다. 첫 번째 화면과 그 다음 섹션에서 이를 사용하므로 점수판은 점수로 열리고 상점은 제품으로 열립니다. layout.topic을 none으로 설정하여 주제 컴포넌트를 제거하세요.
• overrides (선택 사항): {"brand_primary": "#hex", "brand_accent": "#hex"} 브리프가 브랜드 색상을 고정하는 경우. 빌더가 대비 색상을 다시 계산하고 대비 실패를 보고합니다.

빌드하기 전에 모든 방향에 대해 references/anti-patterns.md의 안티-텔 검사를 실행하세요. 브리프가 이름을 명시적으로 요청하지 않는 한 텔을 거부하고, 요청한 경우 근거에 그렇게 명시하세요.

첫 번째 화면 규칙: 어떤 방향도 일반 템플릿(중앙 헤드라인, 두 개의 버튼, 스크린샷, 세 개의 동일한 카드)으로 시작하지 않습니다. 각 스타일은 존경하는 사이트에서 관찰된 레이아웃 원형(캡션이 있는 그림이 포함된 진술 단락, 평평한 디스크를 감싸는 타입, 제품 우선 스테이지, 객체 옆 디스플레이 폰트, 전체 블리드 아트, 사이드바 인덱스, 포스터 타입)과 팔레트에서 생성된 아트워크(청사진, 등각 투영 도형, 터미널, 스위스 구성, 등고선, 하프톤, 궤도 링, 스티커, 스파크라인, 단일 마크)를 기본값으로 사용합니다. 브리프가 특별히 친숙한 모양을 요청하지 않는 한 이러한 기본값을 유지하세요. 방향 중 적어도 두 개는 distinct로 표시된 스타일에서 가져옵니다. 추천기가 이를 강제하며, 또한 두 방향이 내비게이션 장치, 첫 화면 장치 또는 텍스처를 공유하지 않도록 합니다.

5. 미리보기 빌드 및 열기

python3 <skill>/scripts/build_preview.py --directions .design-preview/directions.json
python3 <skill>/scripts/serve_preview.py --dir .design-preview --open

build_preview.py는 .design-preview/를 작성합니다: 갤러리와 각 방향에 대한 스타일 타일(두 모드 모두에서 대비 등급이 있는 팔레트, 타이포그래피 스케일, 간격, 반경, 높이, 아이콘, 모든 상태의 모든 컴포넌트, 재생 가능한 모션 패턴), 브리프 페이지 유형에 대한 초안 페이지, 그리고 가장 인기 있는 휴대폰, 폴더블, 태블릿 및 노트북의 CSS로 그려진 프레임 안에 실제 뷰포트 크기로 초안을 렌더링하는 기기 보기. 모든 페이지의 컨트롤로 팔레트, 타입 페어링, 반경, 밀도, 모션 레벨 및 테마를 실시간으로 전환할 수 있습니다.

serve_preview.py는 분리된 localhost 서버를 시작하고, .design-preview/server.json을 작성하며, URL을 출력하고 즉시 반환합니다. 오프라인 세션을 위해 빌드에 --vendor-fonts를 추가하세요. 그렇지 않으면 웹 폰트 로드 실패 시 타일에 표시되는 알림이 나타납니다.

브라우저를 열 수 없는 경우(SSH, 컨테이너, CI), URL과 각 방향의 한 줄 설명을 출력하고 채팅을 계속 진행하세요.

6. 개발자에게 알리고 기다리기

무엇을 빌드했는지 말하고, URL을 제공하며, 각 방향을 한 줄로 설명하고 멈추세요. 그들을 위해 선택하지 말고, 코딩을 시작하지 말고, 폴링하지 마세요. 개발자는 미리보기에서 오랜 시간을 보낼 수 있습니다. 그들이 응답하면:

• .design-preview/selection.json이 존재하면 읽으세요. 선택한 방향 ID와 최종 선택한 라이브 재정의(팔레트, 페어링, 반경, 밀도, 모션, 테마)가 저장되어 있습니다.
• 그렇지 않으면 그들의 말("B", "어두운 거", "D의 타입을 가진 A")에서 선택을 가져와 일치하는 재정의로 직접 selection.json을 작성하세요.
• 변형("B지만 더 따뜻하게", "모서리를 덜 둥글게", "헤드라인 폰트 바꾸기")의 경우 directions.json을 편집하거나 번들의 대안을 사용하고 재빌드하여 같은 URL로 다시 안내하세요. 서버는 계속 실행 중입니다. 페이지를 새로고침하도록 요청하세요.
• "더 보여줘"의 경우 recommend.py를 --count 5 또는 변경된 브리프와 함께 다시 실행하고, 새 ID로 새 방향을 추가하고 재빌드하세요.

serve_preview.py --dir .design-preview --wait 1800는 선택이 있을 때까지 차단됩니다(스크립트 사용 전용). --status 및 --stop으로 서버를 관리합니다.

7. 계약 내보내기

python3 <skill>/scripts/export_design.py --selection .design-preview/selection.json \
  --directions .design-preview/directions.json --project .

이 명령은 design/DESIGN.md(계약서: 아이덴티티, 출처와 빌드 노트가 포함된 디자인 아이디어, 대비 테이블이 있는 팔레트, 타이포그래피, 간격 및 반경, 높이, 레이아웃, 상태와 토큰이 있는 모든 컴포넌트, 모션 토큰 및 허용된 패턴, 아이콘그래피, 이미지, 글쓰기 스타일, 접근성 기준, 기기 확인 및 "하지 말아야 할 것" 목록), design/tokens.json(W3C 디자인 토큰 형식), design/tokens.css, Tailwind v4가 감지되면 design/tailwind.css, CLAUDE.md의 포인터 라인, 그리고 .design-preview/에 대한 .gitignore 항목을 작성합니다. 재내보내기는 "프로젝트 노트" 섹션을 유지하고 이전 파일을 design/history/에 복사합니다.

작성된 내용과 개발자가 커밋해야 할 항목(design/ 및 CLAUDE.md 라인)을 한 짧은 메시지로 확인하세요. 그런 다음 계약서에 따라 빌드하세요.

핸드오프 후

design/DESIGN.md가 존재할 때마다:

• UI 변경 전에 항상 읽으세요. 컴포넌트에서 --pf-* 토큰(design/tokens.css에서 제공)을 사용하고, 원시 헥스, 픽셀 또는 밀리초 값을 사용하지 마세요.
• 허용된 모션 패턴과 모션 레벨을 준수하세요. 축소된 모션을 존중하세요.
• 모든 새로운 색상 쌍에 대해 contrast.py FG BG --role body|label|large|ui를 실행하세요.
• "하지 말아야 할 것" 목록을 따르세요. 요청이 계약과 충돌할 때는 말하고, 조용히 이탈하는 대신 단계를 다시 실행하도록 제안하세요.
• 중요한 페이지가 빌드된 후 기기 확인을 제공하세요: 같은 프레임에서 실제 페이지를 보려면 .design-preview/<id>/devices.html?url=http://localhost:PORT/path를 여세요. 프레임 차단 헤더를 보내는 페이지는 표시할 수 없습니다. 그렇게 말하세요.
• design/DESIGN.md의 자유 섹션(끝 마커 아래)은 프로젝트 결정을 위해 남겨두세요.

임포트

프로젝트의 현재 모양이나 개발자가 존경하는 사이트를 방향으로 비교하려면:

python3 <skill>/scripts/import_direction.py --css src/styles.css --into .design-preview/directions.json --name "현재"
python3 <skill>/scripts/import_direction.py --tailwind tailwind.config.js --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --tokens design-tokens.json --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --url https://example.com --into .design-preview/directions.json --name "참조"

임포트는 팔레트, 페어링 및 가장 가까운 스타일을 도출한 후 재빌드합니다. 임포트된 팔레트는 다른 것과 마찬가지로 검사되며, 실패는 타일에 표시됩니다.

지식 및 새로고침

결정은 knowledge/graph.json에서 나옵니다: 스타일, 팔레트(OKLCH, 두 모드 모두), 타입 페어링, 컴포넌트 처리, 모션 패턴, 제품 유형, 분위기, 아이콘 세트, 플랫폼 기능, 참조 사이트가 가중치가 있는 pairs_with, suits, avoid_with, requires, excludes 엣지로 연결됩니다. 정기적인 업데이트를 위해 python3 <skill>/scripts/pull_repos.py를 실행하거나 수동으로 knowledge/ 파일을 편집하세요. 새로고침 후 python3 <skill>/scripts/rebuild_graph.py를 실행하여 graph.json을 다시 만드세요.