@cupped/tokens 0.1.0

package/docs/phoenix.md

@@ -0,0 +1,153 @@
+# Consuming @cupped/tokens from Phoenix LiveView
+
+Three supported modes. All assume Phoenix 1.8 / Tailwind v4 (CSS-first config,
+standalone Tailwind binary — no Node runtime needed at build beyond an
+optional `npm install`).
+
+## Mode 0 — pinned CSS from the GitHub Release (recommended)
+
+Each release attaches version-pinned CSS to its GitHub Release. Pin the version
+(this string is your lockfile analog) and pull the files before the Tailwind
+build — no npm, no `node_modules`:
+
+```bash
+# e.g. in a mix alias or a small fetch script, run before tailwind build
+export CUPPED_TOKENS_VERSION=0.1.0
+mkdir -p assets/vendor/cupped
+gh release download "v${CUPPED_TOKENS_VERSION}" \
+  --repo ybird-labs/cupped-design-system \
+  --pattern "cupped-tokens-${CUPPED_TOKENS_VERSION}.*" \
+  --dir assets/vendor/cupped --clobber
+# verify integrity against the published checksum sidecar
+( cd assets/vendor/cupped && sha256sum -c "cupped-tokens-${CUPPED_TOKENS_VERSION}.sha256" )
+# downloads: cupped-tokens-X.Y.Z.theme.css / .tokens.css / .components.css (+ .sha256)
+```
+
+```css
+@import "tailwindcss" source(none);
+@source "../css";
+@source "../js";
+@source "../../lib/my_app_web";
+
+@import "../vendor/cupped/cupped-tokens-0.1.0.theme.css";
+/* optional: */
+@import "../vendor/cupped/cupped-tokens-0.1.0.tokens.css";
+@import "../vendor/cupped/cupped-tokens-0.1.0.components.css";
+```
+
+(`gh release download` needs an authenticated `gh` / token with read access to
+the package repo. The filenames are stable: `cupped-tokens-<version>.<target>.css`.)
+
+## Mode 1 — npm git dependency
+
+Create `assets/package.json` (or add to it):
+
+```jsonc
+{
+  "dependencies": {
+    "@cupped/tokens": "github:ybird-labs/cupped-design-system#v0.1.0"
+  }
+}
+```
+
+Run `npm install` inside `assets/`. The Tailwind v4 binary resolves
+`@import` against `node_modules`, so in `assets/css/app.css`:
+
+```css
+@import "tailwindcss" source(none);
+@source "../css";
+@source "../js";
+@source "../../lib/my_app_web";
+
+/* Tailwind @theme tokens → utilities (bg-canvas, text-ink-secondary,
+   rounded-lg, shadow-primary, p-base, text-card-title…) + CSS variables. */
+@import "@cupped/tokens/tailwind";
+
+/* Optional: the alias-preserving raw variables (--ink, --xp: var(--sweet)…)
+   if you also write plain CSS against var() names. */
+@import "@cupped/tokens/css";
+
+/* Optional: the canonical web component classes (.btn, .input, .chip-flavor,
+   .banner, .chrome…) — reference styles, skip if you rebuild components in
+   HEEx + utilities. Requires the /css import above. */
+@import "@cupped/tokens/css/components";
+```
+
+HEEx then uses utilities or raw variables — no JS framework assumption:
+
+```heex
+<button class="bg-primary-strong text-ink-inverse rounded-md shadow-primary
+               px-lg py-md min-h-(--hit-target-min) text-(length:--text-body)">
+  Log a coffee
+</button>
+
+<span style={"color: var(--ink-secondary)"}>SEATTLE · 12 MIN AGO · V60</span>
+```
+
+## Mode 2 — vendor mode (zero npm, from a source checkout)
+
+Copy the generated files into the app on each upgrade (Mode 0 is the same idea
+but pulls pinned files from the Release instead of a working checkout):
+
+```bash
+cp dist/tailwind/theme.css  <app>/assets/vendor/cupped/theme.css
+cp dist/css/tokens.css      <app>/assets/vendor/cupped/tokens.css      # optional
+cp dist/css/components.css  <app>/assets/vendor/cupped/components.css # optional
+```
+
+```css
+@import "tailwindcss" source(none);
+@import "../vendor/cupped/theme.css";
+```
+
+## Fonts (self-hosted)
+
+The package ships no font binaries. Self-host WOFF2 in `priv/static/fonts/`
+(already whitelisted by `static_paths/0`) — Google Fonts CDN is discouraged
+(GDPR; no shared-cache benefit since browser cache partitioning). Inter,
+Instrument Serif, and JetBrains Mono are all OFL-licensed.
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/InterVariable.woff2") format("woff2");
+  font-weight: 100 900;
+  font-display: swap;
+}
+@font-face {
+  font-family: "Instrument Serif";
+  src: url("/fonts/InstrumentSerif-Regular.woff2") format("woff2");
+  font-weight: 400;
+  font-display: swap;
+}
+@font-face {
+  font-family: "Instrument Serif";
+  src: url("/fonts/InstrumentSerif-Italic.woff2") format("woff2");
+  font-weight: 400;
+  font-style: italic;
+  font-display: swap;
+}
+@font-face {
+  font-family: "JetBrains Mono";
+  src: url("/fonts/JetBrainsMono[wght].woff2") format("woff2");
+  font-weight: 100 800;
+  font-display: swap;
+}
+```
+
+## Enforcing "no raw values"
+
+*Never hard-code a hex or pixel value that exists as a token.* There is no
+turnkey HEEx linter for this; the practical recipe is a CI grep over
+templates and CSS:
+
+```bash
+# fails CI when a raw hex sneaks into templates/styles (tokens.css itself is generated)
+grep -rnE '#[0-9a-fA-F]{3,8}\b' lib/my_app_web assets/css --include='*.heex' --include='*.css' \
+  | grep -v vendor/ && exit 1 || exit 0
+```
+
+For JS in `assets/js`, port the `no-restricted-syntax` patterns from
+[docs/expo.md](./expo.md).
+
+A complete example lives at [examples/phoenix/app.css](../examples/phoenix/app.css).

package/docs/releasing.md

@@ -0,0 +1,93 @@
+# Releasing @cupped/tokens
+
+The package is published to **GitHub Packages** (npm registry
+`https://npm.pkg.github.com`, `@cupped` scope, `restricted` access) under
+[`ybird-labs/cupped-design-system`](https://github.com/ybird-labs/cupped-design-system).
+Releases are driven by [Changesets](https://github.com/changesets/changesets);
+the [`release.yml`](../.github/workflows/release.yml) workflow does the publish
+and attaches versioned CSS to the GitHub Release.
+
+For *what* bump to choose, see [versioning.md](./versioning.md).
+
+## Day-to-day: adding a changeset
+
+Every PR that changes tokens or generated output should include a changeset:
+
+```bash
+npx changeset           # pick the bump level, write a summary
+git add .changeset/
+```
+
+The summary becomes the `CHANGELOG.md` entry, so write it for a consumer.
+
+## Automated release flow
+
+```
+PR with a .changeset/*.md merged to main
+   │
+   ▼  release.yml runs (npm ci → npm run check)
+changesets/action sees pending changesets
+   │
+   ▼  opens / updates a "Version Packages" PR
+        (bumps package.json + writes CHANGELOG.md, deletes consumed changesets)
+   │
+   ▼  merge the Version Packages PR
+release.yml runs again → no pending changesets, version not yet published
+   │
+   ▼  changesets/action runs `npm run release` (changeset publish)
+changeset publish → publishes to GitHub Packages + creates the git tag vX.Y.Z
+   the changesets/action wrapper then creates the matching GitHub Release
+   │
+   ▼  upload step attaches the three CSS files to Release vX.Y.Z:
+        cupped-tokens-X.Y.Z.theme.css       (Tailwind v4 @theme)
+        cupped-tokens-X.Y.Z.tokens.css      (raw CSS variables)
+        cupped-tokens-X.Y.Z.components.css  (component classes)
+```
+
+You never bump `package.json` or write `CHANGELOG.md` by hand — merging the
+Version Packages PR does it.
+
+## One-time first publish (manual)
+
+The very first publish of a brand-new scoped package usually **cannot** be done
+by the workflow's `GITHUB_TOKEN`, because creating a new package under the org
+typically requires a personal access token. Do this once:
+
+1. Create a **fine-grained PAT** scoped to just `ybird-labs/cupped-design-system`
+   with **Packages: write** and a short expiry. (A classic PAT with
+   `write:packages` works too, but it is org-wide and long-lived — prefer
+   fine-grained.)
+2. Point npm at GitHub Packages for the scope, and pass the token via an env
+   var so it is never persisted to disk:
+   ```bash
+   echo "@cupped:registry=https://npm.pkg.github.com" >> ~/.npmrc
+   echo '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}' >> ~/.npmrc
+   export NODE_AUTH_TOKEN=YOUR_PAT   # this shell only — not written to ~/.npmrc
+   ```
+3. From a clean checkout on the released version:
+   ```bash
+   npm ci
+   npm run check
+   npm publish        # prepublishOnly rebuilds dist/ first
+   ```
+
+After the package exists, the workflow's `GITHUB_TOKEN` can publish every
+subsequent release — no PAT needed in CI.
+
+## Granting consumer repos read access
+
+Consuming repos in the same org need **read** access to the package:
+
+- In the package settings on GitHub → *Package settings* → *Manage Actions
+  access* / *Manage access*, grant the consumer repos (e.g. the Phoenix and
+  Expo apps) read access.
+- Consumers then authenticate with a token that has `read:packages`. (Consumer
+  `.npmrc` setup is documented per-app — see [expo.md](./expo.md). **TODO:**
+  finalize and document the consumer read-token model.)
+
+## Verifying a published release
+
+- The package version appears under the repo's *Packages*.
+- The GitHub Release `vX.Y.Z` exists with the three `cupped-tokens-X.Y.Z.*.css`
+  assets attached.
+- `CHANGELOG.md` has an entry for the version.

package/docs/rules.md

@@ -0,0 +1,62 @@
+# Cupped brand & accessibility invariants
+
+The rules the tokens encode but cannot enforce by themselves. The contrast
+rules marked ✓ are machine-checked in CI (`scripts/validate-contrast.mjs`);
+the rest are review rules.
+
+## Color
+
+- **Coral never carries text below 24px.** `--primary` (#E07A5F) is ~3.0:1
+  on white — accents, illustration, ≥24px display only. Small colored text,
+  links, and text-bearing fills use `--primary-strong` (4.6:1 on white ✓).
+- **Coral = action; slate = chrome.** Flavor colors tag tasting notes
+  *only* — never UI chrome.
+- **Every solid flavor fill carries white text at ≥4.5:1, zero exceptions** ✓
+  (the oklch band guarantees it; `--on-flavor` is always white).
+- **Flavor-colored words on white use the `-accessible` text band** (≥5.5:1 ✓,
+  with a small hex-quantization tolerance — green lands at 5.496).
+- **Feedback `-ink` variants** are the AA text/icon colors on their `-light`
+  backgrounds ✓; banner words stay ink/ink-secondary.
+- **Gamification colors are reserved for reward moments** — never decoration.
+  They are aliases (`xp → sweet`, `badge → floral`, `streak → ember`):
+  change the source, never the alias.
+- Known nuance (flagged upstream, not encoded): `--ink-inverse` (#F8FAFC) on
+  `--primary-strong` is 4.36:1 — the spec's 4.6:1 claim is for pure white.
+
+## Type
+
+- Inter for all UI; six named sizes only — no ad-hoc sizes.
+- **Serif display max once per screen**, often with an italic coral word;
+  tracking −1.5%.
+- Mono is the technical register only (ratios, temps, grind, extraction).
+- Never Lora, Fraunces, or Plus Jakarta. No emoji in product UI — ever.
+
+## Layout & interaction
+
+- Strict 4pt grid; the seven `--space-*` stops are the only spacing values.
+- **Hit targets ≥44pt, always** (`--hit-target-min`; `.btn` enforces it).
+- **One primary action per screen.**
+- Every interactive element ships all six states before it ships:
+  default · hover · pressed · focus · disabled · loading.
+- **Focus is never removed without a replacement** — the dual ring
+  `--focus-ring` keeps ≥3:1 non-text contrast on any surface ✓.
+
+## Materials & motion
+
+- Content surfaces are always opaque. **One chrome layer per screen**
+  (`.chrome` — tab bar or sticky header); scrim for sheets is `--scrim`.
+- `prefers-reduced-transparency` collapses chrome to opaque card (built into
+  the generated CSS).
+- One shared spring (`response 0.55s · damping 0.75`); tap pulse
+  `scale 0.95 · opacity 0.8`; stagger 0.08s; shimmer 1.5s.
+- **Reduced motion keeps the state change and drops the travel** — springs
+  and staggers collapse to 120ms crossfades (built into the generated CSS;
+  app-side via `useReducedMotion` on native).
+- Never gate content behind an animation. No bounces on content, no
+  infinite decorative loops.
+
+## The golden rule
+
+> Never hard-code a hex or pixel value that exists as a token.
+
+Lint recipes per platform: [phoenix.md](./phoenix.md), [expo.md](./expo.md).

package/docs/versioning.md

@@ -0,0 +1,59 @@
+# Versioning policy
+
+`@cupped/tokens` follows [semantic versioning](https://semver.org/), but the
+"public API" is the **token contract**, not just exported types. This page
+defines what counts as a breaking change so consumers can upgrade with
+confidence.
+
+## What is the public contract
+
+- **`tokens/semantic/`** — the public API. Every semantic token aliases a
+  primitive and is what apps consume (via `@cupped/tokens`, `/css`,
+  `/tailwind`, …).
+- **`tokens/primitive/`** — internal raw palettes and scales. **Never consumed
+  directly**; reshaping a primitive is *not* breaking as long as the semantic
+  tokens it feeds keep their resolved values and the contrast invariants hold.
+- The package **subpath exports** (`.`, `./css`, `./css/components`,
+  `./tailwind`, `./json`, `./json/dtcg`) and the generated `.d.ts` shape are
+  also part of the contract.
+
+## Bump levels
+
+### MAJOR (breaking)
+- Remove or **rename** a semantic token.
+- Remove or reshape a subpath export, or a breaking change to the emitted
+  `.d.ts` types (e.g. narrowing a literal union, changing a shadow shape).
+- A value change that **violates a guaranteed accessibility invariant** — the
+  `$extensions["app.cupped"].contrast` data is machine-checked in CI
+  (see [README](../README.md#architecture)); shipping a value that breaks a
+  documented contrast guarantee is breaking even though the key still exists.
+
+### MINOR (additive)
+- Add a token, a new scale step, a new subpath export, or an optional
+  `$extensions` block.
+- Add a deprecation alias (see below) ahead of a future removal.
+
+### PATCH
+- A value tweak that keeps every invariant (contrast, collisions, parity).
+- Documentation, descriptions, or `$description` fixes.
+
+## Softening breaking changes
+
+Prefer **deprecate-then-remove** over a hard rename:
+
+1. Introduce the new token as a **minor**, keeping the old name as an alias to
+   the new one. Mark the old token deprecated in its `$description`.
+2. Remove the deprecated alias in the next **major**, after at least one minor
+   cycle, so consumers get a release where both names resolve.
+
+## Why Changesets (not fully inferred automation)
+
+The bump level for a token change is **human judgment**: a rename is breaking,
+a value tweak usually is not — but a value tweak that crosses a contrast
+threshold *is*. Tools that infer the bump from commit messages
+(semantic-release) or from a fixed convention can't make that call reliably.
+
+With [Changesets](https://github.com/changesets/changesets) the author who
+makes the change declares the intent in a reviewed `.changeset/*.md` file,
+which doubles as the changelog entry. See [releasing.md](./releasing.md) for
+the mechanics.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cupped/tokens",
+  "version": "0.1.0",
+  "description": "Cupped design tokens — canonical DTCG source with generated CSS custom properties, Tailwind v4 @theme, React Native theme object, and raw JSON.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ybird-labs/cupped-design-system.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/native/index.cjs",
+  "types": "./dist/native/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/native/index.d.ts",
+      "react-native": "./dist/native/index.js",
+      "import": "./dist/native/index.js",
+      "require": "./dist/native/index.cjs",
+      "default": "./dist/native/index.cjs"
+    },
+    "./css": "./dist/css/tokens.css",
+    "./css/components": "./dist/css/components.css",
+    "./tailwind": "./dist/tailwind/theme.css",
+    "./json": "./dist/json/tokens.flat.json",
+    "./json/dtcg": "./dist/json/tokens.dtcg.json"
+  },
+  "files": [
+    "dist",
+    "tokens",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node build/config.js",
+    "test": "vitest run",
+    "check": "npm run build && git diff --exit-code -- dist/ && test -z \"$(git status --porcelain --untracked-files=all -- dist/)\" && npm test",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.1",
+    "@changesets/cli": "^2.27.12",
+    "colorjs.io": "^0.6.1",
+    "postcss": "^8.5.15",
+    "style-dictionary": "^5.4.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/tokens/primitive/color.tokens.json

@@ -0,0 +1,94 @@
+{
+  "color": {
+    "$type": "color",
+    "palette": {
+      "$description": "Raw palette values. Never consumed by apps — alias through the semantic layer.",
+      "white": { "$value": "#FFFFFF" },
+      "slate": {
+        "$description": "Cool slate neutrals — carry all UI chrome.",
+        "50": { "$value": "#F8FAFC" },
+        "100": { "$value": "#F1F5F9" },
+        "200": { "$value": "#E2E8F0" },
+        "400": { "$value": "#94A3B8" },
+        "600": { "$value": "#475569" },
+        "900": { "$value": "#0F172A" }
+      },
+      "coral": {
+        "$description": "Warm brand coral — carries action and brand. Coral = action; slate = chrome.",
+        "50": { "$value": "#FDF2F0" },
+        "500": { "$value": "#E07A5F" },
+        "550": { "$value": "#D16A4F" },
+        "600": { "$value": "#C05539" },
+        "650": { "$value": "#AD4A30" }
+      },
+      "ember": {
+        "$description": "Gamification source hue (streak fire). Promoted to a source token in the refreshed export; --streak aliases it.",
+        "fill": { "$value": "#F97316" },
+        "text": { "$value": "#C2410C" }
+      },
+      "green": {
+        "50": { "$value": "#F0FDF4" },
+        "500": { "$value": "#22C55E" },
+        "700": { "$value": "#15803D" }
+      },
+      "red": {
+        "50": { "$value": "#FEF2F2" },
+        "500": { "$value": "#EF4444" },
+        "700": { "$value": "#B91C1C" }
+      },
+      "amber": {
+        "50": { "$value": "#FFFBEB" },
+        "500": { "$value": "#F59E0B" },
+        "700": { "$value": "#B45309" }
+      },
+      "blue": {
+        "50": { "$value": "#EFF6FF" },
+        "500": { "$value": "#3B82F6" },
+        "700": { "$value": "#1D4ED8" }
+      },
+      "flavor": {
+        "$description": "SCA tasting vocabulary — parametric oklch band (\"Espresso\"), not hand-picked hexes. Fill band: L 0.555 · C 0.135 (bright) / 0.062 (earth) / earth ×0.7 (roasted). Text band: L 0.510 · C 0.110 (bright) / 0.060 (earth). Hue carries the flavor; lightness/chroma are shared, so every fill carries white text at ≥4.5:1 with zero exceptions.",
+        "fruity": {
+          "fill": { "$value": "#B44C54", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 18 }, "band": "fill" } } },
+          "text": { "$value": "#9B494E", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 18 }, "band": "text" } } }
+        },
+        "berry": {
+          "fill": { "$value": "#AC4D7B", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 352 }, "band": "fill" } } },
+          "text": { "$value": "#94496D", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 352 }, "band": "text" } } }
+        },
+        "citrus": {
+          "fill": { "$value": "#A65F02", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 62 }, "band": "fill" } } },
+          "text": { "$value": "#925512", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 62 }, "band": "text" } } }
+        },
+        "sweet": {
+          "fill": { "$value": "#8E6E09", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 88 }, "band": "fill" } } },
+          "text": { "$value": "#7E6207", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 88 }, "band": "text" } } }
+        },
+        "floral": {
+          "fill": { "$value": "#865CB2", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 305 }, "band": "fill" } } },
+          "text": { "$value": "#755498", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 305 }, "band": "text" } } }
+        },
+        "green": {
+          "fill": { "$value": "#4E8429", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 135 }, "band": "fill" } } },
+          "text": { "$value": "#49742E", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 135 }, "band": "text" } } }
+        },
+        "spice": {
+          "fill": { "$value": "#B4503A", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.135, "h": 34 }, "band": "fill" } } },
+          "text": { "$value": "#9B4C3A", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.11, "h": 34 }, "band": "text" } } }
+        },
+        "nutty": {
+          "fill": { "$value": "#876F49", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.062, "h": 78 }, "band": "fill" } } },
+          "text": { "$value": "#79623E", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.06, "h": 78 }, "band": "text" } } }
+        },
+        "chocolate": {
+          "fill": { "$value": "#916951", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.062, "h": 52 }, "band": "fill" } } },
+          "text": { "$value": "#825C46", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.06, "h": 52 }, "band": "text" } } }
+        },
+        "roasted": {
+          "fill": { "$value": "#896B5E", "$extensions": { "app.cupped": { "oklch": { "l": 0.555, "c": 0.0434, "h": 45 }, "band": "fill" } } },
+          "text": { "$value": "#7B5F52", "$extensions": { "app.cupped": { "oklch": { "l": 0.51, "c": 0.042, "h": 45 }, "band": "text" } } }
+        }
+      }
+    }
+  }
+}

