Ferrous-Solitaire/docs/ui-mockups/card-face-migration.md

Card-face artwork migration plan

Status: planning artifact (no code changed by this document). Tracks: the "Card-face / suit / card-back artwork regeneration" item in SESSION_HANDOFF.md → "Visual-identity follow-ups" (SESSION_HANDOFF Resume prompt option D). Companion to: docs/ui-mockups/design-system.md (Game Cards spec, lines 214–233) and docs/ui-mockups/desktop-adaptation.md (rules-based companion to the mockups).

Why this is a multi-session arc

Every post-v0.20.0 visual-identity port to date (modal scaffold, toasts, table chrome, splash boot screen, replay overlay) was a single rendering path — change tokens, change comments, ship. Cards have two rendering paths that are visually identical today and would visually disagree the moment one moves:

1. PNG path (production). assets/cards/faces/<rank><suit>.png loaded into CardImageSet.faces[suit][rank] at startup; card sprites blit the texture. 52 face PNGs + 5 back PNGs already in assets/, all the legacy white-card aesthetic from the pre-Terminal design system.
2. Constant fallback (tests + asset-missing edge). When CardImageSet isn't a registered resource (the case under MinimalPlugins test fixtures, and the bare-bones path the first-frame of production hits before assets resolve), the renderer falls back to solid-colour sprites driven by the card_plugin constants:
   • CARD_FACE_COLOUR — (0.98, 0.98, 0.95) cream-ish white.
   • RED_SUIT_COLOUR — (0.78, 0.12, 0.15) warm red.
   • BLACK_SUIT_COLOUR — (0.08, 0.08, 0.08) near-black.
   • CARD_FACE_COLOUR_RED_CBM — (0.85, 0.92, 1.0, 1.0) light blue (the legacy color-blind tint).
   • card_back_colour(idx) — five legacy back themes.

A single-path migration leaves a known-broken state where tests pass against Terminal constants while a human sees legacy artwork on screen — the exact bisection-hostile drift the handoff's "in lockstep" warning preempts.

Target state — Terminal aesthetic

Per design-system.md § Game Cards (lines 214–233):

Card face

Element	Spec
Background	#1a1a1a
Border	1 px solid in suit colour (pink for ♥/♦, foreground gray for ♠/♣)
Corner radius	8 px
Top-left	rank in JetBrains Mono Bold 18 px + small suit glyph (10 px)
Bottom-right	large suit glyph (32 px), rotated 180°
Glyph fill rule	♥ ♠ filled; ♦ ♣ outlined (1.5 px stroke). Always on, not a toggle.

Suit colours (always-on glyph differentiation is the primary

distinguishing mechanism; colour is supplementary):

Suit	Default	Color-blind mode
Hearts	#fb9fb1 (pink)	#6fc2ef (cyan)
Diamonds	#fb9fb1 (pink)	#6fc2ef (cyan)
Spades	#d0d0d0 (gray)	#d0d0d0 (unchanged)
Clubs	#d0d0d0 (gray)	#d0d0d0 (unchanged)

Card back ("Terminal" theme)

Element	Spec
Background	#151515
Pattern	horizontal scanlines at 2 px pitch in #1a1a1a (1 px line, 1 px gap), full bleed
Border	1 px solid #353535
Top-left badge	12×16 px solid #6fc2ef block, 6 px from corner
Bottom-right monogram	▌RS in JetBrains Mono 12 px #505050, 6 px from corner
Corner radius	8 px
Theme name / author	"Terminal" / "Rusty Solitaire"

Generation pipeline — programmatic SVG via the existing

resvg stack

Why this path (vs. external tooling or direct tiny_skia)

The codebase already ships an SVG-to-PNG rasteriser at solitaire_engine/src/assets/svg_loader.rs:

• Public rasterize_svg(svg_bytes: &[u8], target: UVec2) -> Result<Image, _>
• Backed by usvg (parser) + resvg (renderer) + tiny_skia (CPU pixmap)
• Bundled font db includes JetBrains-style mono (FiraMono — same face the splash uses; close enough to JetBrains Mono for rasterisation purposes, and identical to what the Bevy UI consumes in the rest of the app)
• RenderAssetUsages::default() is the call-site convention here

This means: generating new card PNGs is one new file (solitaire_engine/examples/card_face_generator.rs) calling an existing public function. No new dependencies, no asset-pipeline changes, no build-script machinery. Anyone who runs the example gets bit-identical artwork.

The two alternatives are weaker:

• External tool (Inkscape / Figma / hand-design) — produces one-off PNGs that can't be re-generated reproducibly without re-opening the source files in a specific tool. Iteration cost is high; design tweaks (e.g. "make the suit glyph 2 px larger") require a designer-in-the-loop.
• Direct tiny_skia painting calls — bypasses SVG entirely, but loses the readability of "open the SVG to see exactly what the card looks like." Also reinvents primitives (rounded rectangles, text layout) that usvg already handles.

Output format

PNG, RGBA8 sRGB, dimensions 256 × 384 (2:3 aspect, half the default SvgLoaderSettings of 512 × 768).

Rationale: cards never exceed ~250 px wide on desktop windows today, and 256 × 384 PNGs are ~6 KB each at this content density (13.4 KB total for a full deck of 52 + 5 backs). The default 512 × 768 is 2× what's needed and quadruples the on-disk asset weight. The existing legacy PNGs are 512 × 768 — reducing the new ones halves the runtime asset size.

Lockstep migration — recommended order

