@bitbaum/design-tokens 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @bitbaum/design-tokens
 
-The design **single source of truth** for OrangeCat, FleetCrown and Solon.
+The design **single source of truth** for OrangeCat, Loki and Solon.
 
 One file — [`tokens.css`](./tokens.css) — defines every colour, typeface, weight,
 tracking, radius and shared primitive the three products use. They import it.
@@ -15,9 +15,13 @@ three different companies. Copies drift; imports cannot.
 
 ## Retheming the entire stack
 
-1. Edit the block marked `▼▼▼ THE KNOBS ▼▼▼` in `tokens.css`. Nothing else.
-2. Tag a release: `git tag v1.2.0 && git push --tags`
-3. Bump `@bitbaum/design-tokens` in the three apps. Their CI auto-merges.
+1. Edit the block marked `▼▼▼ THE KNOBS ▼▼▼` in `tokens.css` for a retheme, or update the optional `composition.css` contract for interface improvements.
+2. Bump `package.json`'s version **and** set the matching explicit `.github/release-request.txt`; submit a PR and pass package CI.
+3. A successful **main-branch push CI** triggers `tag-approved-release.yml`. It tags only the exact latest verified SHA and never rewrites an existing version tag.
+4. The tag workflow explicitly dispatches `publish.yml`; npm publishing is still guarded by `NPM_PUBLISHING` and requires trusted-publishing bootstrap. If that variable is off, a Git tag exists but **no npm release** is claimed.
+5. Upgrade consumers to the confirmed Git tag, published npm version, or an exact source-commit SHA; run their frozen-lockfile CI.
+
+The one-time release request does not automatically approve future version bumps: a request must match the manifest version.
 
 Changing the display typeface is **one line**:
 
