Custom Seasonal Widget · Tài liệu CS

Quy trình tạo Widget theo mùa lễ 5 bước

Ai cũng làm được một widget mùa lễ theo 5 bước: ChatGPT vẽ 6 mẫu → khách chọn 1 → Claude tách thành file → điền vào CMS → Save và áp dụng cho store.

  1. 1ChatGPT tạo 6 mẫu
  2. 2Khách chọn 1
  3. 3Claude tách file
  4. 4Điền CMS
  5. 5Save + Store apply
BướcLàm ở đâuKết quả
1. Tạo 6 mẫuChatGPT1 ảnh có 6 banner đánh số 1–6
2. Khách chọnChat với kháchSố mẫu khách thích (vd. mẫu 3)
3. Tách fileClaude + skill /seasonal-widget-webp-split1 file zip: 4 ảnh góc + mã màu
4. Điền CMSCMS → Feature → Custom Seasonal WidgetWidget đã có ảnh góc và màu
5. Save + áp storeCMS → Store applyWidget hiện trên storefront

Cần chuẩn bị trước:

  • Tài khoản ChatGPT (có tạo ảnh).
  • Claude đã cài skill seasonal-widget-webp-split (tab Skill).
  • Quyền chỉnh widget trong CMS.
  • Prompt (tab Prompt ChatGPT) + 2 ảnh mẫu Christmas và Halloween.

Bước 1Tạo 6 mẫu bằng ChatGPT

Chỉ sửa 2 dòng đầu của prompt, phần còn lại giữ nguyên.

  1. Mở tab Prompt ChatGPT, copy toàn bộ prompt.
  2. Sửa mục 0. EVENT INPUT:
    • [EVENT NAME] → tên sự kiện, viết tiếng Anh cho rõ. Ví dụ: Lunar New Year (Vietnamese Tết), Diwali, Valentine's Day.
    • [ENTER ANY SPECIAL REQUIREMENTS OR LEAVE BLANK] → yêu cầu riêng của khách. Ví dụ: Use brand colors pink and gold, No animals. Không có thì xóa chữ trong ngoặc, để trống.
  3. Mở ChatGPT, tạo cuộc chat mới.
  4. Đính kèm 2 ảnh mẫu (Christmas + Halloween) — tải 2 ảnh bên dưới.
    Ảnh mẫu Christmas
    Ảnh mẫu 1 · Christmas
    Ảnh mẫu Halloween
    Ảnh mẫu 2 · Halloween
  5. Dán toàn bộ prompt đã sửa rồi gửi.
  6. Nhận 1 ảnh có 6 banner đánh số 1–6. Tải ảnh về máy (bản gốc, không chụp màn hình).

Bước 2Gửi khách chọn mẫu

Gửi ảnh 6 mẫu cho khách và xin 1 số mẫu khách thích nhất.

Tin nhắn mẫu:

  • Khách muốn đổi chi tiết → quay lại Bước 1, ghi yêu cầu vào dòng Additional requirements rồi tạo lại.
  • Khách đã chốt → sang Bước 3.

Bước 3Tách file bằng Claude

Claude cắt 4 góc từ mẫu khách chọn và đo sẵn mã màu nền. Bạn chỉ cần gửi ảnh và 1 câu lệnh.

Cài skill (làm 1 lần): nội dung skill ở tab Skill. Lưu thành file SKILL.md, vào Claude → Settings → Skills → tải lên.

Mỗi lần làm:

  1. Mở Claude, tạo cuộc chat mới.
  2. Đính kèm ảnh 6 mẫu (ảnh gốc từ ChatGPT).
  3. Gửi lệnh, ví dụ:
/seasonal-widget-webp-split làm mẫu số 3, theme lunar-new-year
  1. Đợi Claude chạy xong (thường vài phút). Claude gửi lại 1 file zip và bảng mã màu ngay trong chat.
  2. Mở ...-compare.png kiểm tra bản ghép có giống ảnh gốc không.

Trong file zip có:

FileDùng để
<theme>-top-left.webpẢnh góc trên trái
<theme>-top-right.webpẢnh góc trên phải
<theme>-bottom-left.webpẢnh góc dưới trái
<theme>-bottom-right.webpẢnh góc dưới phải
<theme>-colors.jsonMã màu: Color 1/2/3, Border, Text, tâm gradient
<theme>-preview.pngXem trước widget hoàn chỉnh
<theme>-compare.pngSo sánh ảnh gốc với bản ghép

Vật phụ làm góc bị to quá (cánh hoa rơi xa, đuôi mây dài) sẽ được Claude dời vào trong hoặc thu gọn. Vật lẹm một chút thì vẫn giữ. Claude sẽ báo rõ đã đổi gì.

Bước 4Điền vào CMS

  1. Vào CMS → Feature → Custom Seasonal Widget.
  2. Tạo widget mới (hoặc mở widget cần sửa).
  3. Điền 4 ảnh góc và 5 mã màu lấy từ file zip hoặc bảng màu Claude gửi, theo 2 bảng dưới đây.

Ảnh 4 góc: tải đúng file vào đúng ô.

Ô trong CMSFile
Top left<theme>-top-left.webp
Top right<theme>-top-right.webp
Bottom left<theme>-bottom-left.webp
Bottom right<theme>-bottom-right.webp

Màu nền: copy từng mã trong colors.json, dán cả dấu #.

Ô trong CMSLấy từVí dụ (Tết mẫu 6)
Color 1 (0%, giữa widget)color1#FEF7E6
Color 2 (50%, vành giữa)color2#FEF2D7
Color 3 (100%, mép và góc)color3#FEE8C1
Border colorborder#FA9B15
Text colortext#58401D

