lux/docs/WEBSITE_PLAN.md

# Lux Language Website Plan

## Research Summary

Analyzed 6 beloved language websites: **Elm**, **Gleam**, **Rust**, **Elixir**, **Zig**, and **Go**.

### Key Patterns from Successful Language Websites

| Pattern | Examples | Why It Works |
|---------|----------|--------------|
| **Emotional benefits over features** | Elm: "deploy and go to sleep" | Developers buy peace of mind, not feature lists |
| **Problem-first messaging** | Rust: addresses memory bugs, Zig: "no hidden control flow" | Validates pain points before offering solution |
| **Runnable code immediately** | Go Playground, Gleam Tour | Reduces friction, proves language works |
| **Social proof** | Go: PayPal, Google testimonials | Builds credibility for enterprise adoption |
| **Use-case segmentation** | Rust: CLI, WASM, networking, embedded | Helps users self-identify relevance |
| **Progressive disclosure** | All: simple → complex | Doesn't overwhelm newcomers |
| **Built with itself** | Elm site is built in Elm | Meta demonstration of capabilities |
| **Inclusive community** | Gleam: prominent Code of Conduct | Signals healthy ecosystem |

---

## Lux's Unique Value Proposition

### Core Differentiators

1. **Effects are better than monads** - More intuitive for learning FP
2. **Compile-time effect tracking** - Know exactly what code does
3. **Swap handlers for testing** - No mocks needed
4. **Native performance** - Compiles to C, matches Rust/C speed
5. **Functional but practical** - Not academic, production-ready

### Tagline Options

- "A functional language with first-class effects"
- "Know what your code does. All of it."
- "Effects you can see. Tests you can trust."
- "Functional programming that makes sense"

### Target Audiences

1. **Haskell/FP developers** frustrated by monads
2. **Backend developers** wanting type safety without Java verbosity
3. **Educators** teaching functional programming
4. **Teams** wanting testable, maintainable code

---

## Website Structure

### Navigation

```
[Logo: Lux]  Learn  Docs  Playground  Community  GitHub
```

### Section 1: Hero

**Headline:** "Functional programming with first-class effects"

**Subheadline:** "See exactly what your code does. Test it without mocks. Deploy with confidence."

**CTA Buttons:**
- [Try Lux] → Interactive playground
- [Get Started] → Installation guide

**Visual:** Animated effect flow visualization or side-by-side code showing effect signatures

### Section 2: The Problem (Pain Points)

**"The problem with side effects"**

> "Most bugs come from code doing things you didn't expect—network calls, file writes, database queries hidden deep in the call stack."

Show side-by-side:
- **Other languages:** Function signature doesn't reveal what it does
- **Lux:** Effect signature makes all side effects explicit

```lux
// In Lux, the type tells you everything
fn fetchUser(id: Int): User with Http, Database = {
    // You KNOW this touches network and database
}
```

### Section 3: The Solution (3 Pillars)

#### Pillar 1: Effects You Can See
- Every function declares its effects
- No hidden surprises in production
- Refactor with confidence

```lux
fn processOrder(order: Order): Result<Receipt, Error> with Database, Email = {
    let saved = Database.save(order)
    Email.send(order.customer, "Order confirmed!")
    Ok(Receipt(saved.id))
}
```

#### Pillar 2: Testing Without Mocks
- Swap effect handlers at runtime
- Test database code without a database
- Test HTTP code without network

```lux
// Production
handle processOrder(order) with {
    Database -> realDatabase,
    Email -> smtpServer
}

// Test - same code, different handlers
handle processOrder(order) with {
    Database -> inMemoryStore,
    Email -> collectMessages
}
```

#### Pillar 3: Native Performance
- Compiles to C via gcc -O2
- Matches Rust/C performance
- Reference counting with FBIP optimization

| Benchmark | Lux | Rust | Go | Node.js |
|-----------|-----|------|----|---------|
| Fibonacci | 0.015s | 0.018s | 0.041s | 0.110s |
| Ackermann | 0.020s | 0.029s | 0.107s | 0.207s |

### Section 4: Learn by Example

**Interactive code snippets** (using playground embeds):

1. **Hello World** - Basic syntax
2. **Pattern Matching** - ADTs and matching
3. **Effects** - Console, File, HTTP
4. **Handlers** - Swapping implementations
5. **Testing** - Effect-based testing

Each example: Code + "Run" button + explanation

### Section 5: Use Cases

#### Backend Services
- Effect tracking documents all side effects
- Swap database handlers for testing
- JSON, HTTP, SQL built-in

