Paidax01/웹-투-디자인-md

웹사이트를 DESIGN.md로

개요

이 스킬은 실제 웹사이트를 재사용 가능한 design.md 또는 DESIGN.md 문서와 함께 HTML 미리보기 파일로 변환합니다.

목표는 사이트를 복제하는 것이 아닙니다. 다른 에이전트가 원본 웹사이트를 볼 필요 없이 동일한 디자인 언어, 콘텐츠 톤, 상호작용 느낌을 재현할 수 있을 정도로 깊이 있게 분석하는 것입니다.

HTML 미리보기는 실용적인 검토 도구입니다. 마크다운을 한눈에 볼 수 있는 디자인 보드로 변환하여 사용자가 사이트를 다시 열지 않고도 팔레트, 타이포그래피, 간격, 컴포넌트 단서, 그리고 원시 마크다운 소스를 검사할 수 있게 해줍니다.

범용 브라우저 규칙

이 스킬은 항상 agent-browser를 우선 사용해야 합니다.

• agent-browser open, agent-browser wait, 특히 agent-browser eval을 기본 추출 워크플로우로 사용하세요.
• 사용자가 어떤 앱이나 플랫폼을 사용 중인지부터 확인하지 마세요.
• 사용자가 Codex, Trae, Claude, Cursor 또는 다른 호스트를 사용하는지에 따라 로직을 분기하지 마세요.
• 현재 프로젝트 폴더에 Playwright, Chrome CLI 또는 로컬 브라우저 패키지가 있는지부터 확인하지 마세요.
• agent-browser를 사용할 수 없는 경우, 사용자가 설치하거나 PATH에 노출하도록 도운 후 동일한 워크플로우를 계속 진행하세요.
• 사용자가 명시적으로 별도의 대체 방법을 요청하지 않는 한, Playwright, Chrome CLI 또는 스크린샷 중심의 추출로 자동 전환하지 마세요.

작업 스타일

브라우저 우선, 증거 우선으로 작업하세요.

• 원시 HTML 가져오기보다 agent-browser를 선호하세요. 실제 웹사이트는 종종 하이드레이션, 스크롤 상태, 호버 상태 또는 반응형 레이아웃 변경 뒤에 중요한 동작을 숨깁니다.
• agent-browser eval을 기본 추출 계층으로 취급하세요. 주요 증거는 브라우저 런타임 내에서 수집된 DOM 구조, 렌더링된 HTML, 계산된 스타일, CSS 변수, 읽을 수 있는 스타일시트 규칙 및 상호작용 상태에서 가져와야 합니다.
• 기본 증거 소스로 스크린샷을 사용하지 마세요. agent-browser eval 또는 동등한 페이지 평가 경로를 사용할 수 있는 경우, DOM, 계산된 스타일, CSS 변수, 읽을 수 있는 스타일시트 규칙 및 추출된 텍스트를 기본 증거로 사용하세요.
• DOM 증거가 불충분하거나 사용자가 명시적으로 시각적 확인 단계를 요청하는 경우에만 최후의 수단으로 스크린샷을 사용하세요.
• Playwright 또는 Chrome CLI로 자동 전환하지 마세요. agent-browser를 사용할 수 없는 경우 명시적으로 감지하고 사용자가 설치하거나 노출하도록 도우세요.
• 정적 소스 파일을 주요 진실 소스가 아닌 보조 증거로 취급하세요.
• 기술적 세부 사항을 디자인 언어로 번역하세요. CSS를 맹목적으로 덤프하지 말고, 에이전트가 실제로 사용할 수 있는 무언가로 합성하세요.
• 관찰된 사실과 추론을 구분하세요. 어떤 것이 판단이나 추정 규칙이고 직접 관찰된 값이 아닌 경우 명확하게 표시하세요.
• 사용자가 명시적으로 거부하지 않는 한, HTML 미리보기를 선택 사항이 아닌 기본 결과물의 일부로 취급하세요.

사전 점검

1. 대상을 하나 이상의 URL로 정규화합니다.
2. agent-browser를 이미 사용할 수 있는지 확인합니다.
3. agent-browser가 없는 경우 scripts/check-browser-tooling.mjs를 사용한 후 사용자가 agent-browser를 설치하거나 노출하도록 도우세요.
4. 기본 경로로 현재 폴더에서 Playwright, Chrome CLI 또는 로컬 브라우저 실행 파일을 검사하지 마세요.
5. 사용자가 명시적으로 해당 대체 방법을 요청하지 않는 한 Playwright 또는 Chrome CLI로 자동 전환하지 마세요.
6. 마크다운 출력 파일의 기본 이름을 DESIGN.md로 설정합니다.
7. 동반 미리보기 파일의 기본 이름을 동일한 기본 이름에 -preview.html을 추가하여 설정합니다(예: DESIGN-preview.html 또는 design-preview.html).
8. 사용자가 명시적으로 design.md, 사용자 정의 파일 이름 또는 사용자 정의 폴더를 요청하는 경우 이를 정확히 따르고, 사용자가 요청하지 않는 한 HTML 미리보기를 그 옆에 유지합니다.
9. 여러 URL이 제공된 경우 각각을 독립적으로 검사한 다음, 시각적 언어가 페이지 전체에서 명확하게 일관된 경우에만 하나의 공유 디자인 시스템으로 합성합니다.

