Build world-class marketing website for lumos-lang.org

[rz1989s]

Vision

Create a world-class marketing website for LUMOS that rivals the best developer tool sites (Linear, Vercel, Stripe).

Goal: Convert visitors from "What is LUMOS?" to "I need to try this now" in under 30 seconds.

---

Quick Summary

Technology Stack:

• Next.js 14 (App Router, RSC)
• TypeScript (strict mode)
• Tailwind CSS (dark theme)
• Framer Motion (animations)
• Shiki (syntax highlighting)
• Vercel (deployment + analytics)

Key Sections:

1. Hero - Hook developers in 5 seconds
2. Problem Statement - The pain of manual Borsh
3. Live Code Demo - Interactive editor
4. Features Grid - 6 key capabilities
5. Before/After - Code comparison
6. Use Cases - Gaming, DeFi, NFT, DAO
7. Stats - Social proof
8. Ecosystem - CLI, Docs, VSCode, Examples
9. Getting Started - 3-step process
10. Footer - Resources & links

Success Metrics:

• Lighthouse score 95+
• Time to Interactive < 1.5s
• Bounce rate < 40%
• GitHub CTR > 15%
• WCAG 2.1 AA compliant

---

Complete Specification

Full detailed specification saved in: docs/marketing-website-spec.md

Includes:

• Complete page structure (10 sections)
• Design system (colors, typography, animations)
• Technical requirements (performance, accessibility)
• Development phases (5 weeks)
• Content strategy & SEO
• Repository structure
• Design inspiration references

---

Next Steps

1. Create new repository: getlumos/lumos-website
2. Set up Next.js 14 project
3. Review and approve design direction
4. Development (follow 5-week phases)
5. Deploy to Vercel
6. Point lumos-lang.org to deployment

---

Priority: High
Impact: Critical for ecosystem growth and developer adoption
Timeline: 3-4 weeks to production
Estimated Effort: 1 developer full-time

Related: #34 (syntax highlighting)

[rz1989s]

---

📌 Remember: Update ROADMAP.md after completing this issue!

[rz1989s]

🔄 Architecture Update: Next.js → Astro

After analysis, switching to Astro 5.6 for world-class performance and consistency with docs-lumos.

Why Astro for World-Class Marketing

Performance = First Impression

• Zero JavaScript by default (Next.js ships ~150KB, Astro <50KB)
• Lighthouse 100/100 trivial to achieve
• Instant page loads = professional impression

Consistency with Ecosystem

• docs-lumos uses Astro + Starlight
• Single tech stack = easier maintenance
• Team expertise in one framework

Island Architecture = Best of Both Worlds

---
// Static sections = pure HTML (instant)
---
<Hero />
<ProblemStatement />

<!-- Interactive demo = React island with Framer Motion -->
<LiveCodeDemo client:visible />

<FeaturesGrid />

Updated Tech Stack

Core Framework

• ✅ Astro 5.6 (View Transitions, Islands)
• ✅ TypeScript (strict mode)
• ✅ Tailwind CSS (dark theme)
• ✅ React (islands only, for complex interactions)

World-Class Animation & Interactions

• ✅ Framer Motion (sophisticated component animations)
• ✅ GSAP (advanced timeline animations, ScrollTrigger)
• ✅ View Transitions API (Astro native, instant page transitions)
• ✅ Lenis (butter-smooth scroll with momentum)
• ✅ Rough Notation (hand-drawn emphasis effects)
• ✅ Three.js or Spline (optional 3D hero background/grid)

Code & Syntax

• ✅ Shiki (syntax highlighting with custom themes)
• ✅ Monaco Editor (live code demo, VSCode-like experience)
• ✅ Prettier (format code examples in real-time)

Performance & SEO

• ✅ Astro Image Optimization (automatic WebP, responsive)
• ✅ View Transitions (native SPA feel, zero JS)
• ✅ Partytown (web workers for analytics)

Deployment

• ✅ Vercel (supports Astro, edge functions)
• ✅ Vercel Analytics (Core Web Vitals)

---

World-Class Features (Enterprise-Level)

1. Hero Section - Cinematic Entrance

Advanced Features:

