UI/UX Audit & Improvement: Wayfinding, Landing Pages, Version Clarity

[BrianSeong99]

Summary

A focused UI/UX improvement effort for docs.miden.xyz addressing the six highest-leverage problems identified through a comprehensive audit. All changes work within Docusaurus v3 patterns — no architectural rewrites.

---

Audit Findings

Top 5 UX Problems (Priority Order)

#	Problem	Impact	Type
1	Cross-section wayfinding is absent — No mechanism guides users between Build and Core Concepts	All users navigating between practical and conceptual docs	Component + content
2	Core Concepts landing page is a wall of text — No DocCards, no scannable entry points, confusing version note	Protocol researchers, anyone entering via Core Concepts nav	Content + structure
3	Version messaging is confusing — Two pages say content is "available in released versions only" without explaining how to switch	All users, especially on unstable/next version	Content + component
4	Hub pages have broken learning flow — Tutorials category missing sidebar link, hub pages have misleading pagination	Tutorial users, pagination navigators	Structure
5	No page-level orientation scaffolding — Pages jump into content with no audience, prerequisites, or "what you'll learn"	First-time users landing via search	Component + content

What's Already Good

• Builder landing page has solid DocCard hub structure
• Design system is well-organized (tokens, components, sidebar CSS)
• Theme swizzle wrapper pattern is clean and extensible
• DocItem/Layout wrapper is empty — perfect extension point
• Sidebar hierarchy with section labels works well

---

Implementation Checklist

1. Create SectionLinks component for cross-section wayfinding

Problem: Users in Build docs have no way to discover related Core Concepts pages (and vice versa).

Solution: Reusable React component rendering a styled box with contextual cross-links.

Props:

interface SectionLinksProps {
  title?: string;       // e.g., "Related Core Concepts"
  links: Array<{ href: string; label: string; description?: string }>;
}

Visual: Bordered box with left accent in --color-accent, compact link list, dark theme support. Follows CodeTabs component pattern.

Files:

• Create src/components/SectionLinks/index.tsx
• Create src/components/SectionLinks/styles.module.css
• Modify src/components/index.ts — add export

---

2. Create VersionNote component for actionable version messaging

Problem: Current :::info Version Note blocks say "available in released versions only" without explaining what that means or how to switch. Two pages use this confusing pattern.

Solution: Reusable component with clear copy: "Development version. {subject} is available in released versions. Select {stableVersion} from the version dropdown."

Props:

interface VersionNoteProps {
  subject?: string;         // e.g., "Client documentation"
  stableVersion?: string;   // defaults to "v0.13"
}

Files:

• Create src/components/VersionNote/index.tsx
• Create src/components/VersionNote/styles.module.css
• Modify src/components/index.ts — add export
• Modify docs/core-concepts/index.md — replace :::info Version Note
• Modify docs/builder/tools/index.md — replace :::info Version Note

---

3. Refactor Core Concepts landing page into navigation hub

Problem: The Core Concepts index is a long essay with no DocCards, no scannable entry points, and a confusing version note.

Changes:

• Replace :::info Version Note with <VersionNote> component
• Add "Explore by Topic" section with 4 DocCards (Protocol, VM, Compiler, Node) linking to page anchors
• Add <SectionLinks> cross-linking to Builder docs
• Add front matter: pagination_next: null, pagination_prev: null
• Keep all existing technical prose, improve scannability

Target structure:

# Miden Core Concepts
[1-paragraph framing]
<VersionNote />
## Explore by Topic → [4 DocCards]
<SectionLinks title="Start Building" />
---
## Architecture Overview → [existing content]
## Protocol → [existing content]
## VM → [existing content]
## Compiler → [existing content]
## Node → [existing content]

File: docs/core-concepts/index.md

---

4. Improve Builder landing page with cross-section links

Problem: No cross-links to Core Concepts, slightly alarming version messaging.

Changes:

• Soften version note copy
• Add <SectionLinks> at bottom linking to Core Concepts
• Add front matter: pagination_next: null

File: docs/builder/index.md

---

5. Enhance DocItem/Layout with front matter metadata scaffolding

Problem: Interior pages lack audience, prerequisites, and learning objectives.

Solution: Use the empty DocItem/Layout wrapper + useDoc() hook to render metadata from front matter fields. Zero rendering when fields absent.

Front matter fields (all optional):

audience: Rust developers
prerequisites:
  - Miden CLI installed
  - Basic Rust knowledge
what_you_will_learn:
  - Create accounts programmatically
  - Understand account types

Rendering: Compact bordered container with audience badge + labeled lists. Only appears when fields present.

Files:

• Modify src/theme/DocItem/Layout/index.tsx — add metadata rendering
• Create src/theme/DocItem/Layout/styles.module.css

---

6. Fix sidebar and pagination issues

Problems:

• Tutorials is the only sidebar category without a link property
• Hub pages show confusing Previous/Next pagination across sections

Changes:

• Modify sidebars.ts — add link: { type: "doc", id: "builder/tutorials/rust-compiler/index" } to Tutorials category
• Modify docs/builder/get-started/index.md — add pagination_prev: null
• Modify docs/builder/smart-contracts/index.md — add pagination_prev: null

---

7. Add page-level metadata to high-value pages

Apply metadata to 3 key pages to demonstrate and validate the scaffolding:

• docs/builder/get-started/index.md — audience + what_you_will_learn
• docs/builder/smart-contracts/index.md — audience + prerequisites
• docs/builder/tutorials/rust-compiler/index.md — audience + prerequisites + what_you_will_learn

---

Design Principles

• Orientation before density — Users should know where they are and where to go within seconds
• Builder and concept flows cooperate — Build explains how, Core Concepts explains why
• Landing pages are hubs, not essays — Cards, paths, entry points over walls of text
• Version state is visible and actionable — Don't just warn, explain what to do
• Small reusable primitives — Components used across sections, not one-off styling
• Keep Docusaurus mental model intact — Swizzled components, front matter, MDX, CSS modules

Dependency Graph

1. SectionLinks component ─┬─→ 3. Core Concepts landing
                            └─→ 4. Builder landing
2. VersionNote component  ──→ 3. Core Concepts landing
5. DocItem metadata ────────→ 7. Page metadata content
6. Sidebar/pagination (independent)

Not In Scope

• Editing versioned_docs/ or versioned_sidebars/
• Changing docusaurus.config.ts plugin structure
• Rebuilding site architecture
• Custom routing systems
• Search enhancement (defer to separate effort)

Acceptance Criteria

• npm run build passes cleanly
• No new broken link warnings
• Core Concepts landing page is a scannable hub with DocCards
• Cross-section links exist on both landing pages
• Version messaging is clear and actionable
• Tutorials sidebar category is clickable
• Hub pages have intentional (or no) pagination
• Page metadata renders on annotated pages, invisible on others

Follow-up Work (future PRs)

1. Add SectionLinks to interior pages (e.g., smart-contracts/accounts → core-concepts accounts)
2. Add page metadata to more pages incrementally
3. Improve search placeholder text and empty-state messaging
4. Add sidebar badges via customProps (Tutorial, Reference, Start Here)
5. Create "Choose Your Path" decision component for Builder landing
6. Fix Get Started title inconsistency ("Quick Start" title vs "Get Started" sidebar label)