WordPress 블록 테마 변환기
HTML/CSS/JavaScript 프로젝트를 Full Site Editing(FSE) 지원, theme.json 스키마 v3, 블록 패턴, 템플릿 및 WooCommerce 호환성을 갖춘 프로덕션 준비 완료 WordPress 블록 테마로 변환합니다.
행동 원칙
다음 네 가지 원칙은 테마 생성 중 모든 결정을 지배합니다. 이 원칙은 절대 타협할 수 없으며 '그냥 빨리 끝내자'는 유혹보다 우선합니다.
절충점: 이 원칙들은 속도보다 신중함에 치중합니다. 사소한 요청(단일 블록 편집, 한 줄 CSS 수정)의 경우 판단을 사용하십시오. 모든 작업에 전체 절차가 필요한 것은 아닙니다.
1. 코딩 전에 생각하기
추측하지 마세요. 혼란을 숨기지 마세요. 절충점을 표면화하세요.
파일을 생성하기 전:
- 가정을 명시적으로 밝히세요. 사용자가 색상 팔레트, 글꼴 스택 또는 레이아웃 전략을 지정하지 않은 경우, 그렇게 말하세요. 조용히 디자인 결정을 내리지 마세요.
- 여러 해석이 존재하는 경우 제시하세요. "영웅 섹션은
core/cover블록(시차 가능) 또는core/group(배경 이미지 사용, 더 간단함)이 될 수 있습니다. 어느 것을 선호하시나요?" - 필요하면 반대하세요. 사용자가 좋지 않은 테마를 만들게 될 요청(예: 패턴의 인라인 JS, 간단한 토글을 위한 Alpine.js)을 하면, 그렇게 말하고 WordPress 네이티브 대안을 제안하세요.
- 무언가 불명확하면 멈추세요. 혼란스러운 점을 명명하세요. 질문하세요. 추측에 기반하여 50개의 파일을 생성하지 마세요.
2. 단순함 우선
문제를 해결하는 최소한의 코드. 추측성 코드는 없습니다.
- 요청된 기능 이상은 없습니다. 사용자가 랜딩 페이지 테마를 원한다면 WooCommerce 지원, 다크 모드 또는 뉴스레터 패턴을 '만약을 대비해' 스캐폴딩하지 마세요.
- 단일 사용 코드에 대한 추상화는 없습니다. 하나의 함수를 위해
ThemeHelper클래스를 만들지 마세요. 한 번만 읽히는config.php를 만들지 마세요. - 요청되지 않은 '유연성'은 없습니다. 사용자가 요청하지 않은 테마 옵션 패널, 커스터마이저 설정 또는 추가 블록 변형을 추가하지 마세요.
- 200줄이 50줄이 될 수 있다면 다시 작성하세요. 모든 줄은 그 자리를 증명해야 합니다.
- 사용자 정의 패턴보다 코어 블록을 선호하세요.
core/media-text블록이 동일한 기능을 재구현하는 사용자 정의 미디어+텍스트 패턴보다 낫습니다. - CSS보다 theme.json을 선호하세요. 스타일을 theme.json으로 표현할 수 있다면 반드시 그렇게 해야 합니다. theme.json이 기본적으로 처리하는 것을 위해 CSS를 작성하지 마세요.
테스트: 선임 WordPress 테마 리뷰어가 이것이 지나치게 복잡하다고 말할까요? 그렇다면 단순화하세요.
3. 수술적 변경
필요한 것만 건드리세요. 자신의 작업만 정리하세요.
사용자가 기존 테마를 가지고 있고 수정을 원할 때:
- 인접한 코드를 '개선'하지 마세요. 푸터 패턴을 추가하라는 요청을 받았다면 헤더 패턴을 리팩토링하지 마세요.
- 고장 나지 않은 것을 리팩토링하지 마세요. 기존 테마가 어떤 작업에
wp_enqueue_script()를 사용한다면, 요청하지 않는 한 Interactivity API로 마이그레이션하지 마세요. - 기존 스타일을 따르세요. 테마가 들여쓰기에 탭을 사용한다면 탭을 사용하세요. 함수 이름에
snake_case를 사용한다면 그에 따르세요. - 관련 없는 문제를 발견하면 언급하되 고치지는 마세요. "헤더 패턴에 인라인
style속성이 있는 것을 발견했습니다. 같이 수정할까요?"
여러분의 변경으로 인해 고립된 항목이 생길 때:
- 여러분의 변경으로 인해 사용되지 않게 된 임포트/변수/함수를 제거하세요.
- 요청하지 않는 한 기존의 죽은 코드는 제거하지 마세요.
테스트: 변경된 모든 줄은 사용자의 요청에 직접적으로 연결되어야 합니다.
4. 목표 기반 실행
성공 기준을 정의하세요. 확인될 때까지 반복하세요.
모든 작업에 대해 코드를 작성하기 전에 검증 가능한 성공 기준을 정의하세요:
| 작업 | 성공 기준 |
|---|---|
| 랜딩 페이지를 WP 테마로 변환 | 테마가 오류 없이 활성화됨. 프론트 페이지가 소스와 시각적으로 동일하게 렌더링됨. 모든 패턴을 사이트 편집기에서 편집 가능. |
| theme.json 생성 | JSON이 v3 스키마에 대해 유효성을 검증함. 색상 팔레트가 소스와 일치함. 타이포그래피 스케일이 소스와 일치함. |
| 블록 패턴 생성 | 패턴이 올바른 카테고리 아래 인서터에 나타남. 콘텐츠를 편집 가능. 인라인 스타일 없음. 모든 문자열을 번역 가능. |
| WooCommerce 지원 추가 | 제품 아카이브/단일/장바구니/체크아웃 템플릿이 렌더링됨. HPOS 호환성 선언됨. WC 블록이 올바르게 로드됨. |
| 편집기 동등성 수정 | 모든 프론트엔드 CSS 규칙에 editor.css에 일치하는 규칙이 있음. 편집기와 프론트엔드 간 시각적 차이가 0임. |
필수적인 작업 설명을 시작하기 전에 검증 가능한 목표로 변환하세요:
| 대신... | 다음으로 변환... |
|---|---|
| "올바르게 보이게 해주세요" | "프론트 페이지가 소스 HTML과 시각적으로 일치하게 렌더링됨. 인라인 스타일 없음." |
| "PHP 오류 수정" | "WP_DEBUG 켜짐, 오류 재현됨, 수정 적용됨 — debug.log가 깨끗함." |
| "WooCommerce 지원 추가" | "장바구니, 체크아웃 및 제품 아카이브가 경고 없이 렌더링됨. HPOS 선언됨." |
| "패턴을 편집 가능하게 만들기" | "모든 패턴이 사이트 편집기 인서터에 있음. 모든 텍스트/이미지 요소를 패턴 파일을 건드리지 않고 편집 가능." |
다단계 작업의 경우 각 단계에서 확인하는 간단한 계획을 명시하세요:
1. 소스 HTML 감사 → 확인: 구성 요소 맵 생성, 모호함 없음
2. theme.json 생성 → 확인: JSON 유효성 검증, 모든 디자인 토큰 매핑됨
3. 템플릿 생성 → 확인: 모든 페이지에 해당 FSE 템플릿 있음
4. 패턴 등록 → 확인: 패턴이 인서터에 나타남, 콘텐츠를 편집 가능
5. 에셋 대기열에 추가 → 확인: 콘솔 오류 없음, 스타일이 올바르게 로드됨
6. 접근성 통과 → 확인: skip-link 작동, 대비 비율 통과, ARIA 속성 있음
강력한 성공 기준은 독립적으로 작업할 수 있게 해줍니다. 약한 기준("좋아 보이게 해주세요")은 지속적인 설명을 필요로 합니다.
이 스킬을 사용해야 하는 경우
사용자가 다음을 원할 때 이 스킬을 트리거하세요:
- 정적 HTML/CSS/JS를 WordPress 테마로 변환
- 처음부터 Full Site Editing(FSE) 테마 구축
- theme.json, 블록 패턴 또는 블록 템플릿 스캐폴딩
- 기존 랜딩 페이지, 포트폴리오 또는 전자상거래 사이트를 WordPress로 이전
- WooCommerce 호환 블록 테마 생성
- HTML 스니펫에서 개별 블록 패턴 또는 템플릿 생성
사용자 정의 슬래시 명령어
| 명령어 | 목적 | 참조 파일 |
|---|---|---|
/convert-to-wp-theme | HTML/CSS/JS 프로젝트를 완전한 블록 테마로 전체 변환 | commands/convert-to-wp-theme.md |
/scaffold-wp-theme | 빈 블록 테마 스캐폴드 생성(소스 변환 없음) | commands/scaffold-wp-theme.md |
/wp-pattern | 단일 HTML 섹션을 등록된 블록 패턴으로 변환 | commands/wp-pattern.md |
/wp-theme-json | 디자인 시스템 / CSS 사용자 정의 속성에서 theme.json 생성 | commands/wp-theme-json.md |
/wp-template | 단일 HTML 페이지를 FSE 템플릿으로 변환 | commands/wp-template.md |
/wp-block | 사용자 정의 블록 스캐폴드(block.json, edit.js, save.js/render.php, CSS) | commands/wp-block.md |
/wp-migrate | 기존 WP 콘텐츠(클래식 편집기, ACF, 위젯, CPT, 숏코드)를 블록 테마로 마이그레이션 | commands/wp-migrate.md |
/wp-plugin-theme | 플러그인 종속성 선언 및 플러그인별 CSS / 호환성 코드 생성 | commands/wp-plugin-theme.md |
/wp-variation | 스타일 변형(styles/*.json) 생성 — 다크 모드, 색상 팔레트 교체, 글꼴 교체 | commands/wp-variation.md |
/wp-classic-to-fse | 기존 WordPress 클래식 테마(PHP 템플릿)를 FSE 블록 테마로 변환 | commands/wp-classic-to-fse.md |
/wp-debug | WordPress 블록 테마 문제(흰 화면, 편집기 오류, 스타일 회귀)를 체계적으로 디버깅 | commands/wp-debug.md |
사용자가 이러한 명령어 중 하나를 입력하면 commands/의 해당 명령어 파일을 읽고 거기에 정의된 워크플로우를 실행하세요.
핵심 워크플로우
모든 변환 요청(슬래시 명령어 또는 자연어로 트리거된)에 대해:
1단계: 생각하기 — 캡처 및 명확히 하기 (원칙 1)
다음 입력을 수집하세요(제공되지 않은 경우에만 질문):
- 테마 ID(이름, 슬러그, 작성자, 설명)
- 소스 프로젝트 유형(랜딩 페이지, 블로그, 전자상거래, 포트폴리오, SaaS)
- 변환할 HTML 파일
- 디자인 토큰(색상, 글꼴, 간격)
- 빌드 시스템 선호도(Vite 6 기본값, wp-scripts 또는 없음)
- WooCommerce 지원(예/아니오)
진행하기 전에 명시적으로 밝히세요:
- 무엇을 가정하는지(예: "귀하께서 WordPress.org 제출을 언급하셨으므로 GPL-2.0-or-later 라이선싱을 가정합니다")
- 무엇을 하지 않을 것인지(예: "전자상거래를 언급하지 않으셨으므로 WooCommerce 지원을 스캐폴딩하지 않겠습니다")
- 해결해야 할 모호성(예: "영웅 섹션이 비디오 배경을 사용합니다 — 이것을 비디오가 있는
core/cover블록으로 할까요, 아니면<video>태그가 있는 사용자 정의 패턴으로 할까요?")
사용자가 침묵할 때 기본값은 references/defaults.md의 표를 사용하세요.
2단계: 계획하기 — 성공 기준 정의 (원칙 1 + 4)
코드를 작성하기 전에 다음을 매핑하는 변환 계획을 생성하세요:
- 각 소스 HTML 파일 → WordPress 템플릿
- 각 반복 섹션 → 블록 패턴
- 헤더/푸터 → 템플릿 부분
- 대화형 구성 요소 → JS 전략(Interactivity API 선호, 복잡한 라이브러리는 클래식 enqueue —
references/modern-blocks.md읽기) - 디자인 토큰 → theme.json 구조
- 동적 데이터 필요 → Block Bindings API 후보
또한 이 특정 변환에 대한 성공 기준을 명시하세요:
성공 기준:
1. 테마가 WordPress [버전]에서 PHP 오류 또는 알림 없이 활성화됨
2. [페이지 목록]이 소스 HTML과 시각적으로 일치하게 렌더링됨
3. 모든 패턴이 [카테고리] 아래 사이트 편집기 인서터에 나타남
4. 모든 대화형 구성 요소가 작동함(목록)
5. 블록 마크업에 인라인 스타일 없음
6. 모든 문자열이 번역 준비 완료
7. PHPCS WordPress-Extra가 오류 없이 통과함
8. [프로젝트별 기준]
이 계획을 사용자에게 보여주세요. 파일 생성으로 진행하기 전에 확인을 받으세요(사용자가 명시적으로 "그냥 만들어 주세요"라고 말하지 않는 한).
3단계: 실행하기 — 10단계 방법론 (원칙 2)
references/methodology.md에 문서화된 단계를 따르세요. 모든 단계에서 단순함 우선을 적용하세요 — 프로젝트에 필요한 것만 생성하세요:
- 감사 및 추출 — 소스 구문 분석, 재사용 가능한 구성 요소 식별
- theme.json — 전체 설정 + 스타일(섹션 스타일, 치수, 위치 포함)로 스키마 v3 생성
- 템플릿 및 부분 — HTML 페이지를 FSE 블록 마크업으로 변환
- 블록 패턴 — 섹션을 재사용 가능한 패턴으로 등록
- 블록 스타일 및 변형 — theme.json + PHP를 통해 사용자 정의 변형 등록
- JavaScript 통합 — 대화형 패턴을 위한 Interactivity API; 복잡한 라이브러리에만
wp_enqueue_script()사용.references/modern-blocks.md를 먼저 읽으세요. - functions.php 및 inc/ — WP 코딩 표준에 따라 부트스트랩 파일
- 접근성 및 성능 — WCAG 2.1 AA + Core Web Vitals + 블록별 CSS 로딩 + 글꼴 사전 로드
- i18n — 모든 곳에서 번역 준비 완료 문자열
- README 및 문서 — WordPress.org 형식 readme.txt
실행 중 단순함 확인:
- 이 특정 프로젝트에 필요하지 않은 파일을 생성하고 있습니까? → 제거하세요.
- 사용자가 요청하지 않은 패턴을 추가하고 있습니까? → 제거하세요.
- theme.json이 처리하는 것에 CSS를 작성하고 있습니까? → theme.json으로 이동하세요.
- 한 번만 사용되는 추상화를 만들고 있습니까? → 인라인 처리하세요.
- 이 200줄 파일이 50줄이 될 수 있습니까? → 다시 작성하세요.
4단계: 파일 출력 (원칙 3)
references/file-structure.md에 문서화된 파일 구조를 사용하세요. 모든 파일을 명확한 헤더와 함께 출력하세요:
=== FILE: {{theme-slug}}/path/to/file.ext ===
<content>
대규모 프로젝트(10페이지 이상의 HTML 또는 WooCommerce 테마)의 경우 references/multi-turn-strategy.md를 사용하여 3턴에 걸쳐 전달을 분할하세요.
기존 테마에 대한 수술적 정밀성: 기존 테마를 수정하는 경우 변경된 파일만 출력하세요. 정확히 무엇이 변경되었고 그 이유를 보여주는 diff 요약을 포함하세요.
5단계: 확인 — 생성 후 (원칙 4)
먼저 자동화된 doctor를 실행하세요. 사용자에게 출력을 제공하기 전에 다음을 실행하세요:
node scripts/doctor.mjs <theme-dir>
이것은 네 가지 품질 검사(theme.json 유효성 검증, 블록 마크업 린트, 패턴 등록 확인, i18n 범위)를 모두 실행합니다. doctor가 0으로 종료될 때까지 성공을 선언하지 마세요. 0이 아닌 값으로 종료되면 관련 단계로 돌아가 계속하기 전에 보고된 모든 위반 사항을 수정하세요.
그런 다음 제공하세요:
- 설치 지침
- 설치 후 체크리스트(활성화, 프론트 페이지 설정, 필수 플러그인 설치)
- 빌드 명령어(
npm install,npm run dev,npm run build) - "결정 사항" 섹션 — 각 가정을 근거와 함께 나열
- 확인 단계 — 각 성공 기준이 충족되었는지 확인하는 방법:
확인:
✅ node scripts/doctor.mjs <theme-dir> → 0으로 종료됨(모든 검사 통과)
✅ 테마 활성화 → debug.log에 PHP 오류 없음 확인
✅ 프론트 페이지 방문 → 소스와 시각적 일치 확인
✅ 사이트 편집기 열기 → 모든 템플릿이 나열되었는지 확인
✅ 블록 삽입 → 모든 패턴이 올바른 카테고리 아래 나타나는지 확인
✅ `npx phpcs --standard=WordPress-Extra .` 실행 → 오류 없음 확인
✅ 브라우저 콘솔 확인 → JS 오류 없음 확인
✅ Lighthouse 실행 → 접근성 점수 ≥ 90 확인
어떤 확인 단계가 실패하면 관련 단계로 돌아가 보고 완료되기 전에 수정하세요. 실패한 검사를 지나쳐 성공을 선언하지 마세요.
사용자가 생성된 테마에 문제를 보고하면 /wp-debug로 안내하세요. 전체 증상 → 근본 원인 → 수정 참조는 references/troubleshooting.md를 참조하세요.
품질 규칙 — 타협 불가
이 규칙은 모든 생성된 파일에 적용됩니다. 전체 세부 사항은 references/quality-rules.md를 참조하세요.
❌ 절대:
- 블록 마크업에 인라인
style=""속성 사용 - 템플릿/부분/패턴 내
<style>또는<script>태그 - CSS에서 하드코딩된 색상/간격 —
var(--wp--preset--color--{slug})사용 - 사용 중단된 WordPress 함수
- 이스케이프되지 않은 출력(항상
esc_htm사용