---
name: component-harmony-test
description: Test component color harmony by reading selected component variations and a target screen, grouping variations into tonal harmony families, and producing the minimum set of comparison screens with harmonious component combinations injected. Use when the user wants to see how different component styles and colors work together in a real UI context.
---

# Component Harmony Test

Test how different component color variations work together in a real screen by producing comparison screens that group components into tonal harmony families.

## Running this with Claude and the Figma MCP

Written for Figma's built-in agent, adapted for Claude (Claude Code, Claude Desktop or claude.ai) connected to the official Figma MCP server.

- **Get the file.** If you don't have a Figma link, ask for one. The file key is the segment after `/design/`; a `node-id=1-2` parameter means node `1:2`.
- **Start a session.** Call `create_session` with the file key before any other Figma tool, and pass the returned session ID on every later call.
- **Read before writing.** `get_metadata` shows the structure and the user's current selection, `get_variable_defs` lists the variables on a node, `search_design_system` finds published components, variables and styles, and `get_screenshot` shows what's on the canvas.
- **Write with `use_figma`.** It runs Plugin API JavaScript in the file. Load the `figma-use` skill first (plus `figma-generate-library` when you create variables, styles or components) and list them in `skillNames`. Scripts use top-level `await` and `return` everything they create: nothing persists between calls, so pass node and variable IDs forward as string literals. Colors are 0–1, not 0–255. Switch pages with `await figma.setCurrentPageAsync(page)`, at most once per call; for multi-page work, run one call per page in parallel. `figma.notify()` isn't available.
- **Ask, then wait.** Wherever a step says to ask the user, ask in chat (in Claude Code, use the AskUserQuestion tool) and wait for the answer before building.
- **Clear helper fills.** `figma.createAutoLayout()` frames start with a white fill. Set `fills = []` on rows and wrappers that should be transparent, or they show up as white bars (most visibly in dark-mode previews).
- **Check the result.** After a build step, take one screenshot (`await node.screenshot()` inside `use_figma`, or `get_screenshot`) and fix only what's wrong.

## Core Concept: Harmony Groups

A **harmony group** is a set of component variations whose color ranges share a tonal relationship — they sit in the same region of saturation, lightness, and hue temperature. Components within a harmony group should feel like they belong together.

Examples of harmony groups:
- **Pastel / Light**: fills in the -50 to -100 range, soft saturation, light backgrounds, dark text
- **Mid-tone / Saturated**: fills in the -200 to -300 range, medium saturation, balanced contrast
- **Bold / Deep**: fills in the -400+ range or dark backgrounds with light/colored text, high saturation
- **Monochrome / Neutral**: grays, silvers, subtle tints — no dominant hue

The number of harmony groups determines the number of comparison screens — NOT the cartesian product of every component variation.

## Workflow

### Step 1: Read the Selected Components

The user will select component variations on canvas. Read each selection to extract:

- **Component type**: What role does it play? (e.g., status indicator, tag/label, avatar, button, badge, chip, card header)
- **Color range**: What fills, strokes, and text colors does it use?
- **Style philosophy**: Does it use pastel fills? Bold fills? Strokes? Tone-on-tone? Inverted?
- **Number of sub-variations**: How many color options exist within this component type? (e.g., 4 status colors, 10 tag colors, 5 avatar hues)

### Step 2: Classify into Harmony Families

Group the selected component variations by tonal compatibility:

1. **Identify the dominant style axes.** Look at the component set as a whole. What are the distinct design philosophies present? (e.g., "light pastel fills with dark text" vs. "dark fills with colored text and strokes")
2. **Group components that share a tonal register.** Components with similar lightness, saturation, and contrast strategy belong in the same harmony group. A pastel status chip harmonizes with a pastel tag, not a bold one.
3. **Within each harmony group, select the best-fitting color for each component.** If there are 10 tag colors available and 5 are pastel, those 5 go in the pastel group. The other 5 (if bolder) go in the bold group.
4. **Handle components with only one variation.** If a component (like a button) has a single replacement color, it appears in ALL harmony groups unchanged.

