kvyatkovskys/swiftui-component-preview

SwiftUI 컴포넌트 미리보기

작고 결정론적인 SwiftUI 픽스처에서 컴포넌트 렌더를 생성합니다. macOS 14 이상 및 Xcode 15 이상(Swift 5.9+)이 필요합니다. Swift 6은 필수가 아닙니다. 프로젝트 온보딩, HTML 갤러리 및 라이브 빌더에는 Python 3.8 이상이 추가로 필요합니다(표준 라이브러리만 사용). 정적 검사에는 PNG를, 이미지 비교에는 갤러리를, 실제 픽스처 상호작용에는 네이티브 창을 선택하세요. 이 도구들은 Xcode Canvas나 핫 리로드를 제공하지 않습니다.

출력 선택

무엇이든 빌드하기 전에 다음 순서로 출력을 결정하세요:

1. 명시적 단어. 요청이나 스킬 인수가 png, gallery, live로 시작하거나 명명되는 경우(예: "screenshot", "render"는 PNG; "window", "interactive"는 라이브), 그 출력을 사용합니다.

2. 요청의 의도.

   사용자가 원하는 것	출력
   어떻게 보이는지 확인, 레이아웃, 간격, 텍스트, 상태, 로케일 확인	PNG
   라이트/다크 모드 비교, 프레임 있음/없음 비교, 나란히 보기 또는 토글	갤러리
   클릭, 입력, 토글, 탐색, 시트나 알림 열기, 플로우 확인	라이브 창

   요청이 여러 행과 일치할 경우, 상호작용이 우선합니다: 클릭이나 입력 후에야 나타나는 것은 라이브 창이 필요합니다.

3. 전체 화면 또는 플로우, 신호 없음. 대상이 전체 화면이거나 다단계 플로우이고 위 규칙 중 어느 것도 적용되지 않는 경우(예: "체크아웃 화면 미리보기"), PNG, 갤러리, 라이브 창 중 하나를 묻는 질문을 하나 합니다.

4. 기본값. 신호가 없는 단일 컴포넌트의 경우, fit 크기로 라이트 PNG 하나를 생성합니다. 이것이 가장 빠른 출력이며 직접 검사할 수 있는 유일한 출력입니다. 그런 다음 다른 두 출력을 제안하는 한 줄을 추가합니다.

규칙 1, 2, 4는 질문 없이 진행됩니다. 여러 출력이 요청되면 동일한 구성에서 모두 생성합니다. .swiftui-preview/config.json에 선택 사항을 저장하지 마세요: 이는 프로젝트가 아닌 요청에 속합니다.

프로젝트에서 첫 사용

아래 명령에서 <skill-directory>는 이 SKILL.md가 포함된 디렉토리이며, 설치된 위치에서 확인하세요. Claude Code는 스킬이 로드될 때 이를 스킬의 기본 디렉토리로 표시합니다(${CLAUDE_SKILL_DIR}). Codex 및 기타 에이전트에서는 이 파일이 읽힌 경로를 사용하세요. 개발자별 경로나 설정이 필요하지 않습니다. 사용자의 현재 프로젝트 루트를 사용하고 읽기 전용 검색을 실행하세요:

python3 "<skill-directory>/scripts/bootstrap.py" discover --root "<project-root>"

검색은 SwiftPM 매니페스트, Xcode 프로젝트/워크스페이스, SwiftUI 소스, #Preview 존재 여부, 텍스트 기반 플랫폼 증거를 보고합니다. 매니페스트를 평가하거나, 플러그인을 실행하거나, 빌드하거나, 프로젝트를 수정하지 않습니다. 중첩된 의존성/빌드 디렉토리와 심볼릭 링크는 건너뜁니다. 플랫폼 메타데이터가 없으면 미지원이 아닌 알 수 없음으로 처리합니다. 요청과 검색된 경로를 사용하여 의도된 프로젝트와 컴포넌트를 선택하세요. 확실히 모호한 경우에만 선택을 위해 질문하세요. 여러 마커만으로는 요청된 소스가 명확할 때 질문을 강제할 필요가 없습니다.

픽스처를 생성하기 전에 선택한 실제 소스, 기존 #Preview 구축, 필요한 로컬 정의를 읽으세요. 스킬 에이전트는 첫 번째 미리보기 요청의 일부로 이 적응을 수행합니다. 안전하게 수행할 수 있을 때 사용자에게 수동으로 적응하라고 지시하는 지침에서 멈추지 마세요. 컴포넌트의 실제 뷰 계층, 컨트롤, 스타일, 입력을 유지하세요. 값 뷰를 추출하고 필요한 로컬 정의를 포함하며, 서비스 의존성은 합성 값으로, 로컬 액션은 그대로 대체하세요. 요청된 컴포넌트를 비슷해 보이는 화면, 일반 데모, 또는 번들 예제로 대체하지 마세요. 예제는 픽스처 API만 설명합니다.

