The deck spec defines the four suits, the visual style, and optionally card-specific subjects for the deck.

Required fields:

• suits — Array of exactly 4 suits, each with:
  • name: Display name (e.g., "Critters", "Hearts")
  • theme: Thematic category for the suit (e.g., "backyard mammals")
  • pip_description: Description of the pip symbol — this appears on number cards and as corner indices. Focus on subject and composition, not style.
• suit_colors — Array of exactly 2 hex colors. Suits 0 and 2 use the first color; suits 1 and 3 use the second (like red/black in standard decks).
• accent_colors — Array of exactly 2 hex colors for court card details and accents.
• style_description — Visual style applied to all cards (e.g., "classic engraving with fine crosshatch shading").

Optional: cards

Array of card-specific overrides. Each entry can specify:

• rank: Card rank ("A", "2"-"10", "J", "Q", "K", or "back")
• suit_index: 0-3 for face cards (omit for "back")
• subject: What to draw on this card (recommended for court cards)
• rotational_symmetry: Override default (true for courts, false for others)
• use_body_pips: Override default (true for number cards only)

Tips:

• Pips must work at small sizes — favor distinct silhouettes over detailed designs
• Describe whole objects, not parts (e.g., "full body squirrel" not "squirrel head")
• No style language in pip_description — that goes in style_description
• Court cards benefit from specific subjects; without one, they'll get a generic theme-based default

{
  "suits": [
    {
      "name": "Critters",
      "theme": "backyard mammals",
      "pip_description": "Full body squirrel in profile with bushy tail raised"
    },
    {
      "name": "Seeds",
      "theme": "nuts and seeds",
      "pip_description": "Striped sunflower seed, tapered oval shape"
    },
    {
      "name": "Birds",
      "theme": "backyard birds",
      "pip_description": "House sparrow in profile, full body, small and plump"
    },
    {
      "name": "Flowers",
      "theme": "garden flowers",
      "pip_description": "Iris bloom from front view, three upright petals, three falling petals"
    }
  ],
  "suit_colors": ["#5D4037", "#2E5D4E"],
  "accent_colors": ["#C62828", "#E6A817"],
  "style_description": "Classic playing card style with bold outlines and flat color fills",
  "cards": [
    {"rank": "J", "suit_index": 0, "subject": "Raccoon standing upright, masked face, ringed tail"},
    {"rank": "Q", "suit_index": 0, "subject": "Possum with delicate pointed face, maternal pose"},
    {"rank": "K", "suit_index": 0, "subject": "White-tailed buck with full antlers, noble stance"},
    {"rank": "back", "subject": "Repeating pattern of acorns and oak leaves"}
  ]
}