From 05b5dba44535f60ce517ee443e3671cccc129493 Mon Sep 17 00:00:00 2001
From: Guillem Arias Fauste <gariasf@proton.me>
Date: Fri, 1 May 2026 16:05:35 +0200
Subject: [PATCH] feat(tokens): add $version field + document versioning policy
 (#1620)

Adds $version: "1.0.0" at the root of design/tokens/sure.tokens.json so
external consumers (Tokens Studio, future Figma sync, AI design tooling,
etc.) have a stable signal for when their cached snapshot of the token
API is out of date.

The build script's walker already skips top-level $-prefixed keys, so no
code change is needed and _generated.css is unchanged.

README documents semver semantics scoped to the token contract:
- Major: breaking (token removed/renamed, type changed, dark dropped).
- Minor: additive (new tokens, new $extensions.sure.* keys, new groups).
- Patch: cosmetic value tweaks.

Bump on commit.
---
 design/tokens/README.md        | 10 ++++++++++
 design/tokens/sure.tokens.json |  1 +
 2 files changed, 11 insertions(+)

diff --git a/design/tokens/README.md b/design/tokens/README.md
index 5fdf80c8c..eb40a6d00 100644
--- a/design/tokens/README.md
+++ b/design/tokens/README.md
@@ -23,6 +23,16 @@ git add design/tokens/sure.tokens.json app/assets/tailwind/sure-design-system/_g
 
 `bin/setup` runs the build automatically on a fresh checkout.
 
+## Versioning
+
+The root `$version` field follows semver, scoped to the token contract:
+
+- **Major** (`X.0.0`): breaking changes — token removed or renamed, value type changed, dark variant removed, semantic meaning changed.
+- **Minor** (`1.X.0`): additive changes — new tokens, new `$extensions.sure.*` keys, new top-level groups.
+- **Patch** (`1.0.X`): cosmetic / value tweaks that consumers don't need to know about — a hex shifts a few points without changing intent.
+
+Bump it when you commit. External consumers (Tokens Studio, future Figma sync, etc.) read this to decide whether their cached snapshot is stale.
+
 ## Schema
 
 The file uses the [W3C DTCG token format](https://design-tokens.github.io/community-group/format/): `$value`, `$type`, `$description`, `$extensions`. Tokens cross-reference via `{path.to.token}` placeholders.
diff --git a/design/tokens/sure.tokens.json b/design/tokens/sure.tokens.json
index 87911351d..48cbd46b6 100644
--- a/design/tokens/sure.tokens.json
+++ b/design/tokens/sure.tokens.json
@@ -1,5 +1,6 @@
 {
   "$schema": "https://design-tokens.github.io/community-group/format/",
+  "$version": "1.0.0",
   "$description": "Sure design tokens. Single source of truth. Hand-edit; run `npm run tokens:build` to regenerate CSS. Template syntax in $value strings: `{path.to.token}` resolves to `var(--path-to-token)`; `{path|N%}` becomes `--alpha(var(--path) / N%)`. Utility tokens whose value lacks `{}` are treated as raw Tailwind class lists for @apply.",
 
   "font": {