브라우저 도구 부트스트랩

브라우저 도구 설정을 별도의 사용자 작업이 아닌 스킬의 일부로 취급하세요.

감지

다음 순서로 확인하세요.

• agent-browser를 이미 호출할 수 있는지
• 그렇지 않은 경우, 즉시 설치하거나 노출할 수 있는지

번들된 확인 스크립트는 다음을 보고합니다.

• node와 npm을 사용할 수 있는지
• agent-browser를 호출할 수 있는지
• 다음에 어떤 도구를 사용해야 하는지
• 설치가 권장되는지

기본 설치

agent-browser를 사용할 수 없는 경우, 사용자가 설치하거나 PATH에 노출하도록 돕고, 스킬을 사용하기 전에 agent-browser --help로 확인합니다.

설치 동작

• 스킬이 일관되게 agent-browser를 사용할 수 있도록 설치가 필요하다고 설명합니다.
• 네트워크 또는 샌드박스 제한으로 인해 첫 번째 설치 시도가 실패하면 필요한 승인을 요청하고 재시도합니다.
• 설치에 성공하면 동일한 턴에서 사이트 분석을 직접 진행합니다.
• 설치에 실패하면 누락된 것이 무엇인지 사용자에게 명확히 알리고 다른 추출기로 자동 전환하지 않고 중단합니다.
• 도구가 없어도 정적 HTML 스크래핑으로 자동 다운그레이드하지 마세요.

필수 추출 단계

더 깊은 검사 대상이 필요할 때 references/website-reading-checklist.md의 체크리스트를 사용하세요.

1. 페이지 범위 파악

• 페이지 목적을 식별합니다.
• 페이지가 마케팅, 제품, 대시보드, 문서, 전자상거래, 에디토리얼 또는 혼합 유형인지 식별합니다.
• 위에서 아래로 중요한 가시적 섹션을 식별합니다.
• 게이트 또는 접근 불가능 영역이 있으면 실제로 확인하지 않고 추측하지 말고 기록합니다.

2. 기준선 캡처

• 먼저 데스크톱에서 페이지를 검사합니다.
• 레이아웃이 실질적으로 변경되는 경우 태블릿 및 모바일에서도 검사합니다.
• 아무것도 작성하기 전에 전체 페이지를 천천히 스크롤하여 지연 애니메이션, 고정 UI 또는 점진적 공개를 놓치지 않도록 합니다.
• 페이지가 활성화된 동안 브라우저 측 코드 증거를 캡처합니다: 렌더링된 HTML, 주요 노드의 outerHTML, 루트 CSS 변수, 읽을 수 있는 스타일시트 규칙 및 대표 컴포넌트의 계산된 스타일.
• 다른 브라우저 스택으로 전환하지 않고 직접 agent-browser eval 호출 또는 agent-browser 기반 래퍼 스크립트를 선호합니다.
• 사용자가 명시적으로 셸 생성 JSON 아티팩트를 원하면서도 agent-browser를 계속 사용하려는 경우에만 scripts/extract-browser-evidence.mjs를 사용하세요.
• 기본 단계 중에는 스크린샷 캡처를 위해 일시 중지하지 마세요. 페이지 평가를 사용하여 실행 중인 페이지에서 구조와 스타일을 직접 추출합니다.

2.1 선호되는 평가 워크플로우

agent-browser eval 또는 동등한 브라우저 평가 경로를 사용할 수 있는 경우 다음 순서를 따르세요.

1. 페이지 열기
2. 로드 및 하이드레이션 대기
3. 지연 콘텐츠 및 고정 상태 변경을 트리거하기 위해 페이지 스크롤
4. 대표 노드의 렌더링된 HTML 추출
5. 제목, 버튼, 카드, 탐색 및 섹션 래퍼의 계산된 스타일 추출
6. 루트 CSS 변수 및 읽을 수 있는 스타일시트 규칙 추출
7. 가시적 텍스트 조각 및 CTA 사본 추출
8. DOM 또는 계산된 스타일 변경을 통해 호버, 활성, 고정 또는 확장 상태 조사

4단계에서 8단계를 스크린샷으로 대체하지 마세요.

3. 디자인 시스템 추출

페이지별 표면뿐만 아니라 재사용 가능한 규칙을 캡처합니다.