### Step 3: Determine Screen Count

Suggest the number of screens based on the number of **distinct harmony groups**, NOT the total number of individual variations.

**Formula:** Screens = number of distinct harmony groups identified in Step 2.

Explain the reasoning to the user:
- "I see 2 distinct harmony families in your selections: a pastel set and a bold set. I'd suggest **2 screens** — one per family — so you can compare which tonal approach works best."
- "Your components all fall within the same tonal range, so **1 screen** should be enough to see the harmony."
- "I see 3 tonal registers: light, mid-tone, and bold. I'd suggest **3 screens**."

If the user wants to see additional sub-variations (e.g., different avatar hues within a harmony group), offer that as an optional expansion — but recommend starting with the minimum.

Wait for the user to confirm or adjust the screen count before proceeding.

### Step 4: Read the Target Screen

Read the target screen's layer tree to understand:

- **What component types are present** and where they sit in the hierarchy
- **Which nodes match the selected component types** — match by component name, instance type, or structural role (e.g., find all instances of "Status Badge" in a Status column, find all "Tag" instances in a Tags column)
- **The injection points** — the specific node IDs where each component type's color/style will be overridden

Log the mapping: "Found 10 Tag instances in the Tags column, 10 Status chips in the Status column, 1 Avatar in the Header, 1 Primary Button above the table."

### Step 5: Clone and Inject

For each harmony group:

1. **Clone the target screen** (`node.clone()` in `use_figma`; position the clone in clear space to the right). Name it descriptively: `{ScreenName} — {HarmonyGroupName}` (e.g., "Customer Lookup — Pastel Harmony", "Customer Lookup — Bold Harmony")
2. **Inject component overrides.** For each component type in this harmony group:
   - Navigate to each injection point identified in Step 4
   - Override fills, strokes, and text colors to match this harmony group's assigned variation
   - Maintain WCAG 2.2 contrast: 4.5:1 for text-on-fill, 3:1 for fill-on-background
3. **Position the clone** next to the previous screen on canvas for easy comparison.

### Step 6: Verify Harmony

For each completed screen:
- Screenshot and visually verify that all injected components feel cohesive
- Check that no single component stands out as tonally mismatched
- Confirm all text remains legible against its background

Report to the user: "Here are your {N} harmony comparison screens. How do they look?"

## Harmony Principles

When classifying and selecting component colors, apply these principles:

1. **Tonal cohesion over individual beauty.** A color that looks great in isolation may clash in context. Prefer colors that sit in the same lightness/saturation band as their neighbors.
2. **Match saturation levels.** Pastel components pair with pastel. Bold with bold. Mixing registers within a screen creates visual tension.
3. **Complementary hue temperature.** Warm and cool hues can coexist if their saturation and lightness match. A warm pastel yellow and a cool pastel teal can harmonize; a bold warm red and a pastel cool blue will fight.
4. **Contrast strategy consistency.** If status chips use dark-text-on-light-fill, tags in the same screen should too. If chips use light-text-on-dark-fill, tags should match that strategy.
5. **Let the screen's existing palette guide you.** The background, text colors, and chrome of the target screen establish a tonal baseline. Injected components should complement it, not compete.

## Accessibility

All injected colors must meet WCAG 2.2:
- **Text on fill:** minimum 4.5:1 contrast ratio
- **Fill on background:** minimum 3:1 contrast ratio
- **Interactive indicators** (dots, icons): clearly visible against their container

If a desired color fails contrast, shift it toward a passing variant in the same hue family rather than switching hues.

## Key Gotchas

- **Cannot appendChild into instances** — use fill, stroke, and text overrides instead of inserting new nodes
- **Load fonts** before editing any TEXT node's fills or characters
- **Column-wise tables**: each column may be a separate child — walk the full tree to find all instances of a component type
- **Deeply nested instances**: component variations may be 3–5 levels deep in the hierarchy — traverse thoroughly
- **Single-variation components** (like a button with one new color) go in every screen unchanged