blu/lux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 Wiki Activity
Files
5a853702d1cc8dd50e24abc6e0a0b9ff36f69f50
lux/docs/WEBSITE_PLAN.md
Brandon Lucas 552e7a4972 feat: create Lux website with sleek/noble aesthetic 
Website design:
- Translucent black (#0a0a0a) with gold (#d4af37) accents
- Strong serif typography (Playfair Display, Source Serif Pro)
- Glass-morphism cards with gold borders
- Responsive layout with elegant animations

Content:
- Landing page with hero, code demo, value props, benchmarks
- Effects-focused messaging ("No surprises. No hidden side effects.")
- Performance benchmarks showing Lux matches C
- Quick start guide

Technical:
- Added HTML rendering functions to stdlib/html.lux
- Created Lux-based site generator (blocked by module import issues)
- Documented Lux weaknesses discovered during development:
  - Module import system not working
  - FileSystem effect incomplete
  - No template string support

The landing page HTML/CSS is complete and viewable.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-16 06:41:49 -05:00

616 lines
26 KiB
Markdown
Raw Blame History

# 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 |
Reference in New Issue View Git Blame Copy Permalink