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: 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: fabdfd2

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 20s —— View job

---

Review: @clickhouse/design-tokens package

• Read relevant files
• Analyze changes since last review
• Post review

---

All previously flagged must-fix items are now resolved — great progress! 🙌

✅ Previously flagged items now resolved

• publishConfig (package.json:21-23): "publishConfig": { "access": "public" } present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:146-156): :root, [data-theme='light'] specificity (0,1,0) beats :root inside @media (prefers-color-scheme: dark) (0,0,1). ✅
• tokens:watch fixed: tokens:build:watch correctly uses chokidar to re-run the full build on dictionary changes. ✅
• radius.full (semantic.dtcg.json:677): Renamed from radius.all. ✅

---

💡 Suggestions (non-blocking, carried from prior reviews)

• Border feedback colors still low contrast (semantic.dtcg.json:464–506): Three of the four feedback border tokens still resolve to near-white primitives that won't be visible on a light surface:

  • border.feedback.error → {color.red.300} = #ffdddd (HSL 0, 100%, 93%) — "Danger background subtle" in primitives
  • border.feedback.info → {color.blue.300} = #e7effd (HSL 219, 85%, 95%) — "Info/selection background subtle"
  • border.feedback.warning → {color.orange.100} = #fdeee5 (HSL 22, 100%, 95%) — "Warning border - solid light orange"
  • border.feedback.success → {color.green.100} = #255E27 ✅ correctly a dark green

  Solid alternatives already exist in the primitives: red.600 (#c20000), blue.400 (#437fef) or blue.600 (#104dc6), orange.600 (#d64f00). Fix this →

• buildSemanticToPrimitiveMap redundant paths (terrazzo.config.ts:26-44): The $extensions traversal block (lines 26–44) and the $type === "color" check block (lines 47–64) both insert the same tokenId → { light, dark } entries into the map. The second block is the clean path; the first can be removed entirely.

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

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

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

[DreaminDani]

I'm wary of merging this before I've gotten a chance to try out these variables in Figma directly. But just commenting here to say I love this direction and that the design team is 80-90% aligned with this approach. I'll start a branch in Figma next week to try out these variables in real use-cases and see if I have any feedback from there.

[github-actions]

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

---

Review: @clickhouse/design-tokens package

• Read relevant files and CLAUDE.md
• Analyze changes since last review
• Post review

---

Good progress on this iteration! The new sizing primitives refactor is clean and the semantic alias layer is well structured.

---

✅ Previously flagged items now resolved

• publishConfig (package.json:21-23): "publishConfig": { "access": "public" } present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:146-156): :root, [data-theme='light'] specificity (0,1,0) correctly beats :root inside @media (prefers-color-scheme: dark) (0,0,1). ✅
• tokens:build:watch (.scripts/bash/tokens-build): Fixed — chokidar correctly re-runs the full build including concatenation. ✅
• radius.full (semantic.dtcg.json:677): Renamed from radius.all. ✅

✅ New in this iteration

• Sizing primitives refactor (sizing.dtcg.json): Organizing by category (sizing.symbol.*, sizing.border.*) with semantic aliases (sizing.icon.*, sizing.stroke.*) in the semantic layer is a clean, scalable pattern. Nice work. ✅

---

💡 Suggestions (non-blocking, carried from prior reviews)

• Border feedback colors still low contrast (semantic.dtcg.json:464–507): Three of the four feedback border tokens still resolve to near-white primitives that won't be visible as borders on a light surface:

  • border.feedback.error → {color.red.300} = #ffdddd (HSL 0, 100%, 93%) — described in primitives as "Danger background subtle"
  • border.feedback.info → {color.blue.300} = #e7effd (HSL 219, 85%, 95%) — "Info/selection background subtle"
  • border.feedback.warning → {color.orange.100} = #fdeee5 (HSL 22, 100%, 95%) — "Warning border - solid light orange"
  • border.feedback.success → {color.green.100} = #255E27 ✅ (correctly a dark green)

  Solid darker alternatives exist in the primitives: red.600 (#c20000), blue.400 (#437fef), orange.600 (#d64f00). Fix this →

• buildSemanticToPrimitiveMap redundant paths (terrazzo.config.ts:26-44): The $extensions traversal block (lines 26–44) and the $type === "color" check (lines 47–64) both insert the same tokenId → { light, dark } entries into the map. The $type === "color" block is the clean path; the $extensions traversal can be removed.

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

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

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

[github-actions]

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

---

Review: @clickhouse/design-tokens package

• Read repo conventions and CLAUDE.md
• Analyze changes since last review (cc669a99 — docs only: SPECIFICATION.md updated)
• Review key files
• Post review

---

No functional code changed in this push — just documentation updates to SPECIFICATION.md. Carrying the full review forward.

---

✅ Previously flagged items resolved

• publishConfig (package.json:21-23): "publishConfig": { "access": "public" } present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:146-156): :root, [data-theme='light'] specificity (0,1,0) beats :root inside @media (prefers-color-scheme: dark). ✅
• tokens:build:watch: chokidar correctly re-runs full build on dictionary changes. ✅
• radius.full (semantic.dtcg.json:677): Renamed from radius.all. ✅

