The Container
This page documents the design decisions for sunlitmoon.online so that the presentation substrate itself is auditable, versioned, and load-bearing. The thesis ("own the algorithmic bottleneck") applies to the web artifact that carries it.
Core Principles (Non-Negotiable)
- Precision & Verifiability: Every element earns its place. Deep links, version stamps on content, no broken titles, no "[LiveView pending]" placeholders. The same falsifier discipline applied to essays applies to the UI.
- Density with Navigability: "Iceberg" model. Summaries and abstracts first. Progressive disclosure via sidenotes (in progress), collapsibles, related panels. Reader attention is the bottleneck we own.
- Aesthetically Pleasing Minimalism: High contrast dark (deep basalt #0D0E15 / parchment #F4F1EA), molten accent #FF9E00, generous but controlled whitespace, no decorative fluff. Austerity as choice, not default laziness.
- Advanced Hypertext: Footnotes upgraded toward Gwern-style margin notes. Related substrate panels, see-also, canon cross-links. Backlinks where practical.
- Performance & Sovereignty: Static build. Self-hosted fonts only (Inter Variable, JetBrains Mono Variable, Fraunces Variable, Source Serif 4 Variable). Custom Zig builder (no Jekyll/Hugo/Eleventy rent). Fly or CF pages deploy. Deterministic where possible.
- Craft as Ownership: The site is hand-maintained with the same rigor as vllm-zig or tokenizers-zig. This /design page is the receipts.
Information Architecture
Linear canon for the already-converted ("read in order; they build") plus orthogonal access for the curious:
/— Manifesto + terminal proof-of-work hero + Start Here path (7 essays) + recent + series./start-here/— Guided sequence with abstracts and "why this order"./essays.html+/search.html(pagefind) + tag indexes — filterable archive./posts/*.html— Individual essays with rich header (read time, series nav, version stamp, pre-reg claims, companion substrate, see-also)./substrate/— The star. Lane-grouped cards, status vocabulary, now with client-side search + status chips (vanilla JS, data-* driven). Live telemetry is internal (Elixir LiveView harnesses); public surface is the ledger./canon/,/arc/*— Doctrine / Anti-Edison / Lineage / Sovereign Audit grouped views./design— This page. Self-documenting.
Breadcrumbs implicit via header nav + series nav in posts. No mega-menu. Friction is a feature for the converted; on-ramps exist for others.
Typography & Measure
Body copy targets 65–72ch (enforced via --measure: 68ch on main containers). Line-height 1.72 for dense prose.
Display / headings: Fraunces Variable or Inter for weight. Serif for ledes where voice needs gravity (Source Serif 4 / Fraunces). Mono: JetBrains Mono Variable for all code, terminals, data, tokens.
Self-hosted WOFF2 variable fonts only. No Google Fonts ever again (previous stax-brand.css violation removed in this redesign).
Color & Tokens
--bg: #0D0E15; /* Deep Cathedral Void */
--bg-raised: #0A0A0E;
--text: #F4F1EA; /* Parchment */
--text-soft: rgba(244,241,234,0.6);
--accent: #FF9E00; /* Molten Iron */
--rule-strong: #3f3f46;
--measure: 68ch;Accents are purposeful "sunlit" moments on an otherwise brutalist field. Selection color inverts to accent.
Components & Patterns
- Terminal mock: Retained in hero as the "harness-pre-commit" signal. It is the cheapest honest semiotics for this audience; we own it rather than pretend it is high design.
- Substrate cards: Grid with status pills (experimental / pre-1.0 / stable), meta rows, now filterable. Data-driven from frontmatter in content/substrate/*.md.
- Version stamp + pre-reg + companion substrate: Rendered by the Zig builder from frontmatter. Every essay that touches code shows the receipt.
- Footnotes → Sidenotes: Classic bottom footnotes today (Pandoc [^label] support in builder since early). CSS + JS path to margin notes on wide viewports (this redesign begins the migration; full renderer output change pending).
- Diagrams: Existing in /img/diagrams/ (bottleneck-flow, eight-axis-check, etc.). Referenced from essays. More conceptual SVGs (tollbooth gate, topology nodes) to be added as load-bearing claims require them.
Build & Pipeline (The Actual Substrate)
Custom Zig 0.16 binary (blog-build in tools/blog-builder/):
- Frontmatter (YAML or HTML comment) → strong schema for posts, substrate, objects, workshop, lab.
- Markdown with real footnote extraction, inline render, fenced code + block opts (run, vega, capture for future notebook mode).
- Special renders: substrate index + per-entry, canon arcs with number parsing from slug, version stamps, pre-reg claims blocks, companion substrate panels, RSS/Atom/JSON Feed, sitemap, crosspost txt.
- Templates for home, about, subscribe with {{recent N}} and {{featured}} substitution.
- Deterministic date handling via BLOG_TODAY for previews.
OG cards via scripts/gen-og-images.py + rsvg. Pagefind for client search (static index). No runtime server for the journal itself.
Current Gaps & Roadmap (Auditable)
- Sidenotes: CSS prepared; full HTML restructure in renderer or JS mover still to land (Type II: reader time on dense essays is real cost).
- Start Here / canon list: still partially hard-coded in index.template.html. Next: data-driven from a curated "canon_order" frontmatter or manifest so titles cannot drift.
- More visual rhetoric: tollbooth icon system, live-updating (client) benchmark sparklines from known data, topology graph (D3 or SVG) for the mercantile thesis.
- Print: improved (this page declares it); test with actual long essays.
- a11y: axe / manual pass needed after each wave. Keyboard for filters is there; ARIA on new controls added.
- Builder tests: more property tests on renderMarkdown for edge cases (nested, bad frontmatter).
Proof Level
This page itself is the design receipt. Changes land via the same builder. The CSS and Zig source are the implementation. No Figma theater; the production artifact is the spec.
Related substrate: the blog-builder itself (Zig), the visualizer JS modules, the diagram SVGs.
Last edited: 2026-06-02. Version-stamped by the same discipline as the rest of the canon.