@conduction/docusaurus-preset 2.6.1 → 2.7.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "2.6.1",
+  "version": "2.7.0-beta.2",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js"
   },

package/src/components/DetailHero/DetailHero.jsx

@@ -147,6 +147,7 @@ export default function DetailHero({
                   variant="primary"
                   tone={primaryCta.tone}
                   href={primaryCta.href}
+                  icon={primaryCta.icon}
                 >
                   {primaryCta.label}
                 </Button>
@@ -156,11 +157,26 @@ export default function DetailHero({
                   variant="secondary"
                   tone={secondaryCta.tone}
                   href={secondaryCta.href}
+                  icon={secondaryCta.icon}
                 >
                   {secondaryCta.label}
                 </Button>
               )}
-              {tertiaryCta && <Button variant="ghost" href={tertiaryCta.href}>{tertiaryCta.label} →</Button>}
+              {tertiaryCta && (
+                /* On a cobalt-bg hero the default ghost variant
+                   (cobalt-700 text) disappears against the dark panel;
+                   auto-switch to on-dark-tertiary (white text + white
+                   border) so the CTA reads at parity with the primary
+                   and secondary buttons. Sites can still pass an
+                   explicit `variant` to opt out. */
+                <Button
+                  variant={tertiaryCta.variant || (background === 'cobalt' ? 'on-dark-tertiary' : 'ghost')}
+                  href={tertiaryCta.href}
+                  icon={tertiaryCta.icon}
+                >
+                  {tertiaryCta.label} →
+                </Button>
+              )}
             </div>
           )}
         </div>

package/src/components/primitives/Button.jsx

@@ -1,33 +1,45 @@
 /**
  * <Button />
  *
- * Three brand variants (primary / secondary / ghost) used across hero,
- * cta-banner, top-navbar, game-modal, and per-page CTA rows.
+ * Brand variants used across hero, cta-banner, top-navbar, game-modal,
+ * and per-page CTA rows.
  *
  * Renders as <a> when href is provided, <button> otherwise. Inherits
  * the brand transition (140ms ease) and KNVB-orange focus ring from
  * brand.css.
  *
  * Variants:
- *   - primary:    cobalt fill, white text
- *   - secondary:  white bg, cobalt-200 border, cobalt text
- *   - ghost:      plain text + arrow
- *   - on-dark:    primary variant inverted for use inside cobalt CTA panels
+ *   - primary:             cobalt fill, white text
+ *   - secondary:           white bg, cobalt-200 border, cobalt text
+ *   - ghost:               plain text + arrow, for on-white surfaces
+ *   - on-dark-primary:     primary inverted for use on cobalt CTA panels
+ *   - on-dark-secondary:   ghost-style with white-translucent border, on cobalt
+ *   - on-dark-tertiary:    transparent fill, solid white border + white text,
+ *                          for the "View on GitHub" CTA on cobalt-bg heroes
  *
  * Tone (optional): override the primary/secondary fill colour. The
  * brand default is cobalt; product pages with an orange-accent identity
  * (e.g. mydash) pass `tone="orange"` to flip the primary CTA to
  * KNVB-orange while keeping the rest of the brand chrome intact.
  *
+ * Icon (optional): pass a key from icons.jsx (e.g. `"github"`) or a
+ * React node directly. The icon sits inline before the label and
+ * inherits the button's font-size + colour.
+ *
  * Usage:
  *
  *   <Button href="/apps">Install</Button>
  *   <Button variant="secondary" href="/partners">Get a demo</Button>
  *   <Button variant="ghost" href="https://github.com/...">View on GitHub →</Button>
- *   <Button tone="orange" href="/install">Install from app store</Button>
+ *   <Button
+ *     variant="on-dark-tertiary"
+ *     icon="github"
+ *     href="https://github.com/ConductionNL/shillinq"
+ *   >View on GitHub</Button>
  */
 
 import React from 'react';
