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.
• suit_colors — Array of exactly 2 hex colors. Suits 0 and 2 use the first color; suits 1 and 3 use the second.
• accent_colors — Array of exactly 2 hex colors for court card details and accents.
• style_description — Visual style applied to all cards.

Optional: cards

Array of card-specific overrides for subjects and design options.

{
  "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"}
  ]
}

Custom decks can have any number of cards with any content. Each card is defined individually in the spec.

Required fields:

• deck_type — Must be "custom"
• style_description — Visual style applied to all cards.
• back_subject — What to draw on the back card (required for printing).
• cards — Array of card definitions, each with:
  • card_id: Unique identifier (e.g., "pine_1")
  • display_name: Human-readable name for UI (NOT used in prompts)
  • subject: What to draw — the main prompt content
  • rotational_symmetry: (optional) Require 180° symmetry, default false
  • corner_rank: (optional) Text for corner index, e.g., "1", "A"
  • corner_symbol: (optional) Symbol below corner rank, e.g., "▢"
  • corner_color: (optional) Color for corner text/symbol
  • background_color: (optional) Override deck background for this card
  • category: (optional) Category name for organization
  • number: (optional) Card number within category

Optional deck-level fields:

• color_palette — Array of hex colors to restrict the palette.
• corners — Corner index configuration: {"font": "Times New Roman", "font_size": 48, "pip_size": 30}
• canvas_width, canvas_height — Output dimensions in pixels (default: 816×1110).
• bleed_margin — Trim margin in pixels (default: 36).
• safe_margin — Content margin from edge (default: 66).
• background_color — Card background color (default: "#FFFFFF").
• categories — Array of category definitions for organization.

{
  "deck_type": "custom",
  "style_description": "Minimalist watercolor with soft earth tones, hand-lettered text, organic brushstrokes",
  "color_palette": ["#2D5016", "#1E3A5F", "#4A7023", "#2B4C7E"],
  "corners": {"font": "Times New Roman", "font_size": 48, "pip_size": 30},
  "back_subject": "An interlocking pattern of all four symbols (square, waves, star, diamond) in a balanced, meditative composition",
  "categories": [
    {"name": "PINE", "symbol": "▢", "color": "#2D5016"},
    {"name": "CREEK", "symbol": "≋", "color": "#1E3A5F"}
  ],
  "cards": [
    {
      "card_id": "pine_1",
      "display_name": "1 ▢ PINE",
      "subject": "A single pine tree standing in morning mist, symbolizing structure and solitude",
      "corner_rank": "1",
      "corner_symbol": "▢",
      "corner_color": "#2D5016",
      "category": "PINE",
      "number": 1
    },
    {
      "card_id": "pine_2",
      "display_name": "2 ▢ PINE",
      "subject": "Two pine trees growing together, representing partnership and balance",
      "corner_rank": "2",
      "corner_symbol": "▢",
      "corner_color": "#2D5016",
      "category": "PINE",
      "number": 2
    },
    {
      "card_id": "creek_1",
      "display_name": "1 ≋ CREEK",
      "subject": "A single stream beginning its journey, representing flow and new beginnings",
      "corner_rank": "1",
      "corner_symbol": "≋",
      "corner_color": "#1E3A5F",
      "category": "CREEK",
      "number": 1
    }
  ]
}