Chỉnh vị trí nâng cao (chỉ khi cần):

  • Tâm gradient (Color option nâng cao): mặc định 50% 50%. Nếu Claude ghi tâm khác (vd. 40% 41%) và màu nền trông lệch so với ảnh gốc, nhập giá trị đó vào ô vị trí tâm.
  • Vị trí / kích thước góc: ảnh góc đã cắt sát và đúng tỉ lệ, thường không cần chỉnh. Chỉ chỉnh khi xem trước thấy góc đè lên chữ hoặc lệch mép.

So màn hình xem trước của CMS với <theme>-preview.png. Giống nhau là đúng.

Bước 5Save và áp dụng cho store

Phải bấm Save 2 lần: lần 1 lưu widget, lần 2 để widget hiện trên storefront.

  1. Bấm Save để lưu widget.
  2. Cửa sổ Store apply hiện ra → nhập (chọn) store của khách.
  3. Bấm Save thêm 1 lần nữa.
  4. Mở storefront của khách, tải lại trang để kiểm tra widget đã hiện.

Prompt ChatGPT

Copy toàn bộ khối dưới đây và dán vào ChatGPT (Bước 1). Chỉ sửa 2 dòng ở mục 0. EVENT INPUT.

festival-widget-prompt.txt
FESTIVAL STOREFRONT WIDGET GENERATOR
Automatic Theme Analysis – 6 Designs – 4 Independent Corner Decorations

0. EVENT INPUT – CHANGE THIS SECTION
Event / Theme Name: [EVENT NAME]
Additional requirements (optional): [ENTER ANY SPECIAL REQUIREMENTS OR LEAVE BLANK]
Reference Images: Use the images attached to this conversation as the layout and visual style references.
Only the Event / Theme Name needs to be changed when creating a new theme.

1. Automatic Event Research & Theme Analysis
Before generating images, independently analyze the event specified in the input section.
Do not wait for the user to provide a list of decorative objects.
Automatically identify:
* The event's cultural background and meaning.
* Its most recognizable symbols and objects.
* Traditional decorations, accessories, clothing, and materials.
* Typical colors and visual characteristics.
* Objects that are essential to the event's identity.
* Supporting decorative elements that can enhance the design.
* Elements that should be avoided because they are culturally inappropriate, sensitive, or unrelated.
Use reliable general knowledge and, when necessary, external research to understand the event correctly.
Do not simply choose random objects based on the event name. Every decorative element must have a clear visual or cultural connection to the event.
If the event has different regional or cultural variations, select a coherent visual direction instead of mixing unrelated traditions.

Automatic Icon Classification
After analyzing the event, classify the available symbols into three priority levels:
Tier 1 – Essential Symbols
* The most recognizable symbols of the event.
* Must appear more frequently across the six widgets.
* Can appear in approximately 3–5 out of 6 designs.
* Vary their combinations, positions, sizes, and illustration styles.
Tier 2 – Recognizable Symbols
* Important supporting symbols that strengthen event recognition.
* Appear in approximately 2–3 out of 6 designs.
Tier 3 – Supporting Decorations
* Smaller accessories, patterns, ornaments, and decorative details.
* Appear selectively in approximately 1–2 out of 6 designs.
Do not distribute all symbols equally. Prioritize the event's identity over forced variety.

2. Overall Widget Layout
Follow the proportions and visual language of the supplied Christmas and Halloween references.
* Horizontal banner, approximately 3.3:1 aspect ratio.
* Rounded corners with a thin, subtle border.
* Simple, light pastel gradient background.
* Central area occupies approximately 70–75% of the banner.
* Decorations are concentrated in the four corners.
* Keep the center clean and unobstructed for storefront content.
* Each design can have its own coordinated background color.
Do not create a full-frame illustration or continuous decorative border.

3. Four-Corner Composition
Each widget must have four independent decorative clusters.
Bottom-left and Bottom-right – Main Decorations
* Generally contain the two most prominent event-related subjects.
* Larger and more visually noticeable than the supporting decorations.
* Prioritize recognizable Tier 1 symbols.
* Combine 2–3 related objects when appropriate.
* Maintain a compact composition within each corner.
Top-left and Top-right – Supporting Decorations
* Can include secondary event symbols, flowers, ornaments, hanging decorations, garlands, curtains, wreaths, leaves, patterns, or other relevant elements.
* Can also contain important symbols if they naturally belong in the upper corners.
* Keep decorations compact and close to the edges.
Do not force every event to use the same hierarchy. Adapt the four corners to the actual characteristics of the event.

3.1 Main Subject Size & Compact Decoration Composition (CRITICAL)
The main subject in each corner must be the largest and most visually prominent element of the entire decorative cluster.
Main Subject Priority
* Make the main event-related object as large as reasonably possible within its corner.
* The main subject must dominate the visual composition and remain immediately recognizable.
* Do not reduce the main subject's size to accommodate secondary decorations.
* Supporting elements must adapt to the size and position of the main subject, never the other way around.
* The main subject should occupy most of the cluster's visual area.
Supporting Decoration Proportions
* Supporting objects should be relatively small and positioned close to the main subject.
* They may slightly overlap, tuck behind, or extend around the main subject to create a natural, layered composition.
* Supporting decorations should only extend slightly beyond the main subject's silhouette.
* Avoid long branches, extended flower arrangements, trailing leaves, long garlands, ribbons, or other elements that stretch far away from the main subject.
* Do not use decorative elements simply to fill empty space.
* Do not make supporting objects unnecessarily large or spread them across the corner.
Compact Cluster Silhouette
* Each corner decoration must form a compact, visually concentrated composition.
* Prefer a roughly square or compact silhouette rather than a long horizontal or vertical rectangle.
* Keep the overall width and height of the decorative cluster relatively balanced.
* Avoid thin, elongated shapes that significantly increase the cluster's overall bounding box.
* Keep secondary details close to the focal object.
* The main subject should remain visually dominant even when the entire cluster is viewed at a smaller size.
Important Scaling Rule – SVG/PNG Export Consideration
Consider how the entire corner cluster will eventually be cropped into a single rectangular SVG/PNG asset and scaled proportionally on a Shopify storefront.
* The main subject must remain large after the entire cluster is fitted into its rectangular asset boundaries.
* Do not let long decorative extensions unnecessarily increase the overall width or height of the cluster.
* Avoid excessive empty space inside the cluster's bounding box.
* Do not sacrifice the main subject's display size because of unnecessary decorative extensions.
* Design each corner as a compact asset that can be scaled without making its main subject significantly smaller.
Visual Priority:
1. Large and recognizable main subject.
2. Small supporting decorations placed close to the main subject.
3. Minimal decorative extensions for balance and visual connection.
The goal is to create compact corner decorations with large focal objects, not long decorative arrangements that occupy more space but become significantly smaller when scaled.
Important: This rule applies to all four corners, including upper supporting decorations. Even when a corner contains flowers, leaves, hanging ornaments, or other secondary elements, keep the composition compact rather than stretching it across the banner.