---

💡 Suggestions (non-blocking)

• All four border feedback colors are low contrast (semantic.dtcg.json:463–518): All feedback border tokens in light mode resolve to pastel background tints — none will be visible as borders against a white/light surface:

  • border.feedback.error → {color.red.50} = #ffdddd (HSL 0, 100%, 93%)
  • border.feedback.info → {color.blue.50} = #E7EFFD (HSL 218, 85%, 95%)
  • border.feedback.success → {color.green.100} = #CCFFD0 (HSL 125, 100%, 90%) — note: not the dark green prior reviews assumed; the primitives changed in 26f51f3c
  • border.feedback.warning → {color.orange.100} = #FFCBAD (HSL 22, 100%, 84%)

  All four sit in the same "lightest" tint band used for backgrounds. Solid border alternatives exist in the primitives: red.600 (#c10000), blue.400 (#437EEF), green.600 or green.700, orange.600. Fix this →

• buildSemanticToPrimitiveMap redundant paths (terrazzo.config.ts:22-44): The $extensions traversal block (lines 22–44) and the $type === "color" check block (lines 47–64) both produce identical tokenId → { light, dark } map entries. The second block is the clean path; the first can be removed.

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

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

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

[github-actions]

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

---

Review: @clickhouse/design-tokens package

• Read repo conventions and CLAUDE.md
• Analyze changes since last review (ec84060a — two new primitives + semantic tokens)
• Review key files
• Post review

---

Good iteration! This push adds two new gray primitives and two semantic foreground tokens — a clean, targeted change.

---

✅ Previously flagged items resolved

• publishConfig (package.json:21-23): "publishConfig": { "access": "public" } present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:146-156): :root, [data-theme='light'] specificity (0,1,0) beats :root inside @media (prefers-color-scheme: dark). ✅
• tokens:build:watch: Fixed — chokidar correctly re-runs full build on dictionary changes. ✅
• radius.full (semantic.dtcg.json:677): Renamed from radius.all. ✅

---

✅ New in this iteration

• gray.350 (primitives.dtcg.json:74-83): #ADB1B8 — fills the gap between gray.300 (72% L) and gray.400 (63% L). Used for format hint text. ✅
• gray.850 (primitives.dtcg.json:134-143): #1E1D1F — near-black between gray.800 (19% L) and gray.900 (9% L). Used for strong titles. ✅
• color.foreground.strong (semantic.dtcg.json:312-322): gray.850 light / gray.100 dark — correct high-contrast inversion for dark mode. ✅
• color.foreground.format updated from gray.400 → gray.350 (semantic.dtcg.json:323-333): gray.350 (#ADB1B8) is slightly lighter (70% L vs 63% L) but fits better as a hint/helper text value. ✅

---

💡 Suggestions (non-blocking, carried from prior reviews)

• All four border feedback colors are low contrast (semantic.dtcg.json:474–518): All feedback border tokens in light mode still resolve to the lightest tint band — none will be visible as strokes on a white/light surface:

  • border.feedback.error → {color.red.50} = #ffdddd (L=93%)
  • border.feedback.info → {color.blue.50} = #E7EFFD (L=95%)
  • border.feedback.success → {color.green.100} = #CCFFD0 (L=90%) ← light green, not dark
  • border.feedback.warning → {color.orange.100} = #FFCBAD (L=84%)

  Solid visible alternatives exist in the primitives: red.600 (#c10000), blue.400 (#437EEF), green.700 (#008A0B), orange.600 (#D64F00). Fix this →

• buildSemanticToPrimitiveMap redundant paths (terrazzo.config.ts:22-44): The $extensions traversal block (lines 22–44) and the $type === "color" check block (lines 47–64) both insert identical tokenId → { light, dark } entries into the map. The second block is sufficient; the first can be removed.

• color.foreground.format in dark mode contrast (semantic.dtcg.json:327): Dark mode uses {color.gray.400} = #9a9ea7 (L=63%) against the dark surface. Worth a quick contrast check once the dark background tokens are finalised — format/hint text should still meet at least 3:1 against the field background.

• Font sizes in px (typography.dtcg.json): All font.size.* tokens still use "unit": "px", preventing browser font-size preferences from scaling. The $description fields already include rem equivalents, making a future switch straightforward.

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

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

[github-actions]

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

---

Review: @clickhouse/design-tokens package

• Read repo conventions
• Analyze changes since last review (e49e2468 — color pass based on Dani's curation)
• Review key files
• Post review

---

Good iteration — the new "winter" dark mode tints (red.750, green.850) are a nice curation step for desaturated dark surfaces, and color.foreground.interactive.on-danger is a clean addition. One broken reference needs a fix before merge.

---

✅ Previously flagged items resolved

• publishConfig (package.json:21-23): "publishConfig": { "access": "public" } present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:146-156): :root, [data-theme='light'] specificity (0,1,0) beats :root inside @media (prefers-color-scheme: dark). ✅
• tokens:build:watch: chokidar correctly re-runs full build on dictionary changes. ✅
• radius.full: Renamed from radius.all. ✅

✅ New in this iteration

• color.background.feedback.danger dark: red.800 (#610000, pure-dark) → red.750 (#4C201D, desaturated winter red). Intentional muted pairing for dark surfaces. ✅
• color.background.feedback.success dark: green.800 → green.850 (#234C24, winter green). Same desaturated-for-dark pattern. ✅
• color.foreground.interactive.on-danger (semantic.dtcg.json:333-344): red.600 light / red.100 dark — correct high-contrast inversion. ✅

---

🚨 Must Fix

• Broken token reference (semantic.dtcg.json): color.foreground.interactive.on-primary dark mode now references {color.charcoal.surface.50}, but no charcoal primitive is defined anywhere in primitives.dtcg.json. Terrazzo will fail to resolve this reference at build time. The terrazzo.config.ts lists "color.charcoal.**" as a scope pattern (line 81) but the actual token data doesn't exist. Revert to {color.gray.900} or define the charcoal palette first. Fix this →

---

⚠️ Worth Checking

• color.background.interactive.primary dark now {color.brand.300} = #FAFF69 (L=71%, vivid yellow) (semantic.dtcg.json:64): Once the charcoal.surface.50 reference is resolved, verify contrast between this background and the on-primary text token — #FAFF69 is a very light surface and needs a clearly legible dark foreground to meet WCAG AA (4.5:1).

---

💡 Suggestions (non-blocking, carried from prior reviews)

• All four border feedback colors still low contrast (semantic.dtcg.json:486–529): All feedback border tokens in light mode still resolve to pastel background tints — none will be visible as strokes against a white/light surface:

  • border.feedback.error → {color.red.50} = #ffdddd (L=93%)
  • border.feedback.info → {color.blue.50} = #E7EFFD (L=95%)
  • border.feedback.success → {color.green.100} = #CCFFD0 (L=90%)
  • border.feedback.warning → {color.orange.100} = #FFCBAD (L=84%)

  Solid visible alternatives exist: red.600 (#c10000), blue.400, green.700 (#008A0B), orange.600 (#D64F00). Fix this →

• buildSemanticToPrimitiveMap redundant paths (terrazzo.config.ts:22-44): The $extensions traversal block (lines 22–44) and the $type === "color" check (lines 47–64) both produce identical map entries. The $type === "color" block is sufficient; the $extensions block can be removed.

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

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

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

[github-actions]

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

---

Review: @clickhouse/design-tokens package

• Read repo conventions
• Analyze changes since last review (fabdfd25 — formatting pass only on SPECIFICATION.md)
• Review key files
• Post review

---

No functional code changed in this push — just table alignment/whitespace formatting in SPECIFICATION.md. Carrying the full review forward.

---

✅ Previously flagged items resolved

• publishConfig (package.json:21-23): "publishConfig": { "access": "public" } present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:146-156): :root, [data-theme='light'] specificity (0,1,0) beats :root inside @media (prefers-color-scheme: dark). ✅
• tokens:build:watch: chokidar correctly re-runs full build on dictionary changes. ✅
• radius.full: Renamed from radius.all. ✅

---

🚨 Must Fix

• Broken token reference (semantic.dtcg.json:352): color.foreground.interactive.on-primary dark mode still references {color.charcoal.surface.50}, but charcoal is not defined anywhere in primitives.dtcg.json. This was flagged in the previous review and remains unresolved — Terrazzo will fail to resolve this reference at build time. Revert to {color.gray.900} or define the charcoal palette first. Fix this →

---

💡 Suggestions (non-blocking, carried from prior reviews)

• All four border feedback colors still low contrast (semantic.dtcg.json:486–529): All feedback border tokens in light mode still resolve to pastel background tints that won't be visible as strokes on a white/light surface:

  • border.feedback.error → {color.red.50} = #ffdddd (L=93%)
  • border.feedback.info → {color.blue.50} = #E7EFFD (L=95%)
  • border.feedback.success → {color.green.100} = #CCFFD0 (L=90%)
  • border.feedback.warning → {color.orange.100} = #FFCBAD (L=84%)

  Solid visible alternatives exist in the primitives: red.600 (#c10000), blue.400 (#437EEF), green.700 (#008A0B), orange.600 (#D64F00). Fix this →

• buildSemanticToPrimitiveMap redundant paths (terrazzo.config.ts:22-44): The $extensions traversal block (lines 22–44) and the $type === "color" check block (lines 47–64) both produce identical tokenId → { light, dark } map entries. The $type === "color" block is sufficient; the $extensions block can be removed.

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

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

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

[workflow-authentication-public]

📚 Storybook Preview Deployed

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

Built from commit: cfcb5ba4eae0b3436f6085429466647c3919f06c