@cueplusplus/tokens 0.13.0

package/dist/tokens.js

@@ -0,0 +1,240 @@
+/**
+ * @cueplusplus/tokens — the runtime half of the public contract.
+ * Generated by build.mjs. Do not edit by hand.
+ *
+ * The typed half is `tokens.d.ts`, beside this file and generated with it:
+ * `Density`, `Mode`, `ColorToken`, `GeometryToken`, `FontToken`, `FontName`,
+ * `FontDelivery` and `FontPairing` are declared there. This file is plain
+ * JavaScript because Node refuses to strip types under `node_modules`, so a
+ * `.ts` entry is one a registry consumer cannot load.
+ */
+
+/**
+ * There is no `THEMES`, and no `ThemeName`, in this package any more.
+ *
+ * A palette is a package: `ThemeName` is `@cueplusplus/theme-base`'s, and it is
+ * the keys of a registry interface every installed theme package augments —
+ * open by construction, where a tuple baked into this build could only ever
+ * name the ten that happened to live here. `@cueplusplus/ui` re-exports it.
+ */
+
+/** Every density level, in ladder order. */
+export const DENSITIES = ["ultra-compact", "compact", "normal", "large", "ultra-large"];
+
+/** Color-scheme modes. `system` tracks `prefers-color-scheme`. */
+export const MODES = ["dark", "light", "system"];
+
+/**
+ * The values the ThemeProvider falls back to on the two axes this package still
+ * owns. There is no `DEFAULT_THEME`: with no preset shipped here there is no
+ * default palette to name, and a page that registers nothing paints
+ * `@cueplusplus/theme-base`'s blank base rather than somebody's brand.
+ */
+export const DEFAULT_DENSITY = "compact";
+export const DEFAULT_MODE = "dark";
+
+/** The colour tokens every theme block declares, in emission order. */
+export const COLOR_CONTRACT = ["bg", "sunken", "surface-1", "surface-2", "surface-3", "fg", "fg-muted", "fg-subtle", "border", "border-strong", "border-overlay", "accent", "accent-hover", "accent-fg", "ok", "busy", "warn", "warn-fg", "danger", "danger-fg", "info", "stream", "selection", "focus", "data-ground", "scrim"];
+
+/** The geometry tokens every density block declares, in emission order. */
+export const GEOMETRY_CONTRACT = ["control-sm", "control-md", "control-lg", "chip-h", "icon-sm", "icon-md", "text-micro", "text-label", "text-ui", "text-body", "text-emphasis", "text-title", "radius-control", "radius-surface", "radius-overlay", "pad-row-y", "pad-row-x", "space-1", "space-2", "space-3", "space-4", "space-5", "space-6", "space-7", "space-8", "chrome-toolbar", "chrome-statusbar", "chrome-titlebar", "density", "radius-scale"];
+
+/** The three type stacks a pairing may name. */
+export const FONT_TOKENS = ["font-sans", "font-mono", "font-display"];
+
+/**
+ * The page-composition tokens `:root` declares, in emission order.
+ *
+ * The `:root` slice, which is wider than a set's: `leading-ui` and the three
+ * page widths are here and belong to no set (a set that moved either would
+ * restyle every settings page and form in the library while claiming to compose
+ * a page), and `style-display` is the other way round — a set may declare it and
+ * `:root` must not, so a page under no set renders a hero's own literal through
+ * the `var()` fallback.
+ */
+export const STYLE_CONTRACT = ["leading-prose", "leading-ui", "measure-narrow", "measure-wide", "measure-broad", "measure-prose", "band-y", "band-rule", "band-ground"];
+
+/** The page-composition tokens every `[data-style]` block declares. */
+export const STYLE_SET_CONTRACT = ["measure-prose", "leading-prose", "band-y", "band-rule", "band-ground"];
+
+/**
+ * Style sets, in menu order — the fourth composable axis.
+ *
+ * `console` restates the `:root` defaults exactly (the build refuses it if one
+ * value differs), so switching to it changes nothing; it exists because a picker
+ * needs a row to point at and a subtree inside an `editorial` page needs a block
+ * to reset to.
+ */
+export const STYLE_SETS = ["console", "editorial", "marketing"];
+
+/**
+ * The set that costs nothing.
+ *
+ * NOT what a `<ThemeProvider>` opens on: the provider stamps no `data-style` at
+ * all, because a style set is opt-in page composition. This is the set a subtree
+ * stamps to declare itself ordinary inside a page that is not.
+ */
+export const DEFAULT_STYLE_SET = "console";
+
+/*
+ * `THEME_SUPPORTS_LIGHT` is gone with the presets: whether a theme ships a light
+ * block is now `supportsLight` on its own `manifest.json`, which is the only
+ * place that can answer it for a theme this build never saw.
+ */
+
+/** Every font pairing, in menu order. `system` is the default and costs nothing. */
+export const FONTS = ["system", "geist", "inter", "plex", "roboto", "source", "apple", "office"];
+
+/**
+ * The pairing an app that never touched the axis renders at.
+ *
+ * It declares no `--cue-font-mono`, so a preset's own monospace survives it.
+ * Every other pairing was chosen by a person and outranks the preset on both
+ * families — see the `[data-font]` blocks at the end of `theme.css`.
+ */
+export const DEFAULT_FONT = "system";
+
+/**
+ * How a pairing reaches a reader's screen.
+ *
+ * - `none` — the platform's own faces. Nothing to download, resolves everywhere.
+ * - `webfont` — freely redistributable; the app self-hosts it and assigns the
+ *   `faces` properties. Undelivered, the stack still resolves: a local install
+ *   first, then the platform.
+ * - `system` — licensed such that it CANNOT be served (SF Pro, Calibri). It
+ *   lights up where installed and falls through cleanly where it is not, and no
+ *   app may bundle it.
+ *
+ * @typedef {"none" | "webfont" | "system"} FontDelivery
+ */
+
+/**
+ * One pairing, for a picker row, a docs table and a delivery wiring.
+ *
+ * @typedef {object} FontPairing
+ * @property {string} label Menu label.
+ * @property {string} sans The sans family this pairing names.
+ * @property {string | null} mono The mono family, or `null` for the default pairing, which leaves the theme's.
+ * @property {FontDelivery} delivery How it reaches a screen.
+ * @property {readonly string[]} faces Custom properties an app assigns to deliver it. Empty unless `delivery` is `"webfont"`.
+ * @property {string} note The licensing and fallback facts, in one sentence a docs page can print.
+ */
+
+/**
+ * Every pairing's families, delivery and licensing note, keyed by id.
+ *
+ * @type {Record<FontName, FontPairing>}
+ */
+export const FONT_PAIRINGS = {
+  "system": {
+    "label": "System",
+    "sans": "Platform UI sans",
+    "mono": null,
+    "delivery": "none",
+    "faces": [],
+    "note": "SF Pro on Apple platforms, Segoe UI on Windows, Roboto on Android, whatever the desktop is set to on Linux. Zero bytes, and it resolves everywhere. Monospace is left to the theme: a preset that names one keeps it."
+  },
+  "geist": {
+    "label": "Geist",
+    "sans": "Geist",
+    "mono": "JetBrains Mono",
+    "delivery": "webfont",
+    "faces": [
+      "--cue-face-geist",
+      "--cue-face-jetbrains-mono"
+    ],
+    "note": "Vercel's Geist (SIL OFL 1.1) with JetBrains Mono (SIL OFL 1.1). Both are freely redistributable, so an app may self-host them."
+  },
+  "inter": {
+    "label": "Inter",
+    "sans": "Inter",
+    "mono": "IBM Plex Mono",
+    "delivery": "webfont",
+    "faces": [
+      "--cue-face-inter",
+      "--cue-face-ibm-plex-mono"
+    ],
+    "note": "Inter (SIL OFL 1.1) with IBM Plex Mono (SIL OFL 1.1). Both are freely redistributable, so an app may self-host them."
+  },
+  "plex": {
+    "label": "Plex",
+    "sans": "IBM Plex Sans",
+    "mono": "IBM Plex Mono",
+    "delivery": "webfont",
+    "faces": [
+      "--cue-face-ibm-plex-sans",
+      "--cue-face-ibm-plex-mono"
+    ],
+    "note": "IBM Plex Sans and IBM Plex Mono (both SIL OFL 1.1). Freely redistributable, so an app may self-host them."
+  },
+  "roboto": {
+    "label": "Roboto",
+    "sans": "Roboto",
+    "mono": "Roboto Mono",
+    "delivery": "webfont",
+    "faces": [
+      "--cue-face-roboto",
+      "--cue-face-roboto-mono"
+    ],
+    "note": "Roboto and Roboto Mono (both Apache 2.0). Freely redistributable, so an app may self-host them."
+  },
+  "source": {
+    "label": "Source",
+    "sans": "Source Sans 3",
+    "mono": "Source Code Pro",
+    "delivery": "webfont",
+    "faces": [
+      "--cue-face-source-sans-3",
+      "--cue-face-source-code-pro"
+    ],
+    "note": "Source Sans 3 and Source Code Pro (both SIL OFL 1.1). Freely redistributable, so an app may self-host them. \"Source Sans Pro\" is the family's former name and stays in the stack for machines that have the old install."
+  },
+  "apple": {
+    "label": "Apple",
+    "sans": "SF Pro Text",
+    "mono": "SF Mono",
+    "delivery": "system",
+    "faces": [],
+    "note": "SF Pro and SF Mono are Apple-licensed. Their licence permits use on Apple platforms and does NOT permit redistribution as a webfont, so this pairing is a stack and nothing else: it lights up on macOS and iOS and falls through to the platform sans anywhere else."
+  },
+  "office": {
+    "label": "Office",
+    "sans": "Calibri",
+    "mono": "Cascadia Mono",
+    "delivery": "system",
+    "faces": [],
+    "note": "Calibri is Microsoft-licensed and cannot be served as a webfont; Carlito is its metric-compatible libre twin (SIL OFL 1.1) and is what most Linux machines resolve this to. Cascadia Mono is MIT-licensed and Consolas is not, so the stack names both and serves neither."
+  }
+};
+
+/**
+ * Every face an app must self-host to deliver the webfont pairings, as
+ * `custom property -> family name`. Assign each one the family your bundler
+ * generated; `next/font` hashes family names, so the literal never matches.
+ *
+ * @type {Record<string, string>}
+ */
+export const FONT_FACES = {
+  "--cue-face-geist": "Geist",
+  "--cue-face-jetbrains-mono": "JetBrains Mono",
+  "--cue-face-inter": "Inter",
+  "--cue-face-ibm-plex-mono": "IBM Plex Mono",
+  "--cue-face-ibm-plex-sans": "IBM Plex Sans",
+  "--cue-face-roboto": "Roboto",
+  "--cue-face-roboto-mono": "Roboto Mono",
+  "--cue-face-source-sans-3": "Source Sans 3",
+  "--cue-face-source-code-pro": "Source Code Pro"
+};
+
+/**
+ * The custom property that delivers one face.
+ * @example faceProperty("IBM Plex Mono") // "--cue-face-ibm-plex-mono"
+ */
+export const faceProperty = (family) =>
+  `--cue-face-${family.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")}`;
+
+/**
+ * Reference a semantic token as a CSS value.
+ * @example token("accent") // "var(--cue-accent)"
+ */
+export const token = (name) => `var(--cue-${name})`;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cueplusplus/tokens",
+  "version": "0.13.0",
+  "description": "DTCG design tokens for the CUE++ design system: 5 density levels and 8 font pairings, compiled to attribute-scoped CSS custom properties. Colour lives in a theme package.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cueplusplus/cue-ui",
+    "directory": "packages/tokens"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/tokens.d.ts",
+      "default": "./dist/tokens.js"
+    },
+    "./theme.css": "./dist/theme.css",
+    "./tailwind.css": "./dist/tailwind.css",
+    "./axes.css": "./dist/axes.css",
+    "./base.json": "./dist/base.json",
+    "./primitives.tokens.json": "./dist/primitives.tokens.json",
+    "./registry/token-layer.json": "./dist/registry/token-layer.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "eslint": "^9.17.0",
+    "publint": "^0.3.23",
+    "style-dictionary": "^5.5.1",
+    "@repo/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "check:publish": "publint",
+    "lint": "eslint . --max-warnings 0",
+    "test": "node --test \"test/*.test.mjs\""
+  }
+}