4. Six Different Design Combinations
Generate six different widget compositions.
Before generating, create six different combinations based on the symbols identified in the automatic event analysis.
Rules:
* Do not simply rearrange the same four objects.
* Essential symbols can repeat across multiple designs.
* Change the combination of main and supporting subjects.
* Vary positions, scale, orientation, and decorative details.
* Avoid repeating the exact same composition.
* All six designs must clearly belong to the same event theme.
* Keep the main subject large in every design.
* Vary the main subject and supporting decorations without creating unnecessarily elongated corner clusters.
* Different designs should have different compact silhouettes and object combinations.
Each design should feel like a different creative interpretation of the event while maintaining a consistent illustration style.

5. Critical SVG Separation Requirements
The four decorative corner clusters will eventually be extracted into four independent SVG/PNG assets for Shopify storefront implementation.
Therefore:
* Each corner must be completely independent.
* No object should overlap or connect to another corner's decoration.
* No flowers, leaves, branches, ribbons, or garlands should extend between different corners.
* Do not create continuous decorations around the banner.
* Avoid objects being unintentionally cut off.
* Every cluster must have a clearly identifiable silhouette.
* Leave enough spacing between the four clusters for clean cropping.
* Keep all important parts of each object inside its own corner area.
* Keep each cluster compact to minimize unnecessary cropping boundaries.
* Do not allow secondary decorations to extend far beyond the main subject.
* Make sure the main subject occupies a substantial portion of the final cropped asset.
Treat every corner as an individual asset that can be exported independently without reconstructing missing parts.

6. Visual Style & Color Direction
Follow the visual language of the supplied references.
* Premium 3D cartoon illustration style.
* Soft, clean, polished materials.
* Light pastel colors.
* Simple gradient backgrounds.
* Avoid excessively dark, saturated, or high-contrast backgrounds.
* Main objects should have more depth, highlights, and subtle shadows than the background.
* Keep icons recognizable and visually clear.
* Use realistic object proportions.
* Avoid excessive tiny decorative details.
* Maintain consistent illustration quality across all six designs.
The background should support the decorations rather than compete with them.
Choose colors that are appropriate for the event. Do not automatically use the same color palette for every theme.
Main Subject Rendering Priority:
* Main subjects should have stronger visual presence, more depth, clearer details, and more prominent 3D volume.
* Supporting decorations should remain visually secondary.
* Do not let small decorative details compete with the main subject.
* Maintain a clear difference in scale and visual hierarchy between focal objects and supporting elements.

7. Central Content Space
The center is reserved for Shopify storefront content.
* Keep approximately 70–75% of the banner visually open.
* Do not place important objects in the center.
* Do not extend large decorations too far inward.
* Keep the background gradient smooth and subtle.
* Small floating decorative details are acceptable if they do not interfere with content.

8. Output Requirements
Generate exactly 6 complete widget designs in one image.
* Arrange them in a clean 2-column × 3-row or 3-column × 2-row grid.
* Number each design from 1 to 6 outside the individual banner.
* Each banner must have its own complete four-corner layout.
* Maintain consistent banner proportions.
* Show all four corners clearly.
* Do not add text, titles, logos, or sample content inside the banners.
* Do not crop or distort the banners.
* Make the six concepts visually different enough for comparison.
* Ensure the main subjects in all four corners remain large and recognizable.
* Do not use long decorative extensions to artificially increase the size of the corner clusters.

9. Final Design Validation
Before producing the final image, check all six concepts:
1. Does each widget have four distinct decorative corner clusters?
2. Are essential event symbols distributed with appropriate frequency?
3. Are the main subjects visually prominent and sufficiently large?
4. Are the upper decorations balanced and relevant?
5. Are all four clusters independent, without overlapping or connecting?
6. Is the central content area sufficiently spacious?
7. Is the background light and visually subtle?
8. Can each corner be cropped and exported independently?
9. Are all objects culturally and contextually appropriate for the specified event?
10. Are the six designs sufficiently different from one another?
11. Is each corner cluster compact rather than unnecessarily elongated?
12. Do supporting decorations stay close to the main subject?
13. Does the main subject occupy most of the cluster's visual area?
14. Will the main subject remain sufficiently large when the complete corner asset is proportionally scaled down?
15. Are there any unnecessary branches, flowers, leaves, ribbons, garlands, or other extensions that increase the cluster's bounding box without adding meaningful visual value?
If any design fails these requirements, revise its composition before generating the final image.

EXECUTION INSTRUCTION
Read the Event / Theme Name from Section 0.
Automatically analyze the event, identify its essential and supporting symbols, determine their appropriate frequency, select a suitable color palette, and create six different four-corner widget designs.
Do not ask the user to provide an icon list. Do not wait for additional instructions if the event name is sufficiently clear.