적응된 픽스처를 사용자 프로젝트 내에 저장하세요(예: .swiftui-preview/fixtures/StatusCard.swift). 공유 설치된 스킬로 프로젝트 소스를 복사하지 마세요. @main, 앱 델리게이트, 프로덕션 컴포지션 루트, #Preview 매크로, 프로덕션 서비스를 포함하지 마세요. configure, run, refresh는 픽스처를 텍스트로 스캔하여 @main, #Preview, import UIKit이 주석 포함 어디에나 나타나면 거부합니다. 주석에도 해당 문자열을 포함하지 마세요. 오류는 일치하는 토큰과 해당 줄을 명명합니다. 실행하기 전에 전체 픽스처를 검사하세요: 실행 가능한 Swift는 일반 호출자 권한으로 실행됩니다. 이 도우미는 샌드박스가 아닙니다. 구성 해시는 시각적 충실도나 부작용 부재를 확립할 수 없습니다.

명시적인 UIKit 또는 iOS 전용 API로 인해 컴포넌트가 macOS와 호환되지 않는 경우, 사용 가능한 iOS 시뮬레이터/Xcode Canvas 워크플로우를 사용하거나 정확히 지원되지 않는 의존성을 보고하세요. 일반 macOS 호스트는 UIKit을 실행하지 않습니다. 모듈, 에셋, String Catalog를 단일 파일 계약으로 안전하게 적응할 수 없는 경우, 사용 가능한 프로젝트별 워크플로우를 사용하거나 구체적인 제한 사항을 명시하세요. 프로덕션 앱을 조용히 링크하거나, 라이프사이클을 실행하거나, 빌드 구성을 변경하지 마세요.

실제 픽스처를 준비하고 검토한 후, 선택한 경로(프로젝트 루트 기준 상대 경로)를 저장하세요:

python3 "<skill-directory>/scripts/bootstrap.py" configure --root "<project-root>" \
  --project "Package.swift" --source "Sources/StatusCard.swift" \
  --fixture ".swiftui-preview/fixtures/StatusCard.swift" --component StatusCard

--project는 상대 .xcodeproj 또는 .xcworkspace 디렉토리도 허용합니다. init은 configure의 별칭입니다. 라이브 빌드용 별도 상태 저장 픽스처를 등록하려면 --live-fixture "<상대 경로>"를 추가하세요(references/live.md 참조). 버전 관리되는 .swiftui-preview/config.json은 상대 경로, 컴포넌트 이름, 플랫폼 macos, 선택한 소스와 적응된 픽스처의 SHA-256 해시만 저장합니다. 프로젝트와 함께 이동하며 사용자가 커밋할 수 있습니다. 요청되지 않는 한 Git 작업을 수행하지 마세요. 기존 구성은 검사 및 적응 후 configure --replace로 명시적으로 대체되지 않는 한 유지됩니다. 선택된 경로와 구성은 루트 내에 존재해야 하며, 심볼릭 링크나 경로 탐색이 없어야 합니다.

configure 성공 후, 다음 설명대로 run을 사용하여 첫 번째 미리보기를 생성하세요. 이후 섹션의 직접 도우미는 저장된 구성이 없는 일회성 픽스처용입니다.

후속 미리보기

구성이 존재하면 검사하고 run을 사용하세요. 이는 스키마, 경로, 해시를 검증한 후 고정된 인수 위치로 알려진 도우미를 디스패치합니다:

python3 "<skill-directory>/scripts/bootstrap.py" run --root "<project-root>" \
  --mode render --output "/절대/경로/task-output/card.png" \
  --width 480 --height 320 --locale en_US --theme light --frame

갤러리에는 --mode gallery와 .html 출력을, 라이브에는 --mode live와 새로운 .app 출력을 사용하세요. --theme와 --frame은 렌더에만 적용됩니다. 갤러리는 모든 변형을 포함하고 라이브 미리보기는 네이티브 컨트롤이 있습니다. 출력 부모는 존재해야 합니다. bootstrap은 직접 render.sh 및 gallery.sh 도우미와 달리 기존 출력을 대체하지 않고 거부합니다. 다시 렌더링하려면 새 파일 이름을 선택하거나 기존 작업 소유 아티팩트를 먼저 제거하세요. 상대 출력 경로는 프로젝트 루트에서 확인됩니다. --mode live는 빌드만 수행합니다. 실행 및 검사 규칙은 references/live.md에 있습니다.