• 색상 및 그 역할
• 사이트가 지원하는 경우 라이트 및 다크 테마 변형
• 타이포그래피 계층 구조
• 간격 리듬 및 그리드 동작
• 모서리 반경 언어
• 테두리 처리
• 그림자 및 표면 레이어링
• 이미지 스타일
• 아이콘 스타일
• 모션 및 전환 스타일
• 밀도 및 여백 철학
• 관찰 가능한 경우 스타일시트 및 CSS 변수 규칙
• 반복되는 컴포넌트가 실제로 어떻게 구조화되어 있는지 설명하는 DOM 패턴

4. 컴포넌트 및 상태 추출

주요 반복 패턴을 검사합니다.

• 탐색
• 공지 표시줄
• 히어로 블록
• 버튼 및 링크
• 카드
• 배지
• 양식 및 입력
• 탭 또는 필
• 아코디언
• 테이블
• 바닥글

각 중요한 컴포넌트에 대해 관련된 가시적 상태를 검사합니다.

• 기본
• 호버
• 활성 또는 선택됨
• 포커스(가시적인 경우)
• 비활성화(가시적인 경우)
• 스크롤 또는 고정 변형
• 열림 또는 확장 상태
• 사이트가 테마 전환을 지원하는 경우 라이트 모드 및 다크 모드 변형

5. 상호작용 동작 추출

정적 시각적 요소에 그치지 마세요.

문서화:

• 스크롤 시 변경되는 사항
• 호버 시 변경되는 사항
• 클릭 시 변경되는 사항
• 사용자가 라이트 모드와 다크 모드 사이를 전환할 때 변경되는 사항
• 보기로 애니메이션되는 사항
• 캐러셀, 탭 또는 고정 사이드바가 클릭 기반, 스크롤 기반 또는 시간 기반인지 여부
• 모션 속도가 얼마나 빠른지, 미묘한지, 선명한지, 영화적인지, 장난기 있는지 또는 절제된지 여부
• 브라우저에서 관찰 가능한 상호작용 중 어떤 CSS 또는 DOM 상태가 변경되는지

6. 콘텐츠 및 브랜드 보이스 추출

디자인을 형성하는 톤을 캡처합니다.

• 헤드라인 스타일
• CTA 문구
• 문장 밀도
• 제품 프레이밍
• 신뢰 신호
• 기능 명명 패턴
• 카피가 기술적인지, 장난기 있는지, 프리미엄인지, 직접적인지, 학술적인지 또는 대화체인지 여부

좋은 DESIGN.md는 시각적 요소와 프레젠테이션 스타일을 모두 안내해야 하므로 이는 중요합니다.

6.1 테마 모드 스위핑

사이트가 모양 전환을 지원하는 경우:

• 브라우저에서 직접 라이트 및 다크 모드 토글을 트리거합니다.
• 두 모드에 대한 DOM 및 계산된 스타일 증거를 추출합니다.
• 어떤 토큰이 반전되고 어떤 악센트가 안정적으로 유지되는지 문서화합니다.
• 모드 간에 이미지, 그림자, 테두리, 카드 및 코드 블록의 처리가 변경되는지 확인합니다.
• 두 모드를 최종 마크다운 및 HTML 미리보기에 포함합니다.

출력 계약

assets/DESIGN.template.md의 구조를 사용하여 최종 문서를 작성합니다.

마크다운이 작성된 후, 가능한 경우 scripts/render-design-preview.mjs를 사용하여 동반 HTML 미리보기를 생성합니다.

브라우저 도구를 사용할 수 있는 경우, 작성 전에 DOM 및 스타일 추출 단계를 선호합니다. 예상 증거 순서는 다음과 같습니다.

1. 렌더링된 HTML 및 주요 노드 구조
2. 계산된 스타일 및 CSS 변수
3. 상호작용 상태 차이
4. 사용자가 명시적으로 요청하거나 DOM 증거가 모호한 경우에만 선택적 스크린샷 교차 확인

페이지가 라이트 및 다크 테마를 지원하는 경우 출력 계약에는 다음도 필요합니다.

1. DESIGN.md에 명시적인 테마 모드 문서화
2. 라이트 모드와 다크 모드가 실질적으로 다른 경우 별도의 토큰 노트
3. 동반 HTML 미리보기의 가시적인 라이트/다크 테마 요약 블록

문서에는 일반적으로 다음 섹션이 포함되어야 합니다.

1. 시각적 테마 및 분위기
2. 색상 팔레트 및 역할
3. 타이포그래피 규칙
4. 컴포넌트 스타일링
5. 레이아웃 원칙
6. 깊이 및 고도
7. 권장 사항 및 금지 사항
8. 반응형 동작
9. 에이전트 프롬프트 가이드