CRITICAL DESIGN PRIORITY:
Preserve the original reference layout, illustration style, color direction, banner proportions, and four-corner composition.
The main subject in every corner must be large and visually dominant. Supporting decorations must remain small, compact, and close to the main subject.
Never stretch corner decorations unnecessarily in horizontal or vertical directions. Consider the final rectangular SVG/PNG cropping and proportional scaling when composing every corner.
The goal is to maximize the visual size of the main subject while keeping each corner decoration compact, balanced, independent, and easy to export.
Generate the six images directly using the supplied reference layout and all requirements above.

Skill seasonal-widget-webp-split

Nội dung file SKILL.md dùng ở Bước 3. Cài 1 lần: copy toàn bộ, lưu thành file SKILL.md, rồi tải lên Claude (Settings → Skills).

SKILL.md
---
name: "seasonal-widget-webp-split"
description: "Tách ảnh widget/banner theo mùa lễ thành 4 góc WebP nền trong suốt + mã màu nền gradient 3 màu (kèm border, text), cắt sạch theo viền vật thể, có ảnh so sánh gốc/ghép, giao 1 zip + 1 thư mục."
---

# Tách widget mùa lễ thành 4 góc WebP + mã màu nền

Dùng khi người dùng gửi ảnh một thẻ/widget trang trí (Christmas, Diwali, Halloween, Trung Thu…) và muốn tách thành:
- 4 góc `<theme>-top-left|top-right|bottom-left|bottom-right.webp` (nền trong suốt), và
- **mã màu nền** cho ô cấu hình của app: **Color 1 / Color 2 / Color 3** (gradient), **Border color**, **Text color**.

**Không còn xuất ảnh nền** (`background.webp`) — nền do app vẽ từ 3 màu. Chỉ xuất ảnh nền/SVG khi người dùng yêu cầu rõ.

Quy tắc gradient của app (radial, `ellipse farthest-corner`):

| Ô | Offset | Vị trí trên widget |
|---|---|---|
| Color 1 | 0% | đúng tâm `(centerX%, centerY%)` |
| Color 2 | 50% | vành giữa, nằm giữa tâm và mép |
| Color 3 | 100% | góc xa tâm nhất; các mép khác nhạt dần về màu này |

## Nguyên tắc bắt buộc (người dùng đã chốt)

1. **Không vẽ lại** vật thể chính. Pixel vật thể phải lấy từ ảnh gốc. Chỉ dựng mới cho nền và bóng.
2. **Cắt theo viền vật thể**, không dùng alpha mềm theo khoảng cách màu: phải xác định hình thái viền trước
   (mask nhị phân → lấp lỗ → làm mượt), bỏ hết quầng sáng, đốm mờ, hạt lẻ, màu nền dính vào.
   Kiểm tra bằng cách đặt góc lên **nền tối** — không được thấy viền mờ.
3. **Bóng đổ**: cắt sạch trước, rồi xem lại ảnh gốc. Vật nào có bóng nhẹ thì dựng lại bóng
   **đúng sắc độ và độ đậm đo từ ảnh gốc** (không đoán màu). Vật không có bóng thì thôi
   (vd. vật đặt trên mây/đế trong tranh thì không có bóng xuống nền).
4. **Giữ nguyên màu** khi làm nét — không làm đậm/rực màu.
5. Góc nên **gần vuông** (rộng/cao ≈ 1.0–1.5), không kéo dài như dây ngang. Tham khảo bộ hiện có:
   mỗi góc rộng ~10–26% chiều ngang khung (tối đa ~34%), cao ~25–60% chiều cao khung.
   Góc chủ thể chính (thường dưới-trái) ~20–25% chiều ngang.
6. **Giao file**: ghi vào MỘT thư mục chung trên máy người dùng, và trong chat chỉ gửi **MỘT file zip** chứa cả bộ
   (4 WebP + `<theme>-colors.json` + preview + compare). Không gửi từng file lẻ thành nhiều thẻ trong chat (bước 9).
7. **Luôn có 1 ảnh so sánh** `<theme>-compare.png` (ảnh gốc vs bản ghép: gradient 3 màu + viền + 4 góc WebP)
   để người dùng tự kiểm tra độ giống (bước 8).
8. **Mã màu luôn đo từ ảnh gốc**, không tự chọn theo cảm tính; Text color phải đạt tương phản ≥ 7:1 (AAA)
   với cả Color 1 và Color 3.

## Quy trình

### 1. Chuẩn bị
- Ảnh gốc ở uploads; nếu là lưới nhiều mẫu, crop đúng mẫu được chọn.
- Đo khung thẻ: mép ngoài viền, độ dày viền, bán kính bo (đọc pixel theo hàng/cột qua giữa thẻ;
  bán kính suy từ vị trí viền ở vài hàng gần góc).
- Tạo mask phủ thẻ bằng hình chữ nhật bo góc hình học, siêu mẫu 2–4× (`COV`), loại dải viền.
- Tạo `EDGE` = dải 3 px sát mép trong của thẻ (dùng để khép đường viền vật chạm mép).

### 2. Ước lượng nền sạch
Normalized convolution có mask, lặp 5–6 lần với ngưỡng giảm dần (30→18→12→10).
- Nền là gradient trơn → chỉ dùng **thang lớn** (σ ≈ 40 và 110 cho ảnh ~2000 px; σ ≈ 18/45 cho ảnh ~700 px).
  Không dùng thang nhỏ (σ 6–8) khi có vật màu nhạt: nó "nuốt" lòng vật vào nền.
- Mỗi vòng: `obj = closing(dist > thr)`, rồi **lấp lỗ nhỏ** (`fill_small`, bỏ lỗ > ~90 000 px để không lấp cả
  lòng thẻ) trên `obj | (EDGE & dilate(obj, 12))` — để lòng vật nhạt (trăng, thỏ, mây) không bị lấy làm mẫu nền.
- `dist = ||C − B||` là bản đồ "vật thể". Độ nhiễu nền tốt: std ~0.5–1.3.

