Releases: the versioned contract

Routes: /releases (history) · /tokens/releases/new (composer)

Copy link to sectionWhat a release is

A release is an immutable, semver-versioned snapshot of your compiled contract: every token your code, Figma plugins, and AI tools read, frozen at a point in time. Domain studios author values, the Tokens meaning editor authors meaning, and a release captures the resolved whole so a consumer can pin to "the contract as it was at v2.3.0" and trust it never shifts under them.

Releases live in the ship district, alongside Code packages: the place where the contract leaves the building.

Copy link to sectionCutting a release

Open the composer from the Cut release → link on the Tokens contract page, or Cut a release → on an empty Releases page.

The composer does the bookkeeping for you:

1. The bump is computed, not chosen. The composer diffs the live contract against your last release and proposes the smallest correct version bump:

   Change	Bump	Why
   A token value changed	patch	Consumers re-render; no read breaks
   A token added; an alias added; a token deprecated	minor	Additive; existing reads keep working
   A token renamed or removed; an alias removed; a token retyped	major	A published name stops resolving (breaking)

   You can escalate to a larger bump to mark a milestone, but never a smaller one; the composer won't let you understate a break.

2. The changelog is generated from the same diff, one line per change with its classification.

3. You add notes: the story behind the release (optional).

4. Publish snapshots the resolved contract server-side and validates the token count against what you previewed. If the contract changed while you were composing, the cut is refused rather than publishing something you didn't see. Reopen the composer and cut again.

Copy link to sectionThe Releases page

Each row is one published release: version, a one-line summary, the publish date, and its bump. A red dot marks a release with breaking changes.

Select a release to see its read-only detail: the changelog (what changed from the previous version), the snapshot size, and when consumers on latest began reading it. Releases are immutable: history is the audit trail, so there is no edit or delete. "What did Cursor read on June 1st?" is answerable here: find the release published before that date.

Copy link to sectionConsumers and pins

By default every consumer (Cursor, Figma, Claude Code, …) follows latest: they read a new release the moment you publish it. A consumer can pin to a specific version to opt out of automatic updates.

The pin readout on the Releases page is read-only for now. Pin enforcement and new-release notifications are a planned fast-follow.

Copy link to sectionWhat's not here yet

• Pin enforcement / notifications: the pin board is informational today.
• Versioned MCP reads: tools read latest; reading "the contract at v2.3.0" over MCP is a fast-follow.
• Compare releases: diffing two arbitrary releases.