# Shared card frames and text backings

Canonical reusable layers live here, alongside the shared [fonts](../../fonts/README.md). Card builders reference a pinned tier/version directly rather than generating or copying borders and backings into each proof.

Every asset uses the full **2000 × 2800** canvas at origin **(0, 0)**. `exports/` contains master, 1000, and 500 widths. `source/` contains editable SVGs; Uncommon retains its approved raster border with a linked SVG wrapper. Layout and provenance are retained beside a hash manifest. The original spike files are preserved.

| Tier | Historical reference | Revised candidate | Treatment |
|---|---|---|---|
| Common | `common/v1` — Timothy | `common/v2` | Plain frame and panels, current cream/blue palette; crisp standalone Borderless edges with simple rounded corners |
| Uncommon | `uncommon/v1` — Calling the Disciples | `uncommon/v2` | Existing border and ornament geometry; darker, more substantial single inset rule and lozenge dividers |
| Rare | `rare/v1` — Burning Bush | `rare/v2` | Existing thin frame and floating panels; stronger double rules and corner lozenges |
| Extraordinary | `extraordinary/v1` — The Fall v7 contrast | `extraordinary/v2` | Existing gold vines and emblems; floating Normal panels expose artwork around their perimeter |

`v2` is the selected **review candidate**, not a claim of user approval. The four revised candidates need visual review, including under moving harness lighting. `v1` preserves the historical layer pixels and provenance; it is not an instruction to restore legacy fonts or colors in new cards.

## Components

- `overlay-normal`: Normal backing composited beneath the Normal frame, without lettering.
- `frame-textless`: Textless outer frame, without backing or lettering. Rare intentionally uses a different frame from Normal.
- `backing-borderless`: Standalone backing only, without outer frame or lettering.
- `frame-normal` and `backing-normal`: Separate editable components of the Normal overlay.
- Boundless uses neither frame nor backing.

Text remains card-specific and is rendered with the shared Bold/Medium P052 role system. A glyph mask is derived from the actual lettering alpha; finish maps are compiled from the active printing's actual overlay/lettering alpha.

Borderless panels use crisp, normally antialiased boundaries across all non-Legendary tiers. Do not add Gaussian blur, feathering, or a fuzzy halo to Common. The softened Common treatment is retained only in the historical `v1` reference.

All revised tiers use text **#263f50** and backing base **#f4ead4**. Uncommon/Rare retain their existing cream tonal gradient and fiber overlays. Decorative ink **#806438** is shared by the revised ornate backings; tier distinction comes from ornament structure and density. This darker ink is intended to remain visible at smaller delivery sizes.

## Geometry

Common and Uncommon have joined Normal backings with overlap under the frame. Rare has a **36 master pixel** intentional art reveal between its 24px perimeter and its 60px panel inset. Extraordinary now has a **28 master pixel** reveal between its 32px perimeter and its 60px panel inset. These transparent regions are part of the design, rather than missing join pixels. The title's lower edge remains y=360 and the footer begins y=2180, preserving the established scene window.

Use `layout.json` and actual overlay coverage to review faces and gestures before illustration approval. Do not infer hidden artwork from lettering bounds alone.

## Builder usage

```python
import sys
sys.path.insert(0, str(repo_root / 'artifacts/layers'))
from library import load_tier

shared = load_tier('rare', 'v2')  # Pin an explicit reviewed version in card data.
layout = shared['layout']
normal_overlay = shared['assets']['overlay-normal']
textless_frame = shared['assets']['frame-textless']
borderless_backing = shared['assets']['backing-borderless']
```

The loader fails on missing or changed assets, layout, or source files. Record the returned manifest SHA-256 and each active component's path/hash in the card validation. Do not refresh shared assets as part of a card build. A template revision needs a new version folder once the previous version is approved.

```sh
# Check rendering repeatability and geometry; does not change the templates.
python3 artifacts/layers/build.py

# For an explicitly revised template during template development only:
python3 artifacts/layers/build.py --tier rare --version v2 --refresh
```

The [comparison proof](../../spikes/tier-layer-library-proof/README.md) references this library directly and exports all four printings. Historical spike builders remain reproducible records of their original designs.


## Approved spacing revision — v3

Uncommon, Rare and Extraordinary now also provide `v3`, preserving their `v2` frames, panel geometry, palette, textures and side/corner decoration. Central flourishes use the reviewed 20 master pixel gap to the innermost rule. Layouts declare the fixed reference line-box and visible-ink verse-centering policy from [Art Direction](../../docs/art-direction.md#flourish-and-footer-text-spacing). Common is unchanged.

The three refreshed working cards pin `v3` explicitly. General selected-version defaults remain `v2`; existing accepted cards keep their prior manifests. The spacing comparison was visually approved, while these complete new printings still need user and moving-light review. [spacing_v3.py](spacing_v3.py) records the migration algorithm and checks that retained frames match `v2` and Borderless backings reproduce the approved trial.