### 3. Mask từng góc (cứng)
Với mỗi vùng góc (box riêng; gán pixel cho góc theo thứ tự để không trùng):
- `raw = dist > T` (T ≈ 24–35 cho vật đặc; 12–20 cho nét mảnh/mandala).
- Vật đặc: `closing (×2–3) → fill_small(m | EDGE∩dilate(m)) → opening (×2)`, cộng lại nét mảnh mạnh (`dist > 70–80`)
  như dây đèn, tia pháo.
  - **Vật màu nhạt trùng nền** (thỏ trắng, mây kem, trăng): chỉ lấp lỗ cho pixel có `dist > 10`,
    để phần **trời lộ giữa lá/cành không bị lấp**.
  - Loại `WASH` (pixel nhạt ít bão hòa = quầng sáng/sàn nhạt; pixel xanh nhạt = bóng) chỉ khi vật thể KHÔNG
    phải màu nhạt; bộ có mây/thỏ/tuyết thì không dùng WASH chung mà dùng các bộ lọc riêng dưới đây.
- Bộ lọc riêng hay dùng (áp vào mask trước khi tách màu):
  - `BLUISH`: pixel xanh hơn đỏ (`B > R + 3`) và `dist < 70` → trời lọt vào (giữa lá, sát góc thẻ).
  - **Quầng quanh vật tròn** (trăng, đèn): đo tâm/bán kính (pixel bão hòa, bbox), bỏ vành `r..r+95`
    có `dist < 95` ở **những phía không có vật khác chồng lên** (kiểm tra mây/lá chồng vào trăng).
    Làm mượt mép đĩa bằng độ phủ hình tròn 1 px ở cung đã cắt.
  - Sương/nền màu be sau đèn, giữa lá: vùng cục bộ + `min(R,G,B) > 185`.
- Gán thành phần cho góc theo **trọng tâm** khi hai góc cùng cạnh có thể dính nhau (vd. trên-trái vs dưới-trái).
- Lọc thành phần liên thông: giữ nếu diện tích ≥ ~60–80 px hoặc (≥ 12–25 px và đỉnh `dist` > 70–90);
  bỏ hạt lẻ, bỏ hạt trên mép viền thẻ, bỏ "bột" rải sát sàn.
  Sau đó `fill_small(m, 400)` để vá lỗ kim (vệt sáng trong đèn lồng).
- Cho vật chạm mép thẻ được kéo qua dải viền.
- Nền kem/vàng có **bóng ấm mềm** quanh vật (dist 30–70): mask lõi lấy `dist > ~72` (+ viền sticker trắng `C−B > 20`),
  chỉ nới **1 px** viền răng cưa, closing 1 lần — nới 2 px + closing 2 lần sẽ lấp kín khe bóng giữa các vật.
  Loại riêng: quầng sáng ấm (`R>240, G>190, B>120`, không sáng hơn nền), dải sàn cam sát mép dưới (vài px cuối),
  răng cưa của chính đường viền thẻ (lõi cách viền ≥ 3 px). Vật là **một khối đặc** (lân, thỏ...) thì lấp mọi
  lỗ kín; cành/đèn có khe hở thì chỉ lấp lỗ có `dist > 60` hoặc pixel sáng. Nền có vignette thì bỏ mẹo `EDGE∩dilate`.

### 3b. Vật thể phụ — linh hoạt theo mức ảnh hưởng tới size góc
Mục tiêu: góc ra thực tế không bị thu nhỏ vì phụ kiện kéo dài, vật chính (thỏ, trăng, đèn, lân) to nhất có thể,
nhưng vẫn giữ đúng phong cách và sự hài hòa của ảnh gốc.

**Quy tắc 1 (người dùng đã chốt):** vật phụ **không ảnh hưởng đến size** (nằm trong khung vật chính) thì
**không xóa, không thay đổi** — giữ nguyên như ảnh gốc.

**Quy tắc 2 (người dùng đã chốt): linh hoạt, không máy móc xóa.**
- Vật phụ chỉ **lẹm một chút**, không ảnh hưởng lớn (vd. 2 đám mây góc trên chỉ lẹm nhẹ so với vật bên dưới)
  → **vẫn giữ**, hoặc chỉnh nhẹ cho vừa vặn. Không nhất thiết phải xóa.
- Vật phụ **nhỏ nhưng ảnh hưởng lớn** tới size → thay đổi nó, theo thứ tự ưu tiên:
  **dời vào sâu hơn bên trong** → **thu nhỏ** → **cắt ngắn** phần đuôi (mây kéo dài, mép cắt vẫn là viền mây).
- Chỉ **xóa** khi vật phụ lẹm **quá sâu và xa**, gọt đi hay dời/thu nhỏ đều không tự nhiên.
- Có nhiều cách — chọn cách hiệu quả và tự nhiên nhất cho từng vật, xem lại trên nền tối + preview.

Cách làm (đã dùng cho widget Tết số 6):
- Xem phong cách vật trước. **Vật chính** = thành phần lớn nhất + mảnh dính vào nó (cách ≤ 3 px);
  **khung vật chính** = box từ góc thẻ tới mép xa nhất của vật chính.
- Mỗi vật phụ đo phần lẹm ra ngoài khung: trong khung hoặc lẹm ≤ ~6% chiều tương ứng (tối thiểu 4 px) → giữ.
- Lẹm nhiều → tìm chỗ trống gần nhất trong khung, cách vật khác ≥ 2 px, không chồng lên vật đã giữ (xét các vật
  được giữ trước rồi mới dời). Hoa dời ≤ ~80 px nguồn, cánh hoa/sao nhỏ ≤ ~45 px — xa hơn thì bố cục dồn cục.
