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

// 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

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

// 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

# 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