Ppt Keycolor Changer

What this skill does

Discovers every color in a PPTX file by scanning raw XML, then replaces source colors with target colors via case-insensitive string replacement — capturing 100% of color references including theme tokens, gradient stops, chart series, table cells, hyperlinks, and schemeClr mappings that python-pptx's API misses.

Standing Mandates

• Always run discovery first: Never skip Step 1. Even when the user provides exact hex values, the frequency scan confirms the color is actually in the file and reveals tonal variants they may have missed.
• Confirm before executing: Show the full mapping table (Step 4) and get explicit user sign-off before calling the replace subcommand. Don't run it speculatively.
• Name-to-hex confirmation required: When the user says a brand or named color ("토스 파란색", "Apple blue"), always state the hex you intend to use and wait for confirmation.
• Always include the image caveat: Every report (Step 7) must note that PNG/JPEG embedded image colors cannot be changed via XML, regardless of residual count.

7-Step Workflow

Step 0 · Validate Input

• Accept .pptx or .pptm only. Reject .pdf, .key, .odp.
• If the user provides a path that ends in .pdf, or a directory that contains both foo.pdf and foo.pptx, explicitly confirm: "PPTX 파일로 진행하겠습니다."
• The bundled script is at scripts/ppt_keycolor_changer.py relative to this skill root. Always use an absolute path when invoking it.

Step 1 · Discover Palette

Run discovery before asking about target colors. Always do this first.

python /abs/path/to/scripts/ppt_keycolor_changer.py discover \
  --input "path/to/file.pptx"

This scans all .xml and .rels entries inside the PPTX ZIP and prints a frequency table of every val="XXXXXX" hex value found — theme file, slide layouts, chart XML, table styles, hyperlinks — everything.

Present the table to the user, then:

1. Identify key color candidates: high-frequency, non-grayscale colors are usually brand key colors.
2. Cluster by hue: if the user said "오렌지 계열" or named a hue, group discovered colors within HSL hue ±15° of that hue and show the cluster as the replacement candidates.
3. Flag grayscale / always-excluded colors: mark #000000, #FFFFFF, #F9F9F9, and colors with RGB max−min ≤ 20 — these will be preserved by default.
4. Accent check: for low-frequency colors, ask whether they should also be replaced or left alone.

Step 2 · Resolve Target Colors

The user can specify a target in three ways:

A. Brand preset — e.g., "토스 파란색", "Apple blue":

B. Custom hex — user provides exact hex value(s). Use as-is.

C. Color name — resolve from knowledge (e.g., "카카오 노란색"), state the hex you intend to use, and ask for explicit confirmation before proceeding.

Step 3 · Auto-Map Source Palette → Target Palette

When the source has multiple tonal variants (vivid, light, lighter, muted) and the target is a preset, map by HSL lightness rank to preserve the visual hierarchy:

1. Take the source color cluster from Step 1 (all colors within hue ±15°).
2. Sort them by HSL lightness (L value), darkest to lightest.
3. Sort the target preset's 5 tones by lightness in the same order.
4. Pair 1:1 in lightness order.

If the source has more tones than the target has slots, ask the user which extras to merge into the closest target tone.

Step 4 · Confirm Mapping Table

Show the full proposed mapping before running anything. Format it clearly:

Source color  →  Target color    (occurrences)
#E85E3A       →  #0064FF         (193 ← main key color)
#FF8060       →  #4D96FF         (42  ← light variant)
#FFB399       →  #99C2FF         (18  ← lighter variant)

Preserved (won't be touched):
  #000000   [always-exclude]
  #FFFFFF   [always-exclude]
  #808080   [grayscale]
  #336699   [different hue — >60° from source]

Also list any colors the user flagged as "leave alone" from the Step 1 review.

Get explicit user confirmation before running Step 5.

Step 5 · Apply via Raw XML Replace

python /abs/path/to/scripts/ppt_keycolor_changer.py replace \
  --input  "path/to/file.pptx" \
  --mapping '{"E85E3A":"0064FF","FF8060":"4D96FF","FFB399":"99C2FF"}' \
  [--exclude "336699,AABBCC"]   \
  [--suffix tossblue]

Arguments:

Output naming: <original>_<target_or_suffix>.pptx. If that file already exists, auto-increments to _v2, _v3, etc. — no silent overwrites.

Built-in exclude defaults (always applied): #000000, #FFFFFF, #F9F9F9, #FEFEFE, #FDFDFD.

Step 6 · Verify Zero Residuals

The script automatically re-scans the output file after replacement and reports:

• OK — no residual source colors found. → done.
• WARNING — #E85E3A: 12 occurrences remain → investigate.

If residuals remain after replacement, they almost always mean one of two things:

• Embedded images (PNG/JPEG/WMF/EMF) contain the color — the script cannot change pixels inside binary media files.
• External Excel workbook linked to a chart — some series colors live in the .xlsx and are not part of the PPTX XML.

Report both cases explicitly to the user.

Step 7 · Report

After completion, tell the user:

1. Output file path (full, absolute)
2. Replacement count per source color
3. Verification result (zero residuals, or list of exceptions with cause)
4. Preserved colors and the reason each was skipped
5. Always include this caveat:

   ⚠️ 슬라이드에 삽입된 이미지(PNG/JPEG 등) 내부의 색상은 XML 치환으로 변경되지 않습니다. 해당 이미지는 포토샵 등에서 별도로 수정이 필요합니다.

Preservation Filter (Default Rules)

The following categories are never replaced by the script's built-in defaults and should be excluded from the mapping Claude proposes:

To override a default exclusion, the user must explicitly include it in --mapping.

When presenting the Step 4 confirmation table, call out any "don't touch" candidates with a brief reason so the user can consciously override if they want.

Limitations