- Dời vật thì dời cả **bóng của nó** (gán bóng cho vật gần nhất bằng distance transform); xóa vật thì xóa bóng của nó.
- Mảnh vụn < 25 px do ranh giới vùng cắt → bỏ.
- Khi đã lọc vật phụ bằng tọa độ (TRIM): dựng mask đầy đủ (không TRIM, không bỏ sao) song song mask đã tỉa; thành phần nào của
  `full & ~trimmed` nằm hoàn toàn trong box (co vào 2 px) thì thêm lại. Sao nhỏ thêm lại thì cắt lại theo
  đúng hình (`dist > 40` & màu vàng, quanh thành phần) để giữ 4 cánh.
- Quầng sáng, sương, trời lọt KHÔNG thuộc bước này — luôn bỏ (đó là làm sạch viền, không phải tỉa vật phụ).
- Báo lại từng vật phụ: giữ / dời (bao nhiêu px, tới đâu) / thu nhỏ / cắt / xóa và vì sao; kích thước góc %w/%h.

### 4. Tách màu
- Trong viền: alpha = 1, màu = pixel gốc.
- Vành 1 px ngoài: alpha = chiếu `(C−B)` lên `(ref−B)` với `ref` = pixel vật thể mạnh nhất trong cửa sổ 5×5;
  màu = `ref` (không trộn màu nền). Alpha < 0.08 → 0.
- Nét mảnh/mờ (mandala): alpha mềm theo `dist` trong vùng mask giãn 1px, màu = trung vị màu nét.
- Bước cuối: xóa pixel gần trắng ở dải 4 px sát mép thẻ (màu trang trắng bên ngoài dính vào).

### 5. Làm nét AI (giữ màu) — chỉ khi cần
- **Bỏ qua** nếu ảnh gốc đã rộng hơn kích thước xuất (thẻ ≥ 1900 px): chỉ cần thu nhỏ.
- Ước lượng nền ở bước 2 vẫn bắt buộc (dùng để cắt góc và để kiểm tra bóng), dù không xuất ảnh nền.
- Khi cần: Real-ESRGAN `RealESRGAN_x4plus_anime_6B.pth` (github xinntao releases) chạy không cần torch:
  đọc .pth bằng unpickler tự viết → dựng RRDBNet bằng ONNX (opset 17, `ir_version = 8`) → onnxruntime CPU, tile 160 px.
  - Lấp màu dưới pixel trong suốt bằng láng giềng gần nhất trước khi upscale (tránh viền đen).
  - **Giữ màu gốc**: `up = up + G(bicubic) − G(up)` với gaussian σ=3 (lấy chi tiết từ AI, màu từ ảnh cũ).
  - Upscale alpha bằng cùng mạng (3 kênh lặp) rồi lấy trung bình.
  - Thành phần rời rất nhỏ (< ~150 px ở ảnh gốc, vd. sao nhỏ) bị AI làm méo hình → dùng LANCZOS premultiplied
    thường cho riêng vùng đó (giãn 2 px), phần còn lại giữ bản AI.

### 6. Bóng đổ (chỉ khi ảnh gốc có)
- Dùng nền ước lượng `B` ở bước 2 (hoặc gradient 3 màu render về đúng kích thước crop); hiệu chỉnh lệch nền bằng offset trơn (gaussian 30) đo ở vùng xa vật.
- Vùng bóng = dải quanh vật (giãn ~26 px) trừ vật.
- Màu bóng = hướng tối đi trung bình của 10% pixel tối nhất, đẩy từ màu nền: `SH = bg − dir·190`.
- Alpha từng pixel: `a = ((BG−C)·(BG−SH)) / |BG−SH|²`, kẹp 0–1, lấp phần dưới vật, làm mờ σ≈1.2,
  mờ dần ở cạnh trong và cạnh trên của box góc (14 px) để không lộ vệt cắt.
- Không để bóng trên dải viền thẻ/vignette mép thẻ (nhân alpha với mask lòng thẻ co vào ~7 px) — app tự vẽ viền,
  nếu không sẽ hiện vệt cung viền mờ bên trong góc.
- Lớp bóng = ảnh 1 màu `SH` + alpha, cùng độ phân giải với ảnh vật thể, rồi
  **ghép dưới vật thể** (alpha-composite: bóng trước, vật sau) thành một ảnh RGBA duy nhất cho góc đó.
- So sánh trên/dưới với ảnh gốc ở vùng góc dưới; chỉnh đến khi sắc độ "đủ giống".

### 7. Xuất WebP
- Tỉ lệ chuẩn: chiều ngang thẻ → 950 đơn vị (như các bộ khác), xuất ở **@2x → thẻ rộng 1900 px**.
  `S = 1900 / card_width_px` (pixel crop → pixel đầu ra).
- Mỗi góc: box ôm sát vật, ép sát 2 mép của góc đó; kích thước ảnh = `round(box · S)`;
  resize bằng LANCZOS **trên ảnh premultiplied alpha** rồi chia lại (tránh viền tối).
- Lưu **WebP lossless có alpha** để viền sạch, không bị vệt nén:
  `Image.save(path, 'WEBP', lossless=True, quality=100, method=6, exact=True)`.
- Tên: `<theme>-top-left.webp`, … (bộ thứ hai cùng dịp: `<theme>-2-…`).
- Khi người dùng cần bản @1x, resize ½ bằng LANCZOS và thêm hậu tố `@1x`.

### 7b. Mã màu nền (Color 1/2/3, Border, Text)
- **Mẫu nền sạch**: pixel trong lòng thẻ (cách viền ≥ 7–12 px), **bỏ 4 vùng góc có vật**, chỉ giữ pixel trơn
  (phương sai cục bộ 7–9 px nhỏ, tổng < 20–25).
