From a24245d22c1f138f212b07e122890aacc8127929 Mon Sep 17 00:00:00 2001
From: ruben-cytonic <ruben@cytonic.com>
Date: Fri, 6 Mar 2026 09:02:36 +0000
Subject: [PATCH 1/2] feat(docs): randomize hero terminal demo across all
 integrations

The hero section now randomly shows one of four integration workflows
(Figma, GitHub, Linear, Notion) on each page load, with matching
taglines and highlighted integration logos. Figma is the SSR default.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/src/components/HeroSection/index.tsx     | 142 +++++++++++++-----
 .../components/HeroSection/styles.module.css  |   3 +-
 docs/src/pages/index.tsx                      |  20 +--
 3 files changed, 119 insertions(+), 46 deletions(-)

diff --git a/docs/src/components/HeroSection/index.tsx b/docs/src/components/HeroSection/index.tsx
index 10f4a0ad..fcc41ff8 100644
--- a/docs/src/components/HeroSection/index.tsx
+++ b/docs/src/components/HeroSection/index.tsx
@@ -3,15 +3,95 @@ import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import styles from './styles.module.css';
 
+interface DemoScenario {
+  id: 'figma' | 'github' | 'linear' | 'notion';
+  tagline: [string, string];
+  subtitle: string;
+  command: string;
+  outputLines: string[];
+  successLine: string;
+}
+
+const DEMO_SCENARIOS: DemoScenario[] = [
+  {
+    id: 'figma',
+    tagline: ['Design in Figma.', 'Ship pixel-perfect code.'],
+    subtitle:
+      'Point ralph-starter at a Figma file and get production-ready components with visual validation.',
+    command: 'ralph-starter figma',
+    outputLines: [
+      '  Figma to Code',
+      '? Figma URL: https://figma.com/design/ABC123/Dashboard',
+      '? Build: responsive dashboard with sidebar nav',
+      '? Stack: Next.js + TypeScript + Tailwind CSS',
+      '\u2192 Fetching Figma API... 8 frames, 21 components',
+      '\u2192 Visual validation: 98.2% pixel match',
+    ],
+    successLine: '\u2713 Done! Cost: $0.94 | 3 commits',
+  },
+  {
+    id: 'github',
+    tagline: ['Specs on GitHub.', 'Code ships itself.'],
+    subtitle:
+      'Point ralph-starter at a GitHub issue and get a fully implemented feature with tests and a PR.',
+    command: 'ralph-starter run --from github --issue 42',
+    outputLines: [
+      '\u2192 Fetching GitHub issue #42...',
+      '  Found: "Add user authentication"',
+      '  Labels: feature, auth',
+      '\u2192 Loop 1/5: Generating auth module...',
+      '\u2192 Loop 2/5: Adding tests and validation...',
+      '\u2192 Validation passed: 12 tests, lint clean',
+    ],
+    successLine: '\u2713 Done! Cost: $0.38 | PR #87 created',
+  },
+  {
+    id: 'linear',
+    tagline: ['Tickets in Linear.', 'Features in production.'],
+    subtitle:
+      'Pull Linear tickets and let AI agents implement them end-to-end with automatic commits.',
+    command: 'ralph-starter run --from linear --label ready',
+    outputLines: [
+      '\u2192 Fetching Linear issues (ready)...',
+      '  Found 4 issues: RAL-41, RAL-42, RAL-43, RAL-44',
+      '\u2192 Processing RAL-42: "Dark mode toggle"',
+      '\u2192 Loop 1/8: Implementing theme provider...',
+      '\u2192 Loop 2/8: Adding CSS variables...',
+      '\u2192 Validation passed: build clean',
+    ],
+    successLine: '\u2713 Done! Cost: $0.52 | 5 commits',
+  },
+  {
+    id: 'notion',
+    tagline: ['Specs in Notion.', 'Code writes itself.'],
+    subtitle:
+      'Import requirements from Notion pages and let AI agents turn them into production-ready code.',
+    command: 'ralph-starter run --from notion --project "API Spec"',
+    outputLines: [
+      '\u2192 Fetching Notion page: "API Spec"...',
+      '  Parsed: 3 sections, 12 endpoints',
+      '\u2192 Loop 1/6: Scaffolding Express routes...',
+      '\u2192 Loop 2/6: Adding middleware & validation...',
+      '\u2192 Loop 3/6: Writing integration tests...',
+      '\u2192 Validation passed: 18 tests, lint clean',
+    ],
+    successLine: '\u2713 Done! Cost: $0.61 | 4 commits',
+  },
+];
+
 export default function HeroSection(): React.ReactElement {
   const [isVisible, setIsVisible] = useState(false);
   const [copied, setCopied] = useState(false);
+  const [scenarioIndex, setScenarioIndex] = useState(0);
 
   useEffect(() => {
+    setScenarioIndex(Math.floor(Math.random() * DEMO_SCENARIOS.length));
     const timer = setTimeout(() => setIsVisible(true), 100);
     return () => clearTimeout(timer);
   }, []);
 
+  const scenario = DEMO_SCENARIOS[scenarioIndex];
+
   const handleCopy = useCallback(async () => {
     try {
       await navigator.clipboard.writeText('npx ralph-starter');
@@ -50,12 +130,16 @@ export default function HeroSection(): React.ReactElement {
           {/* Left: Text content */}
           <div className={styles.heroContent}>
             <h1 className={`${styles.tagline} ${styles.animateIn} ${styles.delay1}`}>
-              Get specs from anywhere.<br />
-              Run AI loops<br /> from zero to prod.
+              {scenario.tagline[0]}<br />
+              {scenario.tagline[1]}
             </h1>
 
             <p className={`${styles.subtitle} ${styles.animateIn} ${styles.delay2}`}>
-              Connect your tools, fetch requirements, and let AI agents build production-ready code automatically.
+              {scenario.subtitle} Also works with {
+                ['Figma', 'GitHub', 'Linear', 'Notion']
+                  .filter(name => name.toLowerCase() !== scenario.id)
+                  .join(', ')
+              } specs.
             </p>
 
             {/* CTA row: button + install command + integrations */}
@@ -105,13 +189,13 @@ export default function HeroSection(): React.ReactElement {
               <div className={styles.terminalBody}>
                 <div className={styles.terminalLine}>
                   <span className={styles.terminalPrompt}>$</span>
-                  <span className={styles.terminalCommand}> ralph-starter run &quot;build a todo app&quot; --commit</span>
+                  <span className={styles.terminalCommand}> {scenario.command}</span>
                 </div>
                 <div className={styles.terminalOutput}>
-                  <div>✓ Loop 1: Analyzing requirements...</div>
-                  <div>✓ Loop 2: Creating components...</div>
-                  <div>✓ Loop 3: Adding tests...</div>
-                  <div className={styles.terminalSuccess}>✓ Done! Cost: $0.42 | 3 commits created</div>
+                  {scenario.outputLines.map((line, i) => (
+                    <div key={i}>{line}</div>
+                  ))}
+                  <div className={styles.terminalSuccess}>{scenario.successLine}</div>
                 </div>
               </div>
             </div>
@@ -120,34 +204,20 @@ export default function HeroSection(): React.ReactElement {
             <div className={styles.integrations}>
               <span className={styles.integrationLabel}>Integrations</span>
               <div className={styles.integrationLogos}>
-                <Link to="/docs/sources/github" className={styles.integrationLink}>
-                  <img
-                    src={useBaseUrl('/img/github logo.webp')}
-                    alt="GitHub"
-                    className={styles.integrationLogo}
-                  />
-                </Link>
-                <Link to="/docs/sources/figma" className={styles.integrationLink}>
-                  <img
-                    src={useBaseUrl('/img/figma-logo.svg')}
-                    alt="Figma"
-                    className={styles.integrationLogo}
-                  />
-                </Link>
-                <Link to="/docs/sources/linear" className={styles.integrationLink}>
-                  <img
-                    src={useBaseUrl('/img/linear.jpeg')}
-                    alt="Linear"
-                    className={styles.integrationLogo}
-                  />
-                </Link>
-                <Link to="/docs/sources/notion" className={styles.integrationLink}>
-                  <img
-                    src={useBaseUrl('/img/notion logo.png')}
-                    alt="Notion"
-                    className={styles.integrationLogo}
-                  />
-                </Link>
+                {[
+                  { id: 'figma' as const, to: '/docs/cli/figma', src: '/img/figma-logo.svg', alt: 'Figma' },
+                  { id: 'github' as const, to: '/docs/sources/github', src: '/img/github logo.webp', alt: 'GitHub' },
+                  { id: 'linear' as const, to: '/docs/sources/linear', src: '/img/linear.jpeg', alt: 'Linear' },
+                  { id: 'notion' as const, to: '/docs/sources/notion', src: '/img/notion logo.png', alt: 'Notion' },
+                ].map(({ id, to, src, alt }) => (
+                  <Link key={id} to={to} className={styles.integrationLink}>
+                    <img
+                      src={useBaseUrl(src)}
+                      alt={alt}
+                      className={`${styles.integrationLogo} ${scenario.id === id ? styles.integrationLogoActive : ''}`}
+                    />
+                  </Link>
+                ))}
               </div>
             </div>
           </div>
diff --git a/docs/src/components/HeroSection/styles.module.css b/docs/src/components/HeroSection/styles.module.css
index 7d93f26e..c6964160 100644
--- a/docs/src/components/HeroSection/styles.module.css
+++ b/docs/src/components/HeroSection/styles.module.css
@@ -327,7 +327,8 @@
   transition: all 0.3s ease;
 }
 
-.integrationLogo:hover {
+.integrationLogo:hover,
+.integrationLogoActive {
   opacity: 0.8;
   filter: grayscale(0%) brightness(1);
 }
diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx
index d8d12e1b..604adff6 100644
--- a/docs/src/pages/index.tsx
+++ b/docs/src/pages/index.tsx
@@ -3,15 +3,16 @@ import { useEffect } from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
 import HeroSection from '@site/src/components/HeroSection';
+import FigmaShowcase from '@site/src/components/FigmaShowcase';
+import VisualValidation from '@site/src/components/VisualValidation';
 import FeatureSections from '@site/src/components/FeatureSections';
-import QuickStart from '@site/src/components/QuickStart';
-import UseCases from '@site/src/components/UseCases';
-import ClientShowcase from '@site/src/components/ClientShowcase';
-import LLMProviders from '@site/src/components/LLMProviders';
-import IntegrationShowcase from '@site/src/components/IntegrationShowcase';
 import AutoMode from '@site/src/components/AutoMode';
+import QuickStart from '@site/src/components/QuickStart';
 import PresetsShowcase from '@site/src/components/PresetsShowcase';
 import SkillsShowcase from '@site/src/components/SkillsShowcase';
+import UseCases from '@site/src/components/UseCases';
+import AgentEcosystem from '@site/src/components/AgentEcosystem';
+import IntegrationShowcase from '@site/src/components/IntegrationShowcase';
 
 export default function Home(): ReactNode {
   useDocusaurusContext();
@@ -27,17 +28,18 @@ export default function Home(): ReactNode {
   return (
     <Layout
       title="Home"
-      description="Connect your tools like Figma, GitHub, Linear, and Notion. Fetch specs from anywhere and let AI coding agents build production-ready code automatically with autonomous loops.">
+      description="AI-powered autonomous coding from specs to production. Connect Figma, GitHub, Linear, and Notion to run AI coding loops with visual validation.">
       <HeroSection />
       <main>
+        <FigmaShowcase />
+        <VisualValidation />
         <FeatureSections />
         <AutoMode />
+        <QuickStart />
         <PresetsShowcase />
         <SkillsShowcase />
-        <QuickStart />
         <UseCases />
-        <ClientShowcase />
-        <LLMProviders />
+        <AgentEcosystem />
         <IntegrationShowcase />
       </main>
     </Layout>

From 0b3c6eacebfb97bfcfbdcb6db89461a597af993f Mon Sep 17 00:00:00 2001
From: ruben-cytonic <ruben@cytonic.com>
Date: Sun, 8 Mar 2026 12:36:06 +0000
Subject: [PATCH 2/2] fix(docs): remove imports of non-existent homepage
 components

The index.tsx referenced FigmaShowcase, VisualValidation, and
AgentEcosystem components that were never created. Restored the
original ClientShowcase and LLMProviders components that exist.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/src/pages/index.tsx | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx
index 604adff6..5856d711 100644
--- a/docs/src/pages/index.tsx
+++ b/docs/src/pages/index.tsx
@@ -3,16 +3,15 @@ import { useEffect } from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
 import HeroSection from '@site/src/components/HeroSection';
-import FigmaShowcase from '@site/src/components/FigmaShowcase';
-import VisualValidation from '@site/src/components/VisualValidation';
 import FeatureSections from '@site/src/components/FeatureSections';
-import AutoMode from '@site/src/components/AutoMode';
 import QuickStart from '@site/src/components/QuickStart';
-import PresetsShowcase from '@site/src/components/PresetsShowcase';
-import SkillsShowcase from '@site/src/components/SkillsShowcase';
 import UseCases from '@site/src/components/UseCases';
-import AgentEcosystem from '@site/src/components/AgentEcosystem';
+import ClientShowcase from '@site/src/components/ClientShowcase';
+import LLMProviders from '@site/src/components/LLMProviders';
 import IntegrationShowcase from '@site/src/components/IntegrationShowcase';
+import AutoMode from '@site/src/components/AutoMode';
+import PresetsShowcase from '@site/src/components/PresetsShowcase';
+import SkillsShowcase from '@site/src/components/SkillsShowcase';
 
 export default function Home(): ReactNode {
   useDocusaurusContext();
@@ -31,15 +30,14 @@ export default function Home(): ReactNode {
       description="AI-powered autonomous coding from specs to production. Connect Figma, GitHub, Linear, and Notion to run AI coding loops with visual validation.">
       <HeroSection />
       <main>
-        <FigmaShowcase />
-        <VisualValidation />
         <FeatureSections />
         <AutoMode />
         <QuickStart />
         <PresetsShowcase />
         <SkillsShowcase />
         <UseCases />
-        <AgentEcosystem />
+        <ClientShowcase />
+        <LLMProviders />
         <IntegrationShowcase />
       </main>
     </Layout>