diff --git a/docs/painting-variant.md b/docs/painting-variant.md
new file mode 100644
index 0000000..b660f17
--- /dev/null
+++ b/docs/painting-variant.md
@@ -0,0 +1,57 @@
+# 리소스팩 이미지 추가 (painting variant)
+
+마인크래프트 1.21+ 의 painting variant 시스템.
+**데이터팩에 슬롯을 미리 등록 → 리소스팩 PNG만 갈아끼우면 그림 교체.**
+
+## 폴더 구조
+
+```
+my-datapack/
+  pack.mcmeta
+  data/musicquiz/painting_variant/cover_01.json
+  data/minecraft/tags/painting_variant/placeable.json
+
+my-resourcepack/
+  pack.mcmeta
+  assets/musicquiz/textures/painting/cover_01.png
+```
+
+## 슬롯 정의 (데이터팩, 고정)
+
+`data/musicquiz/painting_variant/cover_01.json`
+
+```json
+{
+  "asset_id": "musicquiz:cover_01",
+  "title": "표지 01",
+  "author": "음악퀴즈",
+  "width": 3,
+  "height": 2
+}
+```
+
+`data/minecraft/tags/painting_variant/placeable.json` (인벤토리·랜덤 배치에 포함)
+
+```json
+{ "replace": false, "values": ["musicquiz:cover_01"] }
+```
+
+## 이미지 (리소스팩, 교체 대상)
+
+`assets/musicquiz/textures/painting/cover_01.png`
+
+- 크기: `width*16 × height*16` (예: 3×2 → `48×32` px, 또는 그 정수배)
+- 슬롯 이름과 동일해야 함 (`cover_01.png`)
+
+## 게임에서 호출
+
+```
+/give @s minecraft:painting[minecraft:painting/variant="musicquiz:cover_01"]
+/summon minecraft:painting ~ ~ ~ {variant:"musicquiz:cover_01",facing:0b}
+```
+
+## 운영 팁
+
+- 슬롯은 크기별로 미리 다 만들어 둔다 (`cover_3x2_01..N`, `cover_2x2_01..N` …). 크기는 데이터팩에 박혀 있으므로 나중에 못 바꿈.
+- 그림 갈이는 리소스팩 PNG만 교체 → 클라이언트가 리소스팩을 새로 적용하면 즉시 반영 (월드 재진입 불필요).
+- 데이터팩 수정(슬롯 추가/삭제/크기 변경)은 `/reload` 불가 → 월드 재진입 필요.