- **Fit gradient**: với tâm `(cx, cy)` (%), bán kính elip farthest-corner `rx = max(X, W−X)·√2`,
  `ry = max(Y, H−Y)·√2`; `t = √(((x−X)/rx)² + ((y−Y)/ry)²)`. Mô hình màu tuyến tính từng đoạn qua 3 mốc t = 0 / 0.5 / 1
  → giải bình phương tối thiểu ra 3 màu (góc thường bị vật che nên Color 3 là ngoại suy — bình thường).
  ```python
  b0 = np.clip(1 - t/.5, 0, 1); b1 = np.where(t < .5, t/.5, np.clip((1 - t)/.5, 0, 1)); b2 = np.clip((t - .5)/.5, 0, None)
  cols = np.linalg.lstsq(np.stack([b0, b1, b2], 1), col, rcond=None)[0]     # 3×RGB
  ```
- **Tâm**: fit 2 lần — tâm tối ưu (Nelder-Mead trên rmse) và tâm mặc định **50% / 50%**. Dựng cả hai bằng CSS
  `radial-gradient(ellipse farthest-corner at cx% cy%, c1 0%, c2 50%, c3 100%)` cạnh ảnh gốc rồi **chọn bằng mắt**;
  ưu tiên 50/50 (app thường không cho chỉnh tâm) trừ khi lệch rõ. Ghi tâm đề xuất nếu khác 50/50.
- **Border color**: lấy dải pixel giữa nét viền (trên/dưới và trái/phải, tránh 4 góc bo), lấy **trung vị của 40% pixel
  tối nhất** (bỏ pixel răng cưa pha nền).
- **Text color**: cùng hue với border (HLS), L ≈ 0.20–0.26, S ≈ 0.45–0.5 (bản đậm của màu viền, như `#83B09C` → `#1E4D3A`);
  kiểm tra tương phản WCAG với Color 1 và Color 3, phải ≥ 7:1.
- Ghi `<theme>-colors.json`:
  `{"color1": "#…", "color2": "#…", "color3": "#…", "center": "50% 50%", "border": "#…", "text": "#…"}`.

### 8. Kiểm tra trước khi giao (preview + compare)
- `<theme>-preview.png`: Playwright — ảnh gốc / thẻ dựng lại (CSS gradient 3 màu + viền border + chữ mẫu
  "HAPPY …" màu text + 4 góc WebP) / 4 góc trên nền tối.
- `<theme>-compare.png` (bắt buộc): cùng tỉ lệ, cùng khung —
  1. hàng "ẢNH GỐC": crop đúng khung thẻ (mép ngoài viền) từ ảnh gốc, resize về kích thước nền (1900×H);
  2. hàng "BẢN GHÉP": thẻ CSS gradient 3 màu + viền (render Playwright, `omit_background`, cùng kích thước 1900×H)
     + 4 góc alpha-composite (góc ghim vào đúng cạnh của nó). Trong script mẫu dưới, thay file
     `<theme>-background.webp` bằng ảnh thẻ gradient vừa render (lưu tạm trong scratchpad, không giao).
  3. lưới 4 ô phóng to từng góc (vùng ~27% rộng × 55% cao), mỗi ô đặt **gốc | ghép** cạnh nhau;
     lưới vừa đúng chiều ngang thẻ, nhãn chữ DejaVuSans-Bold, nền xám nhạt `#ECECF0`.
  In thêm sai lệch trung bình (mean abs diff) để tham khảo; khác biệt hợp lệ là phần cố ý bỏ (quầng sáng, sương).
  Xem lại ảnh compare trước khi giao; chỗ nào lệch rõ (thiếu vật, thủng, trời lọt) thì sửa mask rồi xuất lại.
  Script mẫu (đặt ở scratchpad, chạy: `python3 compare.py <ảnh gốc> <thư mục webp> <theme> <x0> <y0> <x1> <y1> <out.png>`;
  thư mục webp chứa tạm `<theme>-background.webp` = thẻ gradient đã render):
  ```python
  import sys, numpy as np
  from PIL import Image, ImageDraw, ImageFont
  SRC, WEBP, THEME, OX0, OY0, OX1, OY1, OUT = sys.argv[1], sys.argv[2], sys.argv[3], *map(float, sys.argv[4:8]), sys.argv[8]
  names = ['top-left', 'top-right', 'bottom-left', 'bottom-right']
  bg = Image.open(f'{WEBP}/{THEME}-background.webp').convert('RGBA'); W, H = bg.size
  comp = bg.copy()
  for n in names:
      im = Image.open(f'{WEBP}/{THEME}-{n}.webp').convert('RGBA')
      comp.alpha_composite(im, (0 if 'left' in n else W - im.width, 0 if 'top' in n else H - im.height))
  orig = Image.open(SRC).convert('RGBA').crop((round(OX0), round(OY0), round(OX1), round(OY1))).resize((W, H), Image.LANCZOS)
  def on_white(im):
      b = Image.new('RGBA', im.size, (255, 255, 255, 255)); b.alpha_composite(im); return b.convert('RGB')
  orig, comp = on_white(orig), on_white(comp)
  font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf', 30)
  pad, lab = 30, 50
  cw, ch = int(W * 0.27), int(H * 0.55)
  boxes = {'top-left': (0, 0), 'top-right': (W - cw, 0), 'bottom-left': (0, H - ch), 'bottom-right': (W - cw, H - ch)}
  gridW = (W - pad) // 2; zw = (gridW - pad) // 2; zh = int(ch * zw / cw)
  S = Image.new('RGB', (W + 2 * pad, pad + (lab + H + pad) * 2 + 2 * (lab + zh + pad)), (236, 236, 240)); d = ImageDraw.Draw(S)
  y = pad
  for title, im in [('ẢNH GỐC', orig), ('BẢN GHÉP (GRADIENT + 4 GÓC)', comp)]:
      d.text((pad, y + 8), title, fill=(30, 30, 40), font=font); y += lab; S.paste(im, (pad, y)); y += H + pad
  for row in range(2):
      for col in range(2):
          n = names[row * 2 + col]; bx, by = boxes[n]; x = pad + col * (gridW + pad)
          d.text((x, y + 8), f'{n}:  gốc  |  ghép', fill=(30, 30, 40), font=font)
          for k, src in enumerate((orig, comp)):
              S.paste(src.crop((bx, by, bx + cw, by + ch)).resize((zw, zh), Image.LANCZOS), (x + k * (zw + pad), y + lab))
      y += lab + zh + pad
  S.save(OUT, optimize=True)
  print('mean abs diff %.2f' % np.abs(np.asarray(orig, float) - np.asarray(comp, float)).mean())
  ```
