Evidence-informed patterns for building Nostr apps people actually use.
🌐 View the complete guide at: nostr-ux.com
Nostr has a working, censorship-resistant protocol. The critical problem is user experience.
Current metrics:
- 30-day retention trending to 0% for recent cohorts
- Daily active users stuck at 10,000-12,000 despite viral adoption spikes
- Users often need multiple clients to access different features
This is a retention crisis. But it's also solvable. Traditional social apps achieve better retention not through centralization, but through better content discovery, reliable core interactions, and streamlined onboarding—all implementable on Nostr.
This pattern library provides evidence-informed patterns to fix these critical UX problems.
6 critical UX patterns backed by 100+ verified sources:
- Onboarding & First-Run Experience - Minimize time-to-first-value
- Content Discovery & Feed Quality - Solve the empty feed problem
- Core Interaction Loops - Make posting/replying work reliably
- Performance & Perceived Speed - Optimistic UI and loading states
- Progressive Complexity - Hide power features until needed
- Cross-Client Consistency - Data integrity across apps
Each pattern includes:
- Research-backed problem statement
- Universal UX principles (70%) + Nostr-specific considerations (30%)
- Concrete implementation examples
- Anti-patterns to avoid
- Validation checklists with measurable metrics
Plus: The Validation Framework — a decision-making filter to prevent feature bloat.
Or jump directly to a specific pattern:
- Pattern 1: Onboarding - Get users to value in under 2 minutes
- Pattern 2: Content Discovery - Solve the empty feed problem
- Pattern 3: Core Interactions - Make basic actions reliable
- Pattern 4: Performance - Feel fast even when slow
- Pattern 5: Progressive Complexity - Hide advanced features from beginners
- Pattern 6: Cross-Client Consistency - Don't lose data when switching apps
manifest.json - Machine-readable content map for automated tools, AI agents, and RAG systems:
- Complete file inventory with titles, descriptions, and metadata
- 3 curated reading paths (quick/comprehensive/researcher)
- Category organization and importance ratings
- Perfect for feeding to LLMs, documentation generators, or analysis tools
Use cases: LLM context ingestion, RAG indexing, automated documentation, content validation, custom navigation interfaces.
- Nostr developers building consumer social apps (mobile, web, desktop)
- Product designers working on Nostr clients
- Mainstream developers evaluating whether to build on Nostr
Assumed knowledge: Basics of Nostr protocols (relays, events, NIPs)
Patterns were identified through analysis of:
- User feedback and complaints from Nostr clients (GitHub issues, social discussions)
- Usage data and retention metrics (nostr.band)
- Developer discussions on UX challenges
- Industry design systems (Apple HIG, Material Design)
- Available HCI research on social media UX
- Mainstream app practices (TikTok, Instagram, Bluesky, Discord)
Solutions apply established UX principles to Nostr's specific challenges. 100+ sources cited throughout.
Content balance: 70% universal principles (applicable to any social app) + 30% Nostr-specific considerations (relays, keys, decentralization)
View complete approach and references →
Found errors? Have additional research? Implemented these patterns and want to share results?
- GitHub Issues: Report issues or suggest improvements
- Pull Requests: Contributions welcome (see approach and sources)
- Nostr Discussion: Share feedback on Nostr with #NostrUX
- Nostr Design - Design patterns and guidelines for Nostr
- Nostr NIPs - Protocol specifications
- Awesome Nostr - Collection of Nostr projects
This work is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
You are free to:
- Share — copy and redistribute the material in any medium or format
- Adapt — remix, transform, and build upon the material for any purpose, even commercially
Under the following terms:
- Attribution — You must give appropriate credit to Shawn Yeager, provide a link to the license, and indicate if changes were made
Shawn Yeager (@shawnyeager)
Remember: Great UX is the gateway to the protocol's power. Ship working experiences, then add features.