Each step is a separate commit; the constraint is that steps 4 and 5 must land in the same commit (or at most adjacent commits on the same branch) so the rendered output never diverges between the two paths.

1. (Done — this commit) Land the migration plan doc.
2. Land the SVG generator example. New solitaire_engine/examples/card_face_generator.rs. Output goes to assets/cards/faces/ and assets/cards/backs/. Run once locally to seed the new artwork. The example file stays in-tree as a regenerator for future tweaks.
3. (Optional — can land separately) Add a one-shot regression test that re-runs the generator into a tempdir and compares the resulting bytes against the on-disk artwork; pinning the generator output prevents silent drift if usvg/resvg ever tweak rendering. Skip if the test runtime cost is unacceptable.
4. Land the new artwork (PNG bytes from step 2 committed to assets/cards/) and the constant migration in the same commit:
   • CARD_FACE_COLOUR → Color::srgb(0.102, 0.102, 0.102) (#1a1a1a)
   • RED_SUIT_COLOUR → Color::srgb(0.984, 0.624, 0.694) (#fb9fb1)
   • BLACK_SUIT_COLOUR → Color::srgb(0.816, 0.816, 0.816) (#d0d0d0)
   • CARD_FACE_COLOUR_RED_CBM → Color::srgb(0.435, 0.761, 0.937) (#6fc2ef) — note this is now the colour-blind suit colour, not a face tint; semantics shift slightly.
   • card_back_colour(idx) — re-author for the Terminal palette; index 0 stays the canonical "Terminal" back from design-system.md.
5. Test updates land in step 4's commit. The pinning tests at card_plugin.rs lines 1749, 1750, 1767, 1768, 2057, 2063, 2071, 2081 all assert against the old constants. New assertions update in lockstep with the constant changes.

CBM (color-blind mode) semantics shift — flag

The legacy CARD_FACE_COLOUR_RED_CBM was a face tint — red suits got a light-blue background wash. The Terminal spec moves CBM into the suit colour itself (red glyphs swap to cyan). Step 4 will rename / repurpose this constant; it's not a 1:1 replacement.

Two options:

• Rename + repurpose: CARD_FACE_COLOUR_RED_CBM → RED_SUIT_COLOUR_CBM. Communicates the semantic shift in the symbol name. Requires touching every callsite.
• Keep the name, change the meaning: less code churn but worse for greppability — a future reader hitting the legacy name will assume face-tint behaviour.

Recommendation: rename. The CBM swap is a one-frame operation even if it touches every existing callsite (currently lines 642, 2071, 2081 per grep -n CARD_FACE_COLOUR_RED_CBM).

Theme system — out of scope here

The card-theme system (docs/CARD_PLAN.md, theme/plugin.rs) already supports user-supplied themes via assets/themes/<theme>/ SVG files rasterised by svg_loader.rs. The new Terminal artwork is the default theme, not a new entry in the theme picker — the theme system continues to overlay user themes on top of the default at runtime.

If the next session wants to also ship Terminal as a named theme slot (so a user can switch back to the legacy artwork via the theme picker), that's an additive change after step 4 and lives in theme::plugin::apply_theme_to_card_image_set.

Test impact summary

grep -n CARD_FACE_COLOUR\\b\|RED_SUIT_COLOUR\\b\|BLACK_SUIT_COLOUR\\b in card_plugin.rs:

• Line 1749–1750: red-suit text colour assertions (♥ + ♦).
• Line 1767–1768: black-suit text colour assertions (♠ + ♣).
• Line 2057, 2063: face-colour assertion in default mode.
• Line 2071, 2081: face-colour assertion in CBM.

The four suit-colour and two face-colour tests are invariant guards — they exist precisely so a constant tweak surfaces here rather than in a visual review. Step 4 updates each in lockstep with the constant value change. No new test infrastructure needed.

Open questions to resolve before step 4

1. Border colour conflict. The spec (line 218) says "Border: 1 px solid in suit colour." The fallback path doesn't draw a border today — it draws solid-colour sprites. Step 4 either: (a) leaves the fallback as solid-colour squares (the test environment doesn't visually validate borders anyway), or (b) extends the fallback renderer to paint a 1 px outline. Recommend (a) — fallback fidelity isn't load-bearing.
2. Glyph rendering in the constant fallback. The fallback today doesn't render suit glyphs at all — it's a coloured square. The spec's filled-vs-outlined glyph differentiation only matters in the PNG path. No change to the constant fallback for glyphs.
3. High-contrast mode. design-system.md line 274 mentions a high-contrast accessibility mode (boosts foreground from #d0d0d0 to #f5f5f5, suit-red from #fb9fb1 to #ff8aa0). Not currently implemented anywhere; out of scope for this migration but worth flagging for a future accessibility pass.

Post-migration — what's still open

• High-contrast mode (above).
• Reduced-motion mode for card lift / drop transitions (also a design-system.md accessibility item, separate from artwork).
• The 9 missing-plugin screens (splash, challenge, time-attack, weekly-goals, leaderboard, sync, level-up, replay, radial-menu) per project_ui_overhaul memory still need their plugin ports — separate from the cards arc.

Sign-off criteria for "D closed"

D from the SESSION_HANDOFF Resume prompt is closed when all of the following hold simultaneously:

• The 52 face PNGs + 5 back PNGs in assets/cards/ are the Terminal-aesthetic artwork (regeneratable via the example).
• The five card_plugin constants reflect the Terminal palette.
• All pinning tests pass against the new values.
• A human boots the game and sees Terminal cards (not white cards). This sign-off needs a real cargo run, not just cargo test.