# MazeXChain Website Information Architecture

Last updated: 2026-05-11

This document defines the public website structure for MazeXChain. It prevents the website from becoming a single mixed console page and gives every page a clear role, visual language, and content boundary.

## 1. Website Principle

MazeXChain should be presented as a protocol website, not as a single application screen.

The homepage introduces the protocol and routes visitors to the correct destination. Operational tools, developer references, downloads, wallet instructions, node instructions, and explorer data should live on dedicated pages.

```text
Homepage = positioning + routing + live protocol preview
Console = solving workspace and wallet-signed actions
Protocol = protocol explanation and state-transition diagrams
Whitepaper = formal protocol definition
Downloads = release packages and checksums
Wallet = wallet product and security guidance
Node = node operation and verification guidance
Explorer = chain data and network status
Docs = developer and operator documentation
```

## 2. Page Map

| Page | URL | Primary Purpose | Should Contain | Should Not Contain |
| --- | --- | --- | --- | --- |
| Home | `/` | Public protocol entry and routing | Positioning, core principle diagram, current network summary, primary calls to action | Full solving console, long docs, full event streams |
| Console | `/console.html` | Solver workspace | Sampling grid, candidate submission, wallet signer, current commitments, events, rewards, leaderboard | Marketing copy, long whitepaper text |
| Protocol | `/protocol.html` | Explain how the protocol works | Cognitive advancement loop, protocol objects, state transition, diagrams | Wallet setup steps, package downloads as main content |
| Whitepaper | `/whitepaper.zh.html`, `/whitepaper.html` | Formal protocol definition | Abstract, terminology, model, algorithms, security, references | Runtime controls |
| Downloads | `/downloads.html` | Release center | Wallet extension, node program, chain data, PDFs, versions, checksums | Solving workspace |
| Wallet | `/wallet.html` | Wallet product and safety | Install, create/import, phrase verification, site connection, signing confirmation, security model | Full chain explorer |
| Node | `/node.html` | Node operation | Run node, sync, replay, snapshots, CLI, config, verification | Wallet onboarding as primary focus |
| Explorer | `/explorer.html` | Public chain data | Solve Blocks, Solver records, state roots, behavior commitments, network status | Long protocol explanation |
| Docs | `/docs.html` | Documentation portal | Architecture, API, CLI, storage, security, glossary, operator guides | Marketing hero as primary content |

## 3. Homepage Design Rule

The homepage must be reduced to an entry page. It should feel like a protocol portal, not a dashboard dump.

Required homepage sections:

```text
1. Global navigation with grouped Mega Menu
2. Protocol hero
3. Core principle visual
4. Primary calls to action
5. Protocol loop preview
6. Role-based entry portal
7. Footer directory
```

Homepage content to move out:

```text
1. Full sampling grid -> Console
2. Full submit form -> Console
3. Long event stream -> Explorer or Console
4. Reward ledger -> Explorer
5. Node network diagnostics -> Explorer / Node
6. Detailed download cards -> Downloads
7. Wallet onboarding details -> Wallet
```

## 4. Page-Specific Visual Language

Each page should have a distinct layout pattern. Reusing the same card grid on every page is not acceptable.

Every public page must carry at least one page-specific visual explainer. The site should not rely on text cards alone.
Visual modules should encode the page purpose directly: loops for protocol logic, release maps for downloads, signing
boundaries for wallets, runtime lanes for nodes, ledger strips for explorer pages, and knowledge maps for documentation.

Each major page section must also have a reference-mapped layout pattern before implementation. This means the designer
or developer must identify the closest mature pattern first, then adapt the structure to MazeXChain's black-and-white
protocol identity. Examples include:

```text
Mega Menu        -> education/resource navigation pattern
Protocol page    -> explanatory flow and state-machine figure pattern
Downloads page   -> release-center package verification pattern
Wallet page      -> product onboarding and signing-safety pattern
Node page        -> operator guide with command and runtime lanes
Explorer page    -> ledger/data-inspection pattern
Docs page        -> documentation index and knowledge-map pattern
```

Cards must not be only text containers. A card should contain at least one of:

```text
1. A compact diagram or visual object.
2. A release/checksum/status surface.
3. A workflow step with spatial relationship.
4. A data preview that reflects the page purpose.
5. A short action label tied to the page's next step.
```