#### Reliable Systems
- `is pure`, `is total` behavioral types
- Compile-time guarantees
- Idempotency verification (coming soon)

#### Teaching FP
- Effects more intuitive than monads
- Clear progression: pure → effects → handlers
- Excellent error messages

### Section 6: Social Proof

**"What developers are saying"**

(Placeholder for future testimonials)

**Companies using Lux** (logos when available)

**Benchmark results** - Comparison chart vs Rust, Go, Node, Python

### Section 7: Getting Started

```bash
# Install
curl -sSL https://lux-lang.org/install.sh | sh

# Create project
lux new my-app
cd my-app

# Run
lux run
```

**Next steps:**
- [Language Tour] - Interactive tutorial
- [Guide] - In-depth documentation
- [Examples] - Real-world code
- [API Reference] - Standard library

### Section 8: Community

- **GitHub** - Source code, issues, PRs
- **Discord** - Chat with the community
- **Forum** - Discussions
- **Code of Conduct** - Inclusive community

---

## Design Principles

### Visual Identity

- **Primary color:** Deep purple/violet (#6B46C1) - unique, memorable
- **Accent:** Teal (#0D9488) for CTAs
- **Background:** Clean whites and light grays
- **Typography:** System fonts for performance, monospace for code

### Code Highlighting

Syntax highlighting theme that emphasizes:
- **Effects** - Different color to make them stand out
- **Types** - Clear distinction from values
- **Keywords** - Subtle but readable

### Interactive Elements

- **Playground embeds** - Run code in browser
- **Animated effects flow** - Visualize how effects propagate
- **Hover tooltips** - Type information on code examples

---

## Technical Implementation

### Self-Hosting Goal

The website should be **built in Lux** (like Elm's site), demonstrating:
- Lux compiles to JavaScript/WASM
- Full-stack Lux is possible
- The language is production-ready

### Architecture

```
┌─────────────────────────────────────────┐
│           lux-lang.org                  │
├─────────────────────────────────────────┤
│  Frontend (Lux → WASM/JS)               │
│  - Interactive playground               │
│  - Animated examples                    │
│  - Client-side routing                  │
├─────────────────────────────────────────┤
│  Backend (Lux → Native)                 │
│  - Serve static content                 │
│  - Playground compilation API           │
│  - Package registry (future)            │
└─────────────────────────────────────────┘
```

### Required Language Features

To build the website in Lux, we need:

| Feature | Status | Priority |
|---------|--------|----------|
| JS backend | Missing | P0 |
| WASM backend | Missing | P1 |
| DOM manipulation effect | Missing | P1 |
| HTML DSL | Missing | P2 |
| CSS-in-Lux | Missing | P2 |
| Virtual DOM/diffing | Missing | P2 |
| Client routing | Missing | P2 |

---

## Content Priorities

### Phase 1: Essential Content

1. **Landing page** - Hero, 3 pillars, getting started
2. **Installation guide** - All platforms
3. **Language tour** - Interactive tutorial
4. **Effect system guide** - Core concept explanation
5. **Standard library reference** - API docs

### Phase 2: Expansion

6. **Cookbook** - Common patterns
7. **Video tutorials** - YouTube/embedded
8. **Comparison guides** - vs Haskell, vs Rust, vs TypeScript
9. **Blog** - Updates, deep dives
10. **Showcase** - Projects built with Lux

### Phase 3: Community

11. **Package registry** - Browse packages
12. **Forum integration** - Discussions
13. **Contribution guide** - How to contribute
14. **Governance** - RFC process

---

## Success Metrics

| Metric | Target |
|--------|--------|
| Time to first code run | < 60 seconds |
| Tutorial completion rate | > 50% |
| GitHub stars after website launch | 1000 in 6 months |
| Package registry submissions | 50 in first year |
| "I finally understand effects" comments | Qualitative goal |

---

## Inspiration Summary

| From | Take |
|------|------|
| **Elm** | Emotional messaging, interactive demos, built-with-itself |
| **Gleam** | Friendly tone, ecosystem emphasis, inclusive community |
| **Rust** | Problem-first messaging, use-case segmentation |
| **Go** | Pragmatic testimonials, playground, multiple learning paths |
| **Elixir** | Case studies, real code examples, ecosystem confidence |
| **Zig** | Transparency, C interop story, pragmatic positioning |

---

## Next Steps

1. **Build JS/WASM backend** - Required to self-host
2. **Create playground** - Run Lux in browser
3. **Write language tour** - Interactive tutorial
4. **Design visual identity** - Logo, colors, typography
5. **Build MVP landing page** - Even if not in Lux initially
6. **Launch and iterate** - Get feedback early