@@ -51,6 +55,68 @@ module.exports = {
 Tailwind v4 apps consume `tokens.css` through `@theme`; the variable names are
 identical, so both paths stay in sync.
 
+## Optional cross-product composition grammar
+
+The **brand tokens** above intentionally belong to OrangeCat/Loki/Solon.
+Their shared palette should never be imposed on unrelated products or
+customer websites.
+
+For spacing, control sizing, visual rhythm and interaction *decisions*,
+`composition.css` is an opt-in, namespaced layer. It defines no fonts, brand
+colours, body style or global reset.
+
+```tsx
+// App Router — load AFTER the app's CSS reset and BEFORE product CSS modules.
+// The shared classes intentionally use :where() specificity, so importing
+// them before a later universal '*' padding reset would erase their padding.
+import './globals.css';
+import '@bitbaum/design-tokens/composition.css';
+```
+
+```tsx
+<main className="bb-frame">
+  <div className="bb-stack" style={{ '--bb-stack-gap': '1.5rem' }}>
+    <div className="bb-measure">A product-specific headline and description</div>
+    <div className="bb-actions">
+      <a className="bb-button bb-button--primary" href="/start">Get started</a>
+      <a className="bb-button bb-button--secondary" href="/method">Read the method</a>
+    </div>
+  </div>
+</main>
+```
+
+Map only the small seam of **semantic** CSS roles once in each app:
+
+```css
+:root {
+  --bb-action-bg: var(--color-action);
+  --bb-action-fg: var(--color-on-action);
+  --bb-control-bg: var(--color-surface);
+  --bb-control-fg: var(--color-text);
+  --bb-line: var(--color-border);
+  --bb-muted: var(--color-text-muted);
+  --bb-focus: var(--color-focus);
+}
+```
+
+The exported grammar includes `bb-frame`, `bb-measure`, `bb-section`,
+`bb-stack`, `bb-cluster`, `bb-grid`, `bb-actions`,
+`bb-choice-row`, `bb-list`, `bb-keyline`, `bb-tabular`,
+`bb-control`, `bb-button`, and `bb-skip`.
+
+It guarantees 44px controls, visible focus, responsive equal-cell choices,
+and reduced-motion support. Apps own typography, colours, spacing adjustments,
+components and their content. Do **not** render all information as cards: the
+grammar deliberately offers whitespace and hairline lists.
+
+**Release contract:** the new composition subpath first appears in
+source version `1.2.0`; `v1.1.0` does **not** include it. The verified
+tagging pipeline only tags a version explicitly requested in
+`.github/release-request.txt` after main CI is green. Verify the
+`v1.2.0` Git ref and the registry separately before claiming either is
+published. Until then, use a verified exact commit SHA. Existing
+`tokens.css` consumers do not change appearance by opting out.
+
 ## The contract
 
 Components declare **intent**, never mechanics.
@@ -88,3 +154,20 @@ grotesque convention, where the winner is whoever has the largest design budget.
 A high-contrast serif exits that comparison: it reads institutional rather than
 startup, which is exactly right for a stack whose product is *legitimacy* —
 signed votes, verifiable treasuries, an append-only audit trail.
+
+---
+
+Part of **[bitbaum](https://bitbaum.orangecat.ch)** — AI-native products on open
+infrastructure, built in Zürich. Every package here lists the apps that use it:
+**[which apps use design-tokens](https://bitbaum.orangecat.ch/packages/#design-tokens)**.
+
+## Data maps
+
+`--map-scale-1` … `--map-scale-7` are the one sequential scale for every
+choropleth (viridis, dark to light; hex, so an SVG `fill` takes them as is).
+Luminance rises at every step, so the scale survives colour-vision deficiency
+and greyscale; `test/contrast.test.js` keeps it that way. `--map-no-data` and
+`--map-boundary` follow the theme. An area more than one authority claims is
+**hatched**, never given a colour of its own: lines of `--map-hatch-width`
+every `--map-hatch-gap` at `--map-hatch-angle`, in the text colour. Colour is
+never the only carrier: every map has a list and a legend.

package/composition.css

@@ -0,0 +1,196 @@
+/**
+ * @bitbaum/design-tokens/composition.css
+ *
+ * Opt-in cross-product layout and interaction decisions, not a brand skin.
+ * No :root, html, body, element selectors or color values are set.
+ * Every rule is namespaced; apps provide semantic values through --bb-*.
+ *
+ * A site remains responsible for its own palette, fonts and personality.
+ * This layer owns only spatial rhythm, consistent controls, accessible
+ * interactions and density that behaves at 390px.
+ */
+
+:where(.bb-frame) {
+  width: min(100%, var(--bb-frame-max, 72rem));
+  margin-inline: auto;
+  padding-inline: var(--bb-gutter, clamp(1rem, 4vw, 3rem));
+}
+
+:where(.bb-measure) {
+  max-width: var(--bb-measure, 68ch);
+}
+
+:where(.bb-stack) {
+  display: grid;
+  gap: var(--bb-stack-gap, 1rem);
+  min-width: 0;
+}
+
+:where(.bb-cluster) {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--bb-cluster-gap, 0.75rem);
+}
+
+:where(.bb-grid) {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--bb-grid-min, 16rem)), 1fr));
+  gap: var(--bb-grid-gap, 1.5rem);
+}
+
+:where(.bb-section) {
+  padding-block: var(--bb-section-space, clamp(3.5rem, 7vw, 7rem));
+}
+
+:where(.bb-keyline) {
+  border-block-start: 1px solid var(--bb-line, var(--color-border, currentColor));
+}
+
+:where(.bb-tabular) {
+  font-variant-numeric: tabular-nums;
+}
+
+:where(.bb-control) {
+  display: block;
+  inline-size: 100%;
+  min-block-size: 44px;
+  border: 1px solid var(--bb-line, var(--color-border, currentColor));
+  border-radius: var(--bb-radius-control, 0.5rem);
+  padding: 0.75rem 0.9rem;
+  background: var(--bb-control-bg, Canvas);
+  color: var(--bb-control-fg, CanvasText);
+  font: inherit;
+  font-size: 1rem;
+  line-height: 1.4;
+}
+
+:where(.bb-control)::placeholder {
+  color: var(--bb-muted, GrayText);
+  opacity: 1;
+}
+
+:where(.bb-control:focus-visible, .bb-button:focus-visible, .bb-skip:focus-visible) {
+  outline: 3px solid var(--bb-focus, var(--bb-action-bg, Highlight));
+  outline-offset: 3px;
+}
+
+/* A textarea needs room to write, but not a fixed desktop-height on a phone. */
+:where(textarea.bb-control) {
+  resize: vertical;
+  min-block-size: 10rem;
+}
+
+:where(.bb-button) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  min-block-size: 44px;
+  padding: 0.75rem 1.2rem;
+  border: 1px solid transparent;
+  border-radius: var(--bb-radius-control, 0.5rem);
+  font: inherit;
+  font-size: 0.95rem;
+  font-weight: 700;
+  line-height: 1.2;
+  text-align: center;
+  text-decoration: none;
+  cursor: pointer;
+  white-space: normal;
+}
+
+:where(.bb-button--primary) {
+  color: var(--bb-action-fg, Canvas);
+  background: var(--bb-action-bg, CanvasText);
+}
+
+:where(.bb-button--secondary) {
+  color: var(--bb-action-bg, CanvasText);
+  background: var(--bb-control-bg, Canvas);
+  border-color: var(--bb-line, var(--color-border, currentColor));
+}
+
+:where(.bb-button:disabled, .bb-button[aria-disabled='true']) {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+/* Choose once, keep the choices in one row. Equal cells, never a 4+1 wrap. */
+:where(.bb-choice-row) {
+  display: grid;
+  grid-template-columns: repeat(var(--bb-choices, 2), minmax(0, 1fr));
+  gap: 0;
+  overflow: hidden;
+  border: 1px solid var(--bb-line, var(--color-border, currentColor));
+  border-radius: var(--bb-radius-control, 0.5rem);
+}
+
+:where(.bb-choice-row > *) {
+  min-width: 0;
+  min-height: 44px;
+}
+
+:where(.bb-choice-row > * + *) {
+  border-inline-start: 1px solid var(--bb-line, var(--color-border, currentColor));
+}
+
+/* Same shape and predictable vertical rhythm for sibling rows. */
+:where(.bb-list) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+:where(.bb-list > * + *) {
+  border-block-start: 1px solid var(--bb-line, var(--color-border, currentColor));
+}
+
+:where(.bb-list > *) {
+  padding-block: var(--bb-list-row-y, 1rem);
+  min-width: 0;
+}
+
+:where(.bb-skip) {
+  position: absolute;
+  inset-inline-start: var(--bb-gutter, 1rem);
+  inset-block-start: -8rem;
+  z-index: 100;
+  padding: 0.8rem 1rem;
+  background: var(--bb-control-bg, Canvas);
+  color: var(--bb-control-fg, CanvasText);
+  border: 2px solid var(--bb-focus, Highlight);
+  border-radius: var(--bb-radius-control, 0.5rem);
+}
+
+:where(.bb-skip:focus) {
+  inset-block-start: 1rem;
+}
+
+@media (max-width: 640px) {
+  :where(.bb-actions) {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 0.75rem;
+  }
+
+  :where(.bb-actions > .bb-button) {
+    inline-size: 100%;
+  }
+}
+
+@media (min-width: 641px) {
+  :where(.bb-actions) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+    align-items: center;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where(.bb-button, .bb-control) {
+    transition: none;
+    animation: none;
+  }
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@bitbaum/design-tokens",
-  "version": "1.1.0",
+  "version": "1.2.0",
+  "packageManager": "pnpm@11.25.0",
   "engines": {
     "node": ">=20"
   },
@@ -8,7 +9,7 @@
     "access": "public",
     "provenance": true
   },
-  "description": "Design SSOT for OrangeCat, FleetCrown and Solon — tokens, self-hosted faces, and the Tailwind preset that maps them.",
+  "description": "Design SSOT for OrangeCat, Loki and Solon — tokens, self-hosted faces, and the Tailwind preset that maps them.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,25 +17,19 @@
   },
   "files": [
     "tokens.css",
+    "composition.css",
     "tailwind-preset.js",
     "fonts"
   ],
   "exports": {
     "./tokens.css": "./tokens.css",
+    "./composition.css": "./composition.css",
     "./tailwind-preset": "./tailwind-preset.js",
     "./fonts/*": "./fonts/*"
   },
   "sideEffects": [
     "*.css"
   ],
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^26.4.0",
-    "eslint": "^10.9.1",
-    "globals": "^17.12.0",
-    "prettier": "3.9.6",
-    "typescript": "^6.0.3"
-  },
   "scripts": {
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
@@ -42,5 +37,13 @@
     "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm test",
     "format": "prettier --write .",
     "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "prettier": "3.9.10",
+    "typescript": "^6.0.3"
   }
