# Lux Website: Complete Learning Funnel A comprehensive plan for a world-class language website, based on deep analysis of 11 beloved programming language websites. --- ## Research Summary ### Languages Analyzed | Language | Standout Feature | Primary Learning Tool | Hero Tagline | |----------|-----------------|----------------------|--------------| | **Elm** | Friendly errors, semantic versioning | Playground + Guide | "Delightful language for reliable web apps" | | **Zig** | C interop, comptime, transparent governance | Examples + version-specific docs | "Robust, optimal, reusable software" | | **Gleam** | Lucy mascot, friendly tone, values-driven | Language Tour (editable, compiles in browser) | "Friendly, type-safe, scales" | | **Swift** | Use-case pathways, multiplatform focus | Domain-organized docs | "Powerful, flexible, multiplatform" | | **Kotlin** | Koans exercises, enterprise adoption | Playground + Koans + case studies | "Concise. Multiplatform. Fun." | | **Haskell** | Academic rigor, expandable features | Playground + progressive disclosure | "Long-term maintainable software" | | **OCaml** | Industry adoption, curated resources | Play + searchable API + exercises | "Industrial-strength functional" | | **Crystal** | Ruby-like syntax, production stories | Try Online + 8 progressive examples | "For humans and computers" | | **Roc** | Effects notation, clickable annotations | Browser REPL with inline explanations | "Fast, friendly, functional" | | **Rust** | The Book (legendary) | Book + Rustlings exercises + enhanced quizzes | "Reliable, efficient, productive" | | **Go** | Tour of Go (gold standard) | Interactive tour with exercises | "Build simple, secure, scalable" | ### Common Navigation Patterns ``` Elm: Install | Packages | Guide | News Zig: Download | Learn | News | Source | Community | ZSF | Devlog Gleam: News | Community | Sponsor | Packages | Docs | Code Swift: Documentation | Community | Packages | Blog | Install Kotlin: Solutions | Docs | API | Community | Teach OCaml: Learn | Tools | Packages | Community | News | Play Crystal: Blog | Install | Sponsors | Community | Docs Roc: Tutorial | Install | Examples | Community | Docs | Donate ``` **Synthesized Navigation for Lux:** ``` [Logo] Install | Tour | Examples | Docs | Play | Community ``` ### Learning Funnel Pattern All successful language sites follow this progression: ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1. HERO │ │ 3-5 word memorable tagline + immediate code example │ │ Value props as 3 pillars │ │ CTAs: "Try Now" + "Install" + "Learn More" │ ├─────────────────────────────────────────────────────────────────┤ │ 2. TRY NOW (Zero Friction) │ │ Browser-based playground │ │ No account, no install, no setup │ │ Editable code with immediate feedback │ ├─────────────────────────────────────────────────────────────────┤ │ 3. WHY THIS LANGUAGE │ │ 3-4 key differentiators with code examples │ │ Problem/solution framing │ │ Social proof (testimonials, adoption) │ ├─────────────────────────────────────────────────────────────────┤ │ 4. INSTALL │ │ One-liner with copy button │ │ Multiple platform options │ │ Verification steps │ ├─────────────────────────────────────────────────────────────────┤ │ 5. INTERACTIVE TOUR │ │ Step-by-step lessons (10-20) │ │ Editable code that compiles in browser │ │ Progressive complexity │ │ Single-page version available │ ├─────────────────────────────────────────────────────────────────┤ │ 6. BY EXAMPLE │ │ Cookbook of common patterns │ │ Categorized (basics, web, cli, data, concurrent) │ │ Copy-paste ready │ ├─────────────────────────────────────────────────────────────────┤ │ 7. DEEP DIVES │ │ Unique features explained thoroughly │ │ Effects system, behavioral types │ │ For Lux: what makes it different │ ├─────────────────────────────────────────────────────────────────┤ │ 8. REAL PROJECTS │ │ 3-5 complete applications │ │ Full source, tests, README │ │ Demonstrates real-world usage │ ├─────────────────────────────────────────────────────────────────┤ │ 9. API REFERENCE │ │ Searchable │ │ Every function documented │ │ Type signatures prominent │ ├─────────────────────────────────────────────────────────────────┤ │ 10. LANGUAGE SPEC │ │ Formal grammar (EBNF) │ │ Operator precedence │ │ Reserved words │ │ Complete specification │ └─────────────────────────────────────────────────────────────────┘ ``` ### Interactive Elements (Best Practices) | Site | Feature | Implementation | |------|---------|----------------| | **Gleam Tour** | Editable code compiles on every keystroke | WASM in browser | | **Kotlin Koans** | Exercises with immediate feedback | Server-side execution | | **Go Tour** | Step-by-step with navigation | Client+server hybrid | | **Roc** | Clickable code annotations | JS tooltips | | **Haskell** | Expandable feature sections | CSS/JS accordion | | **TypeScript** | Live error highlighting | Monaco editor | ### Effective Tutorial Structure (from Go Tour, Gleam Tour) ``` Lesson Structure: 1. Concept introduction (2-3 sentences) 2. Editable code example 3. Output panel 4. Key points to notice (2-3 bullets) 5. Navigation (← Previous | Next →) 6. Contents dropdown ``` **Go Tour Topics (reference):** 1. Packages, imports, exported names 2. Functions (multiple returns, named returns) 3. Variables (declaration, initialization, short syntax) 4. Basic types (bool, string, int, float, complex) 5. Zero values 6. Type conversions 7. Constants 8. For loops (the only loop) 9. If statements 10. Switch 11. Defer 12. Pointers 13. Structs 14. Arrays and Slices 15. Maps 16. Function values and closures 17. Methods 18. Interfaces 19. Errors 20. Goroutines 21. Channels 22. Select 23. Mutexes 24. Exercises throughout **Gleam Tour Topics (reference):** - Hello World - Type inference - Custom types - Pattern matching - Pipelines - Result type - Concurrency - Interop --- ## Lux Website Architecture ### Site Map ``` lux-lang.org/ │ ├── / # Homepage (hero, playground, value props) │ ├── /install # Installation guide (multi-platform) │ ├── /tour/ # Interactive Language Tour │ ├── 01-hello-world │ ├── 02-values-types │ ├── 03-functions │ ├── 04-custom-types │ ├── 05-pattern-matching │ ├── 06-effects-intro │ ├── 07-using-effects │ ├── 08-custom-handlers │ ├── 09-testing-effects │ ├── 10-modules │ ├── 11-behavioral-types │ ├── 12-compilation │ └── all # Single-page version │ ├── /examples/ # By Example cookbook │ ├── basics/ │ │ ├── hello-world │ │ ├── values │ │ ├── variables │ │ ├── functions │ │ ├── closures │ │ ├── recursion │ │ └── ... │ ├── types/ │ │ ├── records │ │ ├── variants │ │ ├── generics │ │ ├── option │ │ └── result │ ├── effects/ │ │ ├── console-io │ │ ├── file-operations │ │ ├── http-requests │ │ ├── random-numbers │ │ ├── time-sleep │ │ ├── state-management │ │ └── error-handling │ ├── data/ │ │ ├── json-parsing │ │ ├── json-generation │ │ ├── string-processing │ │ ├── list-operations │ │ ├── sqlite-database │ │ └── postgresql │ ├── concurrent/ │ │ ├── spawning-tasks │ │ ├── channels │ │ ├── producer-consumer │ │ └── parallel-map │ └── web/ │ ├── http-server │ ├── rest-api │ ├── middleware │ └── routing │ ├── /learn/ # Deep-dive guides │ ├── effects # Complete effects system guide │ ├── behavioral-types # Pure, total, idempotent, commutative │ ├── compilation # How Lux compiles to C │ ├── performance # Optimization guide │ └── from-x/ # Coming from other languages │ ├── rust │ ├── haskell │ ├── typescript │ └── python │ ├── /projects/ # Complete example applications │ ├── todo-api # REST API with persistence │ ├── cli-tool # Full CLI application │ ├── web-scraper # HTTP + JSON processing │ └── concurrent-worker # Task queue with channels │ ├── /docs/ # API Reference │ ├── stdlib/ │ │ ├── list │ │ ├── string │ │ ├── option │ │ ├── result │ │ ├── math │ │ └── json │ ├── effects/ │ │ ├── console │ │ ├── file │ │ ├── process │ │ ├── http │ │ ├── http-server │ │ ├── time │ │ ├── random │ │ ├── state │ │ ├── fail │ │ ├── sql │ │ ├── postgres │ │ ├── concurrent │ │ ├── channel │ │ └── test │ └── spec/ │ ├── grammar # EBNF grammar │ ├── operators # Precedence table │ └── keywords # Reserved words │ ├── /play # Full-page playground │ ├── /community # Community resources │ ├── discord │ ├── contributing │ └── code-of-conduct │ └── /blog # Technical posts and news ``` --- ## Page Specifications ### 1. Homepage (`/`) **Hero Section:** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ Side Effects Can't Hide │ │ │ │ See what your code does. Test without mocks. Ship with confidence.│ │ │ │ [Try Now] [Install] [Take the Tour] │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ fn processOrder(order: Order): Receipt with {Database, Email} │ │ │ │ // The signature tells you EVERYTHING │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ MIT Licensed · 372+ Tests · Native Performance │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` **Problem/Solution Section:** Side-by-side comparison: - Left: "Other Languages" - hidden side effects - Right: "Lux" - explicit effect signatures **Three Pillars Section:** 1. **Effects You Can See** - Type signatures reveal all side effects - Code example showing `with {Console, Http}` 2. **Testing Without Mocks** - Swap handlers, not implementations - Code example: production vs test handlers 3. **Native Performance** - Compiles to C via gcc/clang - Benchmark comparison (Lux vs Rust vs Go vs Node) **Embedded Playground:** 5 tabs with runnable examples: - Hello World - Effects Basics - Pattern Matching - Custom Handlers - Behavioral Types **Getting Started:** ```bash # One command (Nix) nix run git+https://git.qrty.ink/blu/lux # From source git clone https://git.qrty.ink/blu/lux && cd lux && cargo build --release ``` **Footer:** Source · Docs · Community · Blog --- ### 2. Language Tour (`/tour/`) **Design (inspired by Go Tour + Gleam Tour):** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Tour of Lux [Contents ▾] [1 of 12] │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ # Hello World │ │ │ │ Every Lux program starts with a `main` function. Functions that │ │ perform side effects declare them with `with {...}`. │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ fn main(): Unit with {Console} = { │ │ │ │ Console.print("Hello, Lux!") │ │ │ │ } │ │ │ │ │ │ │ │ run main() with {} │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ [Run ▶] │ │ │ │ Output: │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Hello, Lux! │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ **Key points:** │ │ • `with {Console}` declares this function uses console I/O │ │ • `run ... with {}` executes the effectful code │ │ • The type `Unit` means the function returns nothing │ │ │ │ │ │ [← Previous] [Next: Values & Types →] │ └─────────────────────────────────────────────────────────────────────┘ ``` **Lessons:** | # | Title | Topics | |---|-------|--------| | 1 | Hello World | main function, Console effect, run syntax | | 2 | Values & Types | Int, Float, String, Bool, type annotations | | 3 | Functions | Function syntax, anonymous functions, higher-order | | 4 | Custom Types | Type aliases, records, algebraic data types | | 5 | Pattern Matching | match expressions, destructuring, exhaustiveness | | 6 | Effects: The Basics | What are effects, using built-in effects | | 7 | Using Multiple Effects | Effect composition, propagation | | 8 | Custom Handlers | handler syntax, resume(), handler substitution | | 9 | Testing with Effects | Mock handlers, testing without mocks | | 10 | Modules | Module structure, imports, visibility | | 11 | Behavioral Types | is pure, is total, is idempotent, is commutative | | 12 | Compilation | How Lux compiles to C, native performance | **Interactive Features:** - Editable code (textarea with syntax highlighting) - Run button (server-side execution or WASM) - Output panel (shows stdout, stderr, errors) - Contents dropdown for jumping to any lesson - Progress indicator (1 of 12) - Single-page version at `/tour/all` --- ### 3. Examples (`/examples/`) **Structure (inspired by Go by Example, Rust by Example):** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Lux by Example │ ├───────────────────────┬─────────────────────────────────────────────┤ │ │ │ │ BASICS │ # HTTP Server │ │ Hello World │ │ │ Values │ Lux provides `HttpServer` for building │ │ Variables │ web services with explicit effect tracking. │ │ Functions │ │ │ Closures │ ```lux │ │ Recursion │ fn main(): Unit with {HttpServer, Console} │ │ │ = { │ │ TYPES │ HttpServer.listen(8080) │ │ Records │ Console.print("Listening on :8080") │ │ Variants │ │ │ Generics │ loop { │ │ Option │ let req = HttpServer.accept() │ │ Result │ match req.path { │ │ │ "/" => HttpServer.respond( │ │ EFFECTS │ 200, "Hello!"), │ │ Console I/O ◄ │ _ => HttpServer.respond( │ │ File Operations │ 404, "Not Found") │ │ HTTP Requests │ } │ │ Random Numbers │ } │ │ Time/Sleep │ } │ │ State │ ``` │ │ Error Handling │ │ │ │ The effect signature `{HttpServer, Console}`│ │ DATA │ tells you exactly what this server does. │ │ JSON Parsing │ │ │ JSON Generation │ **Try it:** │ │ String Processing │ ```bash │ │ List Operations │ lux run server.lux │ │ SQLite │ curl http://localhost:8080/ │ │ PostgreSQL │ ``` │ │ │ │ │ CONCURRENT │ │ │ Spawning Tasks │ [← File Operations] [HTTP Requests →] │ │ Channels │ │ │ Producer/Consumer │ │ │ │ │ │ WEB │ │ │ HTTP Server │ │ │ REST API │ │ │ Middleware │ │ │ Routing │ │ │ │ │ └───────────────────────┴─────────────────────────────────────────────┘ ``` --- ### 4. Deep-Dive Guides (`/learn/`) **Effects Guide** (`/learn/effects`) - What are algebraic effects? - Comparison: effects vs monads vs async/await - Built-in effects reference - Custom effect definition - Handler patterns (logging, mocking, state) - Effect composition - Best practices **Behavioral Types Guide** (`/learn/behavioral-types`) - What are behavioral types? - `is pure` - function has no effects - `is total` - function always terminates - `is deterministic` - same inputs → same outputs - `is idempotent` - safe to call multiple times - `is commutative` - argument order doesn't matter - Compiler verification - Optimization benefits - Real-world use cases **Compilation Guide** (`/learn/compilation`) - How Lux compiles to C - Memory management (reference counting + FBIP) - Performance characteristics - Interfacing with C libraries - Build options and flags **Coming From X** (`/learn/from-x/`) - `/learn/from-x/rust` - For Rust developers - `/learn/from-x/haskell` - For Haskell developers - `/learn/from-x/typescript` - For TypeScript developers - `/learn/from-x/python` - For Python developers Each compares Lux concepts to familiar patterns. --- ### 5. Projects (`/projects/`) **Complete, runnable example applications:** **Todo API** (`/projects/todo-api`) ``` todo-api/ ├── src/ │ ├── main.lux # Entry point │ ├── routes.lux # HTTP routes │ ├── handlers.lux # Request handlers │ ├── models.lux # Data types │ └── db.lux # Database operations ├── tests/ │ └── handlers_test.lux # Tests with mock handlers └── README.md # Full documentation ``` Features demonstrated: - REST API design - SQLite persistence - JSON serialization - Effect-based testing **CLI Tool** (`/projects/cli-tool`) - Argument parsing - File processing - Progress output - Error handling **Web Scraper** (`/projects/web-scraper`) - HTTP requests - JSON parsing - Concurrent fetching - Data extraction --- ### 6. API Reference (`/docs/`) **Format:** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Docs > Stdlib > List [Search 🔍] │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ # List │ │ │ │ Operations on immutable lists. │ │ │ │ ## Functions │ │ │ │ ### map │ │ │ │ ```lux │ │ fn map(list: List, f: fn(A): B): List │ │ ``` │ │ │ │ Applies `f` to each element, returning a new list. │ │ │ │ **Example:** │ │ ```lux │ │ List.map([1, 2, 3], fn(x: Int): Int => x * 2) │ │ // Result: [2, 4, 6] │ │ ``` │ │ │ │ --- │ │ │ │ ### filter │ │ │ │ ```lux │ │ fn filter(list: List, pred: fn(A): Bool): List │ │ ``` │ │ │ │ Returns elements where `pred` returns true. │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` **Sections:** - Stdlib (List, String, Option, Result, Math, Json) - Effects (Console, File, Process, Http, HttpServer, Time, Random, State, Fail, Sql, Postgres, Concurrent, Channel, Test) - Spec (Grammar, Operators, Keywords) --- ### 7. Playground (`/play`) **Full-page playground:** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Lux Playground [Examples ▾] [Share] │ ├─────────────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────┐ ┌────────────────────────────────┐ │ │ │ │ │ Output │ │ │ │ fn main(): Unit with ... │ │ │ │ │ │ │ │ > Hello, Lux! │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├────────────────────────────────┤ │ │ │ │ │ Type Info / AST │ │ │ │ │ │ │ │ │ │ │ │ main: () -> Unit with Console │ │ │ │ │ │ │ │ │ └─────────────────────────────┘ └────────────────────────────────┘ │ │ │ │ [Run ▶] [Format] [Clear] │ └─────────────────────────────────────────────────────────────────────┘ ``` **Features:** - Syntax highlighting - Error highlighting - Examples dropdown - Share via URL - Format code - View type info / AST (advanced) --- ## Implementation Plan ### Phase 1: Foundation (Week 1) **Homepage:** - [ ] Hero section with tagline - [ ] Problem/solution comparison - [ ] Three pillars with code examples - [ ] Embedded playground (5 examples) - [ ] Install instructions with copy buttons - [ ] Trust badges - [ ] Responsive navigation - [ ] Footer **Install Page:** - [ ] Multi-platform instructions (Nix, source) - [ ] Copy buttons - [ ] Verification steps ### Phase 2: Tour (Week 2) **Tour Infrastructure:** - [ ] Tour page template - [ ] Code editor component - [ ] Output panel - [ ] Navigation (prev/next) - [ ] Contents dropdown - [ ] Progress indicator **Tour Content (12 lessons):** - [ ] Lesson 1-4: Basics (hello, values, functions, types) - [ ] Lesson 5-6: Pattern matching and effects intro - [ ] Lesson 7-9: Effects deep dive (using, custom, testing) - [ ] Lesson 10-12: Modules, behavioral types, compilation ### Phase 3: Examples (Week 3) **Examples Infrastructure:** - [ ] Category sidebar - [ ] Example page template - [ ] Navigation (prev/next within category) **Examples Content (40+ examples):** - [ ] Basics (10 examples) - [ ] Types (5 examples) - [ ] Effects (7 examples) - [ ] Data (6 examples) - [ ] Concurrent (4 examples) - [ ] Web (4 examples) ### Phase 4: Documentation (Week 4) **API Reference:** - [ ] Sidebar navigation - [ ] Function documentation template - [ ] Search functionality - [ ] Stdlib documentation - [ ] Effects documentation **Language Spec:** - [ ] EBNF grammar - [ ] Operator precedence table - [ ] Reserved words list ### Phase 5: Deep Dives & Projects (Week 5-6) **Guides:** - [ ] Effects guide - [ ] Behavioral types guide - [ ] Compilation guide - [ ] "Coming from X" guides **Projects:** - [ ] Todo API (complete source + tests) - [ ] CLI Tool - [ ] Web Scraper ### Phase 6: Polish (Week 7-8) - [ ] Mobile optimization - [ ] Dark/light theme toggle - [ ] Accessibility audit - [ ] Performance optimization - [ ] SEO meta tags - [ ] Open Graph images - [ ] Community page - [ ] Blog infrastructure --- ## Technical Stack **Option A: Pure HTML/CSS/JS** - No build step - Fast page loads - Easy to maintain - Playground: server-side execution via API **Option B: Lux Static Site Generator** - Dogfooding (Lux builds its own site) - Demonstrates language capabilities - More complex but great marketing **Recommendation:** Start with Option A, migrate to Option B once Lux is more mature. **Playground Implementation:** 1. Server-side: API endpoint calls `lux` binary 2. Future: WASM compilation for client-side execution --- ## Design System **Colors:** ```css --bg-primary: #0a0a0a; /* Near-black */ --bg-secondary: #111111; --bg-glass: rgba(255,255,255,0.03); --text-primary: #ffffff; --text-secondary: rgba(255,255,255,0.7); --gold: #d4af37; /* Accent */ --gold-light: #f4d03f; --code-bg: rgba(212,175,55,0.05); ``` **Typography:** ```css --font-heading: "Playfair Display", Georgia, serif; --font-body: "Source Serif Pro", Georgia, serif; --font-code: "JetBrains Mono", monospace; ``` **Aesthetic:** Sleek and noble - black/gold, serif typography, generous whitespace. --- ## Success Metrics | Metric | Target | |--------|--------| | Time to first run (playground) | < 30 seconds | | Time to local install | < 2 minutes | | Tour completion rate (lesson 5) | > 50% | | Tour completion rate (all 12) | > 25% | | Return visitors (within week) | > 30% | | Examples page views | > 500/month | --- ## Appendix: Tagline Options **Problem-focused (recommended):** - "Side Effects Can't Hide" - "Know What Your Code Does" **Benefit-focused:** - "Test Without Mocks" - "Refactor With Confidence" **Feature-focused:** - "First-Class Effects" - "Functional with Effects" **Recommended:** "Side Effects Can't Hide" - memorable, problem-focused, differentiating