@conduction/docusaurus-preset 0.1.0

package/src/components/primitives/HexBullet.jsx

@@ -0,0 +1,37 @@
+/**
+ * <HexBullet />
+ *
+ * The 12×14 (or 8×9) pointy-top clip-path hexagon used as the bullet
+ * inside eyebrows, status badges, footer triad, and pill chips. The
+ * shape recurs 15+ times across the kit; centralising it removes the
+ * temptation to duplicate `width: 12px; height: 14px; clip-path:
+ * var(--hex-pointy-top)` in every component CSS module.
+ *
+ * Per huisstijl: pointy-top, never rotated, solid colour fill.
+ *
+ * Sizes:
+ *   - sm  =  8 × 9   (inline pill bullet)
+ *   - md  = 12 × 14  (default eyebrow bullet)
+ *   - lg  = 44 × 50  (icon-hex container, see <IconHex/> wrapper)
+ *
+ * Color: any CSS color or token. Defaults to KNVB orange so the bullet
+ * is the brand's only orange-on-cobalt accent.
+ */
+
+import React from 'react';
+import styles from './HexBullet.module.css';
+
+const SIZES = {sm: 'sm', md: 'md', lg: 'lg'};
+
+export default function HexBullet({size = 'md', color, className, style, ...rest}) {
+  const sizeKey = SIZES[size] || 'md';
+  const composed = [styles.hex, styles[sizeKey], className].filter(Boolean).join(' ');
+  return (
+    <span
+      aria-hidden="true"
+      className={composed}
+      style={color ? {background: color, ...style} : style}
+      {...rest}
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+/**
+ * <HexBullet /> styles. Three sizes mirror the recurring measurements
+ * across reference-cards, solution-cards, partner-cards, hero,
+ * footer, eyebrow, etc. Always pointy-top, never rotated.
+ */
+
+.hex {
+  display: inline-block;
+  clip-path: var(--hex-pointy-top);
+  background: var(--c-orange-knvb);
+  flex-shrink: 0;
+}
+
+.sm { width: 8px;  height: 9px; }
+.md { width: 12px; height: 14px; }
+.lg { width: 44px; height: 50px; }

package/src/components/primitives/HexThumbnail.jsx

@@ -0,0 +1,70 @@
+/**
+ * <HexThumbnail />
+ *
+ * Single pointy-top hex tile that holds an icon, a photo (clip-path
+ * masked), or an illustration. Used as the visual on academy
+ * <ContentCard/>, <FeaturedCard/>, <ContentDetailHero/> and anywhere
+ * else a hex-shaped media tile is needed.
+ *
+ * Per huisstijl: pointy-top, never rotated, solid colour ground.
+ *
+ * Sizes:
+ *   - sm = 56  × 64   (small content cards, dense rows)
+ *   - md = 88  × 100  (default content card)
+ *   - lg = 160 × 184  (featured card, secondary visual)
+ *   - xl = 240 × 280  (featured-card primary, detail-hero cover)
+ *
+ * Tones: cobalt (default), cobalt-dark, cobalt-deep, mint, orange,
+ * cobalt-50 (light surface, cobalt content).
+ *
+ * Pass an SVG icon as children for the icon variant; pass `src` for
+ * the photo variant. The component keeps both options in one API so
+ * cards don't need two thumbnail components.
+ *
+ * Usage:
+ *
+ *   <HexThumbnail tone="cobalt-dark" size="md">
+ *     <svg viewBox="0 0 24 24"><path d="..."/></svg>
+ *   </HexThumbnail>
+ *
+ *   <HexThumbnail size="lg" src="/img/posts/install.jpg" alt="Install screen" />
+ */
+
+import React from 'react';
+import styles from './HexThumbnail.module.css';
+
+const SIZES = {sm: 'sm', md: 'md', lg: 'lg', xl: 'xl'};
+const TONES = {
+  cobalt: 'cobalt',
+  'cobalt-dark': 'cobalt-dark',
+  'cobalt-deep': 'cobalt-deep',
+  'cobalt-50': 'cobalt-50',
+  mint: 'mint',
+  orange: 'orange',
+};
+
+export default function HexThumbnail({
+  size = 'md',
+  tone = 'cobalt',
+  src,
+  alt = '',
+  className,
+  children,
+  style,
+  ...rest
+}) {
+  const sizeKey = SIZES[size] || 'md';
+  const toneKey = TONES[tone] || 'cobalt';
+  const composed = [
+    styles.thumb,
+    styles['size-' + sizeKey],
+    styles['tone-' + toneKey],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <span className={composed} style={style} {...rest}>
+      {src ? <img src={src} alt={alt} /> : children}
+    </span>
+  );
+}

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

@@ -0,0 +1,45 @@
+/**
+ * <HexThumbnail /> styles. Pointy-top clip-path hex with size and tone
+ * variants. The img variant fills the hex via object-fit: cover.
+ */
+
+.thumb {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  clip-path: var(--hex-pointy-top);
+  flex-shrink: 0;
+  overflow: hidden;
+  color: white;
+}
+
+.thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.thumb svg {
+  stroke: currentColor;
+  stroke-width: 1.6;
+  fill: none;
+}
+
+/* sizes */
+.size-sm { width: 56px;  height: 64px;  }
+.size-sm svg { width: 22px; height: 22px; }
+.size-md { width: 88px;  height: 100px; }
+.size-md svg { width: 36px; height: 36px; }
+.size-lg { width: 160px; height: 184px; }
+.size-lg svg { width: 64px; height: 64px; }
+.size-xl { width: 240px; height: 280px; }
+.size-xl svg { width: 96px; height: 96px; }
+
+/* tones */
+.tone-cobalt      { background: var(--c-blue-cobalt); }
+.tone-cobalt-dark { background: var(--c-cobalt-700); }
+.tone-cobalt-deep { background: var(--c-cobalt-900); }
+.tone-cobalt-50   { background: var(--c-cobalt-50); color: var(--c-blue-cobalt); }
+.tone-mint        { background: var(--c-mint-500); }
+.tone-orange      { background: var(--c-orange-knvb); }

package/src/components/primitives/Pill.jsx

@@ -0,0 +1,42 @@
+/**
+ * <Pill />
+ *
+ * Inline-flex pill chip with optional leading <HexBullet/>. Used for
+ * status badges (STABLE / BETA), built-on app tags, sector labels,
+ * version tags. Recurs in reference-cards.css, solution-cards.css,
+ * partner-cards.css, apps-grid.css, app-card meta line.
+ *
+ * Tones:
+ *   - default:  cobalt-50 bg, cobalt-700 text, mono caps
+ *   - status:   colored hex bullet (green=stable, orange=beta, blue=soon)
+ *   - solid:    colored bg fill (used for sector tags)
+ *
+ * Usage:
+ *
+ *   <Pill bullet>STABLE</Pill>
+ *   <Pill bullet bulletColor="var(--c-orange-knvb)">BETA</Pill>
+ *   <Pill tone="solid" color="var(--c-mkb)">MKB</Pill>
+ */
+
+import React from 'react';
+import HexBullet from './HexBullet';
+import styles from './Pill.module.css';
+
+export default function Pill({
+  bullet = false,
+  bulletColor,
+  tone = 'default',
+  color,
+  className,
+  children,
+  ...rest
+}) {
+  const composed = [styles.pill, styles['tone-' + tone], className].filter(Boolean).join(' ');
+  const style = tone === 'solid' && color ? {background: color, color: 'white'} : undefined;
+  return (
+    <span className={composed} style={style} {...rest}>
+      {bullet && <HexBullet size="sm" color={bulletColor} />}
+      <span className={styles.label}>{children}</span>
+    </span>
+  );
+}

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

@@ -0,0 +1,30 @@
+/**
+ * <Pill /> styles. Mirrors .pill rules in reference-cards.css,
+ * solution-cards.css, partner-cards.css.
+ */
+
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px;
+  border-radius: var(--radius-pill);
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  line-height: 1.4;
+  white-space: nowrap;
+}
+
+.tone-default {
+  background: var(--c-cobalt-50);
+  color: var(--c-cobalt-700);
+}
+
+.tone-solid {
+  background: var(--c-blue-cobalt);
+  color: white;
+}
+
+.label { display: inline-block; }

package/src/components/primitives/Section.jsx

@@ -0,0 +1,51 @@
+/**
+ * <Section />
+ *
+ * The 1280px max-width 64px-padded section wrapper that every page in
+ * preview/pages/* uses. Eight components currently re-declare these
+ * exact values in their own CSS module; centralising prevents drift.
+ *
+ * Background variants:
+ *   - default:  white
+ *   - tinted:   --c-cobalt-50 (used for stats strip, platform overview)
+ *   - inverse:  --c-blue-cobalt with white type (used for CTA panels)
+ *
+ * Spacing variants:
+ *   - default: 96px vertical padding
+ *   - tight:   48px (stats-strip rhythm)
+ *   - flush:   0    (consumer controls)
+ *
+ * Usage in MDX:
+ *
+ *   <Section background="tinted">
+ *     <SectionHead eyebrow="The platform" title="..." lede="..." />
+ *     <FeatureList items={[...]} />
+ *   </Section>
+ */
+
+import React from 'react';
+import styles from './Section.module.css';
+
+export default function Section({
+  background = 'default',
+  spacing = 'default',
+  as: Tag = 'section',
+  className,
+  innerClassName,
+  children,
+  ...rest
+}) {
+  const wrap = [
+    styles.section,
+    styles['bg-' + background],
+    styles['sp-' + spacing],
+    className,
+  ].filter(Boolean).join(' ');
+  return (
+    <Tag className={wrap} {...rest}>
+      <div className={[styles.inner, innerClassName].filter(Boolean).join(' ')}>
+        {children}
+      </div>
+    </Tag>
+  );
+}

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

@@ -0,0 +1,31 @@
+/**
+ * <Section /> styles. Mirrors the .section / .platform / .strip /
+ * .apps-preview / .cta wrappers from preview/pages/landing.html.
+ */
+
+.section { font-family: var(--conduction-typography-font-family-body); }
+
+.inner {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 0 64px;
+}
+
+@media (max-width: 700px) {
+  .inner { padding: 0 16px; }
+}
+
+/* Background variants */
+.bg-default { background: white; }
+.bg-tinted  { background: var(--c-cobalt-50); border-top: 1px solid var(--c-cobalt-100); border-bottom: 1px solid var(--c-cobalt-100); }
+.bg-inverse { background: var(--c-blue-cobalt); color: white; }
+
+/* Vertical-spacing variants */
+.sp-default .inner { padding-block: 96px; }
+.sp-tight   .inner { padding-block: 48px; }
+.sp-flush   .inner { padding-block: 0; }
+
+@media (max-width: 700px) {
+  .sp-default .inner { padding-block: 56px; }
+  .sp-tight   .inner { padding-block: 32px; }
+}

package/src/components/primitives/SectionHead.jsx

@@ -0,0 +1,36 @@
+/**
+ * <SectionHead />
+ *
+ * The eyebrow + h2 + lede block used at the top of every section in
+ * preview/pages/landing.html (.section-head). Splits left (eyebrow +
+ * h2) from right (lede) on a 1.1fr/1fr grid, collapses to single
+ * column under 900px.
+ *
+ * Mirrors .section-head from landing.html's per-page CSS, which
+ * recurs in apps-catalog, solutions-catalog, support, partners,
+ * about, etc.
+ *
+ * Usage:
+ *
+ *   <SectionHead
+ *     eyebrow="Most installed"
+ *     title="Three apps that ship the most outcomes."
+ *     lede="Start with the apps that solve a concrete problem on day one."
+ *   />
+ */
+
+import React from 'react';
+import Eyebrow from './Eyebrow';
+import styles from './SectionHead.module.css';
+
+export default function SectionHead({eyebrow, title, lede, align = 'split', className}) {
+  return (
+    <div className={[styles.head, styles['align-' + align], className].filter(Boolean).join(' ')}>
+      <div className={styles.copy}>
+        {eyebrow && <Eyebrow>{eyebrow}</Eyebrow>}
+        {title && <h2 className={styles.title}>{title}</h2>}
+      </div>
+      {lede && <p className={styles.lede}>{lede}</p>}
+    </div>
+  );
+}

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

@@ -0,0 +1,43 @@
+/**
+ * <SectionHead /> styles. Mirrors .section-head from preview/pages/
+ * landing.html (and the same rule re-declared on apps-catalog,
+ * solutions-catalog, support, partners, about pages).
+ */
+
+.head { margin-bottom: 48px; }
+
+.align-split {
+  display: grid;
+  grid-template-columns: 1.1fr 1fr;
+  gap: 64px;
+  align-items: end;
+}
+
+.align-stack { display: block; }
+.align-stack .lede { max-width: 60ch; margin-top: 16px; }
+
+@media (max-width: 900px) {
+  .align-split { grid-template-columns: 1fr; gap: 24px; }
+}
+
+.title {
+  font-size: 44px;
+  font-weight: 700;
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+  color: var(--c-cobalt-900);
+  margin: 0;
+}
+@media (max-width: 700px) { .title { font-size: 32px; } }
+
+.title :global(.next-blue) { color: var(--c-nextcloud-blue); }
+.title :global(.cg-yellow) { color: var(--c-commonground-yellow); }
+
+.lede {
+  font-size: 17px;
+  color: var(--c-cobalt-700);
+  line-height: 1.55;
+  margin: 0;
+}
+.lede :global(.next-blue) { color: var(--c-nextcloud-blue); }
+.lede :global(.cg-yellow) { color: var(--c-commonground-yellow); }

package/src/components/primitives/index.js

@@ -0,0 +1,22 @@
+/**
+ * @conduction/docusaurus-preset/components/primitives
+ *
+ * Atomic visual primitives extracted from preview/components/*.html so
+ * higher-level components and MDX pages compose from one source. Each
+ * primitive matches a CSS rule that appeared in 3+ files in the kit.
+ *
+ * Build order matters: HexBullet has no deps, Eyebrow consumes
+ * HexBullet, Pill consumes HexBullet, SectionHead consumes Eyebrow,
+ * etc.
+ */
+
+export {default as HexBullet}    from './HexBullet';
+export {default as HexThumbnail} from './HexThumbnail';
+export {default as AuthorByline} from './AuthorByline';
+export {default as Eyebrow}      from './Eyebrow';
+export {default as Section}      from './Section';
+export {default as SectionHead}  from './SectionHead';
+export {default as Card}         from './Card';
+export {default as Pill}         from './Pill';
+export {default as Button}       from './Button';
+export {NextBlue, CgYellow, KnvbOrange, CommonGroundPlus} from './BrandCitation';

package/src/css/brand.css

@@ -0,0 +1,158 @@
+/**
+ * Conduction brand for Docusaurus 3.
+ *
+ * Imports the canonical tokens (palette, typography, hex clip-paths)
+ * and maps them onto Docusaurus's Infima CSS variables. The result:
+ * Docusaurus chrome (navbar, sidebar, code blocks, buttons) renders
+ * in cobalt + KNVB orange + Plex Mono, without theme-swizzling.
+ *
+ * Sites can append their own customCss to override anything below.
+ */
+
+@import "./tokens.css";
+
+/* ============================================================
+   Infima primary palette → cobalt
+   ============================================================ */
+:root {
+  --ifm-color-primary:           var(--c-blue-cobalt);
+  --ifm-color-primary-dark:      var(--c-cobalt-600);
+  --ifm-color-primary-darker:    var(--c-cobalt-700);
+  --ifm-color-primary-darkest:   var(--c-cobalt-800);
+  --ifm-color-primary-light:     var(--c-cobalt-400);
+  --ifm-color-primary-lighter:   var(--c-cobalt-300);
+  --ifm-color-primary-lightest:  var(--c-cobalt-200);
+
+  /* Accent → KNVB orange (links, CTAs, focus ring) */
+  --ifm-link-color:              var(--c-orange-knvb);
+  --ifm-link-hover-color:        var(--c-cobalt-700);
+  --ifm-button-color:             white;
+
+  /* Typography → Figtree body, Plex Mono code */
+  --ifm-font-family-base:        var(--conduction-typography-font-family-body);
+  --ifm-font-family-monospace:   var(--conduction-typography-font-family-code);
+  --ifm-heading-color:           var(--c-cobalt-900);
+
+  /* Code blocks */
+  --ifm-code-font-size:          92%;
+  --ifm-code-background:         var(--c-cobalt-50);
+  --ifm-pre-background:          var(--c-cobalt-900);
+  --ifm-pre-color:               var(--c-cobalt-100);
+
+  /* Sidebar + navbar surfaces */
+  --ifm-navbar-background-color: white;
+  --ifm-navbar-shadow:           0 1px 0 var(--c-cobalt-100);
+  --ifm-toc-border-color:        var(--c-cobalt-100);
+
+  /* Footer cobalt-900 panel */
+  --ifm-footer-background-color: var(--c-cobalt-900);
+  --ifm-footer-color:            var(--c-cobalt-200);
+  --ifm-footer-link-color:       white;
+  --ifm-footer-title-color:      var(--c-cobalt-200);
+
+  /* Spacing rhythm reused from tokens */
+  --ifm-spacing-horizontal:      var(--space-6);
+  --ifm-spacing-vertical:        var(--space-6);
+  --ifm-line-height-base:        1.55;
+}
+
+[data-theme='dark'] {
+  --ifm-background-color:        var(--c-cobalt-900);
+  --ifm-background-surface-color: var(--c-cobalt-800);
+  --ifm-color-primary:           var(--c-cobalt-300);
+  --ifm-color-primary-light:     var(--c-cobalt-200);
+  --ifm-link-color:              var(--c-orange-knvb);
+  --ifm-heading-color:           white;
+  --ifm-font-color-base:         var(--c-cobalt-100);
+  --ifm-code-background:         var(--c-cobalt-800);
+}
+
+/* ============================================================
+   Brand tells, applied site-wide
+   ============================================================ */
+
+/* Pointy-top hex utility (mirrors design-system .hex) */
+.cn-hex-clip { clip-path: var(--hex-pointy-top); display: inline-block; }
+
+/* Brand citation, "Next" in Nextcloud-blue */
+.next-blue { color: var(--conduction-color-brand-nextcloud); }
+
+/* Brand citation, "Common Ground" in CG-yellow */
+.cg-yellow { color: var(--conduction-color-brand-commonground); }
+
+/* KNVB-orange highlight, for the rare emphasised word per "one orange
+   per screen" rule. Reserved for highlights, never primary fills. */
+.knvb-orange { color: var(--c-orange-knvb); }
+
+/* Common Ground+ wordmark — tri-colour brand mark for the productized
+   Common Ground offering. "Common" in Conduction cobalt, "Ground" in
+   Common Ground yellow (reuses .cg-yellow), "+" in Nextcloud blue.
+   Use through the <CommonGroundPlus/> primitive; the rules below back
+   it (and any plain-HTML preview that wires up the same span shape). */
+.cg-plus-common { color: var(--c-blue-cobalt); }
+.cg-plus-plus   { color: var(--conduction-color-brand-nextcloud); font-weight: inherit; }
+
+/* Buttons inherit brand-primary fill */
+.button--primary {
+  background-color: var(--c-blue-cobalt);
+  border-color: var(--c-blue-cobalt);
+  color: white;
+}
+.button--primary:hover {
+  background-color: var(--c-cobalt-700);
+  border-color: var(--c-cobalt-700);
+  color: white;
+}
+
+/* Focus ring is KNVB orange, never default Infima blue */
+*:focus-visible {
+  outline: 2px solid var(--c-orange-knvb);
+  outline-offset: 2px;
+}
+
+/* Headings keep the brand letter-spacing */
+h1, h2, h3 { letter-spacing: -0.02em; }
+
+/* Marketing pages (frontmatter: hide_table_of_contents: true) get
+   a flush top edge AND full-width sections. The MDXPage swizzle
+   attaches the .marketing-page class on <main>; the rules below:
+     1. Zero out every margin/padding between <main> and the first
+        section so the navbar's bottom border touches the Hero's
+        top edge.
+     2. Override Infima's .markdown vertical-rhythm rules so h1,
+        h2, h3 inside the Hero / SectionHead don't grab a 3rem
+        margin-top from the doc-page rhythm.
+     3. Force the .markdown wrapper itself to render at the page's
+        full width so .strip / .banner sections with their own
+        full-bleed backgrounds (cobalt-50 stats band, cobalt CTA
+        panel) actually bleed to the viewport edges instead of
+        being pinned to the central col-8 width. */
+main.marketing-page,
+main.marketing-page > article,
+main.marketing-page > article > .theme-doc-markdown,
+main.marketing-page > article > div,
+main.marketing-page .markdown {
+  margin: 0 !important;
+  padding: 0 !important;
+  max-width: none !important;
+  width: 100%;
+}
+/* Zero-out the Infima vertical-rhythm rules that target headings inside
+   .markdown so the marketing pages don't inherit doc-page spacing. */
+main.marketing-page .markdown > :first-child,
+main.marketing-page .markdown h1:first-child,
+main.marketing-page .markdown h1,
+main.marketing-page .markdown h2,
+main.marketing-page .markdown h3,
+main.marketing-page .markdown > * {
+  margin-top: 0;
+}
+
+/* Links underline via cobalt-200 by default; orange on hover */
+a:not(.navbar__link):not(.footer__link-item):not(.button) {
+  text-decoration-color: var(--c-cobalt-200);
+  text-underline-offset: 2px;
+}
+a:not(.navbar__link):not(.footer__link-item):not(.button):hover {
+  text-decoration-color: var(--c-orange-knvb);
+}

package/src/css/tokens.css

@@ -0,0 +1,12 @@
+/**
+ * Conduction brand tokens, mirrored for Docusaurus consumers.
+ *
+ * Re-exports the canonical tokens from ../../tokens.css so a Docusaurus
+ * site picking up the preset gets the same palette, typography, and hex
+ * clip-paths as the design-system kit.
+ *
+ * When the preset is published to npm, this file becomes the bundled
+ * copy; until then it imports relatively from the workspace.
+ */
+@import url("../../../tokens.css");
+@import url("../../../typography.css");

package/src/data/app-downloads.js

@@ -0,0 +1,42 @@
+/**
+ * @conduction/docusaurus-preset/data
+ *
+ * Build-time access to the ConductionNL app-download stats. The JSON
+ * itself is refreshed every weekday by .github/workflows/app-downloads.yml
+ * and committed to design-system/data/app-downloads.json.
+ *
+ * Usage in MDX:
+ *
+ *   import {totalDownloads, downloadsForApp} from '@conduction/docusaurus-preset/data';
+ *
+ *   <StatsStrip stats={[
+ *     {value: totalDownloads.toLocaleString('en'), label: 'app store downloads'},
+ *     ...
+ *   ]} />
+ *
+ *   <DetailHero appId="openregister" ... />   // looks up downloads automatically
+ */
+
+import data from '../../../data/app-downloads.json';
+
+export default data;
+
+export const totalDownloads = data.totals.downloads;
+export const appsTotal = data.totals.apps_total;
+export const appsInStore = data.totals.apps_in_store;
+export const generatedAt = data.generated_at;
+
+const byId = new Map(data.apps.map((a) => [a.id, a]));
+
+export function appStats(appId) {
+  return byId.get(appId) || null;
+}
+
+export function downloadsForApp(appId) {
+  const app = byId.get(appId);
+  return app && app.github ? app.github.downloads : 0;
+}
+
+export function formatDownloads(n, locale = 'en') {
+  return Number(n || 0).toLocaleString(locale);
+}