@beehexa/design-tokens

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 and publishes checked tarballs through npm Trusted Publishing/OIDC.

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.

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;

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>.
• tokenPixels(name, locale = 'en', rootFontSize = 16) converts a source numeric scalar or px/rem dimension. The default preserves nominal16px/rem geometry; an explicit observed root scales only rem dimensions. Native Avatar/Image props replacing scalable CSS must pass that root, obtained from useAntDesignVueRootFontSize() in the AntD adapter (children reuse their provider's one measurement). Vietnamese prefixes select resolved alternatives. Zero remains zero; colors, composite fonts and nonnumeric roles throw. Never copy conversion logic or force the root to match a numeric API. Fixed canvas coordinates may deliberately keep the nominal default.
• @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 at 16 px per rem, including compound values. This optional compatibility entrypoint is not dashboard integration: use native /css, preserve the reader's root setting and put font.body.default on the body. Never import both variants.
• All CSS subpaths include package-owned side-effect declarations, so strict TypeScript consumers with noUncheckedSideEffectImports need no ambient module shims. The runtime exports still resolve to the actual CSS files.
• Source font.features is "cv05", "cv08". Generated CSS applies it universally with !important, preserving these features across semantic font shorthand resets. Add local opt-in features through --bh-font-features, not a competing feature property.
• @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.

Application scrollbars

Import @beehexa/design-tokens/css/scrollbars once after the token CSS to opt the application into one native-DOM scrollbar appearance family, including Ant Table bodies, Tree/list holders, drawers, portals and native measurement probes. bh-scroll-region identifies application-created scroll ownership; it is not an appearance exemption for unmarked framework holders. The authored src/styles/scrollbars.css ships unchanged as dist/scrollbars.css. It never supplies overflow, height, forced gutters, fake scrollbars, scroll animation or overscroll containment. Application layout supplies overflow: auto only where needed and keeps one continuous owner per logical pane. Never hide bars or retain competing local recipes.

The scrollbar.* roles model Ant Design Vue 4 Table's real scrollbar token factory: nominal8px (width → space.100, native0.5rem), colorTextPlaceholder (thumb → color.text.subtlest), colorTextHeading (thumbHover → color.text), and colorSplit (track → color.border). thumbActive shares hover as Ant's sticky scrollbar does; corner shares track and radius uses radius.full. The same values serve both axes and inherit light/dark semantic alias resolution; Vietnamese needs no separate scrollbar override. Preserve opaque foreground/thumb contrast against the track, not a local translucent approximation.

Native framework scroll ownership is preserved, not exempt from appearance. The shared module styles actual native-DOM scrollbar pseudo-elements on both axes, including native Table body tracks/corners and Tree holders; no wrapper marking or private-node manipulation is needed. Remove the old direct-child scrollbar-color:auto exemption. Offscreen native scrollbar measurement probes consume the same width as Table bodies, preserving header/body alignment. Virtual bars do not have browser scrollbar pseudo-elements: the AntD4 source adapter maps its virtual-list inline appearance gaps without changing thumb position/height, visibility or drag handlers. Monaco consumes scrollbar.* through public theme/options and the observed reader root; only its missing track/radius paint inputs use the source adapter stylesheet.

WebKit-pseudo-element engines use the token width/height and actual thumb hover/active; standards-only engines use native thin geometry and host hover/active colors because their API has no thumb-state pseudo-elements. Platform overlay visibility/geometry remains native, and forced-colors mode retains native system scrollbar paint and geometry. Keyboard, wheel and touch scrolling remain natural. Full ownership, accessibility and fallback guidance is the Scrollbar component (source src/content/components/scrollbar/).

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 token CSS variants, the opt-in scrollbar stylesheet, unchanged DTCG files and this README. The packed-payload checker requires the typed scrollbar entry, checks its bytes against the authored source and exercises strict side-effect import resolution from the extracted tarball.