| Page | Visual Direction |
| --- | --- |
| Home | Protocol portal: large statement, simple network diagram, concise routing |
| Console | Laboratory dashboard: dense controls, grid interaction, live state panels |
| Protocol | Technical diagram page: loops, state-machine maps, protocol object diagrams |
| Whitepaper | Publication layout: formal typography, figures, tables, references |
| Downloads | Release center: version blocks, checksums, package cards, verification notes |
| Wallet | Product onboarding: install steps, security warnings, account flow, screenshots later |
| Node | Operator guide: command blocks, architecture lanes, sync/replay flow |
| Explorer | Data interface: search, latest blocks, tables, status indicators |
| Docs | Documentation hub: sidebar-like index, module groups, quick links |

## 4.1 Typography And Rhythm

The website uses a publication-style display face for major protocol statements and a cleaner UI face for body copy.
This prevents the interface from becoming dense, while preserving the formal protocol identity.

```text
Display type = hero statements, section theses, protocol claims
UI type      = body text, navigation, cards, operational copy
Mono type    = hashes, commands, labels, roots, package checksums
```

Large text must be paired with whitespace, diagrams, or short operational labels. If a section contains more than three
paragraph-heavy cards, it should be redesigned as a visual flow, split panel, diagram, or release/ledger map.

## 5. Navigation Model

Top-level navigation should remain stable and grouped. The public site uses a hover/focus Mega Menu instead of a flat row of unrelated links.

The public navigation is a sticky protocol shell. It remains available while reading long pages, uses the same neutral
surface as the page canvas, and opens dark mega panels for grouped navigation. The sticky shell should feel like a
protocol operating layer, not a separate app toolbar.

```text
Protocol  -> overview, whitepaper, vocabulary
Solve     -> console, Solve Blocks, wallet
Build     -> node, downloads, CLI/API docs
Network   -> explorer, latest blocks, node status
Resources -> docs, release center, English whitepaper
```

The solving workspace should be exposed as a primary call to action, for example:

```text
Start Solving -> /console.html
```

The homepage should not force visitors to scroll through the entire console before understanding the project.

## 5.1 Visual Rhythm Rule

Public pages should alternate between four layout modes instead of repeating text-only cards:

```text
1. Statement panel: large thesis, short paragraph, one primary action.
2. Diagram panel: grid, orbit, ledger, package map, or wallet boundary.
3. Dark narrative panel: high-contrast explanation for protocol principles.
4. Action portal: large role-based cards with visual objects and arrows.
```

Every major page should include at least one diagram or visual object above the fold. Long explanatory text should be
compressed into shorter claims and paired with a visual system surface.

Card boundaries should be invisible by default. Public pages should feel like one continuous neutral protocol surface:
outside of text, diagrams, and primary controls, cards should not carry a separate fill, border, or shadow until hover
or keyboard focus reveals the interactive target. This keeps the page from looking like stacked white boxes while
preserving clear interaction targets.

## 6. Future Refactor Target

The homepage and console are now separated. Future refinements should preserve this boundary:

```text
Keep index.html as the public landing page.
Keep console.html as the operational solving workspace.
Keep shared navigation and visual system consistent.
Make each child page purpose-built instead of copying card layouts.
```

## 7. Acceptance Checklist

Before considering the website structure complete:

```text
1. Homepage can be understood in under 20 seconds.
2. Console actions are not mixed with whitepaper/docs content.
3. Each top-level navigation item opens a page with a distinct purpose.
4. Downloads page exposes package files and checksums clearly.
5. Wallet page explains install, login, backup, and signing confirmation.
6. Node page explains running and verifying a node.
7. Explorer page shows or previews public chain records.
8. Docs page routes technical users to architecture, API, CLI, security, and storage docs.
9. Footer mirrors the same information architecture.
10. Public wording follows `docs/protocol-vocabulary.md`.
11. Every public child page has a distinct visual module instead of only repeated text cards.
12. Body text uses compact UI typography; oversized display type is reserved for protocol statements.
13. Public navigation remains sticky and visually unified with the page shell.
14. Each repeated card group includes visual objects, workflow markers, or data surfaces, not plain text alone.
15. Public cards are transparent by default and reveal their boundaries only on hover or focus.
```
