@beehexa/design-tokens 0.0.0-stage → 2611.3.2

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @beehexa/design-tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Source-checkout development package (`0.0.0`, `private: true`), not a registry release number. Managers must authorize a release before the GitHub runner stamps the real version. CI stages checked tarballs; npm maintainer approval with 2FA is required before publication.
+
+## Use the installed package
+
+Build in the beehexa.design source checkout with `npm ci && npm run build:packages`. Until release approval, consumers install a local reference to `packages/design-tokens` (for example Yarn `portal:../beehexa.design/packages/design-tokens`). Do not copy generated CSS/JavaScript into a product, use a Vite source alias, or fetch rendered website HTML.
+
+Local references are **local-development only**. Consumer CI requires actual released npm versions and must never check out sibling repositories or build from sibling paths. Producer CI stays single-repository. Do not release, deploy, or execute CI as a prerequisite for local work; an unavailable approved npm release is not permission to add a cross-repository CI fallback.
+
+```js
+import '@beehexa/design-tokens/css';
+import { tokens, tokenInfo } from '@beehexa/design-tokens';
+
+const text = tokens.light['color.text'];
+const darkText = tokens.dark['color.text'] ?? text;
+const description = tokenInfo['color.text'].description;
+```
+
+```ts
+import type { TokenName } from '@beehexa/design-tokens';
+const spacing: TokenName = 'space.200';
+```
+
+- `tokens.light` contains every token with references recursively resolved.
+- `tokens.dark` and `tokens.vi` contain only values differing from light, including indirect changes through aliases. Vietnamese deltas are resolved against the Vietnamese graph, not just the base targets. These are independent mode deltas; there is no exported combined dark+Vietnamese object. Do not assume arbitrary delta merging models overlapping future mode overrides; use the CSS cascade for combined presentation.
+- `tokenInfo` is keyed by the same token names. It contains `name`, `path`, `type`, `description`, raw alias-bearing `value`, optional source `dark`/`vi` extensions, `cssVar`, and fully resolved `resolved`/`darkResolved`/`viResolved`. These descriptions explain individual decisions; they are not a replacement for the complete usage rules in `@beehexa/design-rules`.
+- Generated declarations preserve literal token keys and values. `TokenName` is `keyof typeof tokens.light`; a misspelled key is not widened into `Record<string, string>`.
+- `@beehexa/design-tokens/css` retains native `rem`. It defines `--bh-*` on `:root`, honors explicit `data-theme="light"`/`"dark"`, uses system dark preference only without an explicit light selection, and applies Vietnamese typography via `:lang(vi)` with resets on other explicit languages. It does not set the application's root font size.
+- `@beehexa/design-tokens/css/pixels` uses the identical generator and selectors, converting every `rem` literal to pixels at **16 px per rem**, including compound values. Import this instead of, not alongside, native CSS when integrating the dashboard's current 14px root. This compatibility choice is migration debt, not a 14px design-scale exemption or permission to change token values.
+- `@beehexa/design-tokens/dtcg/color.json` (and every other original `tokens/*.json`) exposes the unchanged source data.
+- `@beehexa/design-tokens/package.json` exposes installed origin/version metadata.
+
+## Source authority and limits
+
+`beehexa.design/tokens/*.json` is the only token source. `scripts/token-utils.mjs` owns flattening, CSS naming, mode-aware graph resolution, and CSS generation; the website and package builders share it. Builds reject duplicate token/CSS names, unknown references, and cycles in light, dark, Vietnamese, and combined dark+Vietnamese graphs. The generated outputs are not another editable source.
+
+Usage choices remain governed by the complete installed rule documents, including accessibility, interaction state, layout, responsive and locale rules. Use semantic role tokens rather than palette primitives where the source defines a role. There are no product/dashboard exemptions. Planned or missing source guidance must be reported upstream instead of invented downstream. The source design system is still a working proposal; the existence of a token or metadata description does not imply its component guidance is complete or GA.
+
+## Producer commands
+
+From the source root: `npm run build:packages`, `npm run check:packages`, `npm run pack:packages`. Workspace `npm run build -w @beehexa/design-tokens` builds just this package; `prepack` also builds real artifacts before packing. Package checks need only this producer repository, never a dashboard checkout. Distribution includes ESM, declarations, both CSS variants, unchanged DTCG files and this README.

package/dist/dtcg/border.json

@@ -0,0 +1,26 @@
+{
+  "border": {
+    "width": {
+      "default": {
+        "$type": "dimension",
+        "$value": "1px",
+        "$description": "1 px. Inputs, secondary buttons, cards, tables and dividers."
+      },
+      "selected": {
+        "$type": "dimension",
+        "$value": "2px",
+        "$description": "2 px. The bar under a selected tab or beside a selected side navigation item, and the edge of a selected card. Pair with color.border.selected."
+      },
+      "focused": {
+        "$type": "dimension",
+        "$value": "2px",
+        "$description": "2 px. The focus ring. Pair with color.border.focus and state.focus.offset."
+      },
+      "accent": {
+        "$type": "dimension",
+        "$value": "4px",
+        "$description": "4 px. A status or emphasis bar on one edge: alerts, banners, rows with an error, callouts and quotes. Pair with a status or brand border colour."
+      }
+    }
+  }
+}

package/dist/dtcg/breakpoints.json

@@ -0,0 +1,8 @@
+{
+  "breakpoint": {
+    "xs": { "$type": "dimension", "$value": "0px", "$description": "Phones and small windows, below 768 px. One fluid layout: 4 columns, gutter and margin 16 px, side navigation in a drawer. Must work down to 320 px." },
+    "md": { "$type": "dimension", "$value": "768px", "$description": "Tablets and narrow windows. 8 columns, gutter and margin 24 px. Side navigation still in a drawer." },
+    "lg": { "$type": "dimension", "$value": "1024px", "$description": "Laptops from 1024 px, including 1280 and 1366 px screens. 12 columns. Side navigation open at 280 px; people can collapse it to the 64 px rail." },
+    "xl": { "$type": "dimension", "$value": "1440px", "$description": "Desktops, including 1536 and 1920 px screens. Page margin 32 px." }
+  }
+}