Architecture

Tokens resolve as brand × mode. Two layers, loaded in order.

tokens/
  brand.default.css      ← one per project. Identity. Mode-independent.
  mode.editorial.css     ← density, rhythm, scale, motion
  mode.product.css
  mode.operator.css

A surface loads exactly one brand file and exactly one mode file.

The token layer's location follows the project. init writes it beside the stylesheet it wires and prints the path it chose — src/styles/jig/ where the CSS lives in src/styles/, app/assets/stylesheets/jig/ in a Rails app. Set brand in jig.config.json to put it elsewhere. Projects set up before 0.7.0 keep their .jig/tokens/ layout; update does not move them.

So never hardcode that path. init writes a barrel, theme.css, which imports the brand and the mode in the right order — import the barrel, and relocating the layer changes one line instead of every stylesheet. With more than one mode, every barrel names its mode instead (theme.editorial.css, theme.operator.css); see "Multiple modes in one app" below:

/* src/styles/jig/theme.css — written by init */
@import "./brand.acme.css";
@import "./mode.operator.css";

/* your stylesheet */
@import "./jig/theme.css";

Three separate mode files rather than one file with variants. The trade: a surface cannot switch modes at runtime, and shared values are duplicated across three files. In exchange each surface ships only the tokens it uses, the files are independently readable, and there is no cascade to reason about. For a system where mode is a routing decision rather than a user preference, that is the right trade.