Surfaces

Board colour palettes. A surface provides the default colours consumed by the render pipeline.

What surfaces provide

A surface is a named colour palette. It defines the fills for light and dark cells, grid lines, borders, and backgrounds. The render pipeline reads these colours when drawing the board.

Surfaces are the lowest layer in the cascade: surface defaults can be overridden by family-level colours, which can be overridden by variant-level colours.

Named surfaces

Reference by string in frontmatter:

surface: parchment

Name	Light cell	Dark cell	Character
wood-classic	#f0d9b5	#b58863	Traditional chess wood
wood-light	#dcb35c	#c8a43c	Go/shogi board wood
felt-green	#4a7c59	#3d6b4a	Card table baize
parchment	#d9c5a0	#c4b088	Aged paper
earth	#9B7740	#7A5A32	Terracotta/clay
slate	#6B7B8F	#4A5A6B	Cool grey stone
jungle	#5B8C5A	#3D6B3C	Deep tropical green
military	#7B8B6F	#5A6B4F	Olive/khaki tactical
cosmic	#2A2A4A	#1A1A3A	Dark space

Inline colours

Define colours directly in frontmatter when no named surface fits:

surface:
  colors:
    cell-light: "#dcb35c"
    cell-dark: "#d4a843"
    stroke: "#3d2b1a"
    background: "#2c2c2c"

Colour keys

Key	Used for
cell-light	Light squares / primary cell fill
cell-dark	Dark squares / alternating cell fill
cell-mid	Third colour for 3-colour patterns
stroke	Grid lines, borders
background	Board background / frame
floor	Playable area fill (pachisi, asalto)
floor-stroke	Playable area border
whitePieceFill	Fallback fill for white stone pieces
blackPieceFill	Fallback fill for black stone pieces

Cascade behaviour

The cascade resolver merges colours in order: named surface → family engine.surface → variant engine.surface. A variant only needs to specify the colours it changes:

# Family (rulebook.md) — uses named surface
engine:
  surface: parchment

# Variant — overrides just the dark cell colour
engine:
  surface:
    colors:
      cell-dark: "#8B0000"

The variant inherits all parchment colours but replaces cell-dark with dark red.