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

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 1m 21s —— View job

---

Review: @clickhouse/design-tokens package

• Read relevant files
• Analyze package structure and token definitions
• Post review

---

Great progress this cycle! The two previously-critical issues are now resolved:

• ✅ publishConfig correctly fixed (packages/design-tokens/package.json:21): Now properly nested as "publishConfig": { "access": "public" } — this was the blocking issue flagged in every prior review, and it's done.
• ✅ core/valid-color re-enabled (terrazzo.config.ts:12): Back to "error" — good.

No must-fix items remain.

---

💡 Suggestions (non-blocking)

• Border feedback colors still low contrast (semantic.dtcg.json:464–506): Three of the four feedback border values are still very light tints that won't be visible as borders on a light surface:

  • border.feedback.error → {color.red.300} = #ffdddd (~1.1:1 contrast on white)
  • border.feedback.info → {color.blue.300} = #e7effd (similarly near-invisible)
  • border.feedback.warning → {color.orange.100} = #fdeee5 (same problem)
  • border.feedback.success → {color.green.100} = #255E27 ✅ correctly a solid dark green

  These "300"/"100" values are the background-subtle tints — not stroke values. Consider stepping up to solid darker primitives (red.600, blue.600, orange.600) for visible borders. Fix this →

• Dark mode CSS ordering (terrazzo.config.ts:22–30): Confirmed correct — [data-theme='light'] (specificity 0,1,0) beats :root inside @media (prefers-color-scheme: dark) (specificity 0,0,1). ✅

• Font sizes in px (typography.dtcg.json): All font.size.* tokens use "unit": "px". The $description fields already include rem equivalents (e.g. "10px, 0.625rem"), 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 your CI workflow on this intermediary PR targeting chore/monorepo-migration.

---

[github-actions]

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

---

Review: @clickhouse/design-tokens package

• Read relevant files
• Analyze package structure and token definitions
• Post review

---

The radius refactor in the latest commit is the key change to evaluate. Clean approach and well-documented rationale. Here's the full picture:

---

✅ Previously flagged items now resolved

• publishConfig (packages/design-tokens/package.json:21): "publishConfig": { "access": "public" } is present. ✅
• core/valid-color (terrazzo.config.ts:12): Back to "error". ✅
• Dark mode CSS ordering (terrazzo.config.ts:22–30): Confirmed correct — [data-theme='light'] specificity wins over :root inside the @media query. ✅

---

🆕 Latest Change: Radius semantic t-shirt sizing (radius.dtcg.json)

The consolidation from 10 numeric values to 7 semantic categories is a solid call — radius is genuinely categorical, and sm/md/lg is far more designer-friendly than radius.25/radius.100. The SPECIFICATION.md rationale is well written.

One minor note: merging 32px (radius.400) → xl (24px) is a larger step than the others (~33% reduction). If any existing consumers are using 32px radii for large cards or feature sections, they'll land on 24px instead. Since this is a new package at v0.0.0 with no consumers yet, this isn't a concern — just worth documenting in the SPECIFICATION.md or a code comment if the original step comes up in design review.

---

💡 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 resolve to near-white primitives at 91–95% lightness:

  • border.feedback.error → {color.red.300} = #ffdddd — described in primitives as "background subtle"
  • border.feedback.info → {color.blue.300} = #e7effd — described as "background subtle"
  • border.feedback.warning → {color.orange.100} = #fdeee5 — described as "Warning border - solid light orange" in primitives, but at 95% lightness it won't be visible against a white field
  • border.feedback.success → {color.green.100} = #255E27 ✅ solid dark green — correctly set

  The solid candidates already exist in primitives: red.600 (#c20000), blue.400 (#437fef), orange.600 (#d64f00). Fix this →

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

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

• 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 3m 9s —— View job

---

Review: @clickhouse/design-tokens package

• Read relevant files
• Analyze package structure and token definitions
• Post review

---

The key change in this cycle is the refactor splitting CSS output into tokens-primitives.css + tokens-semantic.css (concatenated into tokens.css), with semantic tokens now emitting var(--cui-...) references to primitives rather than raw values. This is a solid architectural improvement — primitives stay static in :root, and theme switches only swap the semantic layer.

---

✅ Previously flagged items confirmed resolved

• publishConfig (package.json:21): "publishConfig": { "access": "public" } is present. ✅
• core/valid-color: "error" (terrazzo.config.ts:118): Re-enabled. ✅
• Dark mode CSS ordering (terrazzo.config.ts:148-156): [data-theme='light'] specificity (0,1,0) beats :root inside @media (prefers-color-scheme: dark) (0,0,1). ✅

---

🚨 Must Fix

• tokens:watch script is broken (package.json:34): tokens:watch runs tz build --watch but never concatenates the output files. Terrazzo generates tokens-primitives.css and tokens-semantic.css incrementally, but tokens.css (the exported artifact) is never created or updated during watch. Any developer using tokens:watch for local iteration will see stale output. Either document that tokens:watch should not be used (and remove/rename it), or replace it with a file-system watcher that runs the full tokens:build on change (e.g. nodemon/chokidar). Fix this →

---

💡 Suggestions (non-blocking)

• Redundant code paths in buildSemanticToPrimitiveMap (terrazzo.config.ts:22-70): The function writes to the map twice for each token — once when it encounters the $extensions key directly (lines 27-43), and again when checking value.$type === "color" on the token object itself (lines 48-64). Both produce identical map entries, so there's no bug, but the duplication adds noise. The $type check at line 48 is the cleaner path and can stand alone; the $extensions traversal path at line 27 is redundant and can be removed.

• Border feedback colors still low contrast (semantic.dtcg.json:464-506): Three of the four feedback border tokens still resolve to near-white primitives:

  • border.feedback.error → {color.red.300} = #ffdddd (HSL 0, 100%, 93%) — described in primitives as "Danger background subtle"
  • border.feedback.info → {color.blue.300} (similarly a very light tint)
  • border.feedback.warning → {color.orange.100} = #fdeee5 (HSL 22, 100%, 95%)
  • border.feedback.success → {color.green.100} = #255E27 ✅ correctly dark

  The solid candidates already exist in primitives: red.600 (#c20000), and equivalents for blue/orange. Fix this →

• 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"), making a future switch straightforward.

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

• Changeset bot false positive: The "No Changeset found" warning is safe to ignore — the changeset at 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-p11hrcgxh-clickhouse.vercel.app

Built from commit: 059ac5b9d285c64f7d0b2c100b68cd883c62d868