Catan Board Generator: from weekend idea to working app with vibe coding

3 min read
A sample Catan board generated by the app

It started with a fairly simple question during a long evening of Catan with friends: could I generate balanced boards automatically?

Setting up a Catan board by hand always involved a bit of shuffling and re-shuffling - making sure the valuable number tiles (like 6 and 8) don’t sit next to each other, keeping the same resources from clumping together, and generally trying to get something that feels fair. I figured it was the kind of constraint problem that a script could solve much faster than I could by hand. So over a weekend, I built exactly that.

Sample generated Catan board

The idea

A Catan board is a hex grid of resource tiles, each with a number token. A “balanced” board is one that avoids obvious fairness problems:

  • No 6/8 adjacency - keep the two highest-probability numbers apart
  • No same number adjacency - don’t put the same number on touching tiles
  • No same resource adjacency - avoid identical resources clumping together
  • No 2/12 adjacency - optionally separate the low-probability numbers too

The generator randomizes the resource tiles and number tokens, then applies these placement constraints. If a layout violates a rule, it simply shuffles and tries again - a Fisher-Yates shuffle with a constraint retry loop. The whole thing runs in the browser, renders the board as SVG, and lets you regenerate with Space or Enter (or by toggling any of the constraints).

The vibe-coding workflow

Here is where it gets interesting. Instead of hand-writing every line, I used an AI vibe-coding workflow with Claude Code.

I focused on the parts that matter most: the logic and the constraints. I thought carefully about what a balanced board even means, which placements are fair, and how the generator should behave. Claude Code took that algorithm and helped translate it into reliable, working code with remarkable speed - the plumbing, the SVG rendering, the keyboard shortcuts, the build and deployment setup.

The technical stack stayed deliberately simple. No framework, no database. Just Vanilla JS and SVG, bundled with Vite, built in Docker, and deployed as a static site through GitHub Actions. The code is organized into small, single-purpose modules that make the structure obvious:

  • generator.js - the shuffle and constraint retry loop
  • constraints.js - pure constraint-checking functions
  • hex-grid.js - axial coordinate math for pointy-top hexes
  • renderer.js - SVG rendering of tiles, ports, and number tokens

The takeaway

The biggest lesson from this project: AI is most powerful when paired with clear thinking. If you define the problem well - write down the constraints, decide what “good” looks like, and separate the logic you deeply understand from the boilerplate you don’t - AI tools let you move from idea to high-quality implementation much faster than traditional workflows.

It was a fun project with real engineering value, and a good reminder that a little curiosity can lead to meaningful builds.

Check it out: