webflow-build

Webflow 빌드: 승인된 디자인 → Webflow, 섹션별로

모든 디자인 결정은 사람이 승인하고, Claude는 빌드, 검증 및 보고합니다. 섹션은 승인된 디자인과 모든 너비에서 일치하고, 모든 도착 방식에서 정상 작동하며, 수동 단계가 나열된 경우에만 완료된 것으로 간주됩니다.

• checklists.md는 모든 단계를 게이트합니다: 디자인 핸드오프, Webflow 기초, 미디어 페이지, 각 컴포넌트, 완성된 각 페이지 및 빌드 핸드오프. 진행 상황은 pnpm progress 명령어로 docs/handoff/progress.json에 기록되며(checklists.md › 진행 상황 기록 방법), Bench의 Tasks 패널에 표시됩니다.
• conventions.md는 모든 빌드가 시작하는 페이지 및 섹션 구조, 클래스 및 변수 명명 규칙, 컴포넌트, CMS 및 스타일 가이드 패턴을 설정합니다.
• lessons/는 이전 빌드에서 시간이 많이 소요되었던 내용을 영역별로 담고 있습니다. 작업하려는 영역의 파일을 읽으십시오.
• 프로토타입은 항상 먼저 옵니다: 피그마 파일에서 페이지별로 Bench에서(또는 Claude가 터미널에서 동일한 단계로) 빌드되며, Webflow에서 무언가를 빌드하기 전에 클라이언트가 승인합니다. 단계는 아래에 있습니다(프로토타입, 피그마에서). webflow-prototype 스킬에는 프로젝트 설정, 입력, 스냅샷 및 스타일 가이드가 있으며, figma.md에는 피그마 파일 읽는 방법이 있습니다.
• rules.md는 모든 Webflow 스킬이 공유하는 규칙(승인 없이 커밋 또는 푸시 금지, Designer 우선, 채팅에 자격 증명 없음, 수동 단계, 레슨), 세션 마무리 및 기여 방법을 담고 있습니다.
• starter-site.md는 프로젝트가 복제하는 스타터 Webflow 사이트를 설명하며, 기본 시스템이 이미 포함되어 있습니다.
• webflow-style-guide 스킬은 모든 사이트가 사용하는 단일 레이아웃으로 스타일 가이드 페이지(프로토타입 및 Webflow 빌드의 첫 번째 페이지)를 만듭니다.
• media.md는 미디어 페이지입니다: 사이트의 비디오가 업로드되어 Webflow가 변환 및 호스팅하는 곳이며, 첫 번째 비디오 재생 페이지보다 먼저 빌드됩니다.
• 이미 라이브인 사이트는 빌드 대상이 아닙니다: webflow-audit 스킬을 사용하세요(감사 후 소규모 검증 배치, 일회성 수정에도 사용).
• 빌드 핸드오프 후 webflow-launch 스킬이 인계받습니다: 런칭 전 QA, 런칭 당일, 클라이언트 핸드오프 및 첫 30일.

모든 체크리스트 항목은 누가 수행하는지 명시합니다:

• [Claude] Claude가 수행합니다(MCP, 저장소 또는 스크립트를 통해).
• [Claude 확인] Claude가 확인하고 보고하며, 사람이 Claude가 할 수 없는 부분을 수정합니다.
• [사람] 사람이 수행합니다(클라이언트, PM, 디자이너, DNS, 계정). Claude는 상기시키고 추적할 수 있으며, 절대 수행했다고 주장하지 않습니다.

세션 시작 (모든 세션)

