paper-dynasty-card-creation/docs/refractor-visual-spec.md

Refractor Tier Visual Spec — Cherry-Pick Reference

Approved effects from wip/refractor-card-art mockup (docs/refractor-tier-mockup.html). This document is the handoff reference for applying these visuals to the production card renderer.

---

1. Tier Diamond Indicator

A 4-quadrant diamond icon centered at the intersection of the left/right column headers. Replaces all per-tier emoji badges.

Positioning & Structure

• Position: left: 600px; top: 78.5px (centered between column header top/bottom borders)
• Size: 19px × 19px (tips fit within header row bounds)
• Rotation: transform: translate(-50%, -50%) rotate(45deg)
• Layout: CSS Grid 2×2, gap: 2px
• Background (gap color): rgba(0,0,0,0.75) with border-radius: 2px
• Base shadow: 0 0 0 1.5px rgba(0,0,0,0.7), 0 2px 5px rgba(0,0,0,0.5)
• z-index: 20

Fill Order (Baseball Base Path)

Quadrants fill progressively following the base path: 1st → 2nd → 3rd → Home.

Tier	Quadrants Filled	Visual
T0 (Base)	0 — no diamond shown	—
T1	1st base (right)	◇ with right quadrant filled
T2	1st + 2nd (right + top)	◇ with two quadrants
T3	1st + 2nd + 3rd (right + top + left)	◇ with three quadrants
T4	All 4 (full diamond)	◆ fully filled

Grid-to-Visual Mapping (after 45° rotation)

The CSS grid positions map to visual positions as follows:

Grid Slot	Visual Position	Base
div 1 (top-left)	TOP	2nd base
div 2 (top-right)	RIGHT	1st base
div 3 (bottom-left)	LEFT	3rd base
div 4 (bottom-right)	BOTTOM	Home plate

Render order in HTML: [2nd, 1st, 3rd, home] (matches grid slot order above).

Quadrant Fill Styling

Unfilled quads: background: rgba(0,0,0,0.3) (dark placeholder).

Filled quads use a gradient + inset shadow for depth:

/* Standard filled quad */
.diamond-quad.filled {
  background: linear-gradient(135deg, {highlight} 0%, {color} 50%, {color-darkened-75%} 100%);
  box-shadow:
    inset 0 1px 2px rgba(255,255,255,0.45),
    inset 0 -1px 2px rgba(0,0,0,0.35),
    inset 1px 0 2px rgba(255,255,255,0.15);
}

Approved Effect: Metallic Sheen + Pulse Glow

The approved diamond effect combines metallic inset highlights with an animated glow pulse.

Metallic gradient (replaces standard gradient on filled quads):

background: linear-gradient(135deg,
  rgba(255,255,255,0.9) 0%,
  {highlight} 20%,
  {color} 50%,
  {color-darkened-60%} 80%,
  {highlight} 100%);

Metallic inset shadows (boosted highlights):

.diamond-quad.metallic.filled {
  box-shadow:
    inset 0 1px 3px rgba(255,255,255,0.7),
    inset 0 -1px 2px rgba(0,0,0,0.5),
    inset 1px 0 3px rgba(255,255,255,0.3),
    inset -1px 0 2px rgba(0,0,0,0.2);
}

Glow pulse animation (tight diameter, applied to .tier-diamond container):

@keyframes diamond-glow-pulse {
  0%   { box-shadow:
    0 0 0 1.5px rgba(0,0,0,0.7),
    0 2px 5px rgba(0,0,0,0.5),
    0 0 5px 1px var(--diamond-glow-color);
  }
  50%  { box-shadow:
    0 0 0 1.5px rgba(0,0,0,0.5),
    0 2px 4px rgba(0,0,0,0.3),
    0 0 8px 3px var(--diamond-glow-color),
    0 0 14px 5px color-mix(in srgb, var(--diamond-glow-color) 25%, transparent);
  }
  100% { /* same as 0% */ }
}

.tier-diamond.diamond-glow {
  animation: diamond-glow-pulse 2s ease-in-out infinite;
}

Metallic effect automatically enables the glow pulse (no separate toggle needed in production).

---

2. Tier Diamond Colors

Tier	Color (body)	Highlight (bright edge)	Glow Color	Intent
T1	#d46a1a	#f0a050	#d46a1a	Orange
T2	#b82020	#e85050	#b82020	Red
T3	#7b2d8e	#b860d0	#7b2d8e	Purple
T4	#1a6af0	#60b0ff	#1a6af0	Blue flame

Progression: warm → hot → regal → transcendent.

---

3. T3 Gold Shimmer Sweep (Header Animation)

A single narrow gold stripe sweeps left-to-right across the card header.

• Duration: 2.5s loop, ease-in-out
• Gradient: 105° diagonal, peak opacity 0.38
• Key colors: rgba(255,240,140,0.18) → rgba(255,220,80,0.38) → rgba(255,200,60,0.30)
• Scope: Header only (.card-header has overflow: hidden)
• z-index: 5

@keyframes t3-shimmer {
  0%   { transform: translateX(-130%); }
  100% { transform: translateX(230%); }
}

Playwright APNG Capture

For static card rendering, the shimmer position is driven by --anim-progress (0.0–1.0) instead of CSS animation. Playwright captures 8 frames to produce an APNG.

---

4. T4 Superfractor — Layered Animation System

T4 stacks four independent effect layers for a premium look qualitatively different from T3.

Layer 1: Prismatic Rainbow Header Sweep

• Seamless loop using a 200%-wide element with two mirrored rainbow bands
• translateX(-50%) over 6s linear = continuous wrap
• Colors: red → gold → green → blue → violet → pink, all at ~0.28 opacity
• z-index: 1 (behind header text at z-index: 2)
• Header children get position: relative; z-index: 2 to sit above rainbow

Layer 2+3: Gold/Teal Dual Glow Pulse

• Applied via ::before on the card element
• Gold and teal in opposition: when gold brightens, teal dims and vice versa
• 2s ease-in-out loop
• Inset box-shadows (45px 12px gold, 80px 5px teal)
• z-index: 4

@keyframes t4-dual-pulse {
  0%   { box-shadow: inset 0 0 45px 12px rgba(201,169,78,0.40),
                      inset 0 0 80px 5px rgba(45,212,191,0.08); }
  50%  { box-shadow: inset 0 0 45px 12px rgba(201,169,78,0.08),
                      inset 0 0 80px 5px rgba(45,212,191,0.38); }
  100% { /* same as 0% */ }
}

Layer 4: Column Bar Shimmer

• White highlight (rgba(255,255,255,0.28)) sweeps across each column header bar
• 1.6s ease-in-out loop, staggered by -0.25s per bar for a ripple effect
• 6 bars total (3 left group, 3 right group)

---

5. T4b Variant — Full-Card Rainbow

Same as T4 but the prismatic rainbow covers the entire card height (not just header).

• Applied via ::after on .pd-card instead of .card-header::after
• Slightly reduced opacity (0.18–0.22 vs 0.28–0.32)
• z-index: 6 (above content)
• Dual glow pulse uses a separate .dual-pulse-overlay div at 2.8s (slightly slower)
• Column bar shimmer identical to T4

Status: Experimental variant. May or may not ship — kept as an option.

---

6. Corner Accents (T4 Only)

L-shaped corner brackets on all four card corners.

• Color: #c9a94e (gold)
• Size: 35px arms, 3px thick
• Implementation: Four absolutely-positioned divs with two-sided borders each
• z-index: 6

---

7. Implementation Notes for Production

What to port

1. Diamond indicator CSS (.tier-diamond, .diamond-quad, keyframes) → add to card template stylesheet
2. Diamond HTML generation → add to Playwright card renderer (4 divs in a grid)
3. Metallic + glow effect → always apply metallic class + glow animation to filled diamonds
4. T3 shimmer → APNG capture with --anim-progress variable (8 frames)
5. T4 layered effects → APNG capture with --anim-progress driving all 4 layers
6. Diamond colors → store in tier config or derive from tier level
7. Corner accents → T4 only, simple border divs

What NOT to port

• The mockup control panel UI (sliders, dropdowns, color pickers)
• The diamondEffect dropdown with 5 options (we chose metallic — hardcode it)
• The separate diamondGlow toggle (metallic always includes glow)
• Border preset / header type controls (these are already in production tier configs)
• T4b full-card rainbow (unless explicitly promoted later)

Database/API considerations

The diamond fill count is already derivable from the tier level — no new database fields needed:

• refractor_tier = 1 → diamondFill = 1, color = orange
• refractor_tier = 2 → diamondFill = 2, color = red
• refractor_tier = 3 → diamondFill = 3, color = purple
• refractor_tier = 4 → diamondFill = 4, color = blue-flame

Diamond colors are purely visual (CSS) — they don't need to be stored.