# Lux Website Plan

A comprehensive plan for building the official Lux programming language website.

**Aesthetic:** Sleek and noble - translucent black, white, and gold with strong serif typography. Serious, powerful, divine.

---

## Research Summary

### Websites Analyzed

| Language | URL | Key Strengths | Key Weaknesses |
|----------|-----|---------------|----------------|
| **Gleam** | gleam.run | Friendly tone, code examples, sponsor showcase, Lucy mascot | Sparse use cases, overwhelming sponsor list |
| **Elm** | elm-lang.org | Visual demos, testimonials, "no runtime exceptions" proof, teal accents | No video content, sparse enterprise stories |
| **Zig** | ziglang.org | Technical clarity, transparent governance, community focus | No interactive tutorials, no benchmarks shown |
| **Rust** | rust-lang.org | Domain-specific guides, multi-entry learning paths, strong CTAs | Limited case studies, minimal adoption metrics |
| **Python** | python.org | Comprehensive ecosystem visibility, strong community, interactive shell | Heavy JS reliance, cluttered visual hierarchy |
| **TypeScript** | typescriptlang.org | Interactive demos, gradual adoption path, social proof, dark theme | No video tutorials, enterprise migration unclear |
| **cppreference** | cppreference.com | Exhaustive reference, version awareness, deep linking | Dense, no learning path, desktop-only |

### Best Practices to Adopt

