color-handoff-tonal-bridge

name	color-handoff-tonal-bridge
description	motion-graphic primitive — graphic fill color is intentionally tied to a hue in underlying live-action footage so a wipe between graphic and photo reads as one continuous surface, not a collage. used in slatted-reveal scenes where the original solid fill matches a model's clothing or scene element in the photo behind.

color-handoff-tonal-bridge

Purpose

Bridge a graphic-design layer and a live-action photography layer by matching the graphic's fill color to a dominant hue in the photograph. When the photo is revealed (via slat-wipe or mask-wipe), the transition reads as one surface morphing, not two disparate elements colliding.

Params

{
  "layer_a": {
    "kind": "solid-fill",
    "color": "#C16C4C"                   // terracotta — designer-picked
  },
  "layer_b": {
    "kind": "photograph",
    "src": "assets/model-in-red-sweater.jpg",
    "dominant_hue_at_anchor": "#B85E45"  // model's sweater color
  },
  "delta_e_tolerance": 8,                // perceptual color distance allowed

  "bridge_method": "color-pick-match",   // color-pick-match | overlay-tint | tonal-shift
  "anchor_point_in_photo_pct": [0.45, 0.55]   // where in the photo the bridge color is sampled
}

Behaviour

The atom doesn't animate — it's a validation + advisory primitive. It checks that:

1. layer_a.color ΔE-matches layer_b.dominant_hue_at_anchor within delta_e_tolerance.
2. If they don't match, surface a warning at impl-brief time recommending the designer adjust the fill or pick a different photo anchor.

The actual visual transition uses slat-wipe or mask-wipe; this primitive just enforces that the colors align so the transition lands.

Style pack overrides

• Custom packs (wellness, editorial) — primary use case for slatted reveals.
• SP-C (editorial-cinematic) — occasional, when type beats transition to photo beats.

Quality Checks

• ΔE between layer_a.color and layer_b.dominant_hue ≤ 8 (perceptually similar).
• Anchor point in photo is a substantial color region (not a small accent).
• Bridge method matches the transition type (color-pick-match for slat-wipe, tonal-shift for crossfade).

Failure Modes

• Colors don't match — transition reads as a jump. ΔE too high. Either re-color the graphic or re-anchor the photo sample.
• Bridge color region too small in photo. Reveal exposes a different dominant color. Pick a larger anchor region.