From 1d42a294cf0842e5552c6650fe4f39f350c6bded Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Mon, 18 May 2026 12:49:12 +0200
Subject: [PATCH 1/8] playing with cb_theme.css - please test and feedback

---
 docs/source/_static/css/cb_theme.css      | 863 ++++++++++++++++------
 docs/source/_static/images/headerlink.svg |   4 +
 2 files changed, 642 insertions(+), 225 deletions(-)
 create mode 100644 docs/source/_static/images/headerlink.svg

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 9d5e7a5..690d4a8 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -1,358 +1,771 @@
-@import '../classic.css';
+@import "../classic.css";
 
 @font-face {
   font-family: "Open Sans";
-  src: url(../font/OpenSans-Light.ttf);
+  src: local("Open Sans"), local("OpenSans"),
+    url("../font/OpenSans-Light.ttf") format("truetype");
+  font-weight: 300;
+  font-style: normal;
+  font-display: swap;
+}
+
+:root {
+  --cb-bg: #eef3f8;
+  --cb-surface: #ffffff;
+  --cb-surface-muted: #f6f9fc;
+  --cb-border: #d8e2ee;
+  --cb-border-strong: #c0cfdf;
+  --cb-text: #203247;
+  --cb-text-muted: #5d6f82;
+  --cb-heading: #10263f;
+  --cb-brand: #ff8200;
+  --cb-brand-deep: #db6d00;
+  --cb-nav: #0f2340;
+  --cb-nav-2: #16365b;
+  --cb-link: #0e5ea8;
+  --cb-link-hover: #ff8200;
+  --cb-code-bg: #10263f;
+  --cb-code-inline: #edf3fb;
+  --cb-note-bg: #f3f8fe;
+  --cb-note-border: #90b8de;
+  --cb-warning-bg: #fff4e8;
+  --cb-warning-border: #ffb669;
+  --cb-shadow: 0 18px 48px rgba(16, 38, 63, 0.09);
+}
+
+html {
+  scroll-behavior: smooth;
 }
 
 body {
-  background-color: #111827 !important;
-  font-family: "Open Sans", sans-serif !important;
+  margin: 0;
+  background:
+    radial-gradient(circle at top right, rgba(255, 130, 0, 0.08), transparent 22rem),
+    linear-gradient(180deg, #f7fafd 0%, var(--cb-bg) 18rem, var(--cb-bg) 100%);
+  color: var(--cb-text);
+  font-family: "Open Sans", "Avenir Next", "Segoe UI", sans-serif;
+  line-height: 1.7;
+}
+
+a {
+  color: var(--cb-link);
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.15em;
+  transition: color 140ms ease, text-decoration-color 140ms ease;
+}
+
+a:hover {
+  color: var(--cb-link-hover);
+}
+
+div.document {
+  display: grid;
+  grid-template-columns: 18rem minmax(0, 1fr);
+  align-items: start;
+  column-gap: 0.9rem;
+  min-width: 0;
+  max-width: 1440px;
+  margin: 0 auto;
+  background: transparent;
+}
+
+div.related {
+  position: sticky;
+  top: 0;
+  z-index: 30;
+  width: auto;
+  box-sizing: border-box;
+  height: auto;
+  line-height: 1.55rem;
+  margin: 0 1.5rem;
+  border: 1px solid rgba(192, 207, 223, 0.75);
+  border-radius: 0 0 18px 18px;
+  background: rgba(255, 255, 255, 0.92);
+  backdrop-filter: blur(16px);
+  box-shadow: 0 10px 28px rgba(16, 38, 63, 0.08);
+}
+
+div.related:first-of-type {
+  margin-top: 1rem;
+}
+
+div.related ul {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  margin: 0;
+  padding: 0.42rem 1.15rem;
+  background: transparent;
 }
 
-.document .bodywrapper {
-  background-color: #111827 !important;
+div.related li {
+  display: inline-flex;
+  align-items: center;
+  color: var(--cb-text-muted);
+  font-size: 0.92rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
 }
 
-.document .bodywrapper .body {
-  background-color: #111827 !important;
-  width: 100% !important;
-  max-width: 92% !important;
-  font-family: "Open Sans", sans-serif !important;
-  color: #fff !important;
-  box-shadow: rgba(6, 24, 44, 0.4) 0px 0px 0px 2px, rgba(6, 24, 44, 0.65) 0px 4px 6px -1px, rgba(255, 255, 255, 0.08) 0px 1px 0px inset !important;
+div.related li.nav-item {
+  margin-right: 0.4rem;
 }
 
-.document .bodywrapper .body p {
-  font-size: 18px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 100 !important;
-  line-height: 1.5 !important;
+div.related li.nav-item:not(.nav-item-this) a {
+  margin-right: 0.4rem;
 }
 
-.document .bodywrapper .body p.caption,
-.document .bodywrapper .body caption,
-.document .bodywrapper .body span.caption-number,
-.document .bodywrapper .body span.caption-text {
-  font-size: 18px !important;
-  line-height: 1.5 !important;
+div.related li.right {
+  float: none;
+  min-height: 1.55rem;
+  order: 2;
 }
 
-.document .bodywrapper .body figure figcaption,
-.document .bodywrapper .body figure figcaption p,
-.document .bodywrapper .body div.figure p.caption {
-  text-align: center !important;
+div.related li.right {
+  font-size: 0;
 }
 
-.document .bodywrapper .body figure figcaption,
-.document .bodywrapper .body div.figure p.caption {
-  padding-top: 0.1em !important;
+div.related li.right a {
+  font-size: 0.92rem;
 }
 
-.document .bodywrapper .body figure figcaption p,
-.document .bodywrapper .body div.figure p.caption {
-  margin-top: 0.1em !important;
+div.related li.right:first-child {
+  order: 4;
 }
 
-.document .bodywrapper .body p strong,
-.document .bodywrapper .body p a span {
-  color: #ff8200 !important;
-  font-size: 20px !important;
+div.related li.right:nth-child(2) {
+  order: 3;
+  margin-left: auto;
 }
 
-.document .bodywrapper .body .toctree-wrapper.compound ul li.toctree-l1 a {
-  color: #ff8200 !important;
-  font-size: 24px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 100 !important;
-  line-height: 2 !important;
+div.related a {
+  color: var(--cb-heading);
 }
 
-.document .bodywrapper .body .toctree-wrapper.compound ul li ul li.toctree-l2 a {
-  font-family: "Open Sans", sans-serif !important;
-  color: #fff !important;
-  font-size: 18px !important;
+div.related li.right a {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.38rem 0.8rem;
+  border: 1px solid rgba(255, 130, 0, 0.18);
+  border-radius: 18px;
+  background: linear-gradient(135deg, #ff9226, var(--cb-brand));
+  color: #fff;
+  text-transform: none;
+  box-shadow: 0 10px 18px rgba(255, 130, 0, 0.18);
 }
 
-.document .sphinxsidebar {
-  background-color: #111827 !important;
+div.related li.right a:hover {
+  background: linear-gradient(135deg, #ff9f3f, var(--cb-brand-deep));
+  color: #fff;
+  text-decoration: none;
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper .logo {
-  margin: 0 !important;
+div.documentwrapper {
+  float: none;
+  grid-column: 2;
+  width: 100%;
+  margin: 0;
+}
+
+div.bodywrapper {
+  margin: 2rem 1.5rem 2.5rem 0;
+  background: transparent;
+}
+
+div.bodywrapper div.body {
+  width: auto;
+  max-width: 980px;
+  padding: 3rem clamp(1.75rem, 3vw, 3.25rem);
+  border: 1px solid rgba(216, 226, 238, 0.9);
+  border-radius: 28px;
+  background: linear-gradient(180deg, rgba(255, 255, 255, 0.98), rgba(246, 249, 252, 0.98));
+  color: var(--cb-text);
+  box-shadow: var(--cb-shadow);
+}
+
+div.bodywrapper .body h1,
+div.bodywrapper .body h2,
+div.bodywrapper .body h3,
+div.bodywrapper .body h4,
+div.bodywrapper .body h5,
+div.bodywrapper .body h6 {
+  color: var(--cb-heading);
+  font-family: "Open Sans", "Avenir Next", sans-serif;
+  letter-spacing: -0.02em;
+}
+
+div.bodywrapper .body h1 {
+  margin: 0 0 1.25rem;
+  padding: 0 0 1rem;
+  border-bottom: 1px solid var(--cb-border);
+  font-size: clamp(2.2rem, 4vw, 3.35rem);
+  font-weight: 700;
+  line-height: 1.1;
+  text-align: left;
+  background: transparent;
+}
+
+div.bodywrapper .body h2 {
+  margin: 3rem 0 1rem;
+  padding: 0;
+  border-bottom: none;
+  font-size: clamp(1.6rem, 2.7vw, 2.2rem);
+  font-weight: 700;
+  line-height: 1.2;
+  background: transparent;
+}
+
+div.bodywrapper .body h2::after {
+  content: "";
+  display: block;
+  width: 4.25rem;
+  height: 0.3rem;
+  margin-top: 0.7rem;
+  border-radius: 999px;
+  background: linear-gradient(90deg, var(--cb-brand), rgba(255, 130, 0, 0.2));
+}
+
+div.bodywrapper .body h3 {
+  margin: 2rem 0 0.75rem;
+  padding: 0;
+  font-size: clamp(1.3rem, 2.2vw, 1.65rem);
+  font-weight: 700;
+  line-height: 1.25;
+  background: transparent;
+}
+
+div.bodywrapper .body h4 {
+  display: inline-block;
+  margin: 1.8rem 0 0.6rem;
+  padding: 0.25rem 0.75rem;
+  border: 1px solid rgba(255, 130, 0, 0.2);
+  border-radius: 999px;
+  font-size: 1rem;
+  font-weight: 700;
+  line-height: 1.35;
+  color: var(--cb-brand-deep);
+  background: rgba(255, 130, 0, 0.08);
+}
+
+div.bodywrapper .body a.headerlink {
+  display: inline-block;
+  width: 0.95em;
+  height: 0.95em;
+  margin-left: 0.38rem;
+  padding: 0;
+  vertical-align: baseline;
+  overflow: hidden;
+  text-indent: -9999px;
+  white-space: nowrap;
+  background-image: url("../images/headerlink.svg");
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: contain;
+  opacity: 0.78;
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper h4 {
-  color: #fff !important;
-  font-size: 16px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 700 !important;
-  margin: 16px 0 2px !important;
-  text-transform: capitalize !important;
+div.bodywrapper .body a.headerlink:hover {
+  background-color: var(--cb-nav);
+  opacity: 1;
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper h4::after {
-  content: ":" !important;
+div.bodywrapper .body p,
+div.bodywrapper .body ul,
+div.bodywrapper .body ol,
+div.bodywrapper .body dl,
+div.bodywrapper .body table {
+  font-size: 0.98rem;
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper .topless a {
-  display: inline !important;
-  font-size: 18px !important;
-  font-family: "Open Sans", sans-serif !important;
-  color: #fff !important;
-  line-height: 1.25 !important;
-  padding: 0 !important;
-  background-color: transparent !important;
-  text-decoration: none !important;
-  transition: color 0.15s ease !important;
+div.bodywrapper .body p,
+div.bodywrapper .body li,
+div.bodywrapper .body dd {
+  color: var(--cb-text);
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper .topless a:hover {
-  color: #ff8200 !important;
+div.bodywrapper .body li + li {
+  margin-top: 0.3rem;
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper p {
-  margin: 5px 10px 10px 0px !important;
-  font-family: "Open Sans", sans-serif !important;
+div.bodywrapper .body strong {
+  color: var(--cb-heading);
+  font-weight: 700;
 }
 
-.document .sphinxsidebar .sphinxsidebarwrapper #searchlabel {
-  font-size: 18px !important;
-  font-family: "Open Sans", sans-serif !important;
-  color: #fff !important;
+div.bodywrapper .body em {
+  color: var(--cb-text-muted);
 }
 
-.document .sphinxsidebar a {
-  color: #fff !important;
+div.bodywrapper .body hr {
+  border: 0;
+  border-top: 1px solid var(--cb-border);
 }
 
-.document .bodywrapper h1 {
-  font-size: 50px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 800 !important;
-  background-color: transparent !important;
-  color: #fff !important;
-  text-align: center !important;
-  border-bottom: none !important;
+div.bodywrapper .body p a,
+div.bodywrapper .body li a,
+div.bodywrapper .body dd a {
+  font-weight: 600;
 }
 
-.document .bodywrapper h2 {
-  font-size: 36px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 600 !important;
-  margin: 1.5em 0 0.5em !important;
-  padding: 0 !important;
-  border-bottom: none !important;
-  background-color: #111827 !important;
-  color: #ff8200 !important;
+div.bodywrapper .body code {
+  padding: 0.16rem 0.42rem;
+  border: 1px solid rgba(14, 94, 168, 0.1);
+  border-radius: 0.42rem;
+  background: var(--cb-code-inline);
+  color: #11497d;
+  font-size: 0.92em;
 }
 
-.document .bodywrapper h3 {
-  font-size: 30px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 600 !important;
-  margin: 1.25em 0 0.45em !important;
-  padding: 0 !important;
-  background-color: #111827 !important;
-  color: #fff !important;
-  width: fit-content !important;
+div.bodywrapper .body pre,
+div.bodywrapper .body div.highlight {
+  border: 1px solid rgba(16, 38, 63, 0.18);
+  border-radius: 18px;
+  background: var(--cb-code-bg);
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.06);
 }
 
-.document .bodywrapper h4 {
-  font-size: 26px !important;
-  font-family: "Open Sans", sans-serif !important;
-  font-weight: 600 !important;
-  margin: 1em 0 0.4em !important;
-  padding: 0 !important;
-  background-color: #ff8200 !important;
-  border-bottom: none !important;
-  color: #fff !important;
+div.bodywrapper .body div.highlight {
+  margin: 1.4rem 0;
 }
 
-.document .bodywrapper section>h2+section>h3 {
-  margin-top: 0.2em !important;
+div.bodywrapper .body div.highlight pre {
+  margin: 0;
+  padding: 1.1rem 1.25rem;
+  border: 0;
+  background: transparent;
+  color: #eff5fb;
+  overflow-x: auto;
+  box-shadow: none;
 }
 
-.document .bodywrapper section>h3+section>h4 {
-  margin-top: 0.2em !important;
+div.bodywrapper .body pre,
+div.bodywrapper .body pre code {
+  color: #eff5fb;
 }
 
-.document .bodywrapper .highlight {
-  background: #153659 !important;
+div.bodywrapper .body .highlight .c1,
+div.bodywrapper .body .highlight .c,
+div.bodywrapper .body .highlight .cm {
+  color: #91a9c4;
 }
 
-.document .bodywrapper section p a {
-  color: #ff8200 !important;
+div.bodywrapper .body .highlight .s,
+div.bodywrapper .body .highlight .s2,
+div.bodywrapper .body .highlight .sa {
+  color: #ffd59e;
 }
 
-.document .bodywrapper section img {
-  background: #1c354f;
+div.bodywrapper .body .highlight .k,
+div.bodywrapper .body .highlight .ow,
+div.bodywrapper .body .highlight .nt {
+  color: #8fc7ff;
 }
 
-.document .bodywrapper .highlight .nt {
-  color: #8cb0ff !important;
+div.bodywrapper .body .highlight .nb,
+div.bodywrapper .body .highlight .nf {
+  color: #ffb257;
 }
 
-.document .bodywrapper .highlight .c1,
-.document .bodywrapper .highlight .s,
-.document .bodywrapper .highlight .s2 {
-  color: #fff !important;
+div.bodywrapper .body .highlight .go {
+  color: #d6dfeb;
 }
 
-.document .bodywrapper .highlight .nb {
-  color: #ff8200 !important;
+div.bodywrapper .body img {
+  max-width: 100%;
+  border-radius: 18px;
+  background: var(--cb-surface-muted);
 }
 
-.related {
-  background-color: #162235 !important;
-  height: 80px;
-  display: flex;
-  flex-direction: column;
-  justify-content: center;
-  border-bottom: 1px solid #ccc;
+div.bodywrapper .body figure,
+div.bodywrapper .body div.figure,
+div.bodywrapper .body .figure {
+  margin: 2rem 0;
 }
 
-.related ul {
-  background-color: #162235 !important;
+div.bodywrapper .body .caption,
+div.bodywrapper .body p.caption,
+div.bodywrapper .body span.caption-text {
+  color: var(--cb-text-muted);
+  font-size: 0.96rem;
 }
 
-.related ul li {
-  font-size: 18px !important;
-  font-weight: 600 !important;
-  font-family: "Open Sans", sans-serif !important;
+div.bodywrapper .body table.docutils,
+div.bodywrapper .body table {
+  width: 100%;
+  table-layout: fixed;
+  overflow: hidden;
+  border: 1px solid var(--cb-border);
+  border-collapse: separate;
+  border-spacing: 0;
+  border-radius: 18px;
+  background: var(--cb-surface);
 }
 
-.related ul li.right a {
-  display: inline-block;
-  text-transform: capitalize;
-  padding: 10px 15px;
-  background-color: #ff8200;
-  border-radius: 5px;
-  transition: background-color 0.15s ease, transform 0.15s ease;
+div.bodywrapper .body table.docutils caption,
+div.bodywrapper .body table caption {
+  caption-side: bottom;
+  padding-top: 0.75rem;
+}
+
+div.bodywrapper .body table.docutils th,
+div.bodywrapper .body table th,
+div.bodywrapper .body dl.field-list > dt {
+  padding: 0.95rem 1rem;
+  border-bottom: 1px solid var(--cb-border);
+  background: linear-gradient(180deg, #f5f9fd, #ebf2f9);
+  background-clip: padding-box;
+  color: var(--cb-heading);
+  font-weight: 700;
+}
+
+div.bodywrapper .body table.docutils tr:first-child th:first-child,
+div.bodywrapper .body table.docutils tr:first-child td:first-child,
+div.bodywrapper .body table tr:first-child th:first-child,
+div.bodywrapper .body table tr:first-child td:first-child {
+  border-top-left-radius: 18px;
+}
+
+div.bodywrapper .body table.docutils tr:first-child th:last-child,
+div.bodywrapper .body table.docutils tr:first-child td:last-child,
+div.bodywrapper .body table tr:first-child th:last-child,
+div.bodywrapper .body table tr:first-child td:last-child {
+  border-top-right-radius: 18px;
+}
+
+div.bodywrapper .body table.docutils td,
+div.bodywrapper .body table td,
+div.bodywrapper .body dl.field-list > dd {
+  padding: 0.9rem 1rem;
+  border-bottom: 1px solid var(--cb-border);
+  overflow-wrap: anywhere;
+  word-break: break-word;
+  hyphens: auto;
+}
+
+div.bodywrapper .body table.docutils th,
+div.bodywrapper .body table th {
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+
+div.bodywrapper .body table.docutils td a,
+div.bodywrapper .body table td a {
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+
+div.bodywrapper .body table.docutils tr:last-child td,
+div.bodywrapper .body table tr:last-child td {
+  border-bottom: 0;
+}
+
+div.bodywrapper .body .note,
+div.bodywrapper .body .warning,
+div.bodywrapper .body .important,
+div.bodywrapper .body .tip {
+  margin: 1.5rem 0;
+  padding: 1rem 1.15rem 1rem 1.2rem;
+  border: 1px solid var(--cb-note-border);
+  border-left-width: 0.4rem;
+  border-radius: 16px;
+  background: var(--cb-note-bg);
+}
+
+div.bodywrapper .body .warning,
+div.bodywrapper .body .important {
+  border-color: var(--cb-warning-border);
+  background: var(--cb-warning-bg);
+}
+
+div.bodywrapper .body .admonition-title {
+  margin: 0 0 0.35rem;
+  color: var(--cb-heading);
+  font-size: 0.96rem;
+  font-weight: 700;
+}
+
+div.bodywrapper .body blockquote {
+  margin: 1.5rem 0;
+  padding: 0.4rem 0 0.4rem 1.1rem;
+  border-left: 0.28rem solid rgba(255, 130, 0, 0.5);
+  color: var(--cb-text-muted);
+}
+
+div.bodywrapper .body .toctree-wrapper.compound {
+  margin-top: 2rem;
+}
+
+div.bodywrapper .body .toctree-wrapper.compound > p.caption {
+  margin-bottom: 0.9rem;
+  color: var(--cb-heading);
+  font-size: 0.92rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
 }
 
-.related ul li.right a:hover {
-  background-color: #ff9a26;
-  transform: scale(1.05);
+div.bodywrapper .body .toctree-wrapper.compound ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+div.bodywrapper .body .toctree-wrapper.compound li {
+  margin: 0;
+}
+
+div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 {
+  margin-top: 0.8rem;
+}
+
+div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 > a {
+  display: block;
+  padding: 1rem 1.1rem;
+  border: 1px solid rgba(216, 226, 238, 0.9);
+  border-radius: 16px;
+  background: var(--cb-surface);
+  color: var(--cb-heading);
+  font-size: 1.08rem;
+  font-weight: 700;
   text-decoration: none;
+  box-shadow: 0 8px 18px rgba(16, 38, 63, 0.04);
+  transition: transform 160ms ease, border-color 160ms ease, box-shadow 160ms ease;
+}
+
+div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 > a:hover {
+  transform: translateY(-1px);
+  border-color: rgba(255, 130, 0, 0.35);
+  box-shadow: 0 12px 26px rgba(16, 38, 63, 0.08);
+  color: var(--cb-brand-deep);
 }
 
-.footer {
-  background-color: #111827 !important;
+div.bodywrapper .body .toctree-wrapper.compound li.toctree-l2 {
+  margin: 0.55rem 0 0 1rem;
 }
 
-.document .bodywrapper .warning {
-  background-color: #1c354f !important;
-  padding: 20px 10px !important;
+div.bodywrapper .body .toctree-wrapper.compound li.toctree-l2 > a {
+  color: var(--cb-text-muted);
+  font-size: 0.98rem;
+  font-weight: 600;
 }
 
-.document .bodywrapper th,
-dl.field-list>dt {
-  background-color: #1c354f !important;
+div.sphinxsidebar {
+  grid-column: 1;
+  grid-row: 1;
+  position: sticky;
+  top: 5.5rem;
+  float: none;
+  width: auto;
+  margin: 2rem 0 2rem 1.5rem;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  font-family: "Open Sans", "Avenir Next", sans-serif;
 }
 
-.document .bodywrapper table.docutils th p,
-.document .bodywrapper table.docutils td p {
-  text-align: left !important;
+div.sphinxsidebarwrapper {
+  position: static;
+  padding: 1.3rem 1.1rem 1.2rem;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 24px;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.06), transparent 20%),
+    linear-gradient(180deg, var(--cb-nav) 0%, var(--cb-nav-2) 100%);
+  box-shadow: 0 24px 44px rgba(15, 35, 64, 0.2);
 }
 
-.document .bodywrapper .footnote:target {
-  background-color: transparent !important;
+div.sphinxsidebarwrapper .logo {
+  display: block;
+  max-width: 10.5rem;
+  margin: 0 auto 1.5rem;
 }
 
-.document .bodywrapper .footnote-reference,
-.document .bodywrapper .footnote .label,
-.document .bodywrapper .footnote .label a,
-.document .bodywrapper .footnote .fn-bracket {
-  color: #ff8200 !important;
+div.sphinxsidebarwrapper h3,
+div.sphinxsidebarwrapper h4 {
+  margin: 1.25rem 0 0.55rem;
+  color: rgba(255, 255, 255, 0.88);
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
 }
 
-.document .bodywrapper .footnote,
-.document .bodywrapper .footnote p {
-  line-height: 1.2 !important;
+div.sphinxsidebarwrapper p,
+div.sphinxsidebarwrapper li,
+div.sphinxsidebarwrapper #searchlabel {
+  color: rgba(232, 240, 249, 0.82);
+  font-size: 0.94rem;
+  line-height: 1.35;
 }
 
-.document .bodywrapper .footnote {
-  margin: 0.2em 0 !important;
+div.sphinxsidebar a {
+  color: #fff;
 }
 
-.document .bodywrapper .footnote p {
-  margin-top: 0 !important;
-  margin-bottom: 0 !important;
+div.sphinxsidebar a:hover {
+  color: #ffd39e;
+}
+
+div.sphinxsidebarwrapper ul {
+  margin: 0;
+  padding-left: 0;
+  list-style: none;
+}
+
+div.sphinxsidebarwrapper ul ul {
+  margin-top: 0.25rem;
+  padding-left: 0.9rem;
+}
+
+div.sphinxsidebarwrapper li {
+  margin: 0.08rem 0;
+}
+
+div.sphinxsidebarwrapper li a {
+  display: block;
+  padding: 0.28rem 0.55rem;
+  border-radius: 0.7rem;
+  text-decoration: none;
+  line-height: 1.3;
+  transition: background-color 140ms ease, color 140ms ease;
 }
 
-.document .bodywrapper .note {
-  background-color: #1c354f !important;
+div.sphinxsidebarwrapper li.current > a,
+div.sphinxsidebarwrapper li a:hover {
+  background: rgba(255, 255, 255, 0.12);
 }
 
-.document .bodywrapper .highlight .go {
-  color: #ddd !important
+div.sphinxsidebarwrapper input[type="text"] {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 0.78rem 0.92rem;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.12);
+  color: #fff;
 }
 
-.document .bodywrapper code {
-  background-color: #284a6d !important;
+div.sphinxsidebarwrapper input[type="text"]::placeholder {
+  color: rgba(255, 255, 255, 0.6);
 }
 
-@media only screen and (max-width: 600px) {
-  .document .bodywrapper {
-    margin: 0 0 0 150px !important;
+div.sphinxsidebarwrapper input[type="submit"] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-top: 0.7rem;
+  padding: 0.7rem 1rem;
+  border: 0;
+  border-radius: 999px;
+  background: linear-gradient(135deg, #ff9226, var(--cb-brand));
+  color: #fff;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+div.sphinxsidebarwrapper .searchformwrapper {
+  margin-top: 0.7rem;
+}
+
+div.sphinxsidebarwrapper form.search {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 0.55rem;
+  align-items: center;
+}
+
+div.sphinxsidebarwrapper form.search input[type="submit"] {
+  margin-top: 0;
+  min-width: 3rem;
+  padding-inline: 0.9rem;
+}
+
+div.footer {
+  width: auto;
+  box-sizing: border-box;
+  margin: 0 1.5rem 2rem;
+  padding: 1.1rem 1.25rem 0;
+  color: var(--cb-text-muted);
+  text-align: right;
+}
+
+div.footer a {
+  color: var(--cb-link);
+}
+
+@media only screen and (max-width: 1080px) {
+  div.document {
+    display: block;
+  }
+
+  div.related {
+    margin: 0 1rem;
+    border-radius: 0 0 16px 16px;
   }
 
-  .document .bodywrapper .body {
-    max-width: 78% !important;
+  div.sphinxsidebar {
+    float: none;
+    width: auto;
+    margin: 1.25rem 1rem 0;
   }
 
-  .document h1 {
-    margin: 0 !important;
-    padding: 0 !important;
-    font-size: 25px !important;
+  div.sphinxsidebarwrapper {
+    position: static;
   }
 
-  .document .bodywrapper h2 {
-    font-size: 23px !important;
+  div.bodywrapper {
+    margin: 1rem;
   }
 
-  .document .bodywrapper h3 {
-    font-size: 21px !important;
+  div.bodywrapper div.body {
+    max-width: none;
+    padding: 2.2rem 1.5rem;
+    border-radius: 22px;
   }
+}
 
-  .document .bodywrapper h4 {
-    font-size: 19px !important;
+@media only screen and (max-width: 720px) {
+  body {
+    background:
+      radial-gradient(circle at top right, rgba(255, 130, 0, 0.08), transparent 14rem),
+      linear-gradient(180deg, #f7fafd 0%, var(--cb-bg) 12rem, var(--cb-bg) 100%);
   }
 
-  .document .sphinxsidebar {
-    width: 150px !important;
+  div.related ul {
+    padding: 0.8rem 1rem;
   }
 
-  .document .bodywrapper .body p {
-    font-size: 14px !important;
+  div.related li {
+    font-size: 0.86rem;
   }
 
-  .document .bodywrapper .body p strong,
-  .document .bodywrapper .body p a span {
-    font-size: 17px !important;
+  div.bodywrapper div.body {
+    padding: 1.8rem 1.15rem;
+    border-radius: 18px;
   }
 
-  .document .bodywrapper .body p.caption,
-  .document .bodywrapper .body caption,
-  .document .bodywrapper .body span.caption-number,
-  .document .bodywrapper .body span.caption-text {
-    font-size: 14px !important;
+  div.bodywrapper .body h1 {
+    font-size: 2rem;
   }
 
-  .document .bodywrapper .body .toctree-wrapper.compound ul li.toctree-l1 a {
-    font-size: 20px !important;
+  div.bodywrapper .body p,
+  div.bodywrapper .body ul,
+  div.bodywrapper .body ol,
+  div.bodywrapper .body dl,
+  div.bodywrapper .body table {
+    font-size: 0.98rem;
   }
 
-  .document .bodywrapper .body .toctree-wrapper.compound ul {
-    padding: 5px !important;
+  div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 > a {
+    padding: 0.9rem 1rem;
   }
 
-  .document .bodywrapper .body .toctree-wrapper.compound ul li ul li.toctree-l2 a {
-    font-size: 16px !important;
+  div.sphinxsidebarwrapper form.search {
+    grid-template-columns: 1fr;
   }
 
-  .document .bodywrapper .body .toctree-wrapper.compound ul li ul {
-    padding: 0 0 0 10px;
+  div.sphinxsidebarwrapper form.search input[type="submit"] {
+    width: 100%;
   }
 }
diff --git a/docs/source/_static/images/headerlink.svg b/docs/source/_static/images/headerlink.svg
new file mode 100644
index 0000000..0af312a
--- /dev/null
+++ b/docs/source/_static/images/headerlink.svg
@@ -0,0 +1,4 @@
+<svg width="225" height="227" viewBox="0 0 225 227" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M158.926 94.9968L129.742 94.9379V50.3374H93.261V94.8791H65.6652C49.5431 94.8497 36.4806 81.7578 36.4806 65.6357C36.4806 49.5137 49.5431 36.4512 65.6652 36.4512H73.8145L92.7609 0H65.6652C29.3905 0 0 29.3905 0 65.6652C0 101.94 29.3905 131.33 65.6652 131.33H93.261V160.662C93.261 196.937 122.651 226.327 158.926 226.327C195.201 226.327 224.591 196.937 224.591 160.662C224.591 124.387 195.201 94.9968 158.926 94.9968ZM158.926 189.846C142.804 189.846 129.742 176.784 129.742 160.662V131.419L158.926 131.477C175.048 131.477 188.111 144.54 188.111 160.662C188.111 176.784 175.048 189.846 158.926 189.846Z" fill="#FF8200"/>
+<path d="M93.261 131.389V94.9085L73.8145 94.8791L93.261 131.389Z" fill="#DC5F00"/>
+</svg>

From 269d13dcfbedaeb86c20cf759640434101f275f0 Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Tue, 19 May 2026 09:20:17 +0200
Subject: [PATCH 2/8] add dark mode switch

---
 docs/source/_static/css/cb_theme.css | 148 ++++++++++++++++++++++-----
 docs/source/_static/js/cb_theme.js   |  97 ++++++++++++++++++
 docs/source/conf.py                  |   3 +
 3 files changed, 225 insertions(+), 23 deletions(-)
 create mode 100644 docs/source/_static/js/cb_theme.js

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 690d4a8..e0b9675 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -10,7 +10,10 @@
 }
 
 :root {
+  color-scheme: light;
   --cb-bg: #eef3f8;
+  --cb-bg-top: #f7fafd;
+  --cb-page-glow: rgba(255, 130, 0, 0.08);
   --cb-surface: #ffffff;
   --cb-surface-muted: #f6f9fc;
   --cb-border: #d8e2ee;
@@ -26,13 +29,76 @@
   --cb-link-hover: #ff8200;
   --cb-code-bg: #10263f;
   --cb-code-inline: #edf3fb;
+  --cb-code-border: rgba(14, 94, 168, 0.1);
+  --cb-code-inline-text: #11497d;
+  --cb-code-block-border: rgba(16, 38, 63, 0.18);
   --cb-note-bg: #f3f8fe;
   --cb-note-border: #90b8de;
   --cb-warning-bg: #fff4e8;
   --cb-warning-border: #ffb669;
+  --cb-panel-bg: linear-gradient(180deg, rgba(255, 255, 255, 0.98), rgba(246, 249, 252, 0.98));
+  --cb-related-bg: rgba(255, 255, 255, 0.92);
+  --cb-related-border: rgba(192, 207, 223, 0.75);
+  --cb-related-shadow: 0 10px 28px rgba(16, 38, 63, 0.08);
+  --cb-sidebar-bg:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.06), transparent 20%),
+    linear-gradient(180deg, var(--cb-nav) 0%, var(--cb-nav-2) 100%);
+  --cb-sidebar-border: rgba(255, 255, 255, 0.08);
+  --cb-sidebar-shadow: 0 24px 44px rgba(15, 35, 64, 0.2);
+  --cb-card-border: rgba(216, 226, 238, 0.9);
+  --cb-card-shadow: 0 8px 18px rgba(16, 38, 63, 0.04);
+  --cb-card-shadow-hover: 0 12px 26px rgba(16, 38, 63, 0.08);
+  --cb-table-head-bg: linear-gradient(180deg, #f5f9fd, #ebf2f9);
+  --cb-blockquote-border: rgba(255, 130, 0, 0.5);
+  --cb-headerlink-hover-bg: var(--cb-nav);
   --cb-shadow: 0 18px 48px rgba(16, 38, 63, 0.09);
 }
 
+html[data-theme="dark"] {
+  color-scheme: dark;
+  --cb-bg: #0a1320;
+  --cb-bg-top: #0f1725;
+  --cb-page-glow: rgba(255, 130, 0, 0.14);
+  --cb-surface: #101c2c;
+  --cb-surface-muted: #152437;
+  --cb-border: #26384d;
+  --cb-border-strong: #334b64;
+  --cb-text: #d9e5f2;
+  --cb-text-muted: #97acc3;
+  --cb-heading: #f5f9ff;
+  --cb-brand: #ff8200;
+  --cb-brand-deep: #ffb15d;
+  --cb-nav: #07111d;
+  --cb-nav-2: #10233b;
+  --cb-link: #8bccff;
+  --cb-link-hover: #ffb15d;
+  --cb-code-bg: #07111d;
+  --cb-code-inline: #1a2a3d;
+  --cb-code-border: rgba(139, 204, 255, 0.18);
+  --cb-code-inline-text: #d8ebff;
+  --cb-code-block-border: rgba(139, 204, 255, 0.16);
+  --cb-note-bg: #12263a;
+  --cb-note-border: #3a678f;
+  --cb-warning-bg: #3a2715;
+  --cb-warning-border: #f0a34d;
+  --cb-panel-bg: linear-gradient(180deg, rgba(16, 28, 44, 0.98), rgba(12, 21, 34, 0.98));
+  --cb-related-bg: rgba(10, 19, 32, 0.92);
+  --cb-related-border: rgba(51, 75, 100, 0.82);
+  --cb-related-shadow: 0 12px 28px rgba(0, 0, 0, 0.32);
+  --cb-sidebar-bg:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.04), transparent 20%),
+    linear-gradient(180deg, #07111d 0%, #10233b 100%);
+  --cb-sidebar-border: rgba(139, 204, 255, 0.1);
+  --cb-sidebar-shadow: 0 24px 48px rgba(0, 0, 0, 0.34);
+  --cb-card-border: rgba(51, 75, 100, 0.78);
+  --cb-card-shadow: 0 10px 20px rgba(0, 0, 0, 0.18);
+  --cb-card-shadow-hover: 0 14px 28px rgba(0, 0, 0, 0.26);
+  --cb-table-head-bg: linear-gradient(180deg, #17283c, #122133);
+  --cb-blockquote-border: rgba(255, 130, 0, 0.6);
+  --cb-headerlink-hover-bg: #10233b;
+  --cb-shadow: 0 22px 54px rgba(0, 0, 0, 0.28);
+}
+
 html {
   scroll-behavior: smooth;
 }
@@ -40,8 +106,8 @@ html {
 body {
   margin: 0;
   background:
-    radial-gradient(circle at top right, rgba(255, 130, 0, 0.08), transparent 22rem),
-    linear-gradient(180deg, #f7fafd 0%, var(--cb-bg) 18rem, var(--cb-bg) 100%);
+    radial-gradient(circle at top right, var(--cb-page-glow), transparent 22rem),
+    linear-gradient(180deg, var(--cb-bg-top) 0%, var(--cb-bg) 18rem, var(--cb-bg) 100%);
   color: var(--cb-text);
   font-family: "Open Sans", "Avenir Next", "Segoe UI", sans-serif;
   line-height: 1.7;
@@ -78,11 +144,11 @@ div.related {
   height: auto;
   line-height: 1.55rem;
   margin: 0 1.5rem;
-  border: 1px solid rgba(192, 207, 223, 0.75);
+  border: 1px solid var(--cb-related-border);
   border-radius: 0 0 18px 18px;
-  background: rgba(255, 255, 255, 0.92);
+  background: var(--cb-related-bg);
   backdrop-filter: blur(16px);
-  box-shadow: 0 10px 28px rgba(16, 38, 63, 0.08);
+  box-shadow: var(--cb-related-shadow);
 }
 
 div.related:first-of-type {
@@ -177,9 +243,9 @@ div.bodywrapper div.body {
   width: auto;
   max-width: 980px;
   padding: 3rem clamp(1.75rem, 3vw, 3.25rem);
-  border: 1px solid rgba(216, 226, 238, 0.9);
+  border: 1px solid var(--cb-card-border);
   border-radius: 28px;
-  background: linear-gradient(180deg, rgba(255, 255, 255, 0.98), rgba(246, 249, 252, 0.98));
+  background: var(--cb-panel-bg);
   color: var(--cb-text);
   box-shadow: var(--cb-shadow);
 }
@@ -266,7 +332,7 @@ div.bodywrapper .body a.headerlink {
 }
 
 div.bodywrapper .body a.headerlink:hover {
-  background-color: var(--cb-nav);
+  background-color: var(--cb-headerlink-hover-bg);
   opacity: 1;
 }
 
@@ -310,16 +376,16 @@ div.bodywrapper .body dd a {
 
 div.bodywrapper .body code {
   padding: 0.16rem 0.42rem;
-  border: 1px solid rgba(14, 94, 168, 0.1);
+  border: 1px solid var(--cb-code-border);
   border-radius: 0.42rem;
   background: var(--cb-code-inline);
-  color: #11497d;
+  color: var(--cb-code-inline-text);
   font-size: 0.92em;
 }
 
 div.bodywrapper .body pre,
 div.bodywrapper .body div.highlight {
-  border: 1px solid rgba(16, 38, 63, 0.18);
+  border: 1px solid var(--cb-code-block-border);
   border-radius: 18px;
   background: var(--cb-code-bg);
   box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.06);
@@ -413,7 +479,7 @@ div.bodywrapper .body table th,
 div.bodywrapper .body dl.field-list > dt {
   padding: 0.95rem 1rem;
   border-bottom: 1px solid var(--cb-border);
-  background: linear-gradient(180deg, #f5f9fd, #ebf2f9);
+  background: var(--cb-table-head-bg);
   background-clip: padding-box;
   color: var(--cb-heading);
   font-weight: 700;
@@ -488,7 +554,7 @@ div.bodywrapper .body .admonition-title {
 div.bodywrapper .body blockquote {
   margin: 1.5rem 0;
   padding: 0.4rem 0 0.4rem 1.1rem;
-  border-left: 0.28rem solid rgba(255, 130, 0, 0.5);
+  border-left: 0.28rem solid var(--cb-blockquote-border);
   color: var(--cb-text-muted);
 }
 
@@ -522,21 +588,21 @@ div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 {
 div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 > a {
   display: block;
   padding: 1rem 1.1rem;
-  border: 1px solid rgba(216, 226, 238, 0.9);
+  border: 1px solid var(--cb-card-border);
   border-radius: 16px;
   background: var(--cb-surface);
   color: var(--cb-heading);
   font-size: 1.08rem;
   font-weight: 700;
   text-decoration: none;
-  box-shadow: 0 8px 18px rgba(16, 38, 63, 0.04);
+  box-shadow: var(--cb-card-shadow);
   transition: transform 160ms ease, border-color 160ms ease, box-shadow 160ms ease;
 }
 
 div.bodywrapper .body .toctree-wrapper.compound li.toctree-l1 > a:hover {
   transform: translateY(-1px);
   border-color: rgba(255, 130, 0, 0.35);
-  box-shadow: 0 12px 26px rgba(16, 38, 63, 0.08);
+  box-shadow: var(--cb-card-shadow-hover);
   color: var(--cb-brand-deep);
 }
 
@@ -567,12 +633,10 @@ div.sphinxsidebar {
 div.sphinxsidebarwrapper {
   position: static;
   padding: 1.3rem 1.1rem 1.2rem;
-  border: 1px solid rgba(255, 255, 255, 0.08);
+  border: 1px solid var(--cb-sidebar-border);
   border-radius: 24px;
-  background:
-    linear-gradient(180deg, rgba(255, 255, 255, 0.06), transparent 20%),
-    linear-gradient(180deg, var(--cb-nav) 0%, var(--cb-nav-2) 100%);
-  box-shadow: 0 24px 44px rgba(15, 35, 64, 0.2);
+  background: var(--cb-sidebar-bg);
+  box-shadow: var(--cb-sidebar-shadow);
 }
 
 div.sphinxsidebarwrapper .logo {
@@ -581,6 +645,44 @@ div.sphinxsidebarwrapper .logo {
   margin: 0 auto 1.5rem;
 }
 
+div.sphinxsidebarwrapper .cb-theme-toggle-wrap {
+  margin: 0 0 1.2rem;
+  padding: 0.9rem;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.06);
+}
+
+div.sphinxsidebarwrapper .cb-theme-toggle-wrap h4 {
+  margin-top: 0;
+}
+
+div.sphinxsidebarwrapper .cb-theme-toggle {
+  width: 100%;
+  padding: 0.72rem 0.9rem;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  border-radius: 14px;
+  background: rgba(255, 255, 255, 0.12);
+  color: #fff;
+  font: inherit;
+  font-size: 0.94rem;
+  font-weight: 700;
+  text-align: left;
+  cursor: pointer;
+  transition: background-color 140ms ease, border-color 140ms ease, transform 140ms ease;
+}
+
+div.sphinxsidebarwrapper .cb-theme-toggle:hover {
+  background: rgba(255, 255, 255, 0.18);
+  border-color: rgba(255, 255, 255, 0.24);
+  transform: translateY(-1px);
+}
+
+div.sphinxsidebarwrapper .cb-theme-toggle:focus-visible {
+  outline: 2px solid rgba(255, 130, 0, 0.9);
+  outline-offset: 2px;
+}
+
 div.sphinxsidebarwrapper h3,
 div.sphinxsidebarwrapper h4 {
   margin: 1.25rem 0 0.55rem;
@@ -728,8 +830,8 @@ div.footer a {
 @media only screen and (max-width: 720px) {
   body {
     background:
-      radial-gradient(circle at top right, rgba(255, 130, 0, 0.08), transparent 14rem),
-      linear-gradient(180deg, #f7fafd 0%, var(--cb-bg) 12rem, var(--cb-bg) 100%);
+      radial-gradient(circle at top right, var(--cb-page-glow), transparent 14rem),
+      linear-gradient(180deg, var(--cb-bg-top) 0%, var(--cb-bg) 12rem, var(--cb-bg) 100%);
   }
 
   div.related ul {
diff --git a/docs/source/_static/js/cb_theme.js b/docs/source/_static/js/cb_theme.js
new file mode 100644
index 0000000..6069226
--- /dev/null
+++ b/docs/source/_static/js/cb_theme.js
@@ -0,0 +1,97 @@
+(function () {
+  var STORAGE_KEY = "cb-docs-theme";
+  var root = document.documentElement;
+
+  function readStoredTheme() {
+    try {
+      var stored = window.localStorage.getItem(STORAGE_KEY);
+      if (stored === "light" || stored === "dark") {
+        return stored;
+      }
+    } catch (error) {
+      return "light";
+    }
+
+    return "light";
+  }
+
+  function currentTheme() {
+    return root.getAttribute("data-theme") === "dark" ? "dark" : "light";
+  }
+
+  function nextTheme(theme) {
+    return theme === "dark" ? "light" : "dark";
+  }
+
+  function applyTheme(theme, persist) {
+    root.setAttribute("data-theme", theme);
+    root.style.colorScheme = theme;
+
+    if (persist) {
+      try {
+        window.localStorage.setItem(STORAGE_KEY, theme);
+      } catch (error) {
+        /* Ignore storage failures. */
+      }
+    }
+
+    syncToggleButton();
+  }
+
+  function syncToggleButton() {
+    var button = document.querySelector(".cb-theme-toggle");
+    if (!button) {
+      return;
+    }
+
+    var theme = currentTheme();
+    var targetTheme = nextTheme(theme);
+    button.textContent = targetTheme === "dark" ? "Switch to dark mode" : "Switch to light mode";
+    button.setAttribute("aria-label", button.textContent);
+    button.setAttribute("aria-pressed", theme === "dark" ? "true" : "false");
+    button.setAttribute("data-theme-target", targetTheme);
+  }
+
+  function handleToggleClick() {
+    applyTheme(nextTheme(currentTheme()), true);
+  }
+
+  function mountToggle() {
+    var sidebar = document.querySelector(".sphinxsidebarwrapper");
+    if (!sidebar || sidebar.querySelector(".cb-theme-toggle-wrap")) {
+      syncToggleButton();
+      return;
+    }
+
+    var section = document.createElement("div");
+    section.className = "cb-theme-toggle-wrap";
+
+    var heading = document.createElement("h4");
+    heading.textContent = "Theme";
+
+    var button = document.createElement("button");
+    button.type = "button";
+    button.className = "cb-theme-toggle";
+    button.addEventListener("click", handleToggleClick);
+
+    section.appendChild(heading);
+    section.appendChild(button);
+
+    var logoBlock = sidebar.querySelector("p.logo");
+    if (logoBlock && logoBlock.parentNode) {
+      logoBlock.insertAdjacentElement("afterend", section);
+    } else {
+      sidebar.insertBefore(section, sidebar.firstChild);
+    }
+
+    syncToggleButton();
+  }
+
+  applyTheme(readStoredTheme(), false);
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", mountToggle);
+  } else {
+    mountToggle();
+  }
+})();
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 284d43b..ccc8859 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -45,6 +45,9 @@
 html_css_files = [
     'css/cb_theme.css',
 ]
+html_js_files = [
+    'js/cb_theme.js',
+]
 
 # Disable link "index"
 html_use_index = False

From ac7fe0597666635bd33839f9f58878db1f473e1c Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Tue, 19 May 2026 11:56:48 +0200
Subject: [PATCH 3/8] * Moved the sticky breadcrumb to the top of the window
 and removed the empty space below the footer. * Moved the dark mode toggle
 from the sidebar to the breadcrumb and implemented it as a compact icon. *
 Improved anchor scroll behavior for headings so that target headings are no
 longer obscured by the sticky breadcrumb. * Made the Table of Contents
 sidebar scrollable independently on desktop. * Hidden the visible scrollbar
 of the TOC sidebar while keeping scrolling functionality intact. * Added
 additional bottom spacing to the sidebar on a trial basis and subsequently
 removed it. * Significantly reduced the indentation of nested TOC levels so
 that deep entries wrap later.

---
 docs/source/_static/css/cb_theme.css | 147 +++++++++++++++++++--------
 docs/source/_static/js/cb_theme.js   |  35 +++----
 2 files changed, 122 insertions(+), 60 deletions(-)

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index e0b9675..3213a41 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -52,6 +52,9 @@
   --cb-blockquote-border: rgba(255, 130, 0, 0.5);
   --cb-headerlink-hover-bg: var(--cb-nav);
   --cb-shadow: 0 18px 48px rgba(16, 38, 63, 0.09);
+  --cb-anchor-offset: 4.75rem;
+  --cb-sidebar-top: 5.5rem;
+  --cb-sidebar-bottom-gap: 2rem;
 }
 
 html[data-theme="dark"] {
@@ -103,6 +106,15 @@ html {
   scroll-behavior: smooth;
 }
 
+section[id],
+span[id],
+dt[id],
+caption[id],
+figure[id],
+table[id] {
+  scroll-margin-top: var(--cb-anchor-offset);
+}
+
 body {
   margin: 0;
   background:
@@ -152,10 +164,11 @@ div.related {
 }
 
 div.related:first-of-type {
-  margin-top: 1rem;
+  margin-top: 0;
 }
 
 div.related ul {
+  position: relative;
   display: flex;
   align-items: center;
   flex-wrap: wrap;
@@ -227,6 +240,75 @@ div.related li.right a:hover {
   text-decoration: none;
 }
 
+div.related .cb-theme-toggle-item {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  margin: 0;
+  transform: translate(-50%, -50%);
+  z-index: 1;
+  pointer-events: none;
+}
+
+div.related .cb-theme-toggle {
+  position: relative;
+  width: 1.95rem;
+  height: 1.95rem;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--cb-heading);
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+div.related .cb-theme-toggle::before {
+  content: "";
+  position: absolute;
+  inset: 0.12rem;
+  border: 2px solid currentColor;
+  border-radius: 50%;
+  background: linear-gradient(90deg, currentColor 0 50%, transparent 50% 100%);
+}
+
+div.related .cb-theme-toggle::after {
+  content: "";
+  position: absolute;
+  top: 0.24rem;
+  bottom: 0.24rem;
+  left: 50%;
+  width: 2px;
+  border-radius: 999px;
+  background: currentColor;
+  transform: translateX(-50%);
+}
+
+div.related .cb-theme-toggle[aria-pressed="true"]::before {
+  background: linear-gradient(90deg, transparent 0 50%, currentColor 50% 100%);
+}
+
+div.related .cb-theme-toggle:hover {
+  color: var(--cb-link-hover);
+}
+
+div.related .cb-theme-toggle:focus-visible {
+  outline: 2px solid rgba(255, 130, 0, 0.9);
+  outline-offset: 2px;
+}
+
+.cb-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 div.documentwrapper {
   float: none;
   grid-column: 2;
@@ -620,7 +702,7 @@ div.sphinxsidebar {
   grid-column: 1;
   grid-row: 1;
   position: sticky;
-  top: 5.5rem;
+  top: var(--cb-sidebar-top);
   float: none;
   width: auto;
   margin: 2rem 0 2rem 1.5rem;
@@ -637,6 +719,16 @@ div.sphinxsidebarwrapper {
   border-radius: 24px;
   background: var(--cb-sidebar-bg);
   box-shadow: var(--cb-sidebar-shadow);
+  max-height: calc(100vh - var(--cb-sidebar-top) - var(--cb-sidebar-bottom-gap));
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+div.sphinxsidebarwrapper::-webkit-scrollbar {
+  width: 0;
+  height: 0;
 }
 
 div.sphinxsidebarwrapper .logo {
@@ -645,44 +737,6 @@ div.sphinxsidebarwrapper .logo {
   margin: 0 auto 1.5rem;
 }
 
-div.sphinxsidebarwrapper .cb-theme-toggle-wrap {
-  margin: 0 0 1.2rem;
-  padding: 0.9rem;
-  border: 1px solid rgba(255, 255, 255, 0.1);
-  border-radius: 18px;
-  background: rgba(255, 255, 255, 0.06);
-}
-
-div.sphinxsidebarwrapper .cb-theme-toggle-wrap h4 {
-  margin-top: 0;
-}
-
-div.sphinxsidebarwrapper .cb-theme-toggle {
-  width: 100%;
-  padding: 0.72rem 0.9rem;
-  border: 1px solid rgba(255, 255, 255, 0.18);
-  border-radius: 14px;
-  background: rgba(255, 255, 255, 0.12);
-  color: #fff;
-  font: inherit;
-  font-size: 0.94rem;
-  font-weight: 700;
-  text-align: left;
-  cursor: pointer;
-  transition: background-color 140ms ease, border-color 140ms ease, transform 140ms ease;
-}
-
-div.sphinxsidebarwrapper .cb-theme-toggle:hover {
-  background: rgba(255, 255, 255, 0.18);
-  border-color: rgba(255, 255, 255, 0.24);
-  transform: translateY(-1px);
-}
-
-div.sphinxsidebarwrapper .cb-theme-toggle:focus-visible {
-  outline: 2px solid rgba(255, 130, 0, 0.9);
-  outline-offset: 2px;
-}
-
 div.sphinxsidebarwrapper h3,
 div.sphinxsidebarwrapper h4 {
   margin: 1.25rem 0 0.55rem;
@@ -717,7 +771,7 @@ div.sphinxsidebarwrapper ul {
 
 div.sphinxsidebarwrapper ul ul {
   margin-top: 0.25rem;
-  padding-left: 0.9rem;
+  padding-left: 0.45rem;
 }
 
 div.sphinxsidebarwrapper li {
@@ -786,8 +840,8 @@ div.sphinxsidebarwrapper form.search input[type="submit"] {
 div.footer {
   width: auto;
   box-sizing: border-box;
-  margin: 0 1.5rem 2rem;
-  padding: 1.1rem 1.25rem 0;
+  margin: 0 1.5rem 0;
+  padding: 1.1rem 1.25rem 2rem;
   color: var(--cb-text-muted);
   text-align: right;
 }
@@ -814,6 +868,8 @@ div.footer a {
 
   div.sphinxsidebarwrapper {
     position: static;
+    max-height: none;
+    overflow-y: visible;
   }
 
   div.bodywrapper {
@@ -842,6 +898,11 @@ div.footer a {
     font-size: 0.86rem;
   }
 
+  div.related .cb-theme-toggle {
+    width: 1.75rem;
+    height: 1.75rem;
+  }
+
   div.bodywrapper div.body {
     padding: 1.8rem 1.15rem;
     border-radius: 18px;
diff --git a/docs/source/_static/js/cb_theme.js b/docs/source/_static/js/cb_theme.js
index 6069226..663bc0e 100644
--- a/docs/source/_static/js/cb_theme.js
+++ b/docs/source/_static/js/cb_theme.js
@@ -46,8 +46,15 @@
 
     var theme = currentTheme();
     var targetTheme = nextTheme(theme);
-    button.textContent = targetTheme === "dark" ? "Switch to dark mode" : "Switch to light mode";
-    button.setAttribute("aria-label", button.textContent);
+    var label = targetTheme === "dark" ? "Switch to dark mode" : "Switch to light mode";
+    var hiddenText = button.querySelector(".cb-visually-hidden");
+
+    if (hiddenText) {
+      hiddenText.textContent = label;
+    }
+
+    button.setAttribute("aria-label", label);
+    button.setAttribute("title", label);
     button.setAttribute("aria-pressed", theme === "dark" ? "true" : "false");
     button.setAttribute("data-theme-target", targetTheme);
   }
@@ -57,32 +64,26 @@
   }
 
   function mountToggle() {
-    var sidebar = document.querySelector(".sphinxsidebarwrapper");
-    if (!sidebar || sidebar.querySelector(".cb-theme-toggle-wrap")) {
+    var relatedNav = document.querySelector(".related ul");
+    if (!relatedNav || relatedNav.querySelector(".cb-theme-toggle-item")) {
       syncToggleButton();
       return;
     }
 
-    var section = document.createElement("div");
-    section.className = "cb-theme-toggle-wrap";
-
-    var heading = document.createElement("h4");
-    heading.textContent = "Theme";
+    var item = document.createElement("li");
+    item.className = "cb-theme-toggle-item";
 
     var button = document.createElement("button");
     button.type = "button";
     button.className = "cb-theme-toggle";
     button.addEventListener("click", handleToggleClick);
 
-    section.appendChild(heading);
-    section.appendChild(button);
+    var hiddenText = document.createElement("span");
+    hiddenText.className = "cb-visually-hidden";
+    button.appendChild(hiddenText);
 
-    var logoBlock = sidebar.querySelector("p.logo");
-    if (logoBlock && logoBlock.parentNode) {
-      logoBlock.insertAdjacentElement("afterend", section);
-    } else {
-      sidebar.insertBefore(section, sidebar.firstChild);
-    }
+    item.appendChild(button);
+    relatedNav.appendChild(item);
 
     syncToggleButton();
   }

From 1257a1f394f9b95cd80fc9d4cacaae79f23e3195 Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Mon, 1 Jun 2026 16:55:55 +0200
Subject: [PATCH 4/8] The footnote layout now aligns with its description text.

---
 docs/source/_static/css/cb_theme.css | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 3213a41..61438cf 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -538,6 +538,24 @@ div.bodywrapper .body span.caption-text {
   font-size: 0.96rem;
 }
 
+div.bodywrapper .body aside.footnote {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5em;
+}
+
+div.bodywrapper .body aside.footnote > span.label {
+  flex: 0 0 auto;
+  float: none;
+  padding-right: 0;
+  line-height: 1.3;
+}
+
+div.bodywrapper .body aside.footnote > p {
+  flex: 1 1 auto;
+  margin: 0;
+}
+
 div.bodywrapper .body table.docutils,
 div.bodywrapper .body table {
   width: 100%;

From affb6d29677bfaed39b8b138c6512078c5b8046f Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Mon, 1 Jun 2026 17:08:51 +0200
Subject: [PATCH 5/8] Reduced corner radious from 18 to 8px.

---
 docs/source/_static/css/cb_theme.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 61438cf..3543ef1 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -521,7 +521,7 @@ div.bodywrapper .body .highlight .go {
 
 div.bodywrapper .body img {
   max-width: 100%;
-  border-radius: 18px;
+  border-radius: 8px;
   background: var(--cb-surface-muted);
 }
 

From f740d5e0e958e8a067773a3303898ec86eab16f1 Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Mon, 1 Jun 2026 17:12:33 +0200
Subject: [PATCH 6/8] Image captions and images now all centered.

---
 docs/source/_static/css/cb_theme.css | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 3543ef1..2b116aa 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -529,6 +529,21 @@ div.bodywrapper .body figure,
 div.bodywrapper .body div.figure,
 div.bodywrapper .body .figure {
   margin: 2rem 0;
+  text-align: center;
+}
+
+div.bodywrapper .body figure > a.image-reference,
+div.bodywrapper .body div.figure > a.image-reference,
+div.bodywrapper .body .figure > a.image-reference {
+  display: inline-block;
+}
+
+div.bodywrapper .body figure img,
+div.bodywrapper .body div.figure img,
+div.bodywrapper .body .figure img {
+  display: block;
+  margin-right: auto;
+  margin-left: auto;
 }
 
 div.bodywrapper .body .caption,
@@ -538,6 +553,13 @@ div.bodywrapper .body span.caption-text {
   font-size: 0.96rem;
 }
 
+div.bodywrapper .body figure figcaption,
+div.bodywrapper .body figure figcaption p,
+div.bodywrapper .body div.figure p.caption,
+div.bodywrapper .body .figure p.caption {
+  text-align: center;
+}
+
 div.bodywrapper .body aside.footnote {
   display: flex;
   align-items: baseline;

From 465548beaeff6c9625331d203c11b6ee8bc347e8 Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Tue, 2 Jun 2026 08:39:24 +0200
Subject: [PATCH 7/8] Tweaking tables.

---
 docs/source/_static/css/cb_theme.css | 29 +++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 2b116aa..738c75e 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -580,26 +580,37 @@ div.bodywrapper .body aside.footnote > p {
 
 div.bodywrapper .body table.docutils,
 div.bodywrapper .body table {
+  display: block;
   width: 100%;
+  max-width: 100%;
   table-layout: fixed;
-  overflow: hidden;
+  overflow-x: auto;
+  white-space: nowrap;
+  -webkit-overflow-scrolling: touch;
   border: 1px solid var(--cb-border);
   border-collapse: separate;
   border-spacing: 0;
   border-radius: 18px;
   background: var(--cb-surface);
+  font-size: 0.9rem;
 }
 
 div.bodywrapper .body table.docutils caption,
 div.bodywrapper .body table caption {
   caption-side: bottom;
+  position: sticky;
+  left: 0;
+  display: block;
+  width: 100%;
   padding-top: 0.75rem;
+  white-space: normal;
+  text-align: center;
 }
 
 div.bodywrapper .body table.docutils th,
 div.bodywrapper .body table th,
 div.bodywrapper .body dl.field-list > dt {
-  padding: 0.95rem 1rem;
+  padding: 0.7rem 0.75rem;
   border-bottom: 1px solid var(--cb-border);
   background: var(--cb-table-head-bg);
   background-clip: padding-box;
@@ -624,7 +635,7 @@ div.bodywrapper .body table tr:first-child td:last-child {
 div.bodywrapper .body table.docutils td,
 div.bodywrapper .body table td,
 div.bodywrapper .body dl.field-list > dd {
-  padding: 0.9rem 1rem;
+  padding: 0.65rem 0.75rem;
   border-bottom: 1px solid var(--cb-border);
   overflow-wrap: anywhere;
   word-break: break-word;
@@ -633,8 +644,16 @@ div.bodywrapper .body dl.field-list > dd {
 
 div.bodywrapper .body table.docutils th,
 div.bodywrapper .body table th {
-  overflow-wrap: anywhere;
-  word-break: break-word;
+  overflow-wrap: normal;
+  word-break: normal;
+  hyphens: none;
+}
+
+div.bodywrapper .body table.docutils td,
+div.bodywrapper .body table td {
+  overflow-wrap: normal;
+  word-break: normal;
+  hyphens: none;
 }
 
 div.bodywrapper .body table.docutils td a,

From dda5c645d4ab330e3adbb782c2ed3e556131d126 Mon Sep 17 00:00:00 2001
From: Simon Seres <simon@nymea.io>
Date: Tue, 2 Jun 2026 16:36:15 +0200
Subject: [PATCH 8/8] More tweaks for tables.

---
 docs/source/_static/css/cb_theme.css | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css
index 738c75e..38d8682 100644
--- a/docs/source/_static/css/cb_theme.css
+++ b/docs/source/_static/css/cb_theme.css
@@ -468,7 +468,7 @@ div.bodywrapper .body code {
 div.bodywrapper .body pre,
 div.bodywrapper .body div.highlight {
   border: 1px solid var(--cb-code-block-border);
-  border-radius: 18px;
+  border-radius: 8px;
   background: var(--cb-code-bg);
   box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.06);
 }
@@ -581,16 +581,16 @@ div.bodywrapper .body aside.footnote > p {
 div.bodywrapper .body table.docutils,
 div.bodywrapper .body table {
   display: block;
-  width: 100%;
+  width: fit-content;
   max-width: 100%;
-  table-layout: fixed;
+  table-layout: auto;
   overflow-x: auto;
   white-space: nowrap;
   -webkit-overflow-scrolling: touch;
   border: 1px solid var(--cb-border);
   border-collapse: separate;
   border-spacing: 0;
-  border-radius: 18px;
+  border-radius: 8px;
   background: var(--cb-surface);
   font-size: 0.9rem;
 }
@@ -602,6 +602,7 @@ div.bodywrapper .body table caption {
   left: 0;
   display: block;
   width: 100%;
+  box-sizing: border-box;
   padding-top: 0.75rem;
   white-space: normal;
   text-align: center;
@@ -622,14 +623,14 @@ div.bodywrapper .body table.docutils tr:first-child th:first-child,
 div.bodywrapper .body table.docutils tr:first-child td:first-child,
 div.bodywrapper .body table tr:first-child th:first-child,
 div.bodywrapper .body table tr:first-child td:first-child {
-  border-top-left-radius: 18px;
+  border-top-left-radius: 8px;
 }
 
 div.bodywrapper .body table.docutils tr:first-child th:last-child,
 div.bodywrapper .body table.docutils tr:first-child td:last-child,
 div.bodywrapper .body table tr:first-child th:last-child,
 div.bodywrapper .body table tr:first-child td:last-child {
-  border-top-right-radius: 18px;
+  border-top-right-radius: 8px;
 }
 
 div.bodywrapper .body table.docutils td,