chore(monorepo): 🤖 Design tokens as a package (initial)

[punkbit]

Why?

This PR introduces the @clickhouse/design-tokens package to establish a single source of truth for ClickHouse Design System token definitions following the DTCG standard. The package defines primitives (colours, spacing, radius, sizing, typography and others that might/will be created/migrated/ported as found/seen/encountered/discovered/needed) and semantic tokens, while exposing all tokens via CSS (might add others in the future when found/needed/requested/found/important) for consumer applications.

⚠️ TODO: Pick Colour space
⚠️ TODO: Missing font-family tokens

⚠️ It's part of a set of PR to help migrate the token management from Token Studio to Figma Variables using the Design Tokens Community Group (DTCG) format, enabling synchronisation between design and development.

⚠️ Depends on #938

How?

• Created DTCG JSON files for primitives, semantic tokens, spacing, radius, sizing, and typography
• Implemented scope inference logic to hide primitives from Figma UI while keeping them referenceable
• Built automatic description generation combining values, semantic aliases, and category keywords
• Set up CSS distribution output at ./dist/tokens.css for consumer apps (initial placeholder)
• Documentation, including design token specification

Preview?

Design Tokens

Primitives (Private)

Semantic (Public)

Sizing (Public)

Spacing (Public)

Radius (Public)

Typography (Public)

Distribution tokens

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0d4abc9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

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

[github-actions]

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

---

Review: @clickhouse/design-tokens initial package

Great work! The broken {color.gray.650} reference has been resolved (→ {color.neutral.650}, confirmed in primitives), and the overall DTCG structure is solid. The Terrazzo setup, CSS variable naming convention, and dual light/dark mode support all look well thought out. 🙌

---

🚨 Must Fix

• publishConfig missing (packages/design-tokens/package.json): The changeset config at packages/click-ui/.changeset/config.json has "access": "restricted". Without a "publishConfig": { "access": "public" } override in the package itself, Changesets will publish @clickhouse/design-tokens as restricted (private), and npm publish will fail for the scoped org package. Fix this →

---

💡 Suggestions (non-blocking)