+import {ICONS} from './icons';
 import styles from './Button.module.css';
 
 export default function Button({
@@ -35,6 +47,7 @@ export default function Button({
   tone,
   href,
   size = 'md',
+  icon,
   className,
   children,
   ...rest
@@ -47,8 +60,18 @@ export default function Button({
     className,
   ].filter(Boolean).join(' ');
 
+  /* Icon: accept a string key (looked up in ICONS) or a React node
+     directly. The wrapping span lets us apply consistent inline metrics
+     without forcing every caller to size their SVG. */
+  const iconNode = typeof icon === 'string' ? ICONS[icon] : icon;
+  const iconEl = iconNode ? (
+    <span className={styles.icon} aria-hidden="true">{iconNode}</span>
+  ) : null;
+
+  const body = <>{iconEl}{children}</>;
+
   if (href) {
-    return <a href={href} className={composed} {...rest}>{children}</a>;
+    return <a href={href} className={composed} {...rest}>{body}</a>;
   }
-  return <button type="button" className={composed} {...rest}>{children}</button>;
+  return <button type="button" className={composed} {...rest}>{body}</button>;
 }

package/src/components/primitives/Button.module.css

@@ -17,6 +17,22 @@
   font-family: inherit;
 }
 
+/* Inline icon slot. SVG renders at 1em × 1em via icons.jsx, so it
+   scales with the button's font-size. The wrapping span keeps the
+   icon vertically centred even when the label wraps. */
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  line-height: 1;
+  font-size: 1.05em;
+}
+.icon :global(svg) {
+  width: 1em;
+  height: 1em;
+  display: block;
+}
+
 .s-sm { padding: 9px 14px; font-size: 13px; }
 .s-md { padding: 13px 22px; font-size: 15px; }
 .s-lg { padding: 16px 28px; font-size: 16px; }
@@ -84,6 +100,24 @@
   color: white;
 }
 
+/* On-dark tertiary: the "View on GitHub" CTA that sits next to the
+   primary/secondary buttons on a cobalt-bg DetailHero. Transparent
+   fill, solid white border, white text — readable on cobalt-900 and
+   visually weighted below the primary/secondary CTAs without resorting
+   to the ghost variant (which is cobalt-700 text and disappears on
+   the dark hero). */
+.v-on-dark-tertiary {
+  background: transparent;
+  color: white;
+  border-color: white;
+}
+.v-on-dark-tertiary:hover {
+  background: rgba(255, 255, 255, 0.12);
+  color: white;
+  border-color: white;
+  text-decoration: none;
+}
+
 .v-on-dark-primary :global(.next-blue),
 .v-primary :global(.next-blue) { color: var(--c-nextcloud-cyan); }
 

package/src/components/primitives/icons.jsx

@@ -0,0 +1,64 @@
+/**
+ * Brand icon set.
+ *
+ * Single source of truth for the SVG glyphs used in the brand chrome
+ * (Button, Navbar, hero CTAs). Each icon renders at 1em × 1em with
+ * `currentColor`, so it inherits the surrounding font size and colour
+ * automatically — pass it inside a Button or link and it lines up
+ * without extra styling.
+ *
+ *   <Icon name="github" />
+ *   <Button icon="github" variant="on-dark-tertiary" href={...}>View on GitHub</Button>
+ *
+ * Adding a new icon: define the React node in ICONS below, keep the
+ * viewBox at 0 0 24 24, and use stroke or fill — never both with
+ * different colours, so currentColor stays the single ink.
+ */
+
+import React from 'react';
+
+export const ICONS = {
+  /* Official GitHub mark, simplified to a single filled path so it
+     reads cleanly at 14–20px. Source: github.com/logos. */
+  github: (
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.57.1.78-.25.78-.55v-2.16c-3.2.69-3.87-1.36-3.87-1.36-.52-1.33-1.27-1.69-1.27-1.69-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.02 1.75 2.68 1.25 3.34.95.1-.74.4-1.25.73-1.54-2.55-.29-5.23-1.28-5.23-5.69 0-1.26.45-2.28 1.18-3.09-.12-.29-.51-1.46.11-3.05 0 0 .97-.31 3.18 1.18a11 11 0 015.8 0c2.2-1.49 3.17-1.18 3.17-1.18.63 1.59.23 2.76.11 3.05.74.81 1.18 1.83 1.18 3.09 0 4.42-2.69 5.4-5.25 5.68.41.36.78 1.06.78 2.13v3.16c0 .3.21.66.79.55C20.21 21.39 23.5 17.08 23.5 12 23.5 5.65 18.35.5 12 .5z"/>
+    </svg>
+  ),
+
+  /* API / OpenAPI reference. A stylised open book with a small
+     keyhole, matches the Redocusaurus reference mock at
+     preview/product-pages/api-reference.html. */
+  apiDocs: (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M4 4h6a2 2 0 012 2v14a2 2 0 00-2-2H4z"/>
+      <path d="M20 4h-6a2 2 0 00-2 2v14a2 2 0 012-2h6z"/>
+      <path d="M8 9h2M8 13h2M16 9h-2M16 13h-2"/>
+    </svg>
+  ),
+
+  /* Generic right arrow used by ghost CTAs. Wrapped in this set so the
+     hero CTA can compose `View on GitHub` + `→` with consistent inline
+     metrics on any font-size. */
+  arrowRight: (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <line x1="5" y1="12" x2="19" y2="12"/>
+      <polyline points="13 6 19 12 13 18"/>
+    </svg>
+  ),
+};
+
+/**
+ * Render a brand icon by name (string key from ICONS). Sized 1em × 1em
+ * via inline style; pass extra CSS via `className`. If the caller wants
+ * a custom icon, they can render any React node directly — the helper
+ * is just a convenience.
+ */
+export default function Icon({name, className, style}) {
+  const node = ICONS[name];
+  if (!node) return null;
+  return React.cloneElement(node, {
+    className,
+    style: {width: '1em', height: '1em', display: 'inline-block', flexShrink: 0, ...style},
+  });
+}

package/src/css/brand.css

@@ -156,3 +156,157 @@ a:not(.navbar__link):not(.footer__link-item):not(.button) {
 a:not(.navbar__link):not(.footer__link-item):not(.button):hover {
   text-decoration-color: var(--c-orange-knvb);
 }
+
+/* =========================================================================
+   Docs-page styling — mirror preview/product-pages/_docs-shell.css
+
+   The Docusaurus defaults (Infima) ship a cramped sidebar, Title-Case
+   menu items, and an aggressive vertical rhythm. The design-system
+   product-page mocks define a calmer treatment: a 280px sidebar, code-
+   typeface group labels, a left-border active state on cobalt-50, and a
+   900px content column with a 40/26/22 px heading scale at 1.65 body
+   line-height. These overrides pull the live docs deploys (shillinq,
+   openregister, …) into line with the mocks.
+   ========================================================================= */
+
+/* Sidebar: 280px column with a 1px cobalt-100 right edge. */
+.theme-doc-sidebar-container {
+  width: 280px !important;
+  border-right: 1px solid var(--c-cobalt-100) !important;
+  background: white;
+}
+
+/* Menu list typography + spacing */
+.menu {
+  padding: var(--space-6) var(--space-5) !important;
+  font-size: 13px;
+}
+.menu__list .menu__list {
+  padding-left: var(--space-3);
+  margin-left: 0;
+}
+.menu__list-item {
+  margin: 0;
+}
+
+/* Default link state: idle sentence-case cobalt-700 on white,
+   4-px-radius hover tint cobalt-50. */
+.menu__link {
+  color: var(--c-cobalt-700);
+  padding: 4px 10px;
+  border-radius: var(--radius-sm);
+  margin-bottom: 2px;
+  font-weight: 400;
+  line-height: 1.4;
+}
+.menu__link:hover {
+  background: var(--c-cobalt-50);
+  color: var(--c-cobalt-900);
+}
+
+/* Active item: 2-px cobalt left border + cobalt-50 fill + cobalt-blue text.
+   The padding tweak compensates for the border so the label stays
+   aligned with the idle siblings above and below. */
+.menu__link--active,
+.menu__link--active:hover {
+  background: var(--c-cobalt-50);
+  color: var(--c-blue-cobalt);
+  font-weight: 500;
+  border-left: 2px solid var(--c-blue-cobalt);
+  padding-left: 8px;
+}
+
+/* Category headers (Features / Integrations / Technical groups) get
+   the code-typeface uppercase eyebrow treatment, matching the
+   `.docs-sidebar .group` rule in the mock. */
+.menu__list-item-collapsible > .menu__link,
+.menu__link--sublist {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--c-cobalt-400);
+  font-weight: 500;
+  margin: var(--space-4) 0 var(--space-2);
+}
+.menu__list-item-collapsible > .menu__link:hover {
+  background: transparent;
+  color: var(--c-cobalt-700);
+}
+
+/* Caret on collapsible categories — desaturate to cobalt-300. */
+.menu__caret::before,
+.menu__link--sublist-caret::after {
+  filter: opacity(0.5);
+}
+
+/* Content column: 900px max width, generous padding, brand type scale.
+   We avoid touching the global .markdown selector (it'd hit MDX pages
+   too); scope to the doc-item container instead. */
+.theme-doc-markdown {
+  max-width: 900px;
+  padding: var(--space-8) var(--space-10);
+}
+.theme-doc-markdown h1 {
+  font-size: 40px;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  line-height: 1.1;
+  margin: 0 0 var(--space-4);
+  color: var(--c-cobalt-900);
+}
+.theme-doc-markdown h2 {
+  font-size: 26px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin: var(--space-8) 0 var(--space-3);
+  color: var(--c-cobalt-900);
+}
+.theme-doc-markdown h3 {
+  font-size: 20px;
+  font-weight: 600;
+  margin: var(--space-6) 0 var(--space-3);
+  color: var(--c-cobalt-900);
+}
+.theme-doc-markdown p,
+.theme-doc-markdown ul,
+.theme-doc-markdown ol {
+  font-size: 15px;
+  line-height: 1.65;
+  color: var(--c-cobalt-800);
+  margin: 0 0 var(--space-3);
+}
+.theme-doc-markdown ul,
+.theme-doc-markdown ol {
+  padding-left: var(--space-5);
+}
+.theme-doc-markdown li {
+  margin-bottom: var(--space-2);
+}
+.theme-doc-markdown strong {
+  color: var(--c-cobalt-900);
+}
+
+/* Code-typeface breadcrumb above the H1. Docusaurus renders this
+   via the DocBreadcrumbs component; we restyle in-place. */
+.theme-doc-breadcrumbs {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--c-cobalt-400);
+  margin-bottom: var(--space-4);
+}
+.theme-doc-breadcrumbs .breadcrumbs__link {
+  color: var(--c-cobalt-400);
+  background: transparent;
+  padding: 0;
+}
+.theme-doc-breadcrumbs .breadcrumbs__link:hover {
+  color: var(--c-orange-knvb);
+  background: transparent;
+}
+.theme-doc-breadcrumbs .breadcrumbs__item--active .breadcrumbs__link {
+  color: var(--c-cobalt-700);
+  background: transparent;
+}

