lux/docs/WEBSITE_PLAN.md

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

: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

: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

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

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

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