코드에서 UI 명세 추출
비디오는 제품 인터페이스를 녹화하는 대신 HTML과 CSS로 재구성합니다. 따라서 인터페이스의 정확성은 명세가 기반한 원본 코드에 달려 있습니다. 근사치는 금방 드러납니다. 이 스킬이 비롯된 실제 제작 환경에서는 검토자가 첫 리뷰에서 손으로 그린 아이콘과 로고를 거부했고, 크기와 이름이 잘못된 수제 배지는 검토자를 분노하게 만들었습니다. 수정 사항은 코드를 읽음으로써 발견되었으며, 코드에는 눈으로는 발견할 수 없는 함정이 숨어 있었습니다. 루트 폰트 크기는 앱 셸에 의해 런타임에 설정되었고(14px, 스타일시트가 선언한 10px가 아님), 여러 CSS 변수가 프로덕션에 존재하지 않아 폴백 값을 사용했으며, 한 컴포넌트는 두 달 전 커밋에서 악센트 막대를 잃어버렸고, 두 개의 "대화상자"는 라이브러리의 대화상자가 아닌 사용자 정의 팝업이었습니다.
따라서 명세의 모든 값은 리터럴이고 인용되며, 인용할 수 없는 값은 표시됩니다. 절대 추측하지 않습니다.
입력
videos/<video>/SOURCES.md(source-recon에서 생성): 각 화면, 라우트, 컴포넌트 및 상태. 파일이 없으면 먼저 source-recon을 실행하세요.sources/<role>/및sources.lock. 모든 인용은 잠긴 sha를 사용합니다.product.yaml:app_canvas.logical(UI가 재구성되는 뷰포트),app_canvas.theme,app_canvas.rem_px,sources[].framework.- 프레임워크용 어댑터:
references/adapters/<framework>.md. 서브 에이전트 프롬프트를 작성하기 전에 이를 읽어 해당 스택에서 값이 어디에 숨어 있는지 확인합니다.
| product.yaml의 framework | adapter | 상태 |
|---|---|---|
angular-primeng | references/adapters/angular-primeng.md | 프로덕션에서 검증됨 |
react | references/adapters/react.md | 미검증 |
vue | references/adapters/vue.md | 미검증 |
| Tailwind를 사용하는 모든 스택 | references/adapters/tailwind.md (자체 프레임워크 어댑터와 함께) | 미검증 |
html, other, 서버 템플릿 | references/adapters/html.md | 미검증 |
미검증 어댑터의 경우 사용자에게 미검증 상태임을 알리고, 어댑터를 따르되 마지막에 배운 내용을 추가하여("에서 배운 점" 섹션) 다음 제품이 더 나은 출발점을 가질 수 있도록 합니다.
1. 글로벌 렌더링 사실 (제품당 한 번)
화면 작업 전에 모든 화면이 의존하는 사실을 확인하고 인용과 함께 kit/render-facts.md에 기록합니다.
- 런타임 루트 폰트 크기 (CSS뿐만 아니라 설정하는 코드를 앱 셸에서 검색),
rem변환이 올바르게 이루어지도록 합니다. 다르다면product.yaml의app_canvas.rem_px를 업데이트합니다. - 테마: 비디오의 테마를 활성화하는 선택자와 기본적으로 켜져 있는지 여부.
- 토큰 파일, CSS 레이어 또는 가져오기 순서(어느 규칙이 우선하는지), 정확한 버전의 컴포넌트 라이브러리(잠금 파일에서) 및 해당 테마 프리셋.
- 실제로 로드된 글꼴(링크 태그,
@font-face, 글꼴 패키지). CSS에서 이름만 지정되고 로드되지 않은 글꼴은 프로덕션에서 폴백으로 렌더링됩니다. - 데스크톱 중단점.
app_canvas.logical이 데스크톱 레이아웃을 표시하는지 확인합니다.
그런 다음 비디오 테마에 대해 리터럴로 해결된 토큰을 작성합니다.
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
[--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]
이 스크립트는 sources/<role>/에서 CSS 사용자 정의 속성, 최상위 SCSS 변수 및 Tailwind v3 테마(정적으로)를 읽고, 모든 var() 및 $variable을 해결하며, 각 줄에 /* role/path:line@sha */ 인용과 함께 kit/tokens.css를 작성합니다. UNDEFINED로 표시된 줄은 프로덕션에서 정의되지 않은 변수(가능한 결함)이고, needs a Sass compile은 Sass 함수로 빌드된 값을 표시하며, 서브 에이전트가 함수와 입력에서 수동으로 해결해야 합니다. 내보내기에 관련 없는 스타일시트(문서 사이트, 이메일 템플릿, 벤더 CSS)가 포함된 경우 --files를 사용합니다.
2. 화면당 하나의 서브 에이전트
화면당(또는 큰 화면의 패널당) 하나의 읽기 전용 서브 에이전트를 실행합니다. 모두 병렬로 실행하며, references/ui-spec-prompt.md를 채우고 어댑터의 "값이 숨은 위치" 목록을 추가합니다. 각 서브 에이전트를 sources/<role>/(사용자의 체크아웃이 아님)로 지정하고 렌더링 컨텍스트(논리적 캔버스 크기, 테마, rem, 렌더링 사실, 토큰 및 이미 재구축된 조각의 CSS)를 제공하여 새 조각이 일치하도록 합니다.
각 서브 에이전트는 다음을 반환합니다. 캔버스 내부의 지오메트리, 상태별 정적 HTML(프레임워크 구문 없음), 각 값에 대한 리터럴 값과 인용이 있는 하나의 CSS 블록, 추가 클래스로 표현된 hover/focus/active/disabled/loading 상태, 정확한 지속 시간과 이징이 있는 전환 및 키프레임, 라이브러리 및 이름별 아이콘(또는 인라인 SVG 그대로), 모든 표시 문자열, 그리고 명시적인 "미확인" 목록.
조정자(당신)는 직접 명세를 추출하지 않습니다. 실제 앱의 한 화면은 수십 킬로바이트의 결과를 생성할 수 있으며, 중간에 컨텍스트가 가득 차면 전체 빌드의 추적을 잃게 됩니다.
3. 아이콘 및 이미지
아이콘은 제품 자체 아이콘 세트와 자산에서 가져옵니다. 절대 그리지 않으며 브라우저 프로필이나 확장 폴더에서 가져오지 않습니다. 제품당 한 번(그리고 새 화면에 대해 다시) references/icon-extraction-prompt.md를 실행하여 비디오에 필요한 모든 아이콘을 라이브러리 및 이름에 매핑한 다음, 이름을 product-kit의 collect_icons.py에 전달합니다. 이 스크립트는 SVGs를 인용과 함께 kit/icons/으로 복사합니다. SVG 파일이 없는 아이콘 글꼴의 경우 빌드는 라이브러리 자체 CSS에서 코드 포인트를 작성하고, 빈 상자를 렌더링하는 대신 알 수 없는 이름에서 실패해야 합니다.
4. 명세 작성
각 화면에 대해 videos/<video>/specs/<screen>.md 및 specs/<screen>.html:
# 명세: <screen>
출처: frontend@1a2b3c4 (SOURCES.md 참조). 캔버스 1440x810, 테마 라이트, rem 16.
## 지오메트리
| 요소 | x | y | w | h | 인용 |
## 상태
S1 <name>: <표시되는 내용, 가상 데이터>. HTML은 <screen>.html, 섹션 S1.
## CSS
<하나의 블록, 리터럴 값, 각 줄에 /* role/path:line@sha */>
## 모션
| 항목 | 속성 | 시작 | 끝 | 지속 시간 | 이징 | 지연 | 인용 |
## 아이콘
| 키 | 라이브러리 | 이름 | kit/icons의 파일 | 인용 |
## 문자열
| 키 | 텍스트 | 인용 |
## 수정 사항 (비디오에서 수정된 프로덕션 결함)
| 항목 | 프로덕션 동작 | 비디오 동작 | 이유 |
## 미확인
- <값 또는 동작, 이유 및 사용 가능한 최상의 참조>
외관 유지, 결함 수정
레이아웃, 토큰 및 동작을 1:1로 재구성하며, 실제 제품처럼 느껴지게 하는 애니메이션, 호버, 타이핑 및 로딩 상태를 포함합니다. 하지만 가시적인 프로덕션 결함은 수정합니다. 비디오는 제품의 최상의 모습을 보여주며 검토자는 왜 버그가 화면에 보이는지 질문할 것이기 때문입니다. 누락된 패딩, 오버플로, 잘린 텍스트, 기본 브라우저 컨트롤(회색 기본 오디오 플레이어)이 디자인된 것으로 의도된 위치에 있는 경우, 정의되지 않은 변수가 폴백을 표시하는 경우, 클릭 후 포커스 링이 남아 있는 경우 등입니다. 각 수정 사항을 명세의 수정 사항 테이블과 BRIEF 노트에 나열합니다. 디자인 결정인 특이점은 유지합니다(필드를 덮는 스티키 푸터, 콘텐츠와 함께 스크롤되는 사이드바). 이를 변경하는 것은 수정이 아니라 재설계입니다.
명세가 적용하고 기록하는 두 가지 추가 변환:
- 정식 이름.
product.yaml names의 레거시 문자열을 라이브 UI에 여전히 이전 이름이 표시되더라도 정식 이름으로 바꾸고, 해당 요소의 다른 모든 것은 유지합니다. - 금지 용어. 실제 화면에 벤더 또는
banned_terms의 용어(모델 선택기, 통합 카드)가 표시되면 해당 부분을 프레임 밖으로 남깁니다. 비어 있거나 깨져 보이지 않아야 합니다. 자연스럽게 없는 프레이밍 또는 상태를 선택합니다.
데이터
명세는 product.yaml cast의 가상 데이터만 전달합니다. 저장소의 픽스처, 시드 및 스크린샷은 실제 이름을 보유할 수 있습니다. 모양은 사용하고 값은 사용하지 마십시오.
명세를 빌드에 전달하기 전 체크리스트
- 잠긴 커밋 인용됨; 렌더링 사실 작성됨; 비디오 테마에 대해 토큰 해결됨
- 캔버스 크기가 데스크톱 중단점 이상; rem이 런타임과 일치
- 모든
var()해결됨; 정의되지 않은 변수는 폴백과 함께 나열됨(또는 결함으로 수정됨) - 모든 문자열이 i18n 파일 또는 템플릿에서 가져옴; 정식 이름 적용됨
- 모든 아이콘이 앱의 라이브러리에서 가져옴; 빌드가 누락된 글리프에서 실패
- 로고 및 이미지가 저장소 자산에서 가져옴
- 기본 상태(탭, 아코디언, 토글)가 코드와 일치
- 오버레이, 팝업 및 전환 타이밍이 정확한 이징과 함께
- 스크롤 범위가 실제 콘텐츠 내에 있음; 가장자리에서 텍스트 잘림 없음
- 프레임 내에 벤더, 금지 용어, 내부 ID 또는 실제 고객 데이터 없음
- 수정 사항 및 유지된 특이점이 나열됨; 미확인 값이 검토자용으로 나열됨