Requirements: ZERG Website

Requirements: ZERG Website

Status: APPROVED Feature: zerg-website Epic: #204 Date: 2026-02-07 Prior Art: .gsd/specs/brainstorm-website/ (brainstorm, validated-design, research, tradeoffs)

1. Problem Statement

The current MkDocs-based docs site at https://rocklambros.github.io/zerg/ needs a custom landing page that communicates ZERG's value proposition — security, containerized parallel execution, context engineering, and token efficiency — in a way that's visually compelling and potentially viral.

2. Solution

Single-page landing site replacing MkDocs as the homepage. Pure HTML/CSS/JS with Tailwind CDN. Deployed via repurposed docs.yml GitHub Actions workflow. Existing MkDocs documentation remains accessible at sub-paths.

3. Scope

In Scope

• Custom index.html landing page (7 sections + sticky nav)
• Dark-first design with light mode toggle
• All 26 commands in cheat sheet table
• 4 glass pillar cards (Security, Containers, Parallelism, Context Engineering)
• Optimized logo (<200KB web version)
• Responsive design (mobile, tablet, desktop)
• SEO meta tags + Open Graph
• Scroll animations
• Repurposed GitHub Actions workflow
• Existing docs content preserved and accessible

Out of Scope

• Blog or dynamic content
• User accounts / authentication
• Analytics beyond what GitHub provides
• Custom domain (uses rocklambros.github.io/zerg/)
• JavaScript frameworks (React, Vue, etc.)
• Build step / bundler / node_modules

4. Sections (in order)

4.1 Sticky Navigation Bar

• Fixed top bar, semi-transparent background with backdrop blur
• Left: ZERG logo (optimized) + wordmark
• Center: Section anchor links (Why, How, Commands, Quick Start, FAQ)
• Right: Dark/light toggle (sun/moon icon) + prominent GitHub repo link (icon + "GitHub" text, not just an icon)
• Smooth scroll to anchors on click
• Collapses to hamburger menu on mobile

4.2 Hero Section

• Tone: Playful Zerg-themed, viral-worthy, but grounded in real value
• Headline: Commanding statement incorporating the swarm metaphor + value props (security, parallel execution, token efficiency). Aim for memorable/shareable.
• Subheadline: One-liner explaining what ZERG actually is
• CTA: pip install zerg-ai with copy-to-clipboard button
• 4 Glass Pillar Cards (glassmorphism style, frosted panels):
  1. Secure by Default — Auto-fetched OWASP rules, language-specific security
  2. Run Anywhere — Docker containers, subprocess, or task mode
  3. Massively Parallel — Coordinated workers with dependency-aware scheduling
  4. Token Smart — Context engineering: 30-50% token savings per worker

4.3 Why ZERG

• Compact format: 3-4 bullet pairs (pain point → ZERG solution)
• Example pairs:
  • Manual setup for every feature → Auto-detects stack, fetches rules, generates configs
  • Sequential execution bottleneck → 5+ workers building in parallel
  • Context rot across long sessions → Spec-driven workers, stateless and restartable
  • Token waste on repeated context → Context engineering splits + scoped budgets

4.4 How It Works

• Responsive pipeline visualization: horizontal on desktop, vertical on mobile
• 4 stages with icons: Plan → Design → Rush → Merge
• Each stage: icon + title + 1-line description
• Connecting arrows/lines between stages
• Brief explanation of what happens at each step

4.5 Commands Cheat Sheet

• Full table of all 26 /zerg:* commands
• Columns: Command | Description (one-liner)
• Grouped by category (workflow, utilities, monitoring)
• Link to GitHub wiki for deep documentation
• Searchable/filterable if feasible with vanilla JS, otherwise static table

4.6 Quick Start

• 4-step code block with copy-to-clipboard:

  pip install zerg-ai
  /zerg:plan user-auth
  /zerg:design
  /zerg:rush --workers=5
  

• Brief annotation per step

4.7 Stats / Social Proof

• Feature stats: 26 commands, 3 execution modes, 8 cross-cutting capabilities
• Performance claims: "10x faster feature delivery", "30-50% token savings"
• Displayed as animated counter cards or bold stat blocks

4.8 FAQ