변경된 소스 또는 픽스처 해시는 실행을 중단합니다. 실제 컴포넌트를 다시 검사하고 픽스처를 업데이트한 후, 선택된 경로로 configure --replace를 실행하거나 라이브 창이 반복되는 경우 refresh를 실행하세요. 지원 정의/리소스의 변경 사항도 검사하세요. 해시는 기본 소스와 자체 포함 픽스처를 다루며, 전체 의존성 그래프는 아닙니다. 구성 대체 전에 첫 사용 적응 워크플로우를 따라 컴포넌트를 전환하세요. 기존 픽스처에 대한 사용자 편집을 유지하세요.

픽스처 계약 및 직접 도우미

렌더러는 하나의 자체 포함 Swift 파일을 도우미와 함께 컴파일합니다. 진입점은 다음과 같습니다:

import SwiftUI

@MainActor
enum PreviewFixture {
    static func makeView() -> some View {
        Text("Example")
    }
}

도우미는 컴파일러가 지원할 때 Swift 6 언어 모드와 엄격한 동시성으로 컴파일하고, 그렇지 않으면 Swift 5 모드로 컴파일합니다. Swift 5 프로젝트에서 적응된 픽스처가 동시성 진단(Sendable, 액터 격리)에서만 실패하는 경우, run 또는 refresh에 --swift-version 5를 전달하거나 직접 도우미에 PREVIEW_SWIFT_VERSION=5를 설정하여 컴포넌트를 다시 작성하지 말고, 미리보기가 Swift 5 모드로 빌드되었다고 말하세요.

합성 데이터와 고정된 초기 상태를 사용하세요. 정적 렌더에는 무효 액션을 사용하세요. 라이브 픽스처는 뷰 로컬 상태 변경, 유효성 검사, 탐색을 구현할 수 있습니다. 픽스처에 컴포넌트에 필요한 로컬 뷰 유형을 포함하세요. Form, TextField, SecureField, Toggle과 같은 실제 SwiftUI 컨트롤을 유지하세요. 자격 증명 저장소, 네트워크 호출, 지속성, 뷰 수명을 초과하는 작업은 픽스처에 넣지 마세요. 라이브 픽스처는 짧은 인메모리 지연으로 서비스를 시뮬레이션할 수 있습니다.

프로젝트에 이미 #Preview 픽스처가 있는 경우, 해당 뷰 구축과 입력을 재사용하세요. 이 독립형 픽스처에서 #Preview 매크로나 @main App을 컴파일하지 마세요. 컴포넌트를 렌더링하기 위해 프로젝트 구성을 다시 작성하지 마세요.

동일한 픽스처 계약은 macOS용으로 컴파일되는 SwiftUI 컴포넌트에 대해 프로젝트 간에 작동합니다. UIKit 전용 컴포넌트는 iOS 시뮬레이터 워크플로우가 필요합니다. 도우미는 임의 프로젝트 모듈을 자동으로 링크하거나 에셋 및 String Catalog를 컴파일/복사하지 않습니다. 가능한 경우 자체 포함 값 뷰를 추출하세요. 컴포넌트에 프로젝트 모듈이나 번들이 필요한 경우, 이 독립형 명령이 명시적으로 적응된 빌드가 필요함을 설명하세요. 로케일 주입이 누락된 번역이나 리소스를 제공한다고 주장하지 마세요.

렌더 및 검사

현재 작업에 적합한 경로를 사용하세요. 이 스킬의 위치에서 스킬 디렉토리를 확인하고, 모든 경로를 인용하며, 먼저 출력 부모 디렉토리를 생성하세요. 다음을 호출하세요:

bash "<skill-directory>/scripts/render.sh" \
  "/절대/경로/Fixture.swift" "/절대/경로/component-light.png" \
  480 320 light en_US

인수는 픽스처, 출력 PNG, 콘텐츠 너비, 콘텐츠 높이, 외관(light 또는 dark), 로케일 식별자입니다. 너비와 높이는 1에서 4096 사이의 정수로, 포인트당 1픽셀로 렌더링되거나 fit입니다. 기존 출력 파일은 원자적으로 대체됩니다. 작업 소유 경로를 선택하세요. 외관 비교가 유용한 경우 dark와 별개의 파일 이름으로 반복하세요. 로케일은 SwiftUI 환경만 설정합니다. RTL 레이아웃 방향이 테스트의 일부인 경우 픽스처에서 명시적으로 선택하세요.

