Website rebuilt from scratch based on analysis of 11 beloved language websites (Elm, Zig, Gleam, Swift, Kotlin, Haskell, OCaml, Crystal, Roc, Rust, Go). New website structure: - Homepage with hero, playground, three pillars, install guide - Language Tour with interactive lessons (hello world, types, effects) - Examples cookbook with categorized sidebar - API documentation index - Installation guide (Nix and source) - Sleek/noble design (black/gold, serif typography) Also includes: - New stdlib/json.lux module for JSON serialization - Enhanced stdlib/http.lux with middleware and routing - New string functions (charAt, indexOf, lastIndexOf, repeat) - LSP improvements (rename, signature help, formatting) - Package manager transitive dependency resolution - Updated documentation for effects and stdlib - New showcase example (task_manager.lux) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
800 lines
36 KiB
Markdown
800 lines
36 KiB
Markdown
# 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<A, B>(list: List<A>, f: fn(A): B): List<B> │
|
|
│ ``` │
|
|
│ │
|
|
│ 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<A>(list: List<A>, pred: fn(A): Bool): List<A> │
|
|
│ ``` │
|
|
│ │
|
|
│ 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
|