• Animated gradient mesh background (GSAP + CSS gradients)
• Particle system or 3D grid (Three.js) - subtle, not distracting
• Terminal demo with typed animation (typing effect + syntax highlighting)
• Magnetic cursor effect on CTAs (follows mouse with spring physics)
• Floating trust badges with subtle parallax
• Code transformation visualization (.lumos morphs into Rust + TS)

Animation Timeline:

1. Gradient mesh fades in (0-300ms)
2. Headline slides up with blur fade (300-600ms)
3. Subheadline appears (600-900ms)
4. Terminal starts typing (900ms+)
5. CTAs slide in with bounce (1200ms)

---

2. Interactive Code Demo - Live Editor

Features:

• Monaco Editor (full VSCode experience in browser)
• Real-time .lumos → Rust/TS generation
• Split-pane with smooth resize
• Copy button with animated checkmark feedback
• Download button generates .zip with working project
• Example selector with smooth transitions
• Line highlighting on hover
• Minimap for generated code

Advanced:

• Save to localStorage (persist user edits)
• Share button (generate shareable URL with code)
• Diff view (show changes as user edits)
• Error highlighting with tooltips

---

3. Before/After Comparison - Cinematic Reveal

Animation:

• Scroll-triggered split reveal (GSAP ScrollTrigger)
• Code appears line-by-line as you scroll
• Highlight differences with color coding
• Interactive slider to compare BEFORE ↔ AFTER
• Line count comparison (50 lines → 7 lines) with animated counter

---

4. Micro-Interactions Everywhere

Hover States:

• Cards lift with shadow + scale
• Buttons: gradient shift, scale, shadow
• Code blocks: border glow on hover
• Links: underline animation (left to right)

Cursor Effects:

• Custom cursor with trailing gradient
• Magnetic effect on interactive elements
• Cursor changes on different sections (pointer, text, code)

Loading States:

• Skeleton screens with shimmer effect
• Smooth fade-in for lazy-loaded content
• Progress indicators for async operations

---

5. Scroll Animations - Purposeful Motion

Lenis Smooth Scroll:

• Momentum-based scrolling (feels native, looks premium)
• Easing curve tuned for developer tools (not too slow)

GSAP ScrollTrigger:

• Sections fade/slide in as you scroll
• Parallax effects on background elements
• Stats counter animates when in viewport
• Code examples reveal line-by-line

View Transitions:

• Navigation between sections feels instant
• No page reloads, SPA experience
• Smooth cross-fade between views

---

6. Typography Perfection

Font System:

• Display: Inter (900 weight, tight tracking)
• Headings: Inter (700-800 weight)
• Body: Inter (400-500 weight)
• Code: JetBrains Mono (ligatures enabled)

Advanced Typography:

• Fluid type scale (clamp() for responsive sizing)
• Optical alignment for headlines
• Kerning adjustments on large text
• Text gradients on hero headline

---

7. 3D & Depth Effects

Hero Background Options:

1. Animated 3D grid (Three.js, subtle rotation)
2. Particle field (stars, responds to mouse)
3. Gradient mesh (organic, flowing blobs)

Layering:

• Multiple z-index layers with different scroll speeds
• Blur effects on background layers
• Drop shadows with realistic light source
• Glassmorphism on cards (backdrop-filter)

---

8. Mobile - Not Just Responsive, Beautiful

Mobile-First Interactions:

• Swipeable code examples
• Bottom sheet for CTAs (native feel)
• Touch-friendly hit areas (minimum 44x44px)
• Optimized animations (reduced motion on mobile)
• Pinch-to-zoom on code blocks

Performance:

• Lazy load images below fold
• Defer non-critical JS
• Critical CSS inlined
• Resource hints (preconnect, prefetch)

---

9. Accessibility - WCAG 2.1 AAA

Beyond Compliance:

• Keyboard navigation with focus styles
• Screen reader tested (NVDA, VoiceOver)
• Reduced motion mode (respects prefers-reduced-motion)
• High contrast mode
• Semantic HTML5 everywhere
• ARIA labels on complex interactions

---

10. Performance Targets (World-Class)

Metric	Target	How We Achieve It
Lighthouse	100/100	Astro SSG, optimized assets
FCP	<0.8s	Inline critical CSS, preload fonts
LCP	<1.2s	Optimized images, lazy load
TTI	<1.5s	Minimal JS, code splitting
CLS	<0.05	Reserved space for all content
Bundle	<100KB	Tree-shaking, islands, compression

