dice-lite

A procedural throw of dice as an SVG string — seeded placement and values, a brand-aware table palette, paper or frosted-glass bodies and an optional CSS roll.

Available on: npm GitHub Project site

dice-lite draws a throw of dice on a table by code. One call returns an SVG string — in Node at build time or in the browser — so a static site gets its hero art with no script on the page. Two knobs span the variant space: seed throws the dice (how many, where they lie, what they show), brand colours the table. It is a procedural dice throw in SVG with zero dependencies, ~9 KB minified and gzipped.

What it draws

  • Real cubes — each die is a rounded cube projected from its own seeded orientation, which makes rounded dice with exact pips: three visible faces, projected pips, opposite sides summing to seven by construction, every face corner rounded.
  • Two bodies — paper, the classic white die, or glass: paper or frosted-glass dice, the glass ones showing through each other.
  • Two to five dice — dice appends, so the dice of a smaller throw stay where they were when one more is added.
  • Named results — lucky7, snake, boxcars, matched, mixed. A result such as a lucky seven only places values; nothing is ever scored. values pins exact top faces.
  • One die as an icon — Dice.die({ value: 5 }).

How to use it

Install with npm install @spintax/dice-lite. One ES5 file works as CommonJS, as an ESM default import and as a plain <script> (global Dice); dice.d.ts ships the types. At build time Dice.toss({ seed: 'hero' }) returns the markup to inline; in the browser Dice.init('#hero', { seed: 'spintax.net' }) draws into an element and set() redraws it. motion: 'roll' adds a one-shot settle that honours prefers-reduced-motion. The same seed and options always give identical bytes.

The table

The brand's colours become the table — a brand-aware table palette: the first chromatic colour felts it, a gold-hue colour tones the brass trim, and the dice keep near-black pips in every brand. The table's edge is a dark surround by default; rail: 'brand', 'felt' or any colour reshapes it. Under theme: 'light' the table defaults to a line drawing, because a filled felt over a white page reads as a pastel field. Pin felt and rail to 'transparent' and only the lattice is left, with the page showing through. The picture carries no fixed path data: every coordinate is computed from the seed. Dice.palette() returns the derived colours.

Licence and stability

MIT. The version is the contract: within a minor version the same seed and options give identical bytes, and any change to the output bytes is a minor bump with a changelog entry. Made in 301 for spintax.net.