1. 워크스페이스의 CLAUDE.md, 그 다음 이 저장소의 AGENTS.md와 GOTCHAS.md, 그 다음 docs/handoff/(HANDOFF.md, MANUAL-TODO.md, BUILD-NOTES.md, 그리고 리뷰 단계가 시작되면 REVIEW.md)를 읽습니다. lessons/README.md를 훑어보고 오늘 작업 영역의 레슨 파일을 읽습니다(MCP 작업: lessons/mcp.md). 이미 기록된 실수를 절대 반복하지 마십시오.
2. 프로젝트 메모리를 읽습니다: 마지막 세션이 중단된 위치, 열려 있는 수동 단계, 미해결 질문. pnpm progress show를 실행하여 단계, 아직 열려 있는 체크리스트 및 사람의 할 일을 확인합니다. 현재 상황과 다음 단계를 한 줄로 말합니다. 페이지나 섹션이 명확하지 않으면 물어봅니다.
3. 첫 번째 Webflow 배치 전에 checklists.md의 빌드 전을 실행합니다. 프로토타입 단계는 완료되기 전에 실행합니다(입력은 webflow-prototype의 입력입니다). conventions.md의 변경 사항을 디자이너와 동의합니다. 입력이 누락된 경우 요청하십시오. 콘텐츠, 상태 또는 SEO 필드를 추측하지 마십시오.
4. Webflow MCP: webflow_guide_tool을 한 번 호출한 다음, 세션 전체에 하나의 세션 ID와 에이전트 ID를 재사용합니다.
5. 프로토타입 개발 서버가 실행 중이고 webflow-build.config.json이 존재합니다(pnpm new-project가 작성, webflow-prototype › 프로젝트 설정).
6. 오늘의 범위는 한 페이지입니다(작업 리듬 참조). 어느 페이지인지 말합니다.

상시 규칙

공유 규칙은 rules.md에 있습니다. 빌드에는 다음이 추가됩니다:

• 클래스와 변수를 생성, 편집 또는 제거하기 전에 한 번에 한 배치씩, 이름과 값을 포함하여 질문하십시오. 이를 명확히 암시하는 요청(예: 목업 승인 후 "Webflow에 빌드")은 OK로 간주합니다.
• 게시는 사이트가 라이브인지 여부에 따라 다릅니다.
  • 새 빌드(커스텀 도메인이 연결되지 않음): webflow.io 스테이징 도메인에 게시해도 괜찮습니다.
  • 라이브 사이트: 게시는 사이트 전체에 적용됩니다. 다른 사람의 미완료 편집을 포함하여 보류 중인 모든 것을 전송합니다. 스테이징에만 게시하고, 무엇이 함께 라이브로 갈지 확인한 후, 사람이 "게시"라고 입력할 때까지 기다렸다가 커스텀 도메인에 게시하십시오(webflow-audit에 단계가 있습니다).
  • 묻지 않고 커스텀 도메인에 게시하거나, 릴리스를 하거나, DNS를 변경하지 마십시오.
• 모든 Webflow 쓰기 배치 후에 두 가지를 말하십시오: "Designer를 새로고침하세요" (열린 Designer 탭은 MCP 변경 사항을 표시하지 않으며, 오래된 탭에서 저장하면 덮어쓸 수 있음), 그리고 아직 게시되지 않은 것이 무엇인지.
• 페이지에 수동 단계를 표시하십시오. 요소나 스타일 가이드의 샘플 옆에 data-manual-todo="<문자>"와 텍스트 "수동 단계 <문자>: <내용>"이 포함된 Caption으로 표시합니다. 캔버스와 스테이징에 표시되므로 아무도 미완성 상태를 디자인으로 리뷰하지 않습니다. 해당 행을 완료하는 배치에서 제거하십시오. 빌드 핸드오프나 런칭 시점에 남아 있어서는 안 됩니다(게시된 HTML에서 data-manual-todo를 검색).

프로토타입, 피그마에서

모든 사이트는 피그마 파일에서 시작됩니다. 프로토타입은 파일에서 페이지별로 빌드되며, Webflow에서 무언가를 빌드하기 전에 승인됩니다.

Bench에서. 클라이언트 추가 › 피그마 디자인에서 클라이언트 폴더, 이 템플릿의 저장소 및 빈 prototype/(prototype-starter/의 복사본)을 설정합니다. 피그마 디자인에서 프로토타입 빌드는 프레임을 페이지로 그룹화합니다. 사람이 페이지를 선택하고 순서를 정하며, 각각의 주소를 지정합니다. 그런 다음 하나의 AI 작업이 한 번에 한 페이지씩 빌드합니다: 각 페이지는 자체 메시지와 해당 프레임의 노드 ID와 함께 제공됩니다. 빌드된 각 페이지는 Compare › With Figma에 대해 자체 피그마 프레임을 유지합니다. Bench는 클라이언트가 열 때와 매시간 파일을 확인하고, 프레임이 변경된 페이지를 업데이트하도록 제안합니다: 해당 프레임에서 변경된 내용만 변경하고, 그 이후 프로토타입에서 이루어진 편집 내용은 유지합니다.

Bench가 아닌 경우, Claude는 터미널에서 동일한 단계를 따릅니다: 프레임을 나열하고, 사람과 페이지, 순서 및 주소에 동의한 다음, 한 번에 한 페이지씩 빌드합니다.

한 페이지:

1. 해당 프레임. 데스크탑, 태블릿 및 모바일에서 동일한 이름의 프레임은 하나의 페이지입니다. Figma 커넥터(get_design_context, get_screenshot, get_variable_defs) 또는 Figma 앱의 MCP 서버(figma.md)를 사용하여 각각을 읽습니다. 태블릿 프레임이 없으면: 데스크탑과 모바일 사이에서 태블릿을 그립니다. 모바일 프레임이 없으면: 더 큰 프레임에서 휴대폰에서 작동하도록 만들고, 그렇게 말합니다. 페이지가 아닌 프레임(스타일 가이드)은 토큰, 유형 및 컴포넌트를 위해 읽습니다.
2. 토큰 파일의 변수 및 텍스트 스타일에서 CSS 사용자 정의 속성으로: 스냅샷 변수의 변경 사항과 src/css/proposed.css의 새로운 변수(이전 → 새), conventions.md §4에 따라 이름 지정됨, 생성된 tokens.css에는 절대 넣지 않음.
3. 글꼴 텍스트 스타일이 사용하는 글꼴, public/fonts/에 라이센스와 함께, src/css/prototype.css에 선언되고 partials/head.html에서 사전 로드됨.
4. 이미지 파일에서 prototype/images/로 내보내짐: 사진은 디자인에서 사용하는 가장 큰 크기의 WebP, 아이콘은 SVG.
5. 파일에 있는 내용만. 파일에 제공되지 않은 값, 상태, 텍스트 또는 이미지는 질문입니다: 발명하기 전에 물어보십시오(Bench에서는 mcp__bench__todo_add로 추가하고 계속 진행).
6. 위치: Webflow 주소의 prototype/<page>/index.html(홈은 prototype/index.html), prototype/vite.config.js의 pages에 추가됨. Nav와 footer는 공유 파셜입니다. 해당 페이지만 변경하고, 필요한 파셜과 토큰만 변경하십시오. 커밋, 푸시 또는 게시하지 마십시오.
7. 확인 데스크탑, 태블릿 및 모바일에서 해당 프레임 옆에서, 그리고 Figma 프로토타입의 링크가 작동하는지 확인합니다(메뉴, 탭, 양식).

그런 다음 페이지는 프로토타입 페이지 완료(webflow-prototype의 checklists.md)를 실행하고 사람이 승인합니다(Bench에서: 페이지에서 마우스 오른쪽 버튼 클릭). checklists.md의 프로토타입 단계는 클라이언트의 서면 승인까지 모든 것을 추적합니다:

• 각 페이지가 데스크탑, 태블릿 및 모바일에서 Figma 프레임과 일치함(Bench의 "Matches the Figma frame" 확인);
• Figma 파일이 클라이언트에 연결됨;
• 프레임이 선택되고, 순서대로, 각각 페이지 주소가 있음;
• 선택된 모든 프레임이 프로토타입 페이지로 빌드됨;
• 토큰, 글꼴 및 이미지가 파일에서 제공됨, 조작된 내용 없음;
• Figma 프로토타입의 링크가 작동함;
• 각 페이지가 프로토타입에서 승인됨;
• 클라이언트가 프로토타입을 서면으로 승인함.

빌드 순서

프로토타입 단계가 완료되면 시작됩니다. 구조와 이름은 conventions.md를 따릅니다. 각 단계는 checklists.md에서 게이트됩니다:

1. 변수;
2. 태그 스타일(Designer에서 한 번 설정하여 MCP가 접근할 수 있도록);
3. 클래스;
4. CMS 컬렉션;
5. 저장소 포트(프로토타입의 모듈 및 저장소 CSS) 및 로더, 스테이징이 실제 코드를 실행하도록 → 기초 완료;
6. 스타일 가이드 페이지, 첫 번째로 빌드되는 페이지(webflow-style-guide 스킬) → 스타일 가이드 기초 완료;
7. 미디어 페이지, 어떤 페이지든 비디오를 재생할 때(media.md) → 미디어 완료;
8. 컴포넌트, 실제 페이지 마크업에서 빌드(스타일 가이드 미리보기에서 절대 안 함), 각각 자체 스타일 가이드 행 추가 → 컴포넌트 완료;
9. 페이지, 섹션별로 → 페이지 완료;
10. 스타일 가이드 최종 확인, 그 다음 빌드 핸드오프;
11. 리뷰 단계: docs/handoff/REVIEW.md는 페이지별로 빌드된 내용, 각 피드백 라운드 및 런칭 전 남은 작업을 나열하며, webflow-launch 스킬이 인계받을 때까지 계속됩니다.

