feat: improve guide

apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx

@@ -28,7 +28,9 @@ const tocItems = [
   { id: 'quick-start', text: 'Quick Start', level: 2 },
   { id: 'organizing-placeholders', text: 'Organizing Placeholders', level: 2 },
   { id: 'prompt-tips', text: 'Prompt Tips', level: 2 },
-  { id: 'recipes', text: 'Recipes', level: 2 },
+  { id: 'light-mode-placeholders', text: 'Light Mode Placeholders', level: 2 },
+  { id: 'dark-mode-placeholders', text: 'Dark Mode Placeholders', level: 2 },
+  { id: 'placeholder-image-examples', text: 'Placeholder Image Examples', level: 2 },
   { id: 'file-based-workflow', text: 'File-based Workflow', level: 2 },
 ];
 
@@ -67,7 +69,7 @@ export default function PlaceholderImagesGuidePage() {
         />
 
         {/* What This Guide Covers */}
-        <section id="what-this-guide-covers" className="mb-12">
+        <section id="what-this-guide-covers" className="mb-12 scroll-mt-24">
           <SectionHeader level={2} id="what-this-guide-covers">
             What This Guide Covers
           </SectionHeader>
@@ -76,12 +78,16 @@ export default function PlaceholderImagesGuidePage() {
           </p>
           <ul className="list-disc list-inside text-gray-300 space-y-2 mb-6">
             <li>
-              <strong className="text-white">Live URLs</strong> — describe what you need right in{' '}
+              <a href="#quick-start" className="text-white font-semibold hover:text-purple-400">
-              <InlineCode>&lt;img&gt;</InlineCode> src URLs
+                Live URLs
+              </a>{' '}
+              — describe what you need right in <InlineCode>&lt;img&gt;</InlineCode> src URLs
             </li>
             <li>
-              <strong className="text-white">API generation</strong> — full control, permanent URLs,
+              <a href="#file-based-workflow" className="text-white font-semibold hover:text-purple-400">
-              downloadable files
+                API generation
+              </a>{' '}
+              — full control, permanent URLs, downloadable files
             </li>
           </ul>
           <p className="text-gray-300 leading-relaxed">
@@ -90,7 +96,7 @@ export default function PlaceholderImagesGuidePage() {
         </section>
 
         {/* How to Create Placeholders */}
-        <section id="how-to-create-placeholders" className="mb-12">
+        <section id="how-to-create-placeholders" className="mb-12 scroll-mt-24">
           <SectionHeader level={2} id="how-to-create-placeholders">
             How to Create Placeholders
           </SectionHeader>
@@ -143,7 +149,7 @@ export default function PlaceholderImagesGuidePage() {
         </section>
 
         {/* Quick Start */}
-        <section id="quick-start" className="mb-12">
+        <section id="quick-start" className="mb-12 scroll-mt-24">
           <SectionHeader level={2} id="quick-start">
             Quick Start
           </SectionHeader>
@@ -203,7 +209,7 @@ export default function PlaceholderImagesGuidePage() {
         </section>
 
         {/* Organizing Placeholders */}
-        <section id="organizing-placeholders" className="mb-12">
+        <section id="organizing-placeholders" className="mb-12 scroll-mt-24">
           <SectionHeader level={2} id="organizing-placeholders">
             Organizing Placeholders
           </SectionHeader>
@@ -227,7 +233,7 @@ export default function PlaceholderImagesGuidePage() {
         </section>
 
         {/* Prompt Tips */}
-        <section id="prompt-tips" className="mb-12">
+        <section id="prompt-tips" className="mb-12 scroll-mt-24">
           <SectionHeader level={2} id="prompt-tips">
             Prompt Tips
           </SectionHeader>
@@ -236,12 +242,21 @@ export default function PlaceholderImagesGuidePage() {
             <div>
               <h4 className="text-white font-semibold mb-2">Write less, not more</h4>
               <p className="text-gray-300 mb-2">
-                For placeholders, simple prompts work best. Templates add the details:
+                For placeholders, simple prompts are often enough. You can always add more details
+                later if needed. Templates handle the rest:
               </p>
               <ul className="list-none text-gray-300 space-y-1">
-                <li>Want an office? Write &quot;office&quot;</li>
                 <li>
-                  Need something specific? Add only what matters: &quot;office dark theme&quot;
+                  <span className="text-gray-500">→</span> Want an office? Write{' '}
+                  <InlineCode>office</InlineCode>
+                </li>
+                <li>
+                  <span className="text-gray-500">→</span> Need a dark version? Add{' '}
+                  <InlineCode>office dark background</InlineCode>
+                </li>
+                <li>
+                  <span className="text-gray-500">→</span> Templates handle lighting, composition,
+                  style
                 </li>
               </ul>
             </div>
@@ -266,10 +281,76 @@ export default function PlaceholderImagesGuidePage() {
           </div>
         </section>
 
-        {/* Recipes */}
+        {/* Light Mode Placeholders */}
-        <section id="recipes" className="mb-12">
+        <section id="light-mode-placeholders" className="mb-12 scroll-mt-24">
-          <SectionHeader level={2} id="recipes">
+          <SectionHeader level={2} id="light-mode-placeholders">
-            Recipes
+            Light Mode Placeholders
+          </SectionHeader>
+          <p className="text-gray-300 leading-relaxed mb-4">
+            Generated images work well with light interfaces by default. If you need more control,
+            specify background colors or accents to match your design system.
+          </p>
+
+          <CodeBlock
+            code={`"product on white background"
+"office with soft natural light"
+"portrait, bright studio, pastel tones"
+"dashboard mockup, light gray background, blue accent"`}
+            language="text"
+          />
+
+          <div className="mt-6">
+            <LivePreview label="Light Background Example">
+              <div className="bg-white rounded-xl p-6 max-w-md">
+                <img
+                  src="https://cdn.banatie.app/sys/demo/live/products?prompt=minimalist+desk+setup+white+background+clean+aesthetic&aspectRatio=16:9"
+                  alt="Light theme placeholder"
+                  className="w-full rounded-lg mb-4"
+                />
+                <p className="text-gray-900 font-semibold">Clean Workspace</p>
+                <p className="text-gray-600 text-sm">White background, natural lighting</p>
+              </div>
+            </LivePreview>
+          </div>
+        </section>
+
+        {/* Dark Mode Placeholders */}
+        <section id="dark-mode-placeholders" className="mb-12 scroll-mt-24">
+          <SectionHeader level={2} id="dark-mode-placeholders">
+            Dark Mode Placeholders
+          </SectionHeader>
+          <p className="text-gray-300 leading-relaxed mb-4">
+            For dark interfaces, add <InlineCode>dark background</InlineCode> or descriptive words
+            like night, moody, or twilight. You can also specify accent colors.
+          </p>
+
+          <CodeBlock
+            code={`"office interior, dark background"
+"product photo, dark surface, moody lighting"
+"night cityscape, neon accents"
+"abstract gradient, dark purple and blue"`}
+            language="text"
+          />
+
+          <div className="mt-6">
+            <LivePreview label="Dark Background Example">
+              <div className="bg-slate-900 rounded-xl p-6 max-w-md border border-slate-700">
+                <img
+                  src="https://cdn.banatie.app/sys/demo/live/hero?prompt=abstract+gradient+dark+background+purple+blue+moody&aspectRatio=16:9"
+                  alt="Dark theme placeholder"
+                  className="w-full rounded-lg mb-4"
+                />
+                <p className="text-white font-semibold">Dark Gradient</p>
+                <p className="text-gray-400 text-sm">Dark background with purple accents</p>
+              </div>
+            </LivePreview>
+          </div>
+        </section>
+
+        {/* Placeholder Image Examples */}
+        <section id="placeholder-image-examples" className="mb-12 scroll-mt-24">
+          <SectionHeader level={2} id="placeholder-image-examples">
+            Placeholder Image Examples
           </SectionHeader>
           <p className="text-gray-300 leading-relaxed mb-8">
             Copy-paste examples for common placeholder image use cases.
@@ -417,7 +498,7 @@ export default function PlaceholderImagesGuidePage() {
                   </div>
                   <div className="bg-white rounded-lg p-3">
                     <img
-                      src="https://cdn.banatie.app/sys/demo/live/products?prompt=laptop+stand+aluminum+product+photo&aspectRatio=1:1"
+                      src="https://cdn.banatie.app/sys/demo/live/products?prompt=laptop+stand+aluminum+product&aspectRatio=1:1"
                       alt="Laptop Stand"
                       className="w-full aspect-square object-cover rounded-md mb-2"
                     />
@@ -521,32 +602,32 @@ export default function PlaceholderImagesGuidePage() {
             </p>
 
             <LivePreview>
-              <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+              <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
-                <div className="text-center">
+                <div className="bg-slate-800/60 border border-slate-700/50 rounded-xl p-6 text-center">
                   <img
-                    src="https://cdn.banatie.app/sys/demo/live/features?prompt=minimal+icon+illustration+lightning+bolt+speed+blue&aspectRatio=1:1"
+                    src="https://cdn.banatie.app/sys/demo/live/features?prompt=minimal+icon+lightning+bolt+blue+glow+dark+slate+background&aspectRatio=1:1"
                     alt="Lightning Fast"
-                    className="w-16 h-16 mx-auto rounded-lg"
+                    className="w-20 h-20 mx-auto rounded-xl border border-slate-600/50"
                   />
                   <p className="mt-4 font-semibold text-white">Lightning Fast</p>
                   <p className="mt-2 text-sm text-gray-400">
                     Deploy in seconds with our global CDN
                   </p>
                 </div>
-                <div className="text-center">
+                <div className="bg-slate-800/60 border border-slate-700/50 rounded-xl p-6 text-center">
                   <img
-                    src="https://cdn.banatie.app/sys/demo/live/features?prompt=minimal+icon+illustration+shield+security+green&aspectRatio=1:1"
+                    src="https://cdn.banatie.app/sys/demo/live/features?prompt=minimal+icon+shield+green+glow+dark+slate+background&aspectRatio=1:1"
                     alt="Secure by Default"
-                    className="w-16 h-16 mx-auto rounded-lg"
+                    className="w-20 h-20 mx-auto rounded-xl border border-slate-600/50"
                   />
                   <p className="mt-4 font-semibold text-white">Secure by Default</p>
                   <p className="mt-2 text-sm text-gray-400">Enterprise-grade security built in</p>
                 </div>
-                <div className="text-center">
+                <div className="bg-slate-800/60 border border-slate-700/50 rounded-xl p-6 text-center">
                   <img
-                    src="https://cdn.banatie.app/sys/demo/live/features?prompt=minimal+icon+illustration+puzzle+piece+integration+purple&aspectRatio=1:1"
+                    src="https://cdn.banatie.app/sys/demo/live/features?prompt=minimal+icon+puzzle+piece+purple+glow+dark+slate+background&aspectRatio=1:1"
                     alt="Easy Integration"
-                    className="w-16 h-16 mx-auto rounded-lg"
+                    className="w-20 h-20 mx-auto rounded-xl border border-slate-600/50"
                   />
                   <p className="mt-4 font-semibold text-white">Easy Integration</p>
                   <p className="mt-2 text-sm text-gray-400">Works with your existing stack</p>
@@ -555,18 +636,25 @@ export default function PlaceholderImagesGuidePage() {
             </LivePreview>
 
             <CodeBlock
-              code={`<img
+              code={`<div class="grid grid-cols-1 md:grid-cols-3 gap-4">
-  src="https://cdn.banatie.app/{org}/{project}/live/features?prompt=icon+lightning+bolt&aspectRatio=1:1"
+  <div class="bg-slate-800/60 border border-slate-700/50 rounded-xl p-6 text-center">
-  alt="Feature icon"
+    <img
-  class="w-16 h-16 rounded-lg"
+      src="https://cdn.banatie.app/{org}/{project}/live/features?prompt=minimal+icon+lightning+bolt+blue+glow+dark+slate+background&aspectRatio=1:1"
-/>`}
+      alt="Lightning Fast"
+      class="w-20 h-20 mx-auto rounded-xl border border-slate-600/50"
+    />
+    <p class="mt-4 font-semibold text-white">Lightning Fast</p>
+    <p class="mt-2 text-sm text-gray-400">Deploy in seconds with our global CDN</p>
+  </div>
+  <!-- Repeat for other features -->
+</div>`}
               language="html"
             />
           </div>
         </section>
 
         {/* File-based Workflow */}
-        <section id="file-based-workflow" className="mb-12">
+        <section id="file-based-workflow" className="mb-12 scroll-mt-24">
           <SectionHeader level={2} id="file-based-workflow">
             File-based Workflow
           </SectionHeader>
@@ -582,23 +670,35 @@ export default function PlaceholderImagesGuidePage() {
           </ul>
 
           <h4 className="text-white font-semibold mb-3">Generate via API</h4>
+          <p className="text-gray-300 leading-relaxed mb-4">Request:</p>
           <CodeBlock
-            code={`// Generate image
+            code={`POST https://api.banatie.app/v1/generations
-const response = await fetch('https://api.banatie.app/v1/generations', {
+Content-Type: application/json
-  method: 'POST',
+X-API-Key: your_api_key
-  headers: {
-    'Content-Type': 'application/json',
-    'X-API-Key': process.env.BANATIE_API_KEY,
-  },
-  body: JSON.stringify({ prompt: 'modern office' }),
-});
 
-const { image } = await response.json();
+{
-console.log(image.cdnUrl); // Download this URL`}
+  "prompt": "modern office interior"
-            language="javascript"
+}`}
+            language="http"
+          />
+
+          <p className="text-gray-300 leading-relaxed mt-6 mb-4">Response:</p>
+          <CodeBlock
+            code={`{
+  "image": {
+    "id": "img_abc123",
+    "cdnUrl": "https://cdn.banatie.app/org/project/images/2025-01/abc123.png"
+  }
+}`}
+            language="json"
           />
 
           <p className="text-gray-300 leading-relaxed mt-6">
+            Open <InlineCode>cdnUrl</InlineCode> in your browser, save the image, and add it to your
+            project&apos;s assets folder.
+          </p>
+
+          <p className="text-gray-300 leading-relaxed mt-4">
             For full API reference, see{' '}
             <a href="/docs/api/generations/" className="text-purple-400 hover:underline">
               Generations API

apps/landing/src/components/docs/layout/DocsSidebar.tsx

@@ -80,7 +80,7 @@ const navigationItems: NavItem[] = [
 ];
 
 export const DocsSidebar = ({ currentPath }: DocsSidebarProps) => {
-  const [expandedSections, setExpandedSections] = useState<string[]>(['API Reference']);
+  const [expandedSections, setExpandedSections] = useState<string[]>(['API Reference', 'Guides']);
 
   const toggleSection = (label: string) => {
     setExpandedSections((prev) =>

apps/landing/src/config/docs-seo.ts

@@ -132,16 +132,18 @@ export const DOCS_PAGES = {
   },
   'guide-placeholder-images': {
     path: '/docs/guides/placeholder-images/',
-    title: 'AI Placeholder Images Guide | Banatie',
+    title: 'AI Placeholder Image Generator — Light & Dark Mode | Banatie',
     description:
-      'Generate AI placeholder images for development. Replace gray boxes with contextual visuals. Sizes for avatars, thumbnails, heroes, and more.',
+      'Generate AI placeholder images for development. Image placeholder dark mode, light backgrounds, avatars, products, heroes. Copy-paste HTML examples.',
     keywords: [
-      'placeholder images',
+      'placeholder image generator',
-      'ai placeholder generator',
-      'placeholder image api',
       'image placeholder dark',
-      'profile placeholder image',
       'placeholder image url',
+      'html placeholder image',
+      'ai placeholder images',
+      'dark mode placeholder',
+      'light mode placeholder',
+      'profile placeholder image',
       'dummy image generator',
     ],
   },