@bitbaum/design-tokens 1.1.0 → 1.3.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**:
 
@@ -31,7 +35,7 @@ Changing the display typeface is **one line**:
 
 ```jsonc
 // package.json
-"@bitbaum/design-tokens": "github:bitbaum/design-tokens#v1.1.0"
+"@bitbaum/design-tokens": "^1.2.0"
 ```
 
 ```tsx
@@ -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.
@@ -81,6 +147,58 @@ Self-hosted (latin + latin-ext), no runtime requests to Google:
 
 All three are SIL Open Font License.
 
+### Faces for Next apps (`next/font/local`)
+
+`next/font/google` downloads its faces during `next build`, so a build fails
+whenever Google Fonts does not answer. The faces the fleet's apps use ship in
+`fonts/<face>/` instead, each beside its `OFL.txt`, and
+[`fonts/faces.json`](./fonts/faces.json) lists every file with the subset,
+style, weight range, `unicode-range` and SHA-256 Google serves it under:
+
+| Face (slug) | Weights | Styles | Subsets |
+|---|---|---|---|
+| Inter (`inter`) | 100–900 variable | normal | latin, latin-ext, cyrillic, cyrillic-ext, greek, greek-ext, vietnamese |
+| Space Grotesk (`space-grotesk`) | 300–700 variable | normal | latin, latin-ext, vietnamese |
+| IBM Plex Mono (`ibm-plex-mono`) | 400, 500, 600 | normal | latin, latin-ext, cyrillic, cyrillic-ext, vietnamese |
+| Fraunces (`fraunces`) | 100–900 variable | normal, italic | latin, latin-ext, vietnamese |
+| Cormorant Garamond (`cormorant-garamond`) | 300–700 variable | normal, italic | latin, latin-ext, cyrillic, cyrillic-ext, vietnamese |
+| DM Sans (`dm-sans`) | 100–1000 variable | normal | latin, latin-ext |
+| Geist (`geist`) | 100–900 variable | normal | latin, latin-ext, cyrillic, cyrillic-ext, vietnamese |
+| Geist Mono (`geist-mono`) | 100–900 variable | normal | latin, latin-ext, cyrillic, cyrillic-ext, symbols2, vietnamese |
+| JetBrains Mono (`jetbrains-mono`) | 100–800 variable | normal | latin, latin-ext, cyrillic, cyrillic-ext, greek, vietnamese |
+| Montserrat (`montserrat`) | 100–900 variable | normal | latin, latin-ext, cyrillic, cyrillic-ext, vietnamese |
+
+`next/font` takes only literal options in the calling module, and one call
+carries one `unicode-range`, so an app gets its font module from a command
+rather than from a helper:
+
+```bash
+pnpm exec design-tokens-next-fonts src/app/fonts.ts \
+  'sans=inter;variable=--font-inter' \
+  'display=space-grotesk;weight=500,700;variable=--font-space-grotesk'
+```
+
+```tsx
+// app/layout.tsx
+import { display, sans } from './fonts';
+<html className={`${sans.variable} ${display.variable}`}>
+```
+
+Keys after the face: `weight=` (default: the whole range), `style=` (default
+`normal`), `variable=`, `subsets=` (default: all shipped), `preload=` (default
+`latin`; `none`), `display=` (default `swap`). It writes one `localFont` call
+per subset, in Google's order: the same files, weights, styles, ranges and
+preloads `next/font/google` produced, formatted with the app's own prettier.
+The first lines of the file are the command that wrote it; add `--check` to
+fail when the file and the package disagree. Two things differ from Google, and
+neither changes a rendered page: the family is named after the export (Turbopack
+ignores a `font-family` declaration in `.variable`), and the fallback face is
+measured from the file instead of Google's table.
+
+`node scripts/fetch-fonts.mjs` (maintainers only, never in a build) is how the
+files got here: it asks Google exactly what `next/font/google` asks, with its
+user agent.
+
 ### Why a serif
 
 Every AI and infrastructure company competes inside the same dark-canvas
@@ -88,3 +206,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/fonts/cormorant-garamond/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2015 the Cormorant Project Authors (github.com/CatharsisFonts/Cormorant)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/fonts/dm-sans/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2014 The DM Sans Project Authors (https://github.com/googlefonts/dm-fonts)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.