뷰포트 선택. 예제 숫자가 아닌 컴포넌트에 맞게 크기를 조정하세요. 전체 화면의 경우 대상 창 또는 장치 크기를 포인트 단위로 사용하세요. 행, 카드, 컨트롤의 경우 실제 컨테이너의 너비와 fit 높이를 전달하세요(예: 390 fit). 렌더러는 각 맞춤 축에서 픽스처의 이상적인 크기를 측정하고 render: fitted content size WxH를 stderr로 출력합니다. fit fit은 본질적으로 크기가 조정된 컨트롤에 적합하지만, Spacer, maxWidth: .infinity, ScrollView를 중심으로 구축된 뷰는 맞춤 축에서 최소 크기로 축소되므로 숫자를 지정하세요. run --mode render는 --width fit과 --height fit을 허용합니다. 갤러리와 라이브에는 숫자가 필요하므로 보고된 크기를 재사용하세요.

요청되거나 프레젠테이션에 유용한 경우에만 --frame을 추가하세요. 고정된 콘텐츠 뷰포트 외부에 장식용 타이틀 바와 주변 패딩을 추가합니다. 출력 크기는 너비 + 48 x 높이 + 88이 됩니다. 신호등은 그려진 모양입니다. 실제 창을 만들거나 네이티브 창 크롬을 검증하지 않습니다.

시각적 결과를 보고하기 전에 생성된 이미지를 사용 가능한 로컬 이미지 뷰어로 검사하세요. 콘텐츠가 없거나 잘린 경우, 먼저 픽스처의 레이아웃과 뷰포트를 확인하세요. 프로덕션 앱을 조용히 실행하지 말고 윈도우, 앱 라이프사이클, 사용 불가능한 리소스가 필요한 컴포넌트를 설명하고 중지하세요.

갤러리 및 라이브 창

두 가지 추가 출력이 동일한 픽스처 계약을 사용합니다. 각각을 생성하기 전에 링크된 참조를 전체 읽으세요. 각각 출력 경로, 실행, 검증 기준에 대한 규칙이 있습니다.

• HTML 테마 갤러리, 사용자가 라이트/다크를 비교하거나 장식용 프레임을 토글하고자 할 때: run --mode gallery 또는 scripts/gallery.sh 직접 사용. references/gallery.md 참조.
• 라이브 네이티브 창, 실제 버튼, 텍스트 입력, 포커스, 탐색용: run --mode live 또는 scripts/live.sh 직접 사용. .app을 빌드하고 실행하지는 않습니다. 무효 액션이 있는 정적 픽스처는 클릭해도 아무것도 표시되지 않습니다. references/live.md는 configure --live-fixture로 별도 상태 저장 픽스처를 추가해야 하는 시점을 설명합니다. 열린 창은 코드 변경을 절대 반영하지 않습니다. 픽스처 업데이트 후 refresh는 동일한 경로에서 앱을 다시 빌드하고, 이전 창을 닫고, 다시 엽니다(동일한 참조).

결과 제시

모든 아티팩트를 사용자에게 보여주기 전에 직접 검사하고, 현재 에이전트가 제공하는 모든 것을 사용하여 제시하세요. 세션에서 실제로 사용 가능한 도구를 사용하세요. 이 목록에서 하나가 있다고 가정하지 마세요.

출력 위치. 작업 소유 디렉토리를 사용하세요. 클라이언트가 프로젝트 내 파일만 표시할 수 있는 경우 <project-root>/.swiftui-preview/artifacts/에 기록하고(먼저 생성), 요청되지 않는 한 Git 작업을 수행하지 마세요.

Claude Code.

• PNG: 읽기 도구로 파일을 읽어 이미지를 검사하세요. 표시하려면 세션의 파일 제시 또는 미리보기 도구가 있는 경우 사용하세요. 그렇지 않으면 절대 경로를 링크로 제공하고 사용자가 보기를 요청한 경우 open "/절대/경로/component-light.png"를 실행하세요. 인라인 Markdown 이미지는 터미널에서 렌더링되지 않습니다.
• HTML 갤러리: 사용 가능한 브라우저나 미리보기 도구에서 file:// URL을 사용하여 열거나 open "/절대/경로/component-gallery.html"을 실행하세요. 브라우저 도구를 통해 테마 및 프레임 컨트롤을 테스트한 후 검증되었다고 보고하세요. 없으면 컨트롤이 테스트되지 않았다고 말하세요.
• 라이브 앱: 실행이 요청 범위 내에 있는 경우 open "/절대/경로/SwiftUI Preview.app"을 실행하세요. refresh는 --no-launch가 제공되지 않는 한 앱 자체를 엽니다. 상호작용

...

(번역 중단됨 - 원본이 잘렸지만 주요 섹션은 모두 번역됨)