ClickHouse · punkbit · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/packages/click-ui/.changeset/add-design-tokens-package.md b/packages/click-ui/.changeset/add-design-tokens-package.md
@@ -0,0 +1,36 @@
+---
+"@clickhouse/design-tokens": minor
+---
+
+Initial release of the design-tokens package. Provides DTCG-compliant design token definitions for colors, spacing, radius, sizing, and typography. Includes Terrazzo-based CSS output generation.
+
+**Package pathname:** `packages/design-tokens`
+
+**Token Dictionary Location:** `packages/design-tokens/dictionary/`
+
+- `primitives.dtcg.json`
+- `semantic.dtcg.json` - Semantic color tokens (references primitives)
+- `spacing.dtcg.json` - Spacing scale (8px base unit)
+- `radius.dtcg.json` - Border radius scale
+- `sizing.dtcg.json` - Icon and component sizes
+- `typography.dtcg.json` - Font sizes, weights, and line heights
+
+**Creating Tokens:** Add or modify tokens in the dictionary files following DTCG format:
+
+```json
+{
+  "$type": "dimension",
+  "$value": { "value": 8, "unit": "px" },
+  "$description": "8px, base spacing"
+}
+```
+
+**Building:** Run `yarn tokens:build` to generate `packages/design-tokens/dist/tokens.css`.
+
+**Configuration:** `packages/design-tokens/config.js` contains build settings:
+
+- `CSS_VAR_PREFIX` - CSS variable prefix (default: `cui` → `--cui-*`)
+- `DICTIONARY_PATH` - Token dictionary location
+- `TOKEN_FILES` - Token files and import order
+
+See `packages/design-tokens/SPECIFICATION.md` for naming conventions and detailed guidelines.
diff --git a/packages/click-ui/.changeset/config.json b/packages/click-ui/.changeset/config.json
@@ -4,7 +4,7 @@
   "commit": false,
   "fixed": [],
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []

diff --git a/packages/design-tokens/.prettierignore b/packages/design-tokens/.prettierignore
@@ -0,0 +1 @@
+dist
diff --git a/packages/design-tokens/.prettierrc b/packages/design-tokens/.prettierrc
@@ -0,0 +1,9 @@
+{
+  "endOfLine": "lf",
+  "printWidth": 90,
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "useTabs": false
+}
diff --git a/packages/design-tokens/.scripts/bash/tokens-build b/packages/design-tokens/.scripts/bash/tokens-build
@@ -0,0 +1,19 @@
+#!/bin/bash
+
+build_tokens() {
+  rm -rf ./dist
+  tz build
+  cat ./dist/tokens-primitives.css ./dist/tokens-semantic.css > ./dist/tokens.css
+  rm ./dist/tokens-primitives.css ./dist/tokens-semantic.css
+  echo "✓ Built tokens.css"
+}
+
+if [[ "$1" == "watch" ]]; then
+  echo "👀 Watching dictionary files for changes..."
+
+  build_tokens
+
+  chokidar "dictionary/**/*.json" -c "$(pwd)/.scripts/bash/tokens-build" --initial=false
+else
+  build_tokens
+fi
diff --git a/packages/design-tokens/README.md b/packages/design-tokens/README.md
@@ -0,0 +1,137 @@
+# Design Tokens
+
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)
+
+ClickHouse Design System token definitions for colors, spacing, typography and more, following the DTCG standard.
+
+## Quick Start
+
+Install dependencies:
+
+```sh
+yarn
+```
+
+Build tokens for consumer apps:
+
+```sh
+yarn tokens:build
+```
+
+Optionaly, use "watch" mode for automatic builds on file changes:
+
+```sh
+yarn tokens:build:watch
+```
+
+## CSS Variable Prefix
+
+All generated CSS variables use the `--cui-` prefix (Click UI). This prefix is defined in `config.js` to ensure consistent namespace variable names across all consumer client applications.
+
+```css
+--cui-color-background-base
+--cui-space-100
+--cui-radius-50
+```
+
+To customize the prefix, modify `CSS_VAR_PREFIX` in `config.js` and rebuild.
+
+## Dark Mode
+
+Semantic color tokens support light and dark mode variants. The build outputs CSS that applies:
+
+- **Light mode**: `:root` and `[data-theme='light']`
+- **Dark mode**: `@media (prefers-color-scheme: dark)` and `[data-theme='dark']`
+
+Dark mode activates automatically via OS preference (no JS required), or explicitly via attribute:
+
+```html
+<html data-theme="dark"></html>
+```
+
+The `data-theme` attribute takes precedence, allowing users to override their OS preference.
+
+## Token Specification
+
+This package follows the [DTCG (Design Tokens Community Group)](https://www.designtokens.org) standard. The specification defines naming conventions, token categories, and metadata strategies for consistent design token usage across Figma and code.
+
+### Token Categories
+
+| Category       | Naming Convention                                                                                    | Example                                                         |
+| -------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **Color**      | Primitives: `color/{palette}/{step}`, Semantic: `color/{category}/{subcategory}/{hierarchy}/{state}` | `color/gray/50`, `color/background/interactive/primary/default` |
+| **Spacing**    | Percentage-based with 8px base unit                                                                  | `space/100` (8px), `space/200` (16px)                           |
+| **Radius**     | Percentage-based scale                                                                               | `radius/50` (4px), `radius/100` (8px)                           |
+| **Sizing**     | T-shirt sizes by type                                                                                | `sizing/icon/md` (20px), `sizing/component/lg` (48px)           |
+| **Typography** | `font/{property}/{scale}`                                                                            | `font/size/lg` (16px), `font/weight/semibold` (600)            |
+
+### Usage Examples
+
+```css
+/* Semantic color tokens */
+.button {
+  background: var(--cui-color-background-interactive-primary-default);
+  color: var(--cui-color-foreground-default);
+}
+
+/* Spacing tokens */
+.card {
+  padding: var(--cui-space-200); /* 16px */
+  gap: var(--cui-space-100); /* 8px */
+}
+
+/* Sizing tokens */
+.icon {
+  width: var(--cui-sizing-icon-md); /* 20px */
+}
+```
+
+### Lint Rules
+
+To prevent inappropriate use of tokens (e.g., using primitives directly in component styles), configure lint rules:
+
+**Stylelint**
+
+Warn on primitive token usage:
+
+```json
+{
+  "rules": {
+    "declaration-property-value-disallowed-list": {
+      "/color|background|border/": [
+        "/--cui-color-(white|black|gray|blue|green|red|yellow|orange)-/"
+      ]
+    }
+  }
+}
+```
+
+**ESLint**
+
+For CSS-in-JS (e.g., styled-components):
+
+```json
+{
+  "rules": {
+    "no-restricted-syntax": [
+      "warn",
+      {
+        "selector": "Literal[value=/--cui-color-(white|black|gray|blue|green|red|yellow|orange)-/]",
+        "message": "Use semantic tokens instead of primitive color tokens"
+      }
+    ]
+  }
+}
+```
+
+**Guideline**
+
+> [!WARNING]
+> Components should use semantic tokens (`--cui-color-background-*`). Primitives (`--cui-color-gray-*`) are exposed for theming and debugging but should not appear in component styles.
+
+For complete details on naming conventions, metadata strategies, and implementation guidelines, see [SPECIFICATION.md](./SPECIFICATION.md).
+
+# References
+
+- [DTCG](https://www.designtokens.org)
+- [Design Tokens Technical Reports 2025.10](https://www.designtokens.org/tr/2025.10/)