package/src/css/tokens.css

@@ -192,7 +192,9 @@
   --space-4:  16px;
   --space-5:  20px;
   --space-6:  24px;
+  --space-7:  28px;
   --space-8:  32px;
+  --space-9:  36px;
   --space-10: 40px;
   --space-12: 48px;
   --space-16: 64px;

package/src/index.js

@@ -21,6 +21,56 @@
  */
 
 const path = require('path');
+const fs = require('fs');
+
+/**
+ * Resolve the app version that drives the navbar "Stable · v{x.y.z}"
+ * pill. Order of precedence:
+ *
+ *   1. opts.appVersion (explicit override)
+ *   2. appinfo/info.xml <version> tag (Nextcloud app convention; every
+ *      app in the Conduction fleet has one)
+ *   3. package.json version (sites without an info.xml — Hydra,
+ *      design-system itself, conduction-website)
+ *   4. undefined (pill is hidden by the Navbar swizzle)
+ *
+ * The resolver runs at config build-time inside `process.cwd()`, which
+ * is the consuming site's repo root. Failures are swallowed silently so
+ * a missing info.xml never breaks the site build — the pill just hides.
+ */
+function resolveAppVersion(opts) {
+  if (opts.appVersion) return String(opts.appVersion);
+
+  /* Nextcloud apps: appinfo/info.xml carries the canonical version.
+     We avoid pulling in an XML parser for one tag — a non-greedy regex
+     against the file content is robust enough for the standard
+     `<version>x.y.z</version>` shape the app store mandates. */
+  try {
+    const infoPath = path.join(process.cwd(), 'appinfo', 'info.xml');
+    if (fs.existsSync(infoPath)) {
+      const xml = fs.readFileSync(infoPath, 'utf8');
+      const m = xml.match(/<version>\s*([^<\s]+)\s*<\/version>/);
+      if (m && m[1]) return m[1];
+    }
+  } catch (e) {
+    /* fall through */
+  }
+
+  /* Non-Nextcloud sites: package.json version. Walks up from cwd in
+     case the site builds from a sub-directory; one level deep is
+     enough for the conduction-website layout. */
+  try {
+    const pkgPath = path.join(process.cwd(), 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.version) return pkg.version;
+    }
+  } catch (e) {
+    /* fall through */
+  }
+
+  return undefined;
+}
 
 /**
  * Brand-default i18n block. Nederlands at the URL root, others at /en/, /de/, /fr/.
@@ -39,8 +89,23 @@ const I18N = {
 /**
  * Brand-default navbar. Sites pass their own items[] and logo; the chrome
  * styling (cobalt-on-white, Plex-Mono caption) is locked.
+ *
+ * The right-side default carries the four chrome items that the brand
+ * navbar swizzle (theme/Navbar/index.jsx) renders as icons + pill:
+ *
+ *   versionPill   "Stable · v{x.y.z}" reading customFields.appVersion;
+ *                 hidden when no version is available, so non-Nextcloud
+ *                 sites get a clean navbar.
+ *   apiDocs       Book icon + "API Documentation", pointing at /api
+ *                 (Redocusaurus convention). Sites without an OpenAPI
+ *                 spec remove this item from their own config.
+ *   github        GitHub mark, opens the org GitHub by default.
+ *   localeDropdown  Existing locale switcher (nl/en/de/fr).
+ *
+ * The `opts.repoUrl` plumbing below overrides the GitHub item's href
+ * to point at the specific app repo when the site provides it.
  */