스타터에서 복제된 사이트는 이미 단계 1~3의 기초와 페이지 셸을 가지고 있습니다. 프로젝트는 거기에 추가합니다. 각 가져오기 전에 pnpm wf:preflight를 실행하고, pnpm wf:styles로 클래스 배치를 계획합니다(확인 참조).

섹션 루프

각 섹션에 대해, 페이지 순서대로:

1. 프로토타입을 읽습니다: 마크업, CSS 및 이를 애니메이션하는 모듈, 상태 및 상호작용 사양을 위한 페이지의 Figma 프레임과 함께. 모든 data-* 훅, id 및 aria 속성을 기록합니다.
2. Webflow가 무엇을 가지고 있는지 확인합니다: 클래스(query_styles), 컴포넌트 및 해당 props, CMS 필드, 에셋. 만들기 전에 재사용합니다. 새 항목의 이름은 conventions.md(섹션 2-4)에 따라 지정합니다.
3. 빌드, 다음 순서로 선호:
   • 컴포넌트 인스턴스;
   • DOM 요소(button, ARIA 역할이 유지되어야 할 때 ul/li, svg, 태그가 있는 span)를 위한 요소 빌더, 중첩된 자식 포함;
   • 일반 마크업을 위한 WHTML 가져오기, 그런 다음 놓친 부분 수정(아래 가져오기 체크리스트 참조). 페이지 콘텐츠는 G | Page W 컴포넌트의 G | Main 슬롯에 있습니다. 슬롯이 여전히 비어 있는 페이지에서: G | Page W 뒤에 To Slot 래퍼로 섹션을 빌드하고, 사람에게 래퍼를 슬롯으로 드래그하도록 요청한 다음, 그룹을 해제합니다(각 자식을 래퍼 앞으로 이동하고 래퍼 제거). 섹션이 슬롯에 들어가면, 바로 옆에 직접 빌드합니다(conventions.md §1). query_elements로 슬롯 콘텐츠를 확인합니다. 페이지 트리는 슬롯을 빈 것으로 표시합니다.
4. 연결 속성, CMS 바인딩, prop 값, 링크, 양식 설정.
5. 게시, 그런 다음 확인을 실행합니다. 수정, 재게시, 재확인.
6. 보고: 빌드된 내용, 일치한 내용, 다른 내용 및 이유, 수동 단계, 커밋 승인을 기다리는 파일.

페이지가 완료되면 checklists.md에서 페이지 완료를 실행합니다.

가져오기 체크리스트 (모든 WHTML 가져오기 후)

• <button>이 링크가 됨 → DOM button으로 다시 빌드하고, 자식을 안으로 이동합니다.
• <img>가 모든 속성과 에셋 링크를 잃음 → set_image_asset, data-*, loading, 크기(또는 aspect-ratio가 있는 클래스)를 다시 추가합니다.
• <span>이 텍스트 Span이 됨 → <div>로 모양 유지; 분할된 텍스트 조각은 DOM span으로(그렇지 않으면 부모 텍스트를 편집하면 평탄화됨).
• 하나의 클래스가 누락된 클래스 목록은 모든 클래스를 잃음 → 먼저 클래스를 만들고, styleNames를 다시 확인합니다.
• DOM 요소는 리터럴 class 속성을 유지함 → remove_attribute class.
• <br> 앞의 일반 공백은 잘림 → Line.&nbsp;<br>Next.
• 부울 속성은 값이 필요함(muted="true") 그렇지 않으면 게시 시 삭제됨.
• 리스트는 role="list"로 게시됨 → DOM ul/li에서 ARIA 역할 유지.

캔버스 위생

• 빈 요소의 모든 클래스: 모든 면에 패딩 0 및 font-size: inherit(캔버스 .wf-empty는 75px 패딩과 글꼴 크기 0을 추가함).
• 모든 그리드는 적어도 하나의 행 템플릿과 하나의 열 템플릿을 설정합니다. 단일 자식은 그리드가 아닌 flex로 중앙 정렬합니다.
• 의사 요소(아이콘 글꼴 글리프)로만 그려지는 요소는 공백을 텍스트로 설정합니다(set_settings, 키 text).