-}
+}

package/tailwind-preset.js

@@ -11,7 +11,7 @@
  *     content: [...],
  *   }
  *
- * Tailwind v4 apps (FleetCrown) consume tokens.css directly via @theme instead;
+ * Tailwind v4 apps (Loki) consume tokens.css directly via @theme instead;
  * the variable names are identical, so the two paths stay in sync.
  */
 

package/tokens.css

@@ -1,5 +1,5 @@
 /**
- * @bitbaum/design-tokens — the design SSOT for OrangeCat, FleetCrown and Solon.
+ * @bitbaum/design-tokens — the design SSOT for OrangeCat, Loki and Solon.
  *
  * ┌──────────────────────────────────────────────────────────────────────────┐
  * │  TO RETHEME THE ENTIRE STACK, EDIT THE "KNOBS" BLOCK BELOW AND NOTHING   │
@@ -131,7 +131,7 @@
    *
    * White on #ff5c00 is 3.10:1 — below the 4.5 AA floor — so every primary
    * CTA in the fleet was failing at once: Solon's "Open the Dashboard",
-   * OrangeCat's "Get Started", FleetCrown's "Launch agent". Measured, not
+   * OrangeCat's "Get Started", Loki's "Launch agent". Measured, not
    * guessed. Near-black on the same orange is 6.10:1.
    *
    * The orange is deliberately NOT darkened to rescue white text: it would
@@ -155,7 +155,7 @@
   /* ── LIGHT THEME ────────────────────────────────────────────────────────
      :root is light and `.dark` overrides it — the same mechanism OrangeCat
      uses, so an app can toggle themes without translating anything. An app
-     that is dark-only (Solon, FleetCrown's public surface) pins it by putting
+     that is dark-only (Solon, Loki's public surface) pins it by putting
      `class="dark"` on <html> and never removing it. */
 
   /* Surfaces — page < base < raised < overlay < modal < drawer */
