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

## 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:**
```tsx
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:**
```tsx
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 `` component
- [ ] Add "Explore by Topic" section with 4 DocCards (Protocol, VM, Compiler, Node) linking to page anchors
- [ ] Add `` 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]

## Explore by Topic → [4 DocCards]

---
## 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 `` 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):**
```yaml
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)