**Landing Page**
1. Immediate value demonstration (TypeScript's inline error catching)
2. Three-pillar messaging (Rust: Performance, Reliability, Productivity)
3. Social proof (testimonials, adoption stats, company logos)
4. Interactive playground link (Elm, TypeScript, Gleam)
5. Clear CTAs ("Get Started", "Try Now")

**Documentation**
1. Progressive complexity (TypeScript: JS → JSDoc → TypeScript)
2. Multiple learning paths (books, videos, hands-on)
3. Version-aware docs (cppreference: C++11 through C++26)
4. Searchable with good information architecture

**Community**
1. Decentralized presence (Discord, forums, GitHub)
2. Contributor recognition (Gleam's avatar wall)
3. Code of conduct prominently displayed

**Technical**
1. Fast page loads (no heavy frameworks)
2. Dark/light theme support (TypeScript)
3. Responsive design (mobile-first)
4. Accessibility (ARIA, keyboard navigation)

### Weaknesses to Avoid

1. No video content (most sites lack this)
2. No competitive comparisons (all sites avoid this - we should include it)
3. Sparse enterprise adoption stories
4. Missing performance benchmarks on homepage
5. Poor mobile experience
6. No clear migration path from other languages

---

## Design Direction: "Sleek and Noble"

### Color Palette

```css
:root {
  /* Backgrounds */
  --bg-primary: #0a0a0a;                    /* Near-black */
  --bg-secondary: #111111;                  /* Slightly lighter black */
  --bg-glass: rgba(255, 255, 255, 0.03);   /* Translucent white */
  --bg-glass-hover: rgba(255, 255, 255, 0.06);

  /* Text */
  --text-primary: #ffffff;                  /* Pure white */
  --text-secondary: rgba(255, 255, 255, 0.7);
  --text-muted: rgba(255, 255, 255, 0.5);

  /* Gold accents */
  --gold: #d4af37;                          /* Classic gold */
  --gold-light: #f4d03f;                    /* Bright gold (highlights) */
  --gold-dark: #b8860b;                     /* Dark gold (depth) */
  --gold-glow: rgba(212, 175, 55, 0.3);    /* Gold shadow */

  /* Code */
  --code-bg: rgba(212, 175, 55, 0.05);     /* Gold-tinted background */
  --code-border: rgba(212, 175, 55, 0.2);

  /* Borders */
  --border-subtle: rgba(255, 255, 255, 0.1);
  --border-gold: rgba(212, 175, 55, 0.3);
}
```

### Typography

```css
:root {
  /* Fonts */
  --font-heading: "Playfair Display", "Cormorant Garamond", Georgia, serif;
  --font-body: "Source Serif Pro", "Crimson Pro", Georgia, serif;
  --font-code: "JetBrains Mono", "Fira Code", "SF Mono", monospace;

  /* Sizes */
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 2rem;
  --text-4xl: 2.5rem;
  --text-5xl: 3.5rem;
  --text-hero: 5rem;
}
```

### Visual Elements

- **Glass-morphism** for cards and panels (backdrop-blur + translucent bg)
- **Gold gradients** on buttons and interactive elements
- **Subtle gold lines** as section dividers
- **Minimal imagery** - let typography and code speak
- **Elegant transitions** (ease-out, 300ms)
- **Noble spacing** - generous whitespace, unhurried layout

### Tone of Voice

- Confident but not arrogant
- Technical depth with clarity
- "Divine precision" - every effect is intentional
- Sophisticated language, no casual slang
- Imperative mood for actions ("Create", "Build", "Define")

---

## Site Structure

```
luxlang.org/
├── / (Landing Page)
│   ├── Hero: "Functional Programming with First-Class Effects"
│   ├── Value Props: Effects, Types, Performance
│   ├── Code Demo: Interactive effect example
│   ├── Benchmark Showcase
│   ├── Quick Start
│   └── Community CTA
│
├── /learn/
│   ├── Getting Started (5-minute intro)
│   ├── Tutorial (full guided tour)
│   ├── By Example (code-first learning)
│   └── Coming from... (Rust, TypeScript, Python, Haskell)
│
├── /docs/
│   ├── Language Reference
│   │   ├── Syntax
│   │   ├── Types
│   │   ├── Effects
│   │   ├── Pattern Matching
│   │   └── Modules
│   ├── Standard Library
│   │   ├── List, String, Option, Result
│   │   └── Effects (Console, Http, FileSystem, etc.)
│   └── Tooling
│       ├── CLI Reference
│       ├── LSP Setup
│       └── Editor Integration
│
├── /playground/
│   └── Interactive REPL with examples
│
├── /benchmarks/
│   └── Performance comparisons (methodology transparent)
│
├── /community/
│   ├── Discord
│   ├── GitHub
│   ├── Contributing
│   └── Code of Conduct
│
└── /blog/
    └── News, releases, deep-dives
```

---

## Page Designs

### Landing Page (/)

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  ┌─ NAV ─────────────────────────────────────────────────────┐  │
│  │  LUX        Learn   Docs   Playground   Community    [GH] │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─ HERO ────────────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │                    ╦  ╦ ╦╦ ╦                              │  │
│  │                    ║  ║ ║╔╣                               │  │
│  │                    ╩═╝╚═╝╩ ╩                              │  │
│  │                                                           │  │
│  │         Functional Programming                            │  │
│  │         with First-Class Effects                          │  │
│  │                                                           │  │
│  │    Effects are explicit. Types are powerful.              │  │
│  │    Performance is native.                                 │  │
│  │                                                           │  │
│  │         [Get Started]    [Playground]                     │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─ CODE DEMO ───────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  ┌──────────────────────┐  ┌────────────────────────────┐ │  │
│  │  │ fn processOrder(     │  │ The type signature tells   │ │  │
│  │  │   order: Order       │  │ you this function:         │ │  │
│  │  │ ): Receipt           │  │                            │ │  │
│  │  │   with {Db, Email} = │  │ • Queries the database     │ │  │
│  │  │ {                    │  │ • Sends email              │ │  │
│  │  │   let saved =        │  │ • Returns a Receipt        │ │  │
│  │  │     Db.save(order)   │  │                            │ │  │
│  │  │   Email.send(...)    │  │ No surprises. No hidden    │ │  │
│  │  │   Receipt(saved.id)  │  │ side effects.              │ │  │
│  │  │ }                    │  │                            │ │  │
│  │  └──────────────────────┘  └────────────────────────────┘ │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─ VALUE PROPS ─────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │  │
│  │  │   EFFECTS       │ │     TYPES       │ │ PERFORMANCE  │ │  │
│  │  │                 │ │                 │ │              │ │  │
│  │  │ Side effects    │ │ Full inference  │ │ Compiles to  │ │  │
│  │  │ are tracked     │ │ with algebraic  │ │ native C,    │ │  │
│  │  │ in the type     │ │ data types.     │ │ matches gcc. │ │  │
│  │  │ signature.      │ │                 │ │              │ │  │
│  │  └─────────────────┘ └─────────────────┘ └──────────────┘ │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─ BENCHMARKS ──────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  fib(35)                                                  │  │
│  │                                                           │  │
│  │  Lux   ████████████████████████████████████  28.1ms       │  │
│  │  C     █████████████████████████████████████ 29.0ms       │  │
│  │  Rust  █████████████████████████            41.2ms        │  │
│  │  Zig   ███████████████████████              47.0ms        │  │
│  │                                                           │  │
│  │  Verified with hyperfine. [See methodology →]             │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─ QUICK START ─────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  # Install via Nix                                        │  │
│  │  $ nix run github:luxlang/lux                             │  │
│  │                                                           │  │
│  │  # Or build from source                                   │  │
│  │  $ git clone https://github.com/luxlang/lux               │  │
│  │  $ cd lux && nix develop                                  │  │
│  │  $ cargo build --release                                  │  │
│  │                                                           │  │
│  │                    [Full Guide →]                         │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─ FOOTER ──────────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  LUX            Learn          Community       About      │  │
│  │                 Getting Started Discord        GitHub     │  │
│  │                 Tutorial       Contributing   License     │  │
│  │                 Examples       Code of Conduct            │  │
│  │                 Reference                                 │  │
│  │                                                           │  │
│  │  © 2026 Lux Language                                      │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Documentation Page (/docs/)

```
┌─────────────────────────────────────────────────────────────────┐
│  LUX   Learn   Docs   Playground   Community          [Search] │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─ SIDEBAR ──────┐  ┌─ CONTENT ────────────────────────────┐   │
│  │                │  │                                      │   │
│  │ LANGUAGE       │  │ # Effects                            │   │
│  │  Syntax        │  │                                      │   │
│  │  Types         │  │ Effects are Lux's defining feature.  │   │
│  │  Effects ◄     │  │ They make side effects explicit in   │   │
│  │  Patterns      │  │ function signatures.                 │   │
│  │  Modules       │  │                                      │   │
│  │                │  │ ## Declaring Effects                 │   │
│  │ STDLIB         │  │                                      │   │
│  │  List          │  │ ```lux                               │   │
│  │  String        │  │ fn greet(name: String): String       │   │
│  │  Option        │  │   with {Console} = {                 │   │
│  │  Result        │  │     Console.print("Hello, " + name)  │   │
│  │  ...           │  │     "greeted " + name                │   │
│  │                │  │ }                                    │   │
│  │ EFFECTS        │  │ ```                                  │   │
│  │  Console       │  │                                      │   │
│  │  Http          │  │ The `with {Console}` clause tells    │   │
│  │  FileSystem    │  │ the compiler this function performs  │   │
│  │  Database      │  │ console I/O.                         │   │
│  │                │  │                                      │   │
│  │ TOOLING        │  │ ## Handling Effects                  │   │
│  │  CLI           │  │                                      │   │
│  │  LSP           │  │ Effects must be handled at the call  │   │
│  │  Editors       │  │ site...                              │   │
│  │                │  │                                      │   │
│  └────────────────┘  │           [← Types]  [Patterns →]    │   │
│                      │                                      │   │
│                      └──────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Technical Implementation

### Building in Lux

The website will be built using Lux itself, serving as both documentation and demonstration.

#### HTML Generation

```lux
// Base HTML structure
fn html(head: List<Html>, body: List<Html>): Html = {
    Html.element("html", [("lang", "en")], [
        Html.element("head", [], head),
        Html.element("body", [], body)
    ])
}

// Component: Navigation
fn nav(): Html = {
    Html.element("nav", [("class", "nav")], [
        Html.element("a", [("href", "/"), ("class", "nav-logo")], [
            Html.text("LUX")
        ]),
        Html.element("div", [("class", "nav-links")], [
            navLink("Learn", "/learn/"),
            navLink("Docs", "/docs/"),
            navLink("Playground", "/playground/"),
            navLink("Community", "/community/")
        ])
    ])
}

// Component: Hero section
fn hero(): Html = {
    Html.element("section", [("class", "hero")], [
        Html.element("div", [("class", "hero-logo")], [
            Html.text("╦  ╦ ╦╦ ╦"),
            Html.element("br", [], []),
            Html.text("║  ║ ║╔╣"),
            Html.element("br", [], []),
            Html.text("╩═╝╚═╝╩ ╩")
        ]),
        Html.element("h1", [], [
            Html.text("Functional Programming"),
            Html.element("br", [], []),
            Html.text("with First-Class Effects")
        ]),
        Html.element("p", [("class", "hero-tagline")], [
            Html.text("Effects are explicit. Types are powerful. Performance is native.")
        ]),
        Html.element("div", [("class", "hero-cta")], [
            button("Get Started", "/learn/getting-started/", "primary"),
            button("Playground", "/playground/", "secondary")
        ])
    ])
}
```

#### Static Site Generation

```lux
// Main site generator
fn generateSite(): Unit with {FileSystem, Console} = {
    Console.print("Generating Lux website...")

    // Generate landing page
    let index = landingPage()
    FileSystem.write("dist/index.html", renderHtml(index))

    // Generate documentation pages
    List.forEach(docPages(), fn(page) = {
        let content = docPage(page.title, page.content)
        FileSystem.write("dist/docs/" + page.slug + ".html", renderHtml(content))
    })

    // Generate learn pages
    List.forEach(learnPages(), fn(page) = {
        let content = learnPage(page.title, page.content)
        FileSystem.write("dist/learn/" + page.slug + ".html", renderHtml(content))
    })

    // Copy static assets
    copyDir("static/", "dist/static/")

    Console.print("Site generated: dist/")
}
```

### CSS

Full CSS will be in `website/static/style.css`:

```css
/* Core: Sleek and Noble */
:root {
  --bg-primary: #0a0a0a;
  --bg-glass: rgba(255, 255, 255, 0.03);
  --text-primary: #ffffff;
  --text-secondary: rgba(255, 255, 255, 0.7);
  --gold: #d4af37;
  --gold-light: #f4d03f;
  --font-heading: "Playfair Display", Georgia, serif;
  --font-body: "Source Serif Pro", Georgia, serif;
  --font-code: "JetBrains Mono", monospace;
}

* { box-sizing: border-box; margin: 0; padding: 0; }

body {
  background: var(--bg-primary);
  color: var(--text-primary);
  font-family: var(--font-body);
  font-size: 18px;
  line-height: 1.7;
}

h1, h2, h3, h4 {
  font-family: var(--font-heading);
  font-weight: 600;
  color: var(--gold-light);
  letter-spacing: -0.02em;
}

/* Hero */
.hero {
  min-height: 90vh;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  text-align: center;
  padding: 4rem 2rem;
  background:
    radial-gradient(ellipse at top, rgba(212, 175, 55, 0.08) 0%, transparent 50%),
    var(--bg-primary);
}

.hero-logo {
  font-family: var(--font-code);
  color: var(--gold);
  font-size: 2rem;
  line-height: 1.2;
  margin-bottom: 2rem;
}

.hero h1 {
  font-size: clamp(2.5rem, 6vw, 4rem);
  margin-bottom: 1.5rem;
}

.hero-tagline {
  font-size: 1.25rem;
  color: var(--text-secondary);
  max-width: 600px;
  margin-bottom: 3rem;
}

/* Buttons */
.btn {
  font-family: var(--font-heading);
  font-size: 1rem;
  font-weight: 600;
  padding: 1rem 2.5rem;
  border-radius: 4px;
  text-decoration: none;
  transition: all 0.3s ease;
  display: inline-block;
}

.btn-primary {
  background: linear-gradient(135deg, var(--gold-dark), var(--gold));
  color: #0a0a0a;
}

.btn-primary:hover {
  background: linear-gradient(135deg, var(--gold), var(--gold-light));
  transform: translateY(-2px);
  box-shadow: 0 4px 20px rgba(212, 175, 55, 0.4);
}

.btn-secondary {
  background: transparent;
  color: var(--gold);
  border: 1px solid var(--gold);
}

.btn-secondary:hover {
  background: rgba(212, 175, 55, 0.1);
}

/* Cards */
.card {
  background: var(--bg-glass);
  border: 1px solid rgba(212, 175, 55, 0.15);
  border-radius: 8px;
  padding: 2rem;
  backdrop-filter: blur(10px);
}

/* Code blocks */
pre, code {
  font-family: var(--font-code);
}

code {
  background: rgba(212, 175, 55, 0.1);
  padding: 0.2em 0.4em;
  border-radius: 3px;
  font-size: 0.9em;
}

pre {
  background: rgba(212, 175, 55, 0.05);
  border: 1px solid rgba(212, 175, 55, 0.15);
  border-radius: 6px;
  padding: 1.5rem;
  overflow-x: auto;
}

pre code {
  background: none;
  padding: 0;
}

/* Syntax highlighting */
.hljs-keyword { color: var(--gold); }
.hljs-type { color: #82aaff; }
.hljs-string { color: #c3e88d; }
.hljs-number { color: #f78c6c; }
.hljs-comment { color: rgba(255, 255, 255, 0.4); font-style: italic; }
.hljs-effect { color: var(--gold-light); font-weight: 600; }
```

---

## Content Plan

### Phase 1: Core (Week 1-2)
1. Landing page with hero, value props, benchmarks
2. Installation guide
3. 5-minute getting started
4. Effects documentation
5. Basic syntax reference

### Phase 2: Documentation (Week 3-4)
1. Full language reference
2. Standard library API docs
3. "Coming from X" guides
4. Effect system deep-dive
5. Pattern matching guide

### Phase 3: Interactive (Week 5-6)
1. Playground (if WASM ready)
2. Search functionality
3. Example showcase
4. Tutorial with exercises

### Phase 4: Polish (Week 7-8)
1. Mobile optimization
2. Dark/light theme toggle
3. Accessibility audit
4. Performance optimization
5. SEO

---

## Lux Weaknesses Log

*Issues discovered while building the website in Lux*

| Issue | Description | Status | Fix Commit |
|-------|-------------|--------|------------|
| Module imports broken | `import html` causes parse error | Open | - |
| No FileSystem.mkdir | Can't create directories from Lux | Open | - |
| No template strings | Multi-line HTML difficult to write | Open | - |
| No Markdown parser | Documentation requires manual HTML | Open | - |

**Full details:** See `website/lux-site/LUX_WEAKNESSES.md`

---

## Build Log

| Date | Milestone | Notes |
|------|-----------|-------|
| 2026-02-16 | Plan created | Comprehensive research and design complete |
| 2026-02-16 | Website v1 complete | HTML/CSS landing page with sleek/noble aesthetic |
| 2026-02-16 | Weaknesses documented | Module system, FileSystem need work |