docs: mark old token systems as deprecated and transitional - #5191

@claude review

Claude finished @pomfrida's task in 2m 34s —— View job

Code Review

Reviewed the docs/versioning changes against origin/main. This is a clean, carefully-reasoned PR — the differentiated wording (hard-deprecate the JS object, "transitional but supported" for the CSS variables) is the right call given the replacement only exists on the beta line. I verified the release-mechanics claims against the actual config; they hold up.

Verification (claims in the PR description → confirmed)

• ✅ @deprecated reaches consumers' editors. src/index.ts does export * from './base' and the package's . export maps types to dist/types/index.d.ts, so the JSDoc on tokens will surface in editors via dist/types. Correct.
• ✅ docs: triggers no release. .github/release-please-config.json maps type: docs with "hidden": true, so no version bump. Correct.
• ✅ Manual package.json bump won't fight release-please. eds-tokens uses release-type: simple with the version tracked in version.txt (currently 3.0.0-beta.1, matching .github/release-please-manifest.json). simple only manages version.txt, not package.json, so 2.3.2 sits safely on the stable line — consistent with the package CLAUDE.md note that package.json stays on the last stable version.
• ✅ Beta line unaffected. Manifest and version.txt both on 3.0.0-beta.1; nothing here touches them.

Minor observations (non-blocking)

1. CHANGELOG section header wording. The manual entry uses ### 📝 Documentation, but the release-please config labels the docs type as 📝 Changed (.github/release-please-config.json:132-134). Purely cosmetic since this is a hand-written entry, but if you want the changelog to read consistently with future auto-generated sections you could use 📝 Changed. I'd lean toward leaving it — "Documentation" is clearer for a human reader here.
2. CHANGELOG ordering. 2.3.2 is placed below 3.0.0-beta.1 (both dated 2026-07-20). Given the split-line versioning where release-please keeps the beta entry at the top, this is a reasonable deliberate choice — just flagging it so it's a conscious decision rather than an accident.
3. README-only scope is fine, but note the docs site. The docs-site pages apps/design-system-docs/docs/about/getting-started/develop/getting_started_development.md (and the versioned copy) also reference the tokens. Out of scope for this PR (which correctly targets the npm-published README + types), but a good candidate for a follow-up so the guidance is consistent everywhere consumers land.

Nits

• The heading ## Legacy Tokens (deprecated — do not use) uses an em-dash; the repo's component-doc style avoids em-dashes, though that rule is scoped to component docs and this package README already uses them elsewhere (as does the changelog). No action needed.
• No stale anchor links: nothing in the repo links to the old #css-variables-recommended / #legacy-tokens-backward-compatible slugs, so the heading renames are safe.

Summary

No bugs or blocking issues. The code/doc changes are accurate, the versioning strategy is sound and matches the repo's config, and deferring npm deprecate until 3.0.0 graduation is the correct restraint (avoids install warnings for every 2.x consumer, including transitively via eds-core-react). 👍
• docs/mark-old-tokens-do-not-use