xxd-palette-builder

name	xxd-palette-builder
description	Build complete practical palettes from the Chinese traditional color dataset. Use when a user needs main, support, accent, neutral, ratio, harmony, or role-based palette options from a traditional color, HEX, mood, brand, poster, UI, packaging, or content direction.

xxd-palette-builder

Purpose

Use this skill when the problem is choice. The user may like one color, a mood, or a reference, but still needs a small number of usable palettes with clear roles and tradeoffs.

Pain Points This Solves

• Designers get too many attractive swatches and still do not know which combination is safest.
• Harmony tables are useful, but users need role assignment: main, support, neutral, accent, warning, and background.
• Chinese traditional colors can become decorative quickly unless proportion and surface risk are decided early.

Data Contract

• Load the bundled references/chinese-color-harmony.csv before recommending combinations.
• Use references/chinese-color-master-list.md as the complete 742-color Markdown source list.
• Use references/chinese-color-harmony.md when a Markdown preview of the same harmony relationships is easier to inspect.
• Use the harmony columns selectively: 同类色, 邻近色, 互补色, 分裂互补, 三角色, 四角色, 冷暖对照, 明色搭配, 暗色搭配, 灰调搭配, 中性色搭配, 主色, 辅色, and 点缀色.
• Every recommended HEX must exist in the current 742-color data.
• If the user gives an outside HEX, map it to the nearest project color and say it is a match, not a source color.
• Prefer one strong recommendation over showing every possible harmony relation.

Palette Decision Workflow

1. Classify the anchor:
   • Existing color or HEX: preserve recognition first.
   • Mood or adjectives: run a brief-like translation before picking.
   • Surface: choose by use case, not by beauty alone.
2. Pick a palette strategy:
   • Reliability: adjacent, gray-toned, neutral, and high readability.
   • Identity: one recognizable traditional anchor plus restrained support.
   • Contrast: complementary or split-complementary only when the design needs energy.
   • Series: stable neutrals plus rotating accents.
3. Build 1 to 3 options, each with a job:
   • Safe option: least likely to break layout or readability.
   • Character option: strongest Chinese traditional signal.
   • Contrast option: more memorable, higher risk.
4. Assign roles before presenting colors. Never output unordered swatches.
5. Add ratios and a usage warning for each option.
6. Select one final recommendation unless the user explicitly wants alternatives.

Output Shape

For each palette:

• Palette name and best use case.
• Role table: role, color name, HEX, ratio, source relation, reason.
• Surface notes: background, text, CTA, accent, border, decoration, or packaging panel.
• Risk note: contrast, dark mode, print drift, over-saturation, cultural cliche, or weak hierarchy.
• Final pick: one palette with why it wins.
• Next skill: usually xxd-palette-applier, xxd-ui-token, xxd-accessible-color, or xxd-print-packaging.

Do not explain color theory unless it changes the recommendation.