From 89d608ddbb89a381d75ab113d0e6241a957f4bb7 Mon Sep 17 00:00:00 2001
From: Greg Annandale <greg@raspberrypi.org>
Date: Tue, 31 Mar 2026 11:30:35 +0100
Subject: [PATCH] chore(docs): add Docusaurus components

For:
- Class blocks
- Codelab cards
- Homepage features
- Images
---
 packages/docs/src/components/ClassBlock.js    | 14 +++++
 packages/docs/src/components/CodelabCards.js  | 26 ++++++++
 .../src/components/HomepageFeatures/index.js  | 62 +++++++++++++++++++
 .../HomepageFeatures/styles.module.css        | 11 ++++
 packages/docs/src/components/Image.js         | 45 ++++++++++++++
 5 files changed, 158 insertions(+)
 create mode 100644 packages/docs/src/components/ClassBlock.js
 create mode 100644 packages/docs/src/components/CodelabCards.js
 create mode 100644 packages/docs/src/components/HomepageFeatures/index.js
 create mode 100644 packages/docs/src/components/HomepageFeatures/styles.module.css
 create mode 100644 packages/docs/src/components/Image.js

diff --git a/packages/docs/src/components/ClassBlock.js b/packages/docs/src/components/ClassBlock.js
new file mode 100644
index 000000000..1cddaa7be
--- /dev/null
+++ b/packages/docs/src/components/ClassBlock.js
@@ -0,0 +1,14 @@
+import React from 'react';
+
+/**
+ * ClassBlock Component
+ * Renders a block of content with a CSS class applied
+ * Used for styling specific content blocks (e.g., compare-worse, compare-better)
+ * 
+ * @param {string} className - The CSS class name to apply
+ * @param {React.ReactNode} children - The content to render
+ * @returns {JSX.Element}
+ */
+export default function ClassBlock({ className, children }) {
+  return <p className={className}>{children}</p>;
+}
diff --git a/packages/docs/src/components/CodelabCards.js b/packages/docs/src/components/CodelabCards.js
new file mode 100644
index 000000000..e1b489c9c
--- /dev/null
+++ b/packages/docs/src/components/CodelabCards.js
@@ -0,0 +1,26 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import styles from './styles.module.css';
+
+// This component renders the grid layout
+export function CodelabGrid({ children }) {
+  return <div className={styles.codelabGrid}>{children}</div>;
+}
+
+// This component renders a single card
+export function CodelabCard({ href, title, description, children, level }) {
+  return (
+    <div className={styles.codelabCard}>
+      <div className={styles.cardHeader}>
+        <span className={styles.cardIcon}>{children}</span>
+      </div>
+      <div>
+        <span className={styles.eyebrow}>{level}</span>
+      </div>
+      <div className={styles.cardFooter}>
+        <h3 className={styles.cardTitle}>{title}</h3>
+        <Link href={href}><span className={styles.cardButton}>Start</span></Link>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/docs/src/components/HomepageFeatures/index.js b/packages/docs/src/components/HomepageFeatures/index.js
new file mode 100644
index 000000000..12d08cf41
--- /dev/null
+++ b/packages/docs/src/components/HomepageFeatures/index.js
@@ -0,0 +1,62 @@
+import clsx from 'clsx';
+import Heading from '@theme/Heading';
+import styles from './styles.module.css';
+
+
+const FeatureList = [
+  {
+    title: 'Accessible by design',
+    Svg: require('@site/static/images/HomePage/Accessibility-tier-4.svg').default,
+    description: (
+      <>
+        Built so everyone can engage with visual code — helping developers create experiences that are inclusive by default.
+      </>
+    ),
+  },
+  {
+    title: 'Built for flexibility',
+    Svg: require('@site/static/images/HomePage/Explore-tier-4.svg').default,
+    description: (
+      <>
+       An open-source library that adapts to your needs. With APIs, generators, and integrations, Blockly fits into most platforms, and environments.
+      </>
+    ),
+  },
+  {
+    title: 'Driven by community',
+    Svg: require('@site/static/images/HomePage/Connect-tier-4.svg').default,
+    description: (
+      <>
+        A global community of passionate developers and educators helps Blockly stay open, innovative, and ready for what’s next.
+      </>
+    ),
+  },
+];
+
+function Feature({Svg, title, description}) {
+  return (
+    <div className={clsx('col col--4')}>
+      <div className="text--center">
+        <Svg className={styles.featureSvg} role="img" />
+      </div>
+      <div className="text--center padding-horiz--md">
+        <Heading as="h2">{title}</Heading>
+        <p>{description}</p>
+      </div>
+    </div>
+  );
+}
+
+export default function HomepageFeatures() {
+  return (
+    <section className={styles.features}>
+      <div className="container">
+        <div className="row">
+          {FeatureList.map((props, idx) => (
+            <Feature key={idx} {...props} />
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/packages/docs/src/components/HomepageFeatures/styles.module.css b/packages/docs/src/components/HomepageFeatures/styles.module.css
new file mode 100644
index 000000000..9bf3d69dc
--- /dev/null
+++ b/packages/docs/src/components/HomepageFeatures/styles.module.css
@@ -0,0 +1,11 @@
+.features {
+  display: flex;
+  align-items: center;
+  padding: 3rem 0 5rem 0;
+  width: 100%;
+}
+
+.featureSvg {
+  height: 200px;
+  width: 200px;
+}
diff --git a/packages/docs/src/components/Image.js b/packages/docs/src/components/Image.js
new file mode 100644
index 000000000..57d06004d
--- /dev/null
+++ b/packages/docs/src/components/Image.js
@@ -0,0 +1,45 @@
+import React from 'react';
+import {useColorMode} from '@docusaurus/theme-common';
+
+/**
+ * Image component for use in MDX docs
+ * Wraps HTML img tag with additional styling and responsiveness
+ * Supports theme-based image loading (light/dark mode)
+ * 
+ * @param {string} src - Image source path (for light mode)
+ * @param {string} srcDark - Optional image source path for dark mode
+ * @param {string} alt - Alt text for accessibility
+ * @param {number|string} width - Optional width (in pixels)
+ * @param {number|string} height - Optional height (in pixels)
+ * @param {string} className - Optional CSS class for custom styling
+ * @param {object} style - Optional inline styles
+ */
+export default function Image({ src, srcDark, alt, width, height, className, style = {}, ...props }) {
+  const {colorMode} = useColorMode();
+  
+  // Select image source based on current theme
+  const imageSrc = colorMode === 'dark' && srcDark ? srcDark : src;
+  
+  const imgStyle = {
+    maxWidth: '100%',
+    height: 'auto',
+    ...style,
+  };
+
+  if (width) {
+    imgStyle.width = typeof width === 'number' ? `${width}px` : width;
+  }
+  if (height) {
+    imgStyle.height = typeof height === 'number' ? `${height}px` : height;
+  }
+
+  return (
+    <img
+      src={imageSrc}
+      alt={alt}
+      className={className}
+      style={{ ...imgStyle }}
+      {...props}
+    />
+  );
+}