• Dark mode override order (terrazzo.config.js:23-30): The modeSelectors puts @media (prefers-color-scheme: dark) alongside [data-theme='dark']. If Terrazzo generates the media query block before [data-theme='light'] in the CSS output, a user who sets data-theme="light" while their OS is in dark mode may get dark tokens anyway (media query at-rules don't participate in the cascade the same way selectors do). Verify the generated dist/tokens.css output order before shipping.

• Border feedback colors too low contrast (semantic.dtcg.json:464-485): border.feedback.error = {color.red.50} and border.feedback.info = {color.blue.50} — these are the same 10% opacity tints used for backgrounds. A border at 10% opacity won't be visible against a light field background. Consider stepping up to red.200/red.600 and blue.200/blue.600.

• Changeset bot discrepancy: The bot reports "No Changeset found" because it scans from the repo root (.changeset/), but this repo's CI workflow (create-release.yml:134) correctly reads from packages/click-ui/.changeset/. The changeset file is in the right place for CI — the bot warning can be ignored on this intermediary PR targeting chore/monorepo-migration.

• core/valid-color: "off" (terrazzo.config.js:14): Re-enable once the colour space decision is made (tracked in PR TODO).

• Font sizes in px (typography.dtcg.json): All font.size.* tokens use px. Switching to rem would respect user browser font-size preferences — $description even includes the rem equivalents already, which makes the switch straightforward.

• Font-family tokens — still an open TODO per the PR description.

---

[github-actions]

Claude finished @punkbit's task in 1m 29s —— View job

---

Review: @clickhouse/design-tokens package

Solid initial package! The DTCG structure is well-organized, the recent commits addressing the {color.gray.650} → {color.neutral.650} fix and DTCG colour-space compliance are all good progress. Here's what I found:

---

🚨 Must Fix

• publishConfig missing (packages/design-tokens/package.json): No "publishConfig": { "access": "public" } field. The changeset config at packages/click-ui/.changeset/config.json uses "access": "restricted" — without the override, npm publish will fail for this scoped package. Fix this →

---

💡 Suggestions (non-blocking)

• Dark mode override order (terrazzo.config.js:22-30): @media (prefers-color-scheme: dark) is listed alongside [data-theme='dark'] in the same modeSelectors entry. Depending on Terrazzo's CSS output order, an OS-dark user with data-theme="light" explicitly set may still receive dark tokens — media queries don't participate in cascade specificity the same way attribute selectors do. Verify the generated dist/tokens.css that [data-theme='light'] block appears after the prefers-color-scheme: dark block, or split into separate mode entries with explicit order control.

• Border feedback colors too low contrast (semantic.dtcg.json:464-485): border.feedback.error = {color.red.50} and border.feedback.info = {color.blue.50} — these are the same ~10% tint values used for backgrounds. A border this light won't be visible against a light field surface. Consider stepping up to red.200/red.600 and blue.200/blue.600.

• Font sizes in px (typography.dtcg.json): All font.size.* tokens use px, which prevents user browser font-size preferences from scaling them. The $description fields even include the rem equivalents already (e.g. "0.625rem"), making a switch to rem straightforward.

• Changeset bot false positive: The bot reports "No Changeset found" because it scans from repo root (.changeset/), but the changeset at packages/click-ui/.changeset/add-design-tokens-package.md is in the correct location for your CI workflow — safe to ignore on this intermediary PR targeting chore/monorepo-migration.

• core/valid-color: "off" (terrazzo.config.js:14): Re-enable once the colour space decision is made (tracked in PR TODO).

• Font-family tokens — still an open TODO per the PR description.

---

[github-actions]

Claude finished @punkbit's task in 1m 26s —— View job

---

Review: @clickhouse/design-tokens package

Great work on this initial package! The DTCG structure is solid, the Terrazzo setup is clean, and the dual light/dark mode support is well thought out. Here's the full review:

---

🚨 Must Fix

• publishConfig missing (packages/design-tokens/package.json): The changeset config at packages/click-ui/.changeset/config.json uses "access": "restricted". Without "publishConfig": { "access": "public" } in the package itself, npm publish will fail for this scoped package. Fix this →

---

💡 Suggestions (non-blocking)

• Dark mode override order (terrazzo.config.js:22-30): The dark mode modeSelectors puts the @media (prefers-color-scheme: dark) { :root } block and [data-theme='dark'] in the same prepare string. CSS @media at-rules don't participate in selector specificity, so if Terrazzo emits the media-query block after the :root, [data-theme='light'] block, an OS-dark user who explicitly sets data-theme="light" will still get dark tokens from the media query. Verify the generated dist/tokens.css that [data-theme='light'] appears after the prefers-color-scheme: dark block, or split into two separate permutations entries with an explicit order so [data-theme='light'] always wins.

• Border feedback colors too low contrast (semantic.dtcg.json:464-485): border.feedback.error = {color.red.50} and border.feedback.info = {color.blue.50} — these are the same ~10% opacity tints used as backgrounds. A border at that opacity won't be visible against the color.background.field surface. Consider stepping up to red.200/red.600 and blue.200/blue.600 to match the pattern used for solid feedback colors.

• Font sizes in px (typography.dtcg.json): All font.size.* tokens use "unit": "px", which prevents user browser font-size preferences from scaling them. Notably, the $description fields already include the rem equivalents (e.g. "10px, 0.625rem, xs, tiny"), making a switch to rem straightforward when ready.

• core/valid-color: "off" (terrazzo.config.js:14): Re-enable once the colour space decision is made (tracked in PR TODO). The current legacyHex: true option is a good bridge, but leaving the lint rule disabled indefinitely risks accepting inconsistent colour formats.

• Changeset bot false positive: The bot reports "No Changeset found" because it scans from repo root (.changeset/). The changeset at packages/click-ui/.changeset/add-design-tokens-package.md is in the correct location for your CI workflow — safe to ignore on this PR targeting chore/monorepo-migration.

• Font-family tokens — still an open TODO per the PR description. Worth tracking as a follow-up issue.

---

[github-actions]

Claude finished @punkbit's task in 1m 20s —— View job

---

Review: @clickhouse/design-tokens package

Solid DTCG structure, clean Terrazzo setup, and good dual light/dark support. The changeset is well-documented with usage examples. A few items still need attention from previous reviews:

---

🚨 Must Fix

• publishConfig missing (packages/design-tokens/package.json): Still no "publishConfig": { "access": "public" }. The changeset config at packages/click-ui/.changeset/config.json uses "access": "restricted" — without this override, npm publish will fail for the scoped @clickhouse/ package. Fix this →

---

💡 Suggestions (non-blocking)

• Dark mode override order (terrazzo.config.ts:29-30): The light permutation emits :root, [data-theme='light'] first; the dark permutation then emits @media (prefers-color-scheme: dark) { :root } followed by [data-theme='dark']. Because the media query targets :root at the same specificity as the light block but appears later in the CSS, an OS-dark user who explicitly sets data-theme="light" will still receive dark tokens — the media query wins via source order. Fix: move the @media (prefers-color-scheme: dark) block before the [data-theme='light'] block (i.e., light permutation last), or split into a dedicated third permutation for prefers-color-scheme: dark with explicit ordering. Fix this →

• Border feedback colors too low contrast (semantic.dtcg.json:464-485): border.feedback.error = {color.red.50} and border.feedback.info = {color.blue.50} — same ~10% opacity tints used for backgrounds. These won't be visible as borders against a light field surface. Consider red.200/red.600 and blue.200/blue.600 to match the pattern used in color.feedback.solid.*.

• Font sizes in px (typography.dtcg.json): All font.size.* tokens use "unit": "px", preventing user browser font-size preferences from scaling them. The $description fields already include the rem equivalents (e.g. "10px, 0.625rem, xs, tiny"), making a future switch to rem straightforward.

• core/valid-color: "off" (terrazzo.config.ts:14): Re-enable once the colour space decision is made. Leaving the rule disabled long-term risks accepting inconsistent colour formats.

• Font-family tokens — still an open TODO per the PR description. Consider tracking as a follow-up issue.

• Changeset bot false positive: The bot reports "No Changeset found" because it scans from the repo root (.changeset/). The changeset at packages/click-ui/.changeset/add-design-tokens-package.md is in the correct location for your CI workflow — safe to ignore on this intermediary PR targeting chore/monorepo-migration.

---

[workflow-authentication-public]

📚 Storybook Preview Deployed

✅ Preview URL: https://click-34a8ive8d-clickhouse.vercel.app

Built from commit: b1ef29d5874eb9e16b55afbbe07841d817e527e7