@@ -242,6 +242,32 @@
   /* Bitcoin's own orange. Not a brand colour — it means "this is Bitcoin", so
      it is deliberately NOT --public-accent and must not be used for actions. */
   --bitcoin-orange: #f7931a;
+
+  /**
+   * — Data maps ——————————————————————————————————————————————————————————
+   * One sequential scale for every choropleth (Solon's Places map first):
+   * viridis, dark to light, so it survives every colour-vision deficiency and
+   * reads in greyscale — its luminance rises at every step (pinned in
+   * test/contrast.test.js). Colour is never the only carrier: each map has a
+   * list with the same numbers, and a legend.
+   *
+   * Hatching marks an area more than one authority claims. A map takes no
+   * side, so a contested area gets the pattern, never a colour of its own:
+   * lines of --map-hatch-width every --map-hatch-gap at --map-hatch-angle, in
+   * the text colour, over whatever the scale says.
+   */
+  --map-scale-1: #46327e;
+  --map-scale-2: #365c8d;
+  --map-scale-3: #277f8e;
+  --map-scale-4: #1fa187;
+  --map-scale-5: #4ac16d;
+  --map-scale-6: #a0da39;
+  --map-scale-7: #fde725;
+  --map-no-data: 0 0% 85%;
+  --map-boundary: 0 0% 45%;
+  --map-hatch-angle: 45deg;
+  --map-hatch-gap: 6px;
+  --map-hatch-width: 1.5px;
 }
 
 /* ══════════════════════════════════════════════════════════════════════════
@@ -273,6 +299,10 @@
   --border-subtle: 0 0% 13%;
   --border-default: 0 0% 20%;
   --border-strong: 0 0% 24%;
+
+  /* Data maps: no-data and boundaries sit between the page and the scale */
+  --map-no-data: 0 0% 20%;
+  --map-boundary: 0 0% 40%;
   --border-interactive: 0 0% 60%;
 
   /* Accent */