@billabex/ui-tokens 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Billabex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @billabex/ui-tokens
+
+[![npm](https://img.shields.io/npm/v/@billabex/ui-tokens?color=d4a853)](https://www.npmjs.com/package/@billabex/ui-tokens)
+
+Design tokens for the [Billabex](https://next.billabex.com) design system. Pure TypeScript, framework-agnostic, [Figma Token Studio](https://tokens.studio/) compatible.
+
+Part of the [Lingot](https://github.com/billabex/lingot) monorepo.
+
+## Install
+
+```bash
+pnpm add @billabex/ui-tokens
+```
+
+## Usage
+
+Tokens are rich TypeScript objects with built-in conversion methods — not plain strings:
+
+```ts
+import { bg, text, spacing, shadows } from '@billabex/ui-tokens'
+
+// Colors
+bg.default.hex            // '#ffffff'
+bg.default.rgb            // { r: 255, g: 255, b: 255 }
+bg.default.rgba(0.5)      // 'rgba(255, 255, 255, 0.5)'
+bg.default.hsl            // { h: 0, s: 0, l: 100 }
+`${bg.default}`           // '#ffffff' (toString)
+
+// Dimensions
+spacing.md.value          // 8
+spacing.md.px             // '8px'
+spacing.md.rem            // '0.5rem'
+
+// Shadows
+shadows.sm.css            // '0px 2px 8px 0px rgba(28, 28, 26, 0.08)'
+```
+
+## Token Architecture
+
+```
+Primitive → Semantic → Consumer
+```
+
+- **Primitive tokens** define the raw palette: `colors.neutral[700]`, `spacing.md`, `radii.lg`
+- **Semantic tokens** give purpose: `bg.default`, `text.primary`, `action.destructive`, `border.default`
+
+Semantic tokens reference primitives, so palette changes propagate everywhere automatically.
+
+## Units (px vs rem)
+
+Primitive dimension tokens are authored from **px** values (to match Figma handoff precisely), but each token exposes both:
+
+- `.px` for pixel-precise usage
+- `.rem` for scalable, accessibility-friendly usage
+
+Recommended usage:
+
+- Typography and layout spacing: prefer **`rem`**
+- Borders/hairlines and pixel-critical details: use **`px`**
+
+Example:
+
+```ts
+import { spacing, typography } from '@billabex/ui-tokens'
+
+// Preferred defaults in component CSS
+spacing.md.rem                    // '0.5rem'
+typography.body.fontSize.rem      // e.g. '0.875rem'
+
+// Pixel-precise cases
+spacing.md.px                     // '8px'
+```
+
+## Available Token Categories
+
+| Category | Primitives | Semantics |
+|----------|-----------|-----------|
+| Colors | `neutral`, `gold`, `terracotta`, `status` scales | `bg.*`, `text.*`, `action.*`, `status.*`, `border.*` |
+| Spacing | `xs` through `5xl` (4px–64px) | — |
+| Radii | `sm`, `md`, `lg`, `xl`, `full` | — |
+| Shadows | `sm`, `md`, `lg` | — |
+| Typography | `heading`, `body`, `label`, `caption` | — |
+
+## Figma Token Studio
+
+Tokens are exported to `tokens.json` in [W3C DTCG](https://design-tokens.github.io/community-group/format/) format. Semantic tokens use references (`{global.color.neutral.700}`) so changes to the primitive palette propagate automatically in Token Studio.
+
+## License
+
+[MIT](https://github.com/billabex/lingot/blob/main/LICENSE)

package/dist/index.js

@@ -7,12 +7,12 @@ function m(r) {
   };
 }
 function S(r, o, s) {
-  const l = r / 255, a = o / 255, c = s / 255, i = Math.max(l, a, c), u = Math.min(l, a, c), b = (i + u) / 2;
+  const c = r / 255, a = o / 255, l = s / 255, i = Math.max(c, a, l), u = Math.min(c, a, l), b = (i + u) / 2;
   if (i === u)
     return { h: 0, s: 0, l: Math.round(b * 100) };
   const f = i - u, p = b > 0.5 ? f / (2 - i - u) : f / (i + u);
   let g = 0;
-  return i === l ? g = ((a - c) / f + (a < c ? 6 : 0)) / 6 : i === a ? g = ((c - l) / f + 2) / 6 : g = ((l - a) / f + 4) / 6, {
+  return i === c ? g = ((a - l) / f + (a < l ? 6 : 0)) / 6 : i === a ? g = ((l - c) / f + 2) / 6 : g = ((c - a) / f + 4) / 6, {
     h: Math.round(g * 360),
     s: Math.round(p * 100),
     l: Math.round(b * 100)
@@ -23,16 +23,16 @@ function $(r) {
   return o.length === 8 ? parseInt(o.slice(6, 8), 16) / 255 : 1;
 }
 function n(r) {
-  const { r: o, g: s, b: l } = m(r), a = S(o, s, l);
+  const { r: o, g: s, b: c } = m(r), a = S(o, s, c);
   return Object.freeze({
     hex: r,
-    rgb: Object.freeze({ r: o, g: s, b: l }),
+    rgb: Object.freeze({ r: o, g: s, b: c }),
     hsl: Object.freeze(a),
-    rgba(c) {
-      return `rgba(${o}, ${s}, ${l}, ${c})`;
+    rgba(l) {
+      return `rgba(${o}, ${s}, ${c}, ${l})`;
     },
-    hsla(c) {
-      return `hsla(${a.h}, ${a.s}%, ${a.l}%, ${c})`;
+    hsla(l) {
+      return `hsla(${a.h}, ${a.s}%, ${a.l}%, ${l})`;
     },
     toString() {
       return r;
@@ -49,13 +49,13 @@ function e(r) {
     }
   });
 }
-function h(r, o, s, l, a) {
-  const c = $(a), i = `#${a.replace("#", "").slice(0, 6)}`, u = n(i), { r: b, g: f, b: p } = u.rgb, g = `${r}px ${o}px ${s}px ${l}px rgba(${b}, ${f}, ${p}, ${Number(c.toFixed(2))})`;
+function h(r, o, s, c, a) {
+  const l = $(a), i = `#${a.replace("#", "").slice(0, 6)}`, u = n(i), { r: b, g: f, b: p } = u.rgb, g = `${r}px ${o}px ${s}px ${c}px rgba(${b}, ${f}, ${p}, ${Number(l.toFixed(2))})`;
   return Object.freeze({
     offsetX: r,
     offsetY: o,
     blur: s,
-    spread: l,
+    spread: c,
     color: u,
     css: g,
     toString() {
@@ -88,6 +88,7 @@ const t = {
   },
   /** Terracotta / link color */
   terracotta: {
+    300: n("#eee3de"),
     400: n("#b5634b"),
     500: n("#9c5340")
   },
@@ -124,7 +125,9 @@ const t = {
   /** 32px */
   "3xl": e(32),
   /** 48px */
-  "4xl": e(48)
+  "4xl": e(48),
+  /** 64px */
+  "5xl": e(64)
 }, y = {
   card: e(16),
   page: e(24)
@@ -202,7 +205,7 @@ const t = {
   /** Brand-tinted background */
   brand: t.blue[50],
   /** Accent background (warm) */
-  accent: t.neutral[200]
+  accent: t.terracotta[300]
 }, M = {
   /** Primary text — headings, body */
   primary: t.neutral[700],

package/dist/tokens/primitive.d.ts

@@ -24,6 +24,7 @@ export declare const colors: {
     };
     /** Terracotta / link color */
     readonly terracotta: {
+        readonly 300: ColorToken;
         readonly 400: ColorToken;
         readonly 500: ColorToken;
     };
@@ -62,6 +63,8 @@ export declare const spacing: {
     readonly "3xl": DimensionToken;
     /** 48px */
     readonly "4xl": DimensionToken;
+    /** 64px */
+    readonly "5xl": DimensionToken;
 };
 export declare const padding: {
     readonly card: DimensionToken;

package/dist/tokens/primitive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitive.d.ts","sourceRoot":"","sources":["../../src/tokens/primitive.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAEd,WAAW,EAEZ,MAAM,aAAa,CAAC;AAOrB,eAAO,MAAM,MAAM;IACjB,kBAAkB;;;;;IAMlB,oDAAoD;;;;;;;;;;;IAYpD,0BAA0B;;;;;;IAO1B,8BAA8B;;;;;IAM9B,oBAAoB;;;;;;;;;;;;;;;;;CAoBsE,CAAC;AAM7F,eAAO,MAAM,OAAO;IAClB,UAAU;;IAEV,UAAU;;IAEV,UAAU;;IAEV,WAAW;;IAEX,WAAW;;IAEX,WAAW;;IAEX,WAAW;;IAEX,WAAW;;CAEsC,CAAC;AAMpD,eAAO,MAAM,OAAO;;;CAG+B,CAAC;AAMpD,eAAO,MAAM,KAAK;;;;;;;CAO8B,CAAC;AAMjD,eAAO,MAAM,OAAO;;;;CAI4B,CAAC;AAQjD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2C6B,CAAC"}
+{"version":3,"file":"primitive.d.ts","sourceRoot":"","sources":["../../src/tokens/primitive.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAEd,WAAW,EAEZ,MAAM,aAAa,CAAC;AAOrB,eAAO,MAAM,MAAM;IACjB,kBAAkB;;;;;IAMlB,oDAAoD;;;;;;;;;;;IAYpD,0BAA0B;;;;;;IAO1B,8BAA8B;;;;;;IAO9B,oBAAoB;;;;;;;;;;;;;;;;;CAoBsE,CAAC;AAM7F,eAAO,MAAM,OAAO;IAClB,UAAU;;IAEV,UAAU;;IAEV,UAAU;;IAEV,WAAW;;IAEX,WAAW;;IAEX,WAAW;;IAEX,WAAW;;IAEX,WAAW;;IAEX,WAAW;;CAEsC,CAAC;AAMpD,eAAO,MAAM,OAAO;;;CAG+B,CAAC;AAMpD,eAAO,MAAM,KAAK;;;;;;;CAO8B,CAAC;AAMjD,eAAO,MAAM,OAAO;;;;CAI4B,CAAC;AAQjD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2C6B,CAAC"}

package/dist/tokens/primitive.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=primitive.spec.d.ts.map

package/dist/tokens/primitive.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive.spec.d.ts","sourceRoot":"","sources":["../../src/tokens/primitive.spec.ts"],"names":[],"mappings":""}

package/dist/tokens/semantic.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=semantic.spec.d.ts.map

package/dist/tokens/semantic.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.spec.d.ts","sourceRoot":"","sources":["../../src/tokens/semantic.spec.ts"],"names":[],"mappings":""}

package/dist/utils.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=utils.spec.d.ts.map

package/dist/utils.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.spec.d.ts","sourceRoot":"","sources":["../src/utils.spec.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billabex/ui-tokens",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "Design tokens for the Billabex design system — framework-agnostic, Figma Token Studio compatible",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,15 +19,6 @@
     "dist",
     "tokens.json"
   ],
-  "scripts": {
-    "build": "vite build && tsc --emitDeclarationOnly",
-    "build:figma": "tsx scripts/build-figma.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist",
-    "lint": "tsc --noEmit",
-    "prepare": "pnpm build:figma"
-  },
   "devDependencies": {
     "tsx": "^4.19.0",
     "vite": "^6.0.0",
@@ -43,5 +34,13 @@
     "url": "https://github.com/billabex/lingot.git",
     "directory": "packages/ui-tokens"
   },
-  "sideEffects": false
-}
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "build:figma": "tsx scripts/build-figma.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit"
+  }
+}

package/dist/tokens.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=tokens.test.d.ts.map

package/dist/tokens.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tokens.test.d.ts","sourceRoot":"","sources":["../src/tokens.test.ts"],"names":[],"mappings":""}