---

Design Inspiration (Study These)

1. Linear.app - THE gold standard. Every pixel perfect, animations purposeful
2. Vercel.com - Gradients, code showcases, blazing fast
3. Stripe.com - Clean, interactive demos, trustworthy
4. Raycast.com - Developer-focused, command palette, slick
5. Warp.dev - Terminal animations, beautiful code blocks
6. Framer.com - Animation showcase, motion design mastery

Screenshot these sites. Analyze every detail. We're playing at this level.

---

Repository Structure

lumos-website/
├── src/
│   ├── pages/
│   │   └── index.astro              # Main landing page
│   ├── layouts/
│   │   └── BaseLayout.astro         # Global layout
│   ├── components/
│   │   ├── Hero.astro               # Static hero section
│   │   ├── ProblemStatement.astro   # Static comparison table
│   │   ├── LiveCodeDemo.tsx         # React island (Monaco)
│   │   ├── FeaturesGrid.astro       # Static grid
│   │   ├── BeforeAfter.tsx          # React island (interactive slider)
│   │   ├── UseCases.astro           # Static cards
│   │   ├── Stats.tsx                # React island (animated counters)
│   │   ├── Ecosystem.astro          # Static links
│   │   ├── GetStarted.astro         # Final CTA
│   │   └── Footer.astro             # Static footer
│   ├── animations/
│   │   ├── scroll-animations.ts     # GSAP ScrollTrigger
│   │   ├── hero-animations.ts       # Hero entrance timeline
│   │   └── cursor-effects.ts        # Custom cursor
│   ├── styles/
│   │   ├── global.css               # Tailwind + custom
│   │   └── animations.css           # Reusable animations
│   └── utils/
│       ├── monaco-setup.ts          # Monaco config
│       └── lumos-generator.ts       # Code generation logic
├── public/
│   ├── fonts/                       # Self-hosted Inter, JetBrains Mono
│   ├── videos/                      # Hero background (optional)
│   └── images/                      # Optimized assets
├── astro.config.mjs
├── tailwind.config.js
└── package.json

---

Development Phases (Updated)

Phase 1: Foundation (Week 1)

• Set up Astro 5.6 project
• Configure Tailwind + custom animations
• Install: Framer Motion, GSAP, Lenis, Shiki, Monaco
• Design system implementation (colors, typography, spacing)
• Basic page structure (all 10 sections)

Phase 2: Static Sections (Week 2)

• Hero section (static shell)
• Problem statement (comparison table)
• Features grid (6 cards)
• Use cases (4 personas)
• Ecosystem (4 cards)
• Footer (4 columns)

Phase 3: Interactive Islands (Week 3)

• Live Code Demo (Monaco + real-time generation)
• Before/After interactive slider
• Stats counter animations
• Example selector with transitions

Phase 4: Advanced Animations (Week 4)

• GSAP scroll animations (all sections)
• Lenis smooth scroll
• Hero entrance timeline
• Cursor effects
• Micro-interactions (hover, focus, active)
• View Transitions API

Phase 5: Polish & Optimization (Week 5)

• 3D effects (hero background)
• Performance optimization (100/100 Lighthouse)
• Accessibility audit (WCAG 2.1 AAA)
• Cross-browser testing
• Mobile perfection
• SEO implementation

Phase 6: Deployment & Analytics (Week 6)

• Vercel deployment
• Custom domain (lumos-lang.org)
• Analytics integration (Vercel + Partytown)
• A/B testing setup (optional)
• Final Lighthouse audit
• Handoff documentation

---

Next Steps

1. ✅ Create repository: getlumos/lumos-website
2. Set up Astro project with all dependencies
3. Design review: Finalize color palette, typography, animation principles
4. Content review: Finalize copy for all sections
5. Development: Follow phases 1-6
6. Deploy to Vercel staging
7. User testing + feedback
8. Deploy to production (lumos-lang.org)

---

Timeline: 5-6 weeks to world-class production site
Effort: 1 developer full-time (with design/content support)
Impact: Critical - this is our first impression to the world

Remember: We're not building a website. We're building an experience that makes developers say "Holy shit, I need this."