실질적인 가치를 더할 때만 선택적 부록을 추가합니다.

• 상호작용 패턴
• 콘텐츠 및 메시징 패턴
• 관찰된 페이지
• 증거 노트

해당 섹션 내에서 사이트가 지원하는 경우 더 풍부한 Stitch 스타일 하위 섹션을 선호합니다.

• 주요 특성
• 기본, 상호작용, 중립 스케일, 표면 및 오버레이, 그림자 및 깊이
• 글꼴 패밀리, 계층 구조, 원칙
• 버튼, 카드 및 컨테이너, 입력 및 양식, 탐색, 이미지 처리, 독특한 컴포넌트
• 간격 시스템, 그리드 및 컨테이너, 여백 철학, 경계 반경 스케일
• 중단점, 터치 대상, 축소 전략
• 빠른 색상 참조, 예제 컴포넌트 프롬프트, 반복 가이드

사이트가 더 정밀해지기에 충분한 증거를 노출하는 경우 문서를 높은 수준의 요약 수준으로 유지하지 마세요.

HTML 미리보기 계약

기본적으로 마크다운 옆에 하나의 HTML 파일을 생성합니다.

미리보기는 다음을 수행해야 합니다.

• 별도로 수동으로 유지 관리되는 요약이 아닌 최종 DESIGN.md를 진실 소스로 사용합니다.
• 매번 새로 발명된 HTML 프레임워크가 아닌 고정된 미리보기 셸 템플릿을 사용합니다.
• 왼쪽에 가장 유용한 시각적 규칙(예: 개요, 팔레트, 타이포그래피, 간격, 반경, 버튼, 카드, 깊이, 반응형 노트)을 표시합니다.
• 사용자가 원본 문서를 빠르게 검사하거나 복사할 수 있도록 전용 창에 마크다운 소스를 표시합니다.
• 일반 마크다운 렌더링보다는 정제된 디자인 보드처럼 느껴져야 합니다.
• 미리보기 자체가 문서화된 시스템을 반영하도록 추출된 디자인 토큰을 실용적으로 사용합니다.

사용 가능한 경우 assets/design-preview-shell.template.html을 기본 셸로 사용합니다. 해당 템플릿을 안정적인 인프라로 취급하고, 사용자가 명시적으로 새로운 레이아웃 방향을 요청하지 않는 한 문서화된 토큰과 콘텐츠만 채웁니다.

사용자가 레이아웃에 대한 시각적 참조를 제공하는 경우, 마크다운 데이터에서 생성되면서도 HTML이 동일한 패밀리에 속한다는 것을 알아볼 수 있을 정도로 밀접하게 따릅니다.

합성 규칙

최종 파일을 작성할 때:

• 원시 토큰 레이블보다는 의미론적 이름을 선호합니다.
• 색상 정밀도가 중요한 경우 정확한 16진수 값을 포함합니다.
• 반경, 간격, 그림자 및 글꼴 크기 배율을 다른 에이전트가 즉시 사용할 수 있는 평이한 언어로 번역합니다.
• 문서를 독창적이고 사용 가능하게 유지합니다. 거대한 데이터 덤프는 피합니다.
• 외관뿐만 아니라 기능적 역할도 설명합니다.
• 반복되는 패턴을 시스템으로 그룹화합니다.
• 미묘한 차이를 보존합니다. 사이트가 두 가지 시각적 모드를 혼합하는 경우 둘 다와 각각이 나타나는 시점을 설명합니다.
• 관찰 가능한 경우 정확한 숫자 세부 사항을 선호합니다: 정확한 16진수 값, 글꼴 크기, 줄 높이, 자간, 반경 값, 간격 단위 및 다중 레이어 그림자 공식.
• 패턴이 사이트 정체성의 중심인 경우(예: "그림자-테두리" 또는 "압축 정체성") 짧은 철학 또는 근거를 추가합니다.
• 다른 에이전트가 소스 사이트를 보지 않고 일치하는 UI를 구축하는 데 도움이 되는 경우 컴포넌트별 구현 신호를 포함합니다.
• 규모가 큰 사이트의 경우 에이전트 프롬프트 가이드에 최소한 히어로, 카드, 버튼 또는 탐색 패턴에 대한 프롬프트 준비 예제를 포함합니다.
• 일부 값이 관찰되지 않고 추론된 경우 명확하게 표시하되 여전히 유용하게 유지합니다.

좋은 예:

• "기본 작업은 차가운 전기 블루 #3B82F6을 사용합니다. 호버 시 #2563EB로 진해집니다."
• "카드 간격은 24px 베이스라인 그리드로 일관되게 유지됩니다. 내부 패딩은 16px/24px/32px이며 깊이에 따라 다릅니다."

나쁜 예:

• "사이트는 파란색을 사용합니다."
• "CSS 변수가 있습니다."