This proposal is about the Quartz UI / theme layer, not the research content itself.
The goal is not “make it prettier.” The goal is:
make the garden feel like parameter-llm-golf-code: research-lab, code-native, compressed, technical, elegant, and obviously about constraints / optimization rather than generic publishing.
It builds on the structural thinking in IA audit and the structural proposal, but focuses specifically on visual system, chrome, density, and component feel.
Executive judgment
Right now the site reads as:
- a thoughtful Quartz garden
- lightly customized with better fonts and a muted palette
- structurally serious in content
- but still visually close to a generic digital-garden / notes / blog shell
The content is more technical and more compressed than the interface.
The UI should instead signal:
- lab notebook + codebase + benchmark dashboard
- not personal blog
- not “second brain”
- not soft lifestyle knowledge garden
The strongest design move is to turn the site into a research control surface:
- denser chrome
- sharper typography hierarchy
- darker and more instrument-like surfaces
- lists that feel like dossiers or traces
- graph that feels like topology, not a cute widget
- code blocks that feel like artifacts under inspection
- metadata that feels like signals, budgets, and constraints
1. Audit of current Quartz customization points
The good news is that Quartz already exposes enough surface area to do this without touching research content.
| Layer | Current file(s) | What it controls now | Opportunity |
|---|---|---|---|
| Global theme tokens | quartz-kb/quartz.config.ts | page title, SPA/popovers, fonts, light/dark colors, syntax theme plugin | easiest place to shift overall tone |
| CSS variable generation | quartz-kb/quartz/util/theme.ts | maps theme config into CSS custom properties | useful for expanding token vocabulary later if needed |
| Page composition | quartz-kb/quartz.layout.ts | left rail, right rail, before-body components, footer | determines whether the site feels like a blog, docs shell, or research cockpit |
| Global style base | quartz-kb/quartz/styles/base.scss | page grid, typography, prose, code blocks, tables, spacing | biggest leverage for feel and density |
| Breakpoints / grid widths | quartz-kb/quartz/styles/variables.scss | desktop/mobile widths, side panel width, top spacing | controls compression and chrome balance |
| Project override layer | quartz-kb/quartz/styles/custom.scss | currently just imports base, otherwise empty | cleanest place for site-specific visual system |
| Syntax overrides | quartz-kb/quartz/styles/syntax.scss | syntax token colors | can make code feel more lab-grade |
| Explorer styling | quartz-kb/quartz/components/styles/explorer.scss | left nav tree | currently filesystem-like; can become a control rail |
| Search styling | quartz-kb/quartz/components/styles/search.scss | search button + modal | can become a command palette |
| Graph styling | quartz-kb/quartz/components/styles/graph.scss | local graph card + global graph modal | currently generic card/modal; can become atlas/topology view |
| List styling | quartz-kb/quartz/components/styles/listPage.scss | folder/tag list rows | currently minimal list rows; can become research dossiers |
| Metadata styling | quartz-kb/quartz/components/styles/contentMeta.scss | page date / reading time line | can become a signal strip |
| Footer styling | quartz-kb/quartz/components/styles/footer.scss | footer links | currently generic Quartz footer |
| Page list rendering | quartz-kb/quartz/components/PageList.tsx | title/date/tag rows for folder/tag pages | high leverage for cards / lists / badges |
| Folder / tag page rendering | quartz-kb/quartz/components/pages/FolderContent.tsx, TagContent.tsx | list-page body structure | useful for section intros and scoped list shells |
| OG image generation | quartz-kb/quartz/plugins/emitters/ogImage.tsx | auto-generated social previews | can align off-site previews with new theme |
2. Current visual / component state
Theme
Current fonts and colors are better than stock, but they still read as calm knowledge-garden rather than research-lab system.
Current config:
- headers:
Schibsted Grotesk - body:
Source Sans Pro - code:
IBM Plex Mono - palette: soft off-white / charcoal with muted blue-green accents
- syntax:
github-light/github-dark
That produces a site that is competent and pleasant, but also:
- slightly soft
- slightly editorial
- not especially compressed
- not especially code-native
Layout
Current content-page composition in quartz.layout.ts is:
- before body: breadcrumbs, title, content meta, tags
- left rail: site title, search, darkmode, reader mode, fully open explorer
- right rail: graph, TOC, backlinks, recent notes
- footer: Quartz attribution + repository links
That is a strong default Quartz layout, but it still feels like:
- left: filesystem / utility rail
- center: note page
- right: helpful widgets
rather than:
- left: research control rail
- center: dossier / note / paper page
- right: topology and signal rail
Global styling
custom.scss is effectively unused, so almost all feel comes from Quartz base styles.
base.scss currently gives the site:
- generous white-space
- rounded 5px surfaces
- soft bordered code blocks
- broad prose spacing
- standard link-highlight pills
- default-ish content block behavior
This is solid, but not distinctive.
Explorer
The Explorer is fully open and styled like a standard nested docs tree.
It currently says:
- “browse the folder structure”
It does not yet say:
- “this is a compressed map of the research program”
Graph
The graph is technically present and useful, but visually it is still framed like a generic sidebar card and generic modal.
Given the subject matter, the graph should feel more like:
- topology
- adjacency
- mechanism neighborhood
- pressure map
and less like:
- side widget
Lists / folder pages / tag pages
PageList.tsx renders simple rows with:
- date
- title
- tags
Useful, but visually thin. These should feel more like:
- research traces
- indexed artifacts
- briefings
- ranked entries
Code blocks
Code blocks are competent but generic:
- GitHub-adjacent syntax
- soft box treatment
- line numbers as a utility feature
For this site, code blocks should feel like:
- inspected artifact
- benchmark patch
- source excerpt
- controlled technical surface
3. Desired aesthetic direction
Core design thesis
The site should feel like a mix of:
- a research dossier
- a benchmark lab interface
- a high-end repo browser
- a compressed technical notebook
Adjectives to optimize for
- compressed
- technical
- lucid
- instrumented
- precise
- calm-under-pressure
- elegant without softness
Adjectives to avoid
- cozy
- airy
- hand-crafted scrapbook
- generic blog
- startup-marketing gradient
- playful graph toy
- “Obsidian export with some CSS”
Visual metaphor
The best metaphor is not “garden.”
The best metaphor is:
research control surface over a living code-and-ideas graph
That means the interface should visually emphasize:
- boundaries
- rails
- panels
- labels
- states
- signal colors
- low-noise typography
- compact blocks that look intentionally budgeted
4. Proposed theme system
4.1 Theme and page atmosphere
Proposed shift
Move from paper-notes UI to instrument-panel UI.
That does not mean cyberpunk or terminal gimmicks.
It means:
- darker base surfaces
- sharper border hierarchy
- fewer soft rounded “cards”
- less reliance on whitespace for elegance
- more reliance on rhythm, linework, and type hierarchy
Surface model
Use a clearer 4-layer surface stack:
- field — page background
- panel — explorer, graph, search, code surfaces
- raised panel — modals / overlays / search / global graph
- signal highlight — active rows, hovered nodes, current page state
Recommendation
Make the site dark-first in emotional tone even while keeping a light mode.
Dark mode should feel like the canonical mode:
- deep graphite / midnight backgrounds
- cold steel borders
- icy blue as primary navigation accent
- restrained green / amber / red for semantic signal
Light mode should feel like a printed lab worksheet, not a generic clean blog:
- off-white / cool-gray paper
- blueprint-like accent
- thin technical separators
4.2 Typography
Current issue
The current typography is readable but not especially system-like.
Source Sans Pro especially pushes the site slightly toward editorial generality.
Proposal
Use a more technical, tighter family stack.
Recommended font stack
- title:
IBM Plex Mono - header:
IBM Plex Sans Condensed - body:
IBM Plex Sans - code:
IBM Plex Mono
This would create a strong visual identity with one coherent family system.
Why this works
IBM Plex Monogives code-native authority without looking gimmickyIBM Plex Sans Condensedintroduces the compression the site currently lacksIBM Plex Sanskeeps long-form research prose readable- repeated Plex family usage makes the site feel like a system, not a collage
Typographic behavior
- titles should be dense and intentional, not oversized
- metadata and UI labels should lean mono
- section labels should often be uppercase or tracked slightly wider
- body copy should remain comfortable, but tighter than current Quartz defaults
- tags should stop reading like casual pills and start reading like indexed facets
Specific treatment ideas
- page title: mono or semi-mono dossier heading
- section / component titles: condensed sans, uppercase, small
- dates / reading time / route labels: mono
- inline code: compact token treatment, slightly denser than current
4.3 Color system
Current issue
The current palette is tasteful but too soft and too generic for optimization-heavy technical material.
Proposal
Adopt a token system with one primary accent and a few semantic diagnostics.
Design rule
Do not create a rainbow UI.
Use:
- one primary navigation / interaction accent
- one secondary accent for topology / relation
- 3 to 4 semantic diagnostic colors only where they mean something
Suggested semantic model
- accent / navigation: ice-blue
- topology / relatedness: cool violet-blue or desaturated cyan
- success / improvement / keep: green-teal
- constraint / budget / warning: amber
- failure / regression / invalid: muted coral-red
- neutral infrastructure: steel gray
Example directional palette
These are not final, but they are concrete enough to build around.
Dark mode
bg-0:#0b0f14bg-1:#111720bg-2:#161f2aline-0:#243142line-1:#314256text-0:#d9e2ectext-1:#96a3b5accent:#7dd3fcaccent-2:#93c5fdgood:#6ee7b7warn:#fbbf24bad:#f87171
Light mode
bg-0:#f4f7fbbg-1:#eaf0f6bg-2:#dde6f0line-0:#c8d4e3line-1:#a8b7catext-0:#0f1722text-1:#5b6a7daccent:#0b5ed7accent-2:#2563ebgood:#0f9f6ewarn:#b7791fbad:#c24141
Important visual rule
Signal colors should appear where they imply measurement or status, not decoration.
That is how the UI starts expressing:
- constraints
- wins
- regressions
- active routes
- artifact pressure
4.4 Density and spacing
Current issue
The current site spacing is pleasant but too generous for “compressed technical system” energy.
Proposal
Tighten the interface one level without harming prose readability.
Density rules
- use smaller vertical gaps between chrome elements
- tighten panel paddings
- reduce side-rail width slightly unless a component truly needs it
- keep body copy readable, but compress surrounding chrome
- use linework and micro-labels instead of empty space to create hierarchy
Specific recommendations
- reduce sidebar width from the current
320pxtoward272–288px - reduce top spacing so pages do not feel floated in empty air
- keep prose line-height around
1.5–1.6, but lower UI-line-height elsewhere - standardize on a tighter radius system:
3px,5px,8px - use shadows sparingly; prefer borders and tonal separation
Principle
The interface should look like it respects the same optimization culture as the content.
Nothing should feel wasteful.
5. Navigation and page chrome
5.1 Left rail: from filesystem to control rail
Current problem
The left rail is still mostly:
- title
- utilities
- open folder tree
Proposed role
The left rail should become a research control rail.
It should answer:
- where am I in the research system?
- what major region am I in?
- what are the few highest-value jumps from here?
Recommended structure
- site mark / title
- command search
- curated hub links
- section explorer
- display controls
Concrete changes
- move Darkmode / ReaderMode below the main nav emphasis
- restyle Search as a command palette trigger
- make Explorer collapsed by default, not fully open
- consider a small custom component above Explorer with fixed hub links:
- Home
- Challenge
- Challenge History
- Lanes
- Frontiers
- Hypotheses
- Papers
- Meta
- Reports
Best implementation path
Create a small custom component rather than forcing the Explorer alone to do all the work.
Suggested future file:
quartz-kb/quartz/components/ResearchNav.tsx
This lets the explorer stay useful as a tree while a curated nav establishes identity.
5.2 Center column: dossier header, not just article title
Current problem
The page header is structurally correct but visually thin.
Proposed page header model
Each page should open like a research dossier.
Header stack:
- breadcrumb / path
- page title
- signal row: date, reading time, maybe folder / doc type / route label
- tag / facet row
- optional thin divider before article body
Visual treatment
- breadcrumbs smaller and mono
- title tighter, heavier, more deliberate
- metadata as a compact signal strip
- tags as indexed chips, not soft blog labels
- a thin header divider can help the page feel like a reviewed artifact
5.3 Right rail: topology rail, not widget rail
Current problem
The right rail is useful, but it reads like stacked utilities.
Proposed role
The right rail should feel like:
- local topology
- page structure
- backlink context
- recent deltas
Renaming / framing ideas
- Graph → Local topology
- TOC → On this page
- Backlinks → Referenced by or Graph neighbors
- Recent Notes → Recent changes or Recent traces
This can be done visually even before copy changes.
6. Graph styling proposal
Current problem
The graph is present but under-expressive.
It visually feels like a standard Quartz graph widget instead of something tailored to a mechanism graph.
Proposal
Treat the graph as a technical topology viewer.
Structural recommendations
- disable tag nodes in the graph unless the tag taxonomy is rebuilt first
- use much quieter edges
- make the current node and directly connected nodes more legible
- style the graph container like a panel with technical framing, not a generic card
- make the global graph modal feel like an atlas overlay
Visual recommendations
- darker graph canvas than surrounding chrome
- subtle grid / topology feel only if it stays quiet
- mono micro-labels
- lower edge opacity
- stronger current-node emphasis
- semantic highlight for visited or active nodes
Important behavioral recommendation
Do not make the graph louder than the page.
It should be a precision tool, not the page’s visual mascot.
Immediate configuration recommendation
In quartz.layout.ts, future implementation should likely turn off showTags for both local and global graph unless and until the tag taxonomy becomes structured enough to deserve visualization.
7. Cards, lists, folder pages, and tag pages
Current problem
The current list rendering is informative but not distinctive.
It feels like default generated listings.
Proposal
Make list pages feel like indexed research artifacts.
List-row model
Each row should communicate:
- title
- time
- section / type
- a tiny hint of why the item matters
- optional tags / status
Visual direction
Not big marketing cards.
Better models:
- dossier row
- patch note row
- repo index row
- compact evidence card
Recommended rendering evolution
Phase 1 can be CSS-only.
Phase 2 should likely update PageList.tsx to support:
- optional excerpt / description
- path or section label
- stronger metadata alignment
- status / scope chips if frontmatter supports them later
Folder / tag page shell
For FolderContent.tsx and TagContent.tsx:
- give each listing page a section-intro block
- add a stronger list container shell
- visually separate section description from the listing inventory
8. Code-block feel
Current problem
The site talks like technical research but code blocks still look like fairly generic pretty-code embeds.
Proposal
Make code blocks feel like artifact panes.
Visual rules
- darker, more self-contained surface than surrounding prose
- clearer top label or filename chip
- more subtle but more intentional line numbers
- highlighted lines should feel diagnostic, not decorative
- inline code should feel like a token or symbol, not a soft blob
Syntax direction
Move away from GitHub-like syntax coloration.
A future implementation should test a darker, calmer syntax family such as a Vitesse-like or similarly technical palette, then refine with syntax.scss overrides.
Concrete styling ideas
- stronger distinction between inline code and block code
- top border / title strip on code figures
- lower border radius than current
- slightly smaller mono size for chrome, slightly larger for code body if needed
- subtle background texture only if nearly invisible
Constraint expression through code blocks
Code blocks can visually reinforce the site’s subject matter by feeling like:
- benchmark excerpts
- inspected patches
- export artifacts
- measurement-adjacent source
not like lifestyle-blog snippets.
9. How the UI should visually express constraints, compression, and optimization
This is the most important conceptual shift.
The site should not merely contain pages about constraints.
The interface itself should embody them.
9.1 Compression
Use:
- tighter rails
- tighter label systems
- smaller but clearer component titles
- fewer decorative surfaces
- short, deliberate spacing rhythms
The UI should feel budget-aware.
9.2 Constraints
Use visual grammar that suggests limits and thresholds:
- rulers
- dividers
- thin caps / header bars
- boundary lines
- warning colors only where limits matter
- chips that feel like indexed constraints, not casual tags
9.3 Optimization
Express optimization through emphasis hierarchy:
- active path accent
- low-noise baseline surfaces
- strong signal only on useful interaction points
- “gain / warning / invalid” semantics in badges or callouts
- less ornamental color, more metric-like color
9.4 Technical elegance
The site should feel like a system that has been tuned.
That means:
- low ornament
- consistent type rhythm
- consistent radii
- consistent border language
- no random gradients or glows
- no overly cute card shadows
Strong idea
Even without adding new content fields, the site can start to feel optimization-native by globally styling existing elements as if they are part of a measurement system:
- tags as facets
- metadata as signals
- graph as topology
- list rows as indexed traces
- code blocks as inspected artifacts
10. Concrete implementation plan
Phase 0 — visual foundation audit and freeze
Goal: establish the design language before touching many components.
Files
quartz-kb/quartz.config.tsquartz-kb/quartz/styles/custom.scssquartz-kb/quartz/styles/variables.scssquartz-kb/quartz/styles/base.scssquartz-kb/quartz/styles/syntax.scss
Tasks
- replace font stack with a more technical Plex-based system
- redesign the base color tokens for lab-grade dark/light modes
- tighten core spacing and radii
- restyle global typography, links, inline code, block code, tables, blockquotes
- move the visual baseline away from default Quartz softness
Phase 1 — page chrome and rail identity
Goal: make the layout feel like a research system before refining every component.
Files
quartz-kb/quartz.layout.tsquartz-kb/quartz/components/styles/explorer.scssquartz-kb/quartz/components/styles/search.scssquartz-kb/quartz/components/styles/contentMeta.scssquartz-kb/quartz/components/styles/footer.scss- likely new:
quartz-kb/quartz/components/ResearchNav.tsx
Tasks
- add a curated research nav above or alongside the explorer
- collapse explorer by default or reduce its visual dominance
- restyle search into a command-palette trigger
- turn content meta into a compact signal strip
- de-genericize footer so it feels like part of the research system
Phase 2 — page lists and section inventory
Goal: make generated listings feel designed, not emitted.
Files
quartz-kb/quartz/components/PageList.tsxquartz-kb/quartz/components/styles/listPage.scssquartz-kb/quartz/components/pages/FolderContent.tsxquartz-kb/quartz/components/pages/TagContent.tsx
Tasks
- redesign list rows as dossier / trace entries
- add optional section/path metadata
- improve description handling for list pages
- visually separate inventory from prose intro
- make tag pages feel like faceted research indexes, not raw tag dumps
Phase 3 — graph and topology system
Goal: make the graph feel purposeful and technical.
Files
quartz-kb/quartz.layout.tsquartz-kb/quartz/components/styles/graph.scss- possibly
quartz-kb/quartz/components/Graph.tsxif labels / wrappers need copy changes
Tasks
- turn off noisy tag rendering in graph
- restyle graph panel and global graph overlay
- reframe graph section as topology / adjacency viewer
- make current page and local neighborhood more legible than distant noise
Phase 4 — polish and external identity
Goal: align social previews and detail surfaces with the new system.
Files
quartz-kb/quartz/plugins/emitters/ogImage.tsxquartz-kb/quartz/static/og-image.pngor new themed OG component assets- optionally new custom OG component
Tasks
- make OG images look like research dossier cover cards
- align preview colors / typography with site chrome
- carry the lab-system identity off-site
11. Best first implementation slice
If implementation starts soon, the best first slice is:
- theme tokens
- typography system
- page chrome
- explorer/search restyle
- graph tag removal
Why this first:
- it changes the emotional read of the whole site quickly
- it does not require content edits
- it avoids premature custom-component sprawl
- it creates a coherent base before changing list rendering
12. Small set of hard design rules
These should stay true through implementation.
Do
- design for density with restraint
- use mono strategically, not everywhere
- treat metadata as signal
- use borders more than shadows
- keep light mode cool and technical
- keep dark mode as the emotional center of gravity
- make lists feel indexed and ranked
- make graph feel analytical
Do not
- add decorative gradients as a shortcut for identity
- make every section a card stack
- keep large soft blog-style paddings
- use tag pills as colorful candy
- let Explorer remain the only left-rail identity object
- let the graph become a toy-like centerpiece
- let Quartz attribution visuals dominate the footer tone
Bottom line
The Parameter Golf garden already has serious content and a credible structure.
What it lacks is a UI system that visibly says:
this is a compressed technical research program shaped by budgets, constraints, traces, and optimization pressure.
The redesign should therefore prioritize:
- a technical typography system
- a dark-first lab palette with disciplined semantic accents
- a control-rail navigation model
- dossier-like list and page chrome
- a topology-grade graph treatment
- artifact-like code surfaces
If those are implemented well, the site will stop feeling like “Quartz with better content” and start feeling like a native interface for Parameter Golf research.