UI/UX & IA decisions

This page records the senior UI/UX decisions used to shape this knowledgebase, so changes stay consistent over time.

Primary audience paths

We optimize for four high-frequency intents:

1. Download (official binaries + verification)
2. Stake (PoSV v2, ops, expectations)
3. Troubleshoot (triage → decision tree → recipes)
4. Build (ReddID + namespaces + schema)

These are reflected in both the homepage Quick Actions and the Start Here portal.

Design choices (why)

Quiet authority

Crypto users have high “scam-alert” sensitivity. We therefore prefer a calm, high-contrast UI with restrained color and strong typography.

Accessibility & contrast

We enforce readable header contrast and consistent link emphasis so key actions remain visible in both light and dark modes.

Separation of concerns

“Ecosystem” is user-facing (products/partners/markets). “Builders” is technical (ReddID/specs/schema). This prevents cognitive overload.

What to preserve

• Task-first routing and scannable hub pages
• Safety admonitions on security-critical pages
• “Last verified” notes on pages with changing external links

What to improve next

• Add diagrams for ReddID flows (namespaces → resolution → wallet integration)
• Add a minimal “Network status / advisories” banner when incidents occur

Contrast & visibility (trust markers)

• Header and tabs use a dark surface with white text to prevent “white-on-white” and to keep navigation readable in both light and dark modes.
• Announcement/banner surfaces (if enabled) are forced to a dark background with high-contrast text.
• The custom stylesheet is loaded via extra_css in mkdocs.yml (see docs/assets/stylesheets/extra.css).

Last reviewed: 2026-02-13