• Expandable accordion (details/summary or vanilla JS)
• Smooth expand/collapse animation
• Questions TBD during design phase (cover: install, requirements, pricing, Claude API key, container setup, comparison to alternatives)

4.9 Footer

• Links: GitHub repo, Wiki docs, Sponsor, License (Apache 2.0)
• "Built with Claude Code" attribution
• Copyright line

5. Visual Style

• Dark-first: Dark navy background (#0f172a or similar)
• Light mode: Clean white/light gray, toggle via sun/moon icon
• Accent colors: Purple (#7c3aed) and toxic green (#22c55e) — Zerg-inspired, subtle
• Glassmorphism: Frosted panels with backdrop-filter: blur(), semi-transparent borders
• Typography: System font stack for body, monospace for code blocks
• Gradient text: For hero headline emphasis
• Scroll animations: Staggered fade-in on section entry (IntersectionObserver)
• Code blocks: Dark background with syntax-style coloring, copy button

6. Technical Requirements

6.1 Stack

• HTML5 + Tailwind CSS (Play CDN) + vanilla JavaScript
• Zero build step, zero dependencies
• No node_modules, no bundler, no framework

6.2 File Structure

docs/
  index.html              # Landing page (new)
  assets/
    css/
      custom.css          # Custom styles beyond Tailwind
    js/
      main.js             # Dark/light toggle, copy-to-clipboard, FAQ accordion, scroll animations
    img/
      zerg-logo-web.png   # Optimized logo (<200KB)
      og-image.png        # Open Graph preview image
  commands-quick.md       # Existing (preserved)
  commands-deep.md        # Existing (preserved)
  tutorial-minerals-store.md  # Existing (preserved)
  configuration.md        # Existing (preserved)
  ...                     # Other existing docs

6.3 Deployment

• Repurpose .github/workflows/docs.yml
• Change build step: replace mkdocs build with simple file copy/upload of docs/
• Update path triggers to include docs/** (already present)
• Remove mkdocs.yml trigger (or keep for backward compat)
• Upload docs/ as pages artifact instead of site/

6.4 Logo Optimization

• Source: logo/zerg_logo.png (7.6MB)
• Target: docs/assets/img/zerg-logo-web.png (<200KB)
• Resize to max 400px width for web display
• Compress with quality optimization
• Generate separate OG image (1200x630) for social sharing

7. Non-Functional Requirements

8. Acceptance Criteria

1. Landing page loads at https://rocklambros.github.io/zerg/
2. All 7 content sections render correctly
3. Dark/light mode toggle works and persists via localStorage
4. All 26 commands appear in cheat sheet table
5. Copy-to-clipboard works for code blocks
6. FAQ accordion expands/collapses smoothly
7. Sticky nav scrolls to correct sections
8. Mobile hamburger menu works
9. Existing docs (commands-quick, tutorial, etc.) remain accessible via direct URL
10. Logo loads optimized (<200KB)
11. Open Graph meta tags present and valid
12. Page passes Lighthouse audit (Performance >90, Accessibility >95)
13. No JavaScript framework dependencies
14. GitHub Actions workflow deploys successfully on push to main

9. Dependencies

• GitHub Pages enabled on repo (already configured)
• docs.yml workflow (exists, needs modification)
• logo/zerg_logo.png (exists, needs optimization)
• Image optimization tool (ImageMagick, sharp, or similar — CI or local)

10. GitHub Issues (Pre-Created)

11. Documentation Impact

• CHANGELOG.md: Entry under [Unreleased] > Added for custom landing page
• README.md: Update docs link if URL structure changes
• mkdocs.yml: May be removed or retained as reference only
• docs.yml: Modified workflow (significant change, document in PR)

12. Open Questions

1. Headline copy: Exact wording for viral hero headline (to be drafted during design)
2. FAQ content: Specific Q&A pairs (to be defined during design)
3. OG image design: RESOLVED — Use optimized zerg logo as OG image base (1200x630, logo centered on dark background)
4. MkDocs removal timing: Remove mkdocs.yml + pip install in same PR, or separate cleanup PR?
5. Custom domain: RESOLVED — zerg-ai.com planned. OG URLs and meta tags should use zerg-ai.com as canonical. GitHub Pages serves as interim until domain is configured.

13. Risks