-const baseNavbar = (siteName) => ({
+const baseNavbar = (siteName, repoUrl) => ({
   title: siteName,
   logo: {
     alt: `${siteName} avatar`,
@@ -48,8 +113,10 @@ const baseNavbar = (siteName) => ({
     srcDark: 'img/logo-dark.svg',
   },
   items: [
+    { type: 'versionPill', position: 'right' },
+    { type: 'apiDocs', position: 'right' },
+    { type: 'github', href: repoUrl || 'https://github.com/ConductionNL', position: 'right' },
     { type: 'localeDropdown', position: 'right' },
-    { href: 'https://github.com/ConductionNL', label: 'GitHub', position: 'right' },
   ],
 });
 
@@ -128,6 +195,11 @@ const baseFooter = () => ({
  *   minigames (default true; set false to drop the brand canal-footer's
  *     boat-sinking + kade-cyclist mini-games on product pages while
  *     keeping the static skyline + canal decoration),
+ *   appVersion (explicit override for the navbar "Stable · v{x.y.z}"
+ *     pill; defaults to appinfo/info.xml then package.json — see
+ *     resolveAppVersion above),
+ *   repoUrl (target of the navbar GitHub icon; defaults to the
+ *     ConductionNL org root),
  *   customCss[] (appended to brand.css), plugins[], presets,
  *   i18n (overrides defaults)
  */
@@ -142,6 +214,11 @@ function createConfig(opts) {
      getClientModules(), so customCss carries site-specific CSS only. */
   const customCss = opts.customCss || [];
 
+  /* App version drives the navbar "Stable · v{x.y.z}" pill (resolved
+     once at config time). Pulled from appinfo/info.xml, then
+     package.json — see resolveAppVersion above. */
+  const appVersion = resolveAppVersion(opts);
+
   return {
     title: opts.title,
     tagline: opts.tagline || '',
@@ -153,6 +230,17 @@ function createConfig(opts) {
     organizationName: opts.organizationName || 'ConductionNL',
     projectName: opts.projectName || 'design-system',
 
+    /* customFields is the canonical Docusaurus channel for build-time
+       data the theme reads at runtime via useDocusaurusContext().
+       appVersion drives the navbar "Stable · v{x.y.z}" pill; sites
+       extend this by passing their own customFields in opts. */
+    customFields: Object.assign(
+      {
+        ...(appVersion && {appVersion}),
+      },
+      opts.customFields || {}
+    ),
+
     onBrokenLinks: 'warn',
     onBrokenMarkdownLinks: 'warn',
 
@@ -201,7 +289,7 @@ function createConfig(opts) {
           disableSwitch: false,
           respectPrefersColorScheme: true,
         },
-        navbar: Object.assign(baseNavbar(opts.title), opts.navbar || {}),
+        navbar: Object.assign(baseNavbar(opts.title, opts.repoUrl), opts.navbar || {}),
         /* Per-property fallback so a site can override one slice of the
            footer (e.g. just `links`) and inherit the rest from the brand.
            Previously `opts.footer` replaced the whole footer wholesale,

package/src/theme/Footer/index.jsx

@@ -316,6 +316,15 @@ export default function Footer() {
                 Open-source apps for <span className="next-blue">Nextcloud</span>. Built and
                 maintained by Conduction in Amsterdam, released under EUPL-1.2.
               </p>
+              {/*
+                Brand citation. The producer chain stays dot-separated
+                (Conduction · sub-brand · partner) and connects to
+                Nextcloud through a vermillion-red heart — the "loves"
+                relationship is between the producer stack and the
+                platform it ships on. Nextcloud is a link to
+                nextcloud.com so visitors can verify the platform
+                upstream in one click.
+              */}
               <div className="triad">
                 <span>
                   <span className="h"></span>
@@ -326,7 +335,17 @@ export default function Footer() {
                     .map((b, i) => (
                       <React.Fragment key={i}> · {b.wordmark}</React.Fragment>
                     ))}
-                  {' '}· <span className="next-blue">Nextcloud</span>
+                  {' '}
+                  <svg className="heart" viewBox="0 0 24 24" fill="currentColor" aria-label="loves" role="img">
+                    <path d="M12 21s-6.7-4.35-9.2-8.4C.8 9.2 2 5.5 5.2 4.7c2-.5 3.8.4 4.8 1.9 1-1.5 2.8-2.4 4.8-1.9 3.2.8 4.4 4.5 2.4 7.9C18.7 16.65 12 21 12 21z"/>
+                  </svg>
+                  {' '}
+                  <a
+                    href="https://nextcloud.com"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="next-blue"
+                  >Nextcloud</a>
                 </span>
               </div>
               <div className="socials">

package/src/theme/Navbar/index.jsx

@@ -2,7 +2,7 @@
  * Brand Navbar swizzle.
  *
  * Replaces Docusaurus's default Infima navbar with the Conduction
- * top-navbar pattern: brand wordmark + nav links + Partners + Install.
+ * top-navbar pattern: brand wordmark + nav links + locale + chrome.
  * Navigation items come from themeConfig.navbar.items (configured by
  * the consuming site); the chrome (typography, spacing, brand citation)
  * stays locked in this component.
@@ -18,24 +18,41 @@
  * sub-brand section keeps you in that section. Outside a sub-brand
  * section it goes to the site root.
  *
+ * Item types the brand navbar recognises (sites declare them in
+ * docusaurus.config.js → themeConfig.navbar.items):
+ *
+ *   { type: 'doc', label, to }                       internal doc link
+ *   { type: 'link', label, to | href }               internal/external link
+ *   { type: 'localeDropdown' }                       Docusaurus locale switcher
+ *   { type: 'github', href }                         icon-only GitHub mark
+ *   { type: 'apiDocs', label?, to }                  icon + "API Documentation"
+ *   { type: 'versionPill', prefix? }                 "Stable · v{x.y.z}" pill
+ *                                                    reads customFields.appVersion;
+ *                                                    hidden when no version
+ *
+ * The pill prefix defaults to "Stable" but can be overridden per site
+ * (e.g. prefix="Beta" while on a pre-1.0 release line).
+ *
  * Mirrors preview/components/top-navbar.html in the design-system kit.
  */
 
 import React from 'react';
 import Link from '@docusaurus/Link';
 import {useLocation} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useThemeConfig} from '@docusaurus/theme-common';
 import LocaleDropdownNavbarItem from '@theme/NavbarItem/LocaleDropdownNavbarItem';
-import {brandFor} from '../brand.jsx';
+import {brandFor, productWordmark} from '../brand.jsx';
+import {ICONS} from '../../components/primitives/icons';
 import styles from './styles.module.css';
 
 /**
- * Render a single navbar item. The brand top-navbar supports a small
- * subset of Docusaurus item types (link, locale dropdown, optional
- * primary CTA via items[].cta = true). Everything else falls back to
- * a plain link for forward-compatibility.
+ * Render a single navbar item. The brand navbar supports a small
+ * subset of Docusaurus item types plus the three brand-specific types
+ * (github, apiDocs, versionPill); everything else falls back to a
+ * plain link for forward-compatibility.
  */
-function NavItem({item, location}) {
+function NavItem({item, location, appVersion}) {
   if (item.type === 'localeDropdown') {
     return (
       <div className={styles.localeWrapper}>
@@ -44,6 +61,61 @@ function NavItem({item, location}) {
     );
   }
 
+  /* GitHub: icon-only link with an accessible label. The aria-label
+     gives screen-readers + browser tooltips a name without rendering
+     a visible text label in the navbar. */
+  if (item.type === 'github') {
+    return (
+      <a
+        href={item.href || 'https://github.com/ConductionNL'}
+        className={styles.iconLink}
+        target="_blank"
+        rel="noopener noreferrer"
+        aria-label={item['aria-label'] || 'GitHub repository'}
+        title="GitHub"
+      >
+        <span className={styles.iconGlyph} aria-hidden="true">{ICONS.github}</span>
+      </a>
+    );
+  }
+
+  /* API Documentation: icon + label link. Target defaults to /api
+     (the Redocusaurus mount point used by every Conduction docs site).
+     Sites can override via `to` or `href`. */
+  if (item.type === 'apiDocs') {
+    const label = item.label || 'API Documentation';
+    const to = item.to || '/api';
+    const href = item.href;
+    const isActive = !href && (location?.pathname === to ||
+                               location?.pathname?.startsWith(to + '/'));
+    const className = `${styles.link} ${styles.iconLabelLink} ${isActive ? styles.linkActive : ''}`;
+    const content = (
+      <>
+        <span className={styles.iconGlyph} aria-hidden="true">{ICONS.apiDocs}</span>
+        {label}
+      </>
+    );
+    if (href) {
+      return <a href={href} className={className} target={href.startsWith('http') ? '_blank' : undefined} rel={href.startsWith('http') ? 'noopener noreferrer' : undefined}>{content}</a>;
+    }
+    return <Link to={to} className={className}>{content}</Link>;
+  }
+
+  /* Version pill: code-typeface "Stable · v{version}" chip. Source is
+     customFields.appVersion (set by createConfig() from appinfo/info.xml
+     or package.json). Hidden when no version is available so sites
+     without an app version (Hydra, design-system itself) get a clean
+     navbar instead of an empty pill. */
+  if (item.type === 'versionPill') {
+    if (!appVersion) return null;
+    const prefix = item.prefix || 'Stable';
+    return (
+      <span className={styles.versionPill} title={`${prefix} · v${appVersion}`}>
+        {prefix} · v{appVersion}
+      </span>
+    );
+  }
+
   /* External link, no React-router prefetch */
   if (item.href && !item.to) {
     const isCta = item.cta === true;
@@ -83,20 +155,52 @@ function NavItem({item, location}) {
 
 export default function Navbar() {
   const {navbar} = useThemeConfig();
+  const {siteConfig} = useDocusaurusContext();
+  const appVersion = siteConfig?.customFields?.appVersion;
   const location = useLocation();
   const items = navbar.items || [];
   const brand = brandFor(location.pathname, navbar.title);
-  const wordmark = brand ? brand.wordmark : navbar.title;
+
+  /* Wordmark resolution order:
+     1. ConNext / Common Ground sub-brand → custom JSX (Con<Next>, …)
+     2. Conduction product app (Open*, Docu*, My*, …) → prefix-light
+        treatment: cobalt-400 prefix + blue-cobalt rest, matching the
+        preview/apps.html convention.
+     3. Plain text title (single-word wordmark or unrecognised prefix). */
+  let wordmark;
+  if (brand) {
+    wordmark = brand.wordmark;
+  } else {
+    const split = productWordmark(navbar.title, navbar.brandPrefix);
+    wordmark = split ? (
+      <>
+        <span className={styles.wordmarkPrefix}>{split.prefix}</span>{split.rest}
+      </>
+    ) : navbar.title;
+  }
+
   /* Path-match: keep the visitor in the sub-brand section on logo click.
      Title-match (the site's primary brand IS a sub-brand): logo goes to
      site root since the section IS the site. */
   const homeHref = brand?.source === 'path' ? brand.home : '/';
 
+  /* App icon. The brand rule is that every product navbar shows the
+     app's hex-glyph next to the wordmark. The icon is sourced from
+     navbar.logo (createConfig defaults it to img/logo.svg, which every
+     Conduction docs site ships under static/img/). Sites can opt the
+     icon out by passing `logo: null` in their navbar config. */
+  const logoSrc = navbar.logo?.src;
+  const logoAlt = navbar.logo?.alt || `${navbar.title} avatar`;
+
   /* Split into "left links" (regular nav) and "right CTAs" (locale,
-     external links, install button). The brand pattern groups them
-     this way; consumers control order via item.position. */
-  const leftItems = items.filter(i => i.position !== 'right' && i.type !== 'localeDropdown');
-  const rightItems = items.filter(i => i.position === 'right' || i.type === 'localeDropdown');
+     external links, install button, GitHub icon, version pill).
+     Items default to the left unless they explicitly carry
+     position="right" — but the three brand-specific item types
+     (github, apiDocs, versionPill) live on the right by convention,
+     mirroring the docs-shell mock. */
+  const RIGHT_TYPES = new Set(['localeDropdown', 'github', 'apiDocs', 'versionPill']);
+  const leftItems = items.filter(i => i.position !== 'right' && !RIGHT_TYPES.has(i.type));
+  const rightItems = items.filter(i => i.position === 'right' || RIGHT_TYPES.has(i.type));
 
   return (
     /* `navbar` (Docusaurus's framework class) is added alongside the
@@ -108,17 +212,26 @@ export default function Navbar() {
     <nav className={`navbar ${styles.nav}`} role="navigation" aria-label="Main">
       <div className={styles.left}>
         <Link to={homeHref} className={styles.wordmark}>
-          {wordmark}
+          {logoSrc && (
+            <img
+              src={logoSrc}
+              alt={logoAlt}
+              className={styles.wordmarkIcon}
+              width="32"
+              height="32"
+            />
+          )}
+          <span className={styles.wordmarkText}>{wordmark}</span>
         </Link>
         <div className={styles.links}>
           {leftItems.map((item, i) => (
-            <NavItem key={i} item={item} location={location} />
+            <NavItem key={i} item={item} location={location} appVersion={appVersion} />
           ))}
         </div>
       </div>
       <div className={styles.ctas}>
         {rightItems.map((item, i) => (
-          <NavItem key={i} item={item} location={location} />
+          <NavItem key={i} item={item} location={location} appVersion={appVersion} />
         ))}
       </div>
     </nav>

package/src/theme/Navbar/styles.module.css

@@ -24,6 +24,9 @@
 }
 
 .wordmark {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
   font-size: 22px;
   font-weight: 700;
   letter-spacing: -0.02em;
@@ -32,6 +35,33 @@
 }
 .wordmark:hover { color: var(--c-blue-cobalt); text-decoration: none; }
 
+/* App-glyph hex next to the wordmark. Every product navbar shows the
+   app's icon (sourced from navbar.logo); sized to match the wordmark's
+   cap height so the two land on the same baseline. */
+.wordmarkIcon {
+  width: 32px;
+  height: 32px;
+  display: block;
+  flex-shrink: 0;
+  object-fit: contain;
+}
+
+/* Wordmark text wrapper; gives us a single hook for tweaks like
+   line-height alignment without touching the parent flex container. */
+.wordmarkText {
+  display: inline-block;
+  line-height: 1;
+}
+
+/* "Light" prefix syllable for product wordmarks. Mirrors
+   preview/apps.html .lockup .word .light: cobalt-400 + regular weight,
+   so "OpenRegister" reads as muted-"Open" + bold-"Register" and the
+   eye lands on the noun, not the brand prefix. */
+.wordmarkPrefix {
+  color: var(--c-cobalt-400);
+  font-weight: 400;
+}
+
 .links {
   display: flex;
   gap: 28px;
@@ -100,6 +130,69 @@
   color: var(--c-orange-knvb);
 }
 
+/* Inline SVG slot used by `github` and `apiDocs` items. The icon
+   inherits the link's font-size + colour so a single `currentColor`
+   path stays on brand whether the link is active, hovered, or idle. */
+.iconGlyph {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  line-height: 1;
+}
+.iconGlyph :global(svg) {
+  width: 1em;
+  height: 1em;
+  display: block;
+}
+
+/* Icon-only navbar link. Used by the github item; no visible label,
+   the aria-label gives it a name. Slightly larger icon (18px) than
+   text links so it reads as a fixed glyph rather than letterform. */
+.iconLink {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  border-radius: var(--radius-sm);
+  color: var(--c-cobalt-700);
+  font-size: 18px;
+  text-decoration: none;
+  transition: color 160ms ease, background 160ms ease;
+}
+.iconLink:hover {
+  color: var(--c-blue-cobalt);
+  background: var(--c-cobalt-50);
+  text-decoration: none;
+}
+
+/* Icon + label link. Used by the apiDocs item. Same typography as
+   plain .link but with an inline icon before the label, gap matches
+   the brand button-icon spacing. */
+.iconLabelLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 14px;
+}
+.iconLabelLink .iconGlyph {
+  font-size: 16px;
+}
+
+/* Stable-version pill. Code typeface, cobalt-50 fill, cobalt-400 text,
+   pill-radius. Source is customFields.appVersion via createConfig();
+   when undefined the pill isn't rendered at all (see NavItem). */
+.versionPill {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: var(--c-cobalt-400);
+  background: var(--c-cobalt-50);
+  border-radius: var(--radius-pill);
+  padding: 4px 10px;
+  white-space: nowrap;
+}
+
 /* Responsive collapse, simplified for v1.
    TODO: hamburger menu like the design-system mock. */
 @media (max-width: 900px) {

package/src/theme/brand.jsx

@@ -61,3 +61,50 @@ export function brandFor(pathname, title) {
   }
   return null;
 }
+
+/**
+ * Conduction product-app wordmark patterns. The brand convention,
+ * codified in preview/apps.html, is to render the prefix syllable in
+ * cobalt-400 / regular weight and the rest in blue-cobalt / bold:
+ *
+ *   <span class="light">Open</span>Register
+ *   <span class="light">Docu</span>Desk
+ *   <span class="light">My</span>Dash
+ *
+ * This list covers the prefixes used across the Conduction fleet.
+ * Sites whose wordmark doesn't start with one of these (e.g. Shillinq,
+ * Decidesk) keep the whole wordmark in blue-cobalt unless they pass
+ * an explicit `navbar.brandPrefix` to override.
+ */
+const PRODUCT_PREFIXES = [
+  'OpenAI',    /* must precede 'Open' so 'OpenAI Bridge' splits as OpenAI/Bridge */
+  'Open',
+  'Docu',
+  'My',
+  'Pipe',
+  'Pro',
+  'Decid',
+  'Schol',
+  'Larping',
+];
+
+/**
+ * Split a wordmark into (prefix, rest) so the prefix can render in the
+ * cobalt-400 "light" treatment. `brandPrefix` (optional) overrides
+ * auto-detection — sites with a non-standard wordmark pass it
+ * explicitly. Returns `null` when no split applies (single-word
+ * wordmarks or unrecognised prefixes); callers should render the
+ * wordmark as-is in that case.
+ */
+export function productWordmark(title, brandPrefix) {
+  if (!title) return null;
+  if (brandPrefix && title.startsWith(brandPrefix) && title.length > brandPrefix.length) {
+    return {prefix: brandPrefix, rest: title.slice(brandPrefix.length)};
+  }
+  for (const p of PRODUCT_PREFIXES) {
+    if (title.startsWith(p) && title.length > p.length) {
+      return {prefix: p, rest: title.slice(p.length)};
+    }
+  }
+  return null;
+}

package/static/lib/canal-footer.css

@@ -190,6 +190,25 @@
   display: inline-block; margin-right: 6px;
   vertical-align: middle;
 }
+/* "Conduction ♥ Nextcloud" citation: a vermillion-red heart between
+   the producer chain and the Nextcloud platform link. Sized to the
+   surrounding 11px caption with a small inline lift so the heart
+   centres on the cap-height. */
+.canal-footer .brand .triad .heart {
+  width: 11px; height: 11px;
+  color: var(--c-red-vermillion);
+  display: inline-block;
+  vertical-align: -1px;
+  margin: 0 2px;
+}
+.canal-footer .brand .triad a.next-blue {
+  color: var(--c-nextcloud-blue);
+  text-decoration: none;
+  transition: color 140ms ease;
+}
+.canal-footer .brand .triad a.next-blue:hover {
+  color: var(--c-nextcloud-cyan);
+}
 .canal-footer .brand .socials {
   display: flex; gap: 10px;
   margin-top: 18px;