@bitrise/bitkit-v2 0.3.255-beta.1718 → 0.3.255-beta.1719

package/docs/design-tokens.md

@@ -0,0 +1,94 @@
+# Design tokens — source of truth & sync
+
+How bitkit-v2's color tokens relate to the design source, and how to keep them in sync.
+
+## The pipeline
+
+The **source of truth is the design team's Tokens Studio export** — a single
+`tokens.json` (DTCG / Figma Tokens format) generated from Figma. It currently
+lives in the `bitkit-tokens` repo at `data/tokens.json`.
+
+bitkit-v2 holds **hand-maintained** token files that mirror that source:
+
+| source (`tokens.json`)                                   | bitkit-v2 file                              |
+| -------------------------------------------------------- | ------------------------------------------- |
+| `core/color-primitives.core` (`purple.50`, `red.40`, …)  | `lib/theme/tokens/colors.ts` (primitives)   |
+| `semantic/theme-light.{color,sys,…}`                     | `lib/theme/semantic-tokens/semanticColors.ts` |
+| `components/colors.{background,text,icon,button,status,gradient,…}` | `lib/theme/semantic-tokens/semanticColors.ts` |
+
+When the source changes (it does, in small increments), re-sync bitkit's files
+to match. **The JSON wins** on any conflict — including over the
+`bitkit-color-tokens.xlsx` worksheet, which is a human-readable side view and
+can lag behind.
+
+## Checking for drift
+
+```bash
+# 1. fetch the current source (auth via gh)
+gh api repos/<owner>/bitkit-tokens/contents/data/tokens.json --jq '.content' | base64 -d > /tmp/tokens.json
+
+# 2. diff it against bitkit's token files
+npm run theme:diff-tokens -- /tmp/tokens.json
+```
+
+The script (`scripts/diff-design-tokens.cjs`) reports, for the primitive and
+semantic+component layers:
+
+- tokens the **source has but bitkit is missing**,
+- tokens **bitkit has but the source doesn't** (renamed / stale / intentional extra),
+- **light value/reference mismatches** on the common tokens.
+
+Values are compared canonically, so equivalent spellings (`#fff` ≡ `#ffffff`,
+`core.purple.50` ≡ `colors.purple.50`) are **not** flagged.
+
+After any change, run `npm run theme:generate-types` then `npm run type-check`.
+
+## Naming & layering conventions
+
+- **Primitives** are dot-separated (`purple.50`, `white.10`) and live in `colors.ts`.
+- **Semantic / component** tokens are slash-separated (`color/purple/base`,
+  `sys/bg/surface`, `button/primary/bg`, `gradient/ai/background/base`).
+- References use the `{colors.…}` prefix: `{colors.purple.50}` (primitive) or
+  `{colors.sys/bg/surface}` (semantic).
+- **`sys/*` and primitives are pruned from consumer autocomplete** (see
+  `scripts/prune-color-tokens.cjs`). They still resolve at runtime; they're just
+  hidden so consumers reach for the component layer (`color/*`, `background/*`,
+  `text/*`, `gradient/*`, …). App-shell tokens (`sys/ui/header/*`,
+  `sys/ui/sidenav/*`) are therefore intentionally hidden — they're for bitkit's
+  own header/sidenav components.
+
+## Runtime constraint: why some values can't match the source verbatim
+
+bitkit resolves token references to **CSS custom properties** at runtime
+(`var(--colors-purple-50)`). Two source spellings are therefore impossible to
+reproduce and are deliberately expressed differently — **same rendered color**:
+
+1. **A reference inside a composite value** (gradient, `color-mix`). Chakra
+   parses any `/` inside `{…}` as a `color-mix` opacity delimiter and **throws**.
+   So gradients **inline the dot-primitive** instead of referencing the semantic
+   token:
+   - source: `linear-gradient(90deg, rgba({color.purple.minimal}, 1) 0%, …)`
+   - bitkit: `linear-gradient(90deg, {colors.purple.95} 0%, …)`
+2. **Alpha via `rgba({ref}, a)`**. `rgba(var(--x), 0.5)` is invalid CSS, so
+   bitkit uses `color-mix(in srgb, {colors.x} 50%, transparent)` (and a literal
+   `rgba(255, 255, 255, 0)` for fully-transparent tokens).
+
+A drift report that only flags these representation differences means bitkit is
+**fully in sync**.
+
+## Out of scope (intentional)
+
+- **Dark theme** — the source ships a full `semantic/theme-dark` layer and a
+  `dark` primitive scale. bitkit does **not** implement dark mode yet, so these
+  are intentionally absent. _(Later task — revisit when dark mode is on the roadmap.)_
+- **brand** — the source's `brand/*` primitives (and `brand/primary`) are "not
+  in design" for bitkit and were intentionally dropped.
+
+## Notes on specific tokens
+
+- **`text/helper`** is the canonical helper-text color. bitkit previously also
+  had `input/text/helper` (a duplicate); it was removed in favour of
+  `text/helper`. Consumer repos may still reference `input/text/helper` — migrate
+  them on the next bump.
+- **`sys/interactive/*`** was removed (the source dropped it); the component
+  layer `interactive/*` is the replacement.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitrise/bitkit-v2",
   "private": false,
-  "version": "0.3.255-beta.1718",
+  "version": "0.3.255-beta.1719",
   "description": "Bitrise Design System Components built with Chakra UI V3",
   "keywords": [
     "react",
@@ -42,6 +42,7 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "theme:generate-types": "chakra typegen lib/theme/index.ts && node ./scripts/prune-color-tokens.cjs",
+    "theme:diff-tokens": "node ./scripts/diff-design-tokens.cjs",
     "theme:watch": "chakra typegen lib/theme/index.ts --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",