- Sheet từng góc trên nền trắng và nền tối để soi viền mờ, lỗ thủng, trời lọt vào.
- Mở lại từng WebP bằng PIL: mode `RGBA`, kích thước đúng, alpha có giá trị 0 ở vùng trống.
- Kiểm tra `colors.json` đúng định dạng `#RRGGBB` (chữ hoa) và Text đạt ≥ 7:1.

### 9. Giao file (1 zip trong chat + 1 thư mục trên máy)
- Thư mục chung trên máy: `~/Downloads/seasonal-widgets/`, mỗi bộ một thư mục con đánh số tiếp theo
  (`1-thanksgiving … 7-diwali-2, 8-mid-autumn, 9-<theme>…` — liệt kê thư mục để lấy số kế tiếp).
  Thư mục con chứa 4 file WebP góc + `<theme>-colors.json` + `<theme>-preview.png` + `<theme>-compare.png`.
- Đóng gói: tạo thư mục `<n>-<theme>/` trong outputs (4 WebP + colors.json + preview + compare) → zip thành `<n>-<theme>.zip`
  (zip giữ nguyên thư mục bên trong).
- Gửi trong chat **chỉ 1 lần `SendUserFile` với file zip** (display `attach`) — không gửi từng WebP/preview/compare riêng.
- Trong câu trả lời luôn có **bảng mã màu** (Color 1/2/3, Border, Text + vị trí) để dán thẳng vào app; nêu tâm nếu khác
  50/50 và tỉ lệ tương phản của Text.
- Đưa lên máy bằng chính file zip đó: `device_commit_files` zip vào thư mục tạm `_transfer_tmp` bên trong thư mục
  được kết nối → shell trên máy: giải nén vào `~/Downloads/seasonal-widgets/` (python `zipfile.extractall`),
  `chmod -R go+rX` thư mục mới, xóa thư mục tạm (`rm -rf` chỉ đúng `_transfer_tmp`). Không để lại zip trên máy
  trừ khi người dùng muốn.
- Trong câu trả lời: nói file đã nằm sẵn trong `seasonal-widgets/<n>-<theme>/` và zip có trong chat; tóm tắt
  những khác biệt còn thấy trong ảnh compare (nếu có) và vì sao.
- Báo ngắn: bảng file + kích thước px, những gì đã bỏ (quầng sáng, trời lọt, sương, hạt lẻ), bóng có/không,
  có dùng AI làm nét hay không.

## Lỗi đã gặp
- `ir_version 14` không chạy được với onnxruntime → đặt `m.ir_version = 8`.
- Regex sửa `width=` trong SVG làm hỏng `stroke-width` → dùng `(?<![-\w])width=`.
- Cắt bằng alpha mềm theo `dist` để lại quầng mờ quanh vật → luôn dùng mask cứng (bước 3–4).
- Bóng tự chọn màu (xám/xanh nhạt) bị nhạt hơn gốc → phải đo màu và alpha từ ảnh (bước 6).
- WebP lossy (`quality<100`) làm viền alpha răng cưa/loang màu → luôn dùng `lossless=True`.
- `binary_fill_holes(m | ~inner)` lấp cả lòng thẻ → dùng `fill_small` có giới hạn diện tích lỗ.
- Nền ước lượng có thang nhỏ làm lòng trăng/thỏ/mây bị coi là nền (vật thủng lỗ) → chỉ dùng thang lớn.
- Bộ lọc quầng quanh trăng cắt nhầm mây chồng lên trăng → giới hạn theo phía/tọa độ, kiểm tra vùng chồng.
- Bộ lọc "pixel nhạt" làm thủng vệt sáng trong đèn lồng → `fill_small(m, 400)` sau khi lọc.
- File chuyển lên máy có quyền `-rw-------` → `chmod -R go+rX` thư mục đích.
- Xóa luôn cả vật phụ nằm trong khung vật chính (xoáy mây, sao nhỏ cạnh đèn) dù không làm góc to hơn → sai;
  chỉ tỉa phần làm khung to ra (bước 3b).
- Xếp sương/quầng vào nhóm "tỉa" rồi thêm lại vì nằm trong khung → hiện lại vệt mờ; quầng/sương phải nằm ở
  bộ lọc làm sạch (luôn bỏ).
- Sao nhỏ qua Real-ESRGAN thành cục méo → LANCZOS cho thành phần nhỏ.
- Xóa vật phụ chỉ lẹm một chút (vd. 2 đám mây lẹm nhẹ) → sai; giữ hoặc dời/thu nhỏ cho vừa, xóa là lựa chọn cuối (bước 3b).
- Dời vật phụ chỉ tránh vật chính → chồng lên vật phụ đã giữ thành cụm → xét vật được giữ trước, chừa khoảng cách.
- Nới mask 2 px + closing 2 lần trên nền có bóng ấm → lấp kín khe bóng giữa các vật (hiện mảng kem trên nền tối).
- Bóng đo cả vignette mép thẻ → hiện vệt cung viền mờ trong góc → bỏ bóng trong ~7 px sát mép thẻ.
- Fit tâm tự do có thể ra tâm lệch (vd. 62/45) dù nhìn bằng mắt tâm 50/50 giống hơn → luôn dựng cả hai và chọn bằng mắt.