Design: Conversion-Focused API Docs Entry Page (BUY-3699)

Overview

Create a high-conversion variant of the API docs entry page at /docs that minimizes time-to-first-API-call for developers. The current page is a passive list of markdown files; the new variant should be an active onboarding path.

Hypothesis: Reducing docs friction improves activation.

Metric: Layout proposal with navigation, quickstart CTA, and first-call block.

---

Design Direction

Problem Analysis

• Current /docs page is a passive list of markdown files (file-browser pattern)
• Developers must navigate through multiple pages before making their first API call
• No clear CTA to get started beyond "read documentation"
• No interactive element to try the API immediately

Solution: Conversion-Focused Docs Landing

Three-column layout with progressive disclosure:

┌─────────────────────────────────────────────────────────────────────┐
│  [Nav Bar - sticky]                                                │
├───────────┬─────────────────────────────────────┬───────────────────┤
│           │                                     │                   │
│  Sidebar  │  Hero / Quickstart Block           │  Live API         │
│  Nav      │  - Headline                         │  Playground       │
│           │  - CTA (Get API Key)               │  - Try search     │
│  • Intro  │  - First-call code block           │  - See response   │
│  • Auth   │                                     │                   │
│  • Search │  Feature Cards Grid                 │                   │
│  • etc.   │  - Search                          │                   │
│           │  - Compare                         │                   │
│           │  - Deals                           │                   │
│           │  - etc.                            │                   │
│           │                                     │                   │
│           │  [Endpoint Reference List]          │                   │
│           │                                     │                   │
└───────────┴─────────────────────────────────────┴───────────────────┘

---

Layout Sections

1. Hero Section (Above the fold)

• Headline: "Build with BuyWhere in minutes"
• Subheadline: "Product catalog API for AI agents. Search 80,000+ products across Shopee, Lazada, Amazon, and 20+ platforms."
• Primary CTA: "Get API Key →" (links to /api-keys)
• Secondary CTA: "View Quickstart" (links to /quickstart)
• Trust indicators: "No credit card required", "60 requests/min free", "MCP-compatible"

2. First-Call Block (Prominent, above fold)

A copy-paste ready code example that developers can run immediately:

curl "https://api.buywhere.ai/v1/search?q=iphone+15&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

With interactive elements:

• API key input field (optional, for authenticated requests)
• "Run in terminal" button (copies to clipboard)
• "Try without key" button (runs against public demo endpoint)
• Live response preview panel

3. Sidebar Navigation

Sticky left sidebar with collapsible sections:

Getting Started
├── Quickstart      ← highlighted
├── Authentication
├── Rate Limits
├── Error Reference

Core API
├── Search Products
├── Product Details
├── Price Comparison
├── Categories

Advanced
├── Batch Operations
├── Price History
├── Deals & Drops

Integrations
├── MCP Setup
├── SDK Reference
├── Webhooks

4. Feature Cards Grid

Three-column grid of feature highlights:

Each card links to the relevant docs section.

5. Endpoint Reference Table

Quick reference table at the bottom:

---

Component Specifications

Hero Section

• Background: Dark gradient (#0f172a to #1e1b4b)
• Headline: 48px, bold, white
• Subheadline: 18px, slate-300
• CTA buttons: Primary (white bg, indigo text) + Secondary (white/10 bg, white text)

First-Call Block

• Background: Dark (#0f172a) with border (white/10)
• Code block: Dark (#0a0a0a) with syntax highlighting
• Copy button: Ghost style, appears on hover
• Response panel: Collapsible, shows formatted JSON

Sidebar

• Width: 260px (desktop), drawer (mobile)
• Background: White with subtle shadow
• Active item: Indigo-50 bg, indigo-600 text, left border accent
• Hover: Gray-50 bg
• Collapsible sections with chevron indicators

Feature Cards

• Border: 1px slate-200
• Border-radius: 12px
• Padding: 24px
• Hover: Border indigo-200, subtle shadow
• Icon: 24px, indigo-600
• Title: 18px semibold
• Description: 14px slate-600

Endpoint Table

• Striped rows (alternating white/slate-50)
• Method badges: GET (green), POST (blue), PUT (orange), DELETE (red)
• Hover: Row highlights slate-100

---

Responsive Strategy

---

Design Tokens (Existing)

Use from design-tokens.css:

• Primary: #4f46e5 (indigo-600)
• Primary hover: #4338ca (indigo-700)
• Gray palette: slate-50 through slate-900
• Border: slate-200
• Background: white, slate-50
• Typography: Inter font family

---

Implementation Notes

1. Create new component at src/components/docs/DocsLanding.tsx
2. Reuse existing Nav and Footer components
3. Reuse Button component for CTAs
4. Use existing code block styling from quickstart page
5. Sidebar can use existing Sidebar component with new nav items
6. API playground can be a simplified version of DocsSearch

---

Files to Create/Modify

1. Create: src/app/docs/page.tsx (replace existing)

   • New conversion-focused layout
   • Hero + First-call block + Navigation + Feature cards

2. Create: src/components/docs/DocsSidebar.tsx

   • Collapsible sidebar navigation

3. Create: src/components/docs/FirstCallBlock.tsx

   • Interactive code block with API playground

4. Create: src/components/docs/FeatureCard.tsx

   • Reusable feature highlight card

---

Success Criteria

1. Developer can understand the API value proposition in <5 seconds
2. Developer can copy and run a working API call in <30 seconds
3. Developer can navigate to any docs section in ≤2 clicks
4. Mobile experience is fully functional
5. No external dependencies beyond existing components