chore(design-tokens): 🤖 add legacy backward compatibility exports for styled-components theme

[punkbit]

Why?

To provide backward compatibility for consumer applications that depend on the legacy styled-component/javascript/typescript theme objects and theme context from @clickhouse/click-ui. This allows gradual migration to the new CSS variable-based design tokens without breaking existing code, while making the deprecation explicit through a dedicated /legacy subpath.

Warning

We're effectively dropping support for the old design token system. Source dictionary file(s) and related "generator" are purposely gone and not supported to incentivise use of the new token system.

⚠️ Depends on #946 (branched [chore/design-tokens-package](https://github.com/ClickHouse/click-ui/tree/chore/design-tokens-package), rebase onto 6385b7)

🤖 TODO: Remember to re-enable changeset:verify (in commit hook) once #951 is merged

How?

• Created packages/design-tokens/legacy/ directory structure to host deprecated theme code
• Copied and adapted 15 source files from packages/click-ui/src/: Theme core, types, utils, token variable files, react hooks, etc
• Added deprecated for LSP warnings
• Updated package.json with export paths
• Add legacy:build script and updated main build command
• Created tsconfig.legacy.json for TypeScript compilation to dist/legacy/
• Added comprehensive documentation in LEGACY.md with migration examples
• Added concise "Legacy Support" section in README.md linking to full docs

Contribution checklist?

• You've done enough research before writing
• You have reviewed the PR
• The commit messages are detailed
• The build command runs locally
• Assets or static content are linked and stored in the project
• For documentation, guides or references, you've tested the commands

Security checklist?

• All user inputs are validated and sanitized
• No usage of dangerouslySetInnerHTML
• Sensitive data has been identified and is being protected properly
• Build output contains no secrets or API keys

Preview?

Showcase import legacy hook from click-ui, same API

demo-export-legacy-from-click-ui-design-tokensd.mov

Showcase import legacy hook from design-tokens/legacy (decoupled, Click UI can progress):

demo-use-design-tokens-package-legacy-items.mov

Text example API:

import { useCUITheme } from '@clickhouse/click-ui';

import { useCUITheme } from '@clickhouse/design-tokens/legacy';

[changeset-bot]

🦋 Changeset detected

Latest commit: eecfbd6

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[punkbit]

• useCUITheme may be a silent breaking change (packages/design-tokens/legacy/hooks/useCUITheme.ts:12): The new return type is Pick<Theme, "breakpoint" | "global" | "name" | "sizes"> — a strict subset. If the original useCUITheme in click-ui returned the full Theme object, TypeScript consumers accessing other theme properties (e.g. cuiTheme.click.color.primary) will get compile errors after upgrading. Please confirm this matches the prior signature, or call it out as a breaking change in the changeset.

Same signature. Do ignore!

[github-actions]

Claude finished @punkbit's task in 2m 5s —— View job

---

PR Review — chore(design-tokens): legacy backward compatibility exports

• Gather context (CLAUDE.md, conventions, key files)
• Review diff vs base branch
• Check new/updated files for issues
• Post final review

---

This PR is solid. The latest commits look clean — token source freeze is intentional and well-documented, all previously flagged blocking issues remain resolved. Here's the complete picture:

---

✅ All previously flagged items — still good

• tsup.config.ts:15 — options.jsx = "automatic" ✅
• "use client" in hooks/index.ts, useCUITheme.ts, useInitialTheme.ts ✅
• InitCUIThemeScript.tsx intentionally without "use client" — SSR by design, comment explains why ✅
• dangerouslySetInnerHTML — storageKey, defaultTheme, attribute all pass through JSON.stringify(); THEMES.* are static constants ✅
• Dual ESM/CJS exports with correct .d.ts/.d.cts type paths ✅
• @deprecated JSDoc on all legacy re-exports ✅
• bundle: false in tsup — subpath imports stay isolated ✅
• @clickhouse/design-tokens: "workspace:^" correctly listed as a runtime dependency in click-ui/package.json ✅
• Token source dictionaries and legacy generator removed cleanly ✅
• useCUITheme return type (Pick<Theme, "breakpoint" | "global" | "name" | "sizes">) — author confirmed matches prior signature ✅

---

💡 Suggestion (non-blocking, flagged for the third time — take it or leave it)

• legacy/utils/dom.ts:29 — bare return vs return null: getDOMElement returns null on the early-exit path; getRootElement has a bare return, making its inferred type HTMLElement | undefined instead of HTMLElement | null. All callers use if (!el) so runtime behavior is identical, but the type asymmetry could surprise future readers.

  One-line fix: return; → return null;. Fix this →

---

Everything looks good. The deprecation story is clear, the SSR-safe InitCUIThemeScript design is correct, changesets are versioned appropriately (minor for design-tokens, patch for click-ui), and the token source freeze is a clean cut. Ready to land once #946 merges. 🙌

[workflow-authentication-public]

📚 Storybook Preview Deployed

✅ Preview URL: https://click-8w20x996w-clickhouse.vercel.app

Built from commit: d27c999dc1c7fd436d0a1acf49977447a973b481