package/tokens/primitive/dimension.tokens.json

@@ -0,0 +1,18 @@
+{
+  "dimension": {
+    "$type": "dimension",
+    "scale": {
+      "$description": "Raw 4pt-grid dimension stops (plus 2px ring width and the 9999px pill radius). Never consumed by apps — alias through the semantic layer.",
+      "2": { "$value": "2px" },
+      "4": { "$value": "4px" },
+      "8": { "$value": "8px" },
+      "12": { "$value": "12px" },
+      "16": { "$value": "16px" },
+      "20": { "$value": "20px" },
+      "24": { "$value": "24px" },
+      "32": { "$value": "32px" },
+      "44": { "$value": "44px" },
+      "full": { "$value": "9999px" }
+    }
+  }
+}

package/tokens/primitive/duration.tokens.json

@@ -0,0 +1,10 @@
+{
+  "duration": {
+    "$type": "duration",
+    "$description": "Raw durations. Kept in the spec's original units so generated CSS matches the canonical export character-for-character; the native pipeline normalizes to ms numbers.",
+    "spring": { "$value": "0.55s" },
+    "stagger": { "$value": "0.08s" },
+    "shimmer": { "$value": "1.5s" },
+    "reduced": { "$value": "120ms" }
+  }
+}

package/tokens/primitive/font.tokens.json

@@ -0,0 +1,29 @@
+{
+  "font": {
+    "family": {
+      "$type": "fontFamily",
+      "$description": "Three families, each with a job: Inter for all UI, Instrument Serif for display (max one moment per screen), JetBrains Mono for the technical register. Never Lora, Fraunces, or Plus Jakarta.",
+      "sans": { "$value": ["Inter", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"] },
+      "serif": { "$value": ["Instrument Serif", "Georgia", "serif"] },
+      "mono": { "$value": ["JetBrains Mono", "ui-monospace", "SFMono-Regular", "monospace"] }
+    },
+    "weight": {
+      "$type": "fontWeight",
+      "regular": { "$value": 400 },
+      "medium": { "$value": 500 },
+      "semibold": { "$value": 600 },
+      "bold": { "$value": 700 }
+    },
+    "size": {
+      "$type": "dimension",
+      "$description": "Raw size stops. Every size shipped in a component has a semantic token name — no ad-hoc sizes.",
+      "12": { "$value": "12px" },
+      "14": { "$value": "14px" },
+      "16": { "$value": "16px" },
+      "20": { "$value": "20px" },
+      "24": { "$value": "24px" },
+      "32": { "$value": "32px" },
+      "56": { "$value": "56px" }
+    }
+  }
+}