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:

```css
/* 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):
```css
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):
```css
.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):
```css
@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

```css
@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

```css
@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.