How to Use

Project Context Document: Nearby

Product & Business Context Nearby is a hyperlocal marketplace for buying, selling, and trading within walking distance. It is a neighborhood infrastructure tool, not an e-commerce platform. The business model is density-dependent: value accrues as exchange volume increases per square mile. Revenue comes from optional promoted listings and neighborhood business partnerships, never from transaction fees. The product must reach critical mass within a single neighborhood before expanding geographically; growth is concentric, radiating outward from each activated neighborhood.

Users

• Sellers: People with stuff they want gone: moving, decluttering, upgrading. They want minimal effort: snap a photo, name a price, done. Key context: most have tried Craigslist or Facebook Marketplace and found it too heavy for a $10 lamp. They post in bursts (moving weekend, garage cleanout). Tolerance for friction is near zero; if posting takes more than 60 seconds, they'll just leave it on the curb with a "FREE" sign.
• Buyers: Bargain hunters and convenience seekers. They'd rather walk two blocks than wait two days for shipping. They browse casually and buy impulsively. Key context: discovery is more compelling than search because they don't know what they want until they see it. The walking-distance constraint is the feature. They treat the app like window shopping.
• Organizers: Block captains, community garden coordinators, buy-nothing group admins. They facilitate exchanges that aren't strictly transactional: lending, gifting, sharing. Key context: they are currently managing this work through Facebook Groups, group texts, or paper flyers. Their pain is "I need better tools for what I'm already doing." They are the most likely early evangelists and the hardest to disappoint.

Design Principles

1. Proximity is the product. Everything flows from physical nearness. If it doesn't leverage walking distance, it doesn't belong.
2. Lower the stakes. This isn't a $500 transaction. Most items are under $20. The UX should match that casualness.
3. Trust through transparency. Show the neighborhood. "3 blocks away" builds more trust than "4.8 stars."
4. Respect the asymmetry. Sellers want speed. Buyers want discovery. Don't optimize for one at the expense of the other.

Hard Constraints

• No identity verification at signup: friction kills adoption in small markets
• Must function in neighborhoods with as few as 50 active users
• No delivery infrastructure: walking distance is the delivery method
• Privacy-first; exact addresses never exposed until both parties agree
• Mobile-first: 90%+ of expected usage is on phones, on the move
• No transaction fees: the platform must never stand between neighbors and their money

Ethical Stance

• No engagement tricks. No "3 others are looking at this" urgency. No notification spam. If users open the app less often because they found what they needed quickly, that's success.
• No data harvesting beyond what's needed for core function. Location data is sensitive in a neighborhood context; "where you live" is not a data point to monetize.
• No public shaming. Feedback is private, constructive, and designed to improve behavior, not punish it.
• No dark patterns. If the business model requires manipulating neighbors into transactions, the business model is wrong.

Success Definition Success is exchange density: the number of completed exchanges per 1,000 households per week within a walkable radius. A neighborhood where 20 things change hands every week (some sold, some traded, some given away) is a successful neighborhood. A city with 100,000 users spread across 50 neighborhoods with no density anywhere is a failure.

Design Brief: Nearby

Situation. Peer-to-peer exchange is a $200B+ US activity. Existing tools — Marketplace, Craigslist, Buy Nothing groups — treat geography as a filter, not the organizing principle.

Complication. Sub-block exchange completes at 20–30% on these platforms. The tools aren't absent; they're wrong-shaped for walking-distance trust and logistics.

Resolution. A marketplace whose only feature is proximity. Trust shifts to neighborhood familiarity. Discovery becomes spatial. Logistics collapse to walking. Why now: the hyperlocal shift is accelerating, and the architectural retrofit broad platforms would need takes years.

Discipline note: the first draft sized the complication to fit "compete with Marketplace." Evidence trimmed it to "existing tools are wrong-shaped." Same resolution — but the brief now orients the team to a reality it can verify.

Goals

1. Achieve 15+ completed exchanges per 1,000 households per week in mature neighborhoods
2. Reach 60%+ listing-to-exchange completion rate (2-3x current platform benchmarks)
3. Maintain median time-to-exchange under 48 hours
4. Build neighborhoods where 25%+ of listings are free: generosity is a core feature

Constraints

• Cold start is existential: the product is worthless with zero listings in a neighborhood. Must solve activation before growth.
• Privacy expectations are higher in a neighborhood context than on a general marketplace. "Someone nearby wants your bookshelf" must not become "a stranger knows where you live."
• Revenue model must not depend on transaction volume or engagement optimization.

Guiding Principles

1. Density before breadth: one thriving neighborhood is worth more than 100 empty ones
2. The walking radius is the product: every feature decision flows from it
3. Casual over transactional: the UX should feel like putting a sign in your yard, not listing on eBay
4. Trust is ambient, built from tenure and proximity rather than star ratings

Key Assumptions & Open Questions

• Assumption: Walking distance is a meaningful enough constraint to create a differentiated experience. Risk: In low-density areas, walking distance may be too restrictive to generate sufficient supply.
• Assumption: People will trust neighbors more than strangers from the internet. Risk: Proximity can increase safety concerns, especially for vulnerable populations.
• Open question: What defines a "neighborhood"? Census tract? Zip code? Self-reported? Walking radius from a point? The answer determines the entire product architecture.

Measurable Hypothesis If we constrain a marketplace to walking distance and build trust signals around neighborhood familiarity (tenure, proximity, mutual connections), then exchange completion rates will reach 60%+ (vs. 20-30% on broad platforms), because proximity eliminates logistics friction and neighborhood context reduces trust friction.

Competitive Landscape & Positioning

Proposed Scope (MVP)

• Post an item (photo + price + location radius): under 30 seconds
• Browse items within walking distance (map + list view)
• Express interest (one-tap, no messaging required)
• Neighborhood identity (you see your area, scoped to your surroundings)
• Trust signals: account age, neighborhood tenure, approximate distance
• Explicitly out of scope: Messaging (v2), payments (platform-agnostic), delivery, multi-neighborhood browsing

Research Plan: Understanding Neighborhood Exchange Behavior

Objective Validate three assumptions from the strategic brief: (1) walking distance is a meaningful constraint that creates differentiated exchange behavior, (2) neighborhood familiarity generates more trust than platform-mediated reputation, and (3) the current tools (Facebook Marketplace, Buy Nothing groups, Craigslist) are failing hyperlocal exchange in specific, designable ways.

Method Rationale Semi-structured interviews, not surveys. We're in generative territory and don't yet know what to ask about at scale. Surveys would force premature structure on questions we haven't validated. Interviews let participants tell us things we didn't know to ask about. 45 minutes each, with 5 minutes for warm-up and consent, 35 minutes for core questions, and 5 minutes for open-ended close.

Participant Criteria

• Sellers (n=5): Must have sold or given away 3+ items locally in the past 6 months. Mix of platforms used (Facebook, Craigslist, curb alerts, word of mouth). Exclude professional resellers and business accounts.
• Buyers (n=5): Must have picked up or purchased an item from a local stranger in the past 3 months. Mix of active seekers and casual browsers.
• Community Organizers (n=3): Must currently admin or moderate a Buy Nothing group, neighborhood exchange group, or community swap. Must manage a group of 50+ members.
• Geographic split: 2 neighborhoods, one urban (density >5,000 hh/km²) and one suburban (density 1,000-3,000 hh/km²). This tests whether "walking distance" means fundamentally different things in different contexts.

Recruitment: Buy Nothing group admin outreach, Nextdoor posts, flyers at coffee shops and community boards. $50 gift card incentive. Screen for recency and frequency of local exchange: we want active practitioners, not people who sold one thing on Craigslist in 2019.

Timeline

• Week 1: Recruitment and screening (target 18 recruits for 13 sessions)
• Week 2-3: Conduct interviews (3-4 per day, allow debrief time between sessions)
• Week 4: Synthesis, affinity mapping, findings report

Interview Guide: Sellers

Opening (5 min)

• Introduce purpose: "We're exploring how people in neighborhoods exchange things — sell, give away, trade. We're not testing anything, just learning from your experience. There are no wrong answers."
• Obtain consent for recording. Confirm they can stop at any time.
• Warm-up: "Tell me a bit about your neighborhood. How long have you lived there?"

Core Questions — organized by theme:

Current behavior (10 min)

1. Tell me about the last thing you sold or gave away locally. Walk me through what happened from the moment you decided to get rid of it.
2. How did you decide where to list it? What other options did you consider and why did you reject them?
3. How long did the whole process take, from "I should get rid of this" to "it's gone"?

Friction and failure (10 min)

1. What was the most annoying part of the process?
2. Have you ever decided not to sell or give away something locally, even though you wanted to? What stopped you?
3. Have you ever had a bad experience — someone who ghosted, showed up and the item wasn't what they expected, anything uncomfortable?

Trust and proximity (10 min)

1. Did you know the buyer/recipient beforehand? How did that affect the interaction?
2. How do you feel about strangers knowing approximately where you live? Has that ever made you hesitate?
3. Would knowing someone lives on your block change how you interact with them in an exchange?

Probing techniques:

• Silence — after each answer, wait 5-7 seconds before the next question. Let them fill the space.
• "Walk me through that step by step": when they summarize, push for the sequential details.
• "What made you choose that over...": surfaces decision criteria they may not articulate unprompted.
• Reflecting back: "So it sounds like the hardest part was [X]. Is that right?" Confirms understanding and often triggers correction or elaboration.

Close (5 min)

1. If you could change one thing about how you exchange things with neighbors, what would it be?
2. Is there anything I didn't ask about that feels important?

Interview Guide: Buyers

Opening (5 min) — Same structure as sellers.

Core Questions — organized by theme:

Discovery and motivation (10 min)

1. When was the last time you bought or picked up something from a neighbor? What was it?
2. How did you find out about it? Were you actively looking, or did it just appear?
3. How often do you browse for local items? Is it a habit or occasional?

The exchange experience (10 min)

1. Describe the actual exchange — where did you meet? How did payment work? How did it feel?
2. What made you trust the seller enough to show up?
3. Have you ever been burned — item not as described, uncomfortable interaction, no-show?

Proximity and behavior (10 min)

1. If you could browse everything available within a 10-minute walk right now, would you? How often would you check?
2. Does distance change what you'd be willing to pick up? Would you walk 2 blocks for something you wouldn't drive 10 minutes for?
3. Have you ever walked past a "FREE" sign on someone's curb? What happened?

Close (5 min) — Same structure as sellers.

Interview Guide: Community Organizers

Opening (5 min) — Same structure, plus: "Tell me about the group you run and how you got involved."

Core Questions — organized by theme:

Operations and process (10 min)

1. Walk me through a typical week of managing exchanges in your group. What do you actually do?
2. What breaks? What are the recurring problems you solve over and over?
3. What rules have you had to create that surprised you?

Failure modes and moderation (10 min)

1. How do you handle people who don't follow through — ghost pickups, no-shows, flaky commitments?
2. Have you ever had to remove someone from the group? What happened?
3. What's the worst thing that's happened in your group, and how did you handle it?

Tools and opportunity (10 min)

1. If you could wave a magic wand and fix one thing about how your group works, what would it be?
2. Do you think your community would use a dedicated app, or is "good enough" inside Facebook actually fine?
3. What would a dedicated tool need to do to be worth switching? What's the minimum?

Close (5 min) — Same structure.

Findings Report Format Findings will be organized by theme (not by participant), with evidence strength grading:

• Strong evidence: Pattern appeared in 8+ of 13 interviews with specific examples
• Moderate evidence: Pattern appeared in 4-7 interviews
• Emerging signal: Pattern appeared in 2-3 interviews, worth investigating further
• Single observation: Noted once, may be idiosyncratic

Each finding will include: the insight, supporting quotes (anonymized), evidence strength, and implications for design (routed to the specific skill that should act on it).

Service Blueprint: Item Exchange Flow

The choreography

This blueprint is a performance, not an org chart. Five actors enter and exit at different moments, and the service exists in the coordination between them — not in any single role's path.

• Sarah, the seller. Moving-week panicked. Enters the service when she opens the app to post the couch. Stays present through pickup coordination. Exits when the couch is gone. Her arc is 4–48 hours; the service can't slow her down without losing her.
• Marcus, the buyer. Casual, ambient. Enters by accident — he opens the app while walking home. Stays present briefly: see, decide, walk over, pick up. His arc is 20 minutes to 2 hours. The service can't ask him to commit upfront.
• Diane, the community organizer. Operational, sustained. Always present in the background. Enters reactively when something breaks — a flagged listing, a harassment report, a stale post. Her arc is the lifetime of the neighborhood instance.
• The neighborhood density itself. Not a person, but an actor — the service has no value below a threshold of active users per square mile. Without it, Sarah posts and nobody sees; Marcus opens the app and finds nothing. The choreography depends on density existing as a precondition.
• Future buyers, present in absence. Sarah's first exchange affects the third buyer who hasn't joined yet. Trust and tenure compound across handoffs that haven't happened. Their absence is structural; designing for them means designing the service so the first ten exchanges are visibly trustworthy enough to recruit the eleventh.

The systems below — Notification Service, Trust Inference Engine, Content Moderation, Neighborhood Graph — exist to support this human choreography, not to define it. Where the blueprint started flattening Sarah and Marcus into "the seller" and "the buyer," we re-introduced who they are at each step so the team could feel the coordination across real human moments rather than abstract roles.

Actors (full list): Sarah/Marcus/Diane (named representative humans), the buyer-population, the seller-population, Platform (client + server), Neighborhood Graph Service, Trust Inference Engine, Content Moderation System, Notification Service.

Frontstage — Seller Touchpoints (Sarah's arc)

Frontstage — Buyer Touchpoints (Marcus's arc)

Backstage — Organizational Processes (Diane's arc + system actors)

Neighborhood Graph Service

• Determines walking radius per user based on housing density, street network graph, and physical barriers
• Density tiers: Urban core (>5,000 hh/km²) = 400m radius; Medium density = 800m; Suburban/rural (<1,000 hh/km²) = 1,600m
• Barrier detection: highways, rivers, railways, gated communities treated as hard boundaries. Radius does not cross even if straight-line distance qualifies.
• Updates density classification weekly; barrier data monthly
• Fallback: if street network data unavailable, straight-line distance at 1.3x multiplier

Trust Inference Engine

• No ratings. No star scores. Trust is ambient, built through proximity and tenure.
• Inputs: account age, completed exchanges, neighborhood tenure (how long at current location), mutual contacts (with permission), "as described" feedback rate
• Outputs surfaced to users: "Your neighbor since March 2025" / "12 exchanges in Capitol Hill" / "Also known to [mutual connection]"
• Cold start: new accounts show "New to Nearby" badge for first 4 weeks. Limited to 3 active listings until first completed exchange.

Content Moderation System

• Automated layer: Photo + text classification at post time. Prohibited items (weapons, drugs, regulated goods) flagged and held for review. Duplicate listing detection. Price anomaly flagging during declared emergencies.
• Community layer: Organizers get moderation tools for their neighborhood. Can hide listings, warn users, escalate to platform. First line of defense for ambiguous cases.
• Platform layer: Legal escalation, account suspension, law enforcement coordination. Only engaged when community moderation is insufficient.

Notification Service

• Interest notifications batched every 15 minutes to prevent alert fatigue
• Pickup reminders 1 hour before agreed time
• Daily digest: "What's new on your block," 3-5 items posted in closest radius
• Notification budget: max 5 push notifications per day per user, regardless of activity

Support Processes — Infrastructure

System States & Failure Modes

Decision Documentation

• Why batched notifications instead of real-time? Real-time interest alerts in a marketplace create urgency anxiety. 15-minute batching lets sellers respond thoughtfully. Trade-off: buyer doesn't get instant confirmation. Mitigation: immediate client-side feedback ("Interest sent").
• Why no messaging until mutual interest? Unstructured messaging before commitment invites spam, lowball negotiation, and harassment. Pre-structured quick replies reduce friction and abuse simultaneously. Trade-off: less flexibility. Mitigation: free-text unlocks after 3 successful exchanges between two users.
• Why community organizers as first-line moderators? They already do this work in Facebook Groups and know their neighborhoods. Platform moderation at the neighborhood level would require local context we don't have. Trade-off: moderation quality varies by neighborhood. Mitigation: platform escalation path + organizer guidelines.

The user arcs

Three protagonists shaped these flows. We mapped them as separate arcs rather than one composite — the variance is the design constraint.

Sarah, seller, moving-week. It's Thursday. Parents arrive Saturday. There's a couch, a coffee table, and three lamps that need to be gone — not sold for top dollar, just gone. She's standing in a hallway with bad reception, moving boxes piling up around her, opening her phone in spare moments between packing. Goal: clear the apartment before Saturday. Obstacle: every existing tool wants her to write a description, set up a meet-up, message back and forth. Turning point: the app posts in 30 seconds and her downstairs neighbor messages "I'll come by at 6." Resolution: the couch is gone before dinner; she never had to leave the building.

Marcus, buyer, casual. He's walking home from the train. He opens Nearby out of habit, the way he checks Twitter. He's not shopping for anything. Goal: none, until the app shows him something. Obstacle: discovery has to compete with passive scrolling, not a search query. Turning point: a $15 desk lamp two blocks away, posted twenty minutes ago, picture good enough. Resolution: he taps "interested," walks the long way home, and carries it back.

Diane, organizer, buy-nothing veteran. She runs the neighborhood Facebook group with 800 members. She is drowning in DMs, missing handoffs, and tired of being the only moderator. Goal: keep the gift economy alive without losing her weekends to it. Obstacle: the platform must support generosity as a first-class flow, not just commerce-with-a-free-checkbox. Turning point: she sees the "Free" pickup-prefs flow and recognizes her work in it. Resolution: she moves her group's exchanges into Nearby and recruits two co-organizers within the first month.

These are not personas. The arcs are honest about the variance — Sarah's experience is panicked and time-bounded, Marcus's is ambient and serendipitous, Diane's is operational and sustained. Each flow below was designed against all three; where they diverge, we noted which arc the design optimizes for.

Flow 1: Posting an Item

Primary arc: Sarah's. The flow is optimized for speed under stress.

Entry: Tap "+" from any screen. Camera opens immediately, no intermediate menu.

Decision gates:

• Photo rejected by moderation? → Inline message: "This photo was flagged. Make sure it shows the item clearly and doesn't include prohibited content." User can retake or edit.
• Price anomaly detected? → Soft warning: "This seems higher than similar items nearby. Totally fine, just making sure it's intentional." No blocking.

Error paths:

• Camera permission denied: "Nearby needs camera access to photograph items. You can also choose from your gallery." + Settings link + gallery fallback.
• Photo upload fails: Draft saved locally. "That photo didn't make it. Tap to retry. Your listing is saved." Retry button + offline queue.
• Network lost mid-post: Full draft preserved. "You're offline. Your listing will go live as soon as you're back." Pending indicator on the listing.

Flow metrics: Total taps to post: 4 (photo, confirm title, set price, publish). Target time to post: under 30 seconds for returning users, under 60 for first-time.

Flow 2: Discovering Nearby Items

Primary arc: Marcus's. The flow is optimized for ambient browsing, not intentional search.

Entry: App launch defaults to map view. Deep links from notifications or shares land on item detail.

Screen: Map View (Default Home)

• Map centered on user's location. Items appear as pins with tiny thumbnail previews.
• Radius indicator: subtle circle showing current walking radius, with label: "Showing items within a 10-min walk"
• Radius adjustment: pinch-to-zoom adjusts radius, or tap preset buttons (5 / 10 / 20 min)
• Items beyond current radius shown as faded pins, visible but clearly "further away"
• Neighborhood name in header: "Capitol Hill" / "Your Neighborhood"
• Tap any pin to see item card overlay (photo, title, price, distance). Tap card to open detail.

Screen: List View (Toggle)

• Sorted by distance first, then recency. Shows walking time ("4 min walk"), not miles.
• Each card: thumbnail (64x64), title, price, distance, seller tenure
• Pull-to-refresh. Infinite scroll with distance grouping: "On your block" / "5-min walk" / "10-min walk"

Filters: Category, price range (including Free and Trade), posted today / this week. Filter chips persist across map/list toggle.

Branch: Empty state (no listings nearby)

• "Your neighborhood is quiet right now. Post something and get it started. Someone nearby probably wants it."
• Secondary: "Expand your radius?" with one-tap to 20 min walk.

Branch: Serendipity digest

• Daily push notification: "What's new on your block," 3-5 items posted in closest walking radius.
• Tapping the notification opens a curated card stack, not the full feed.

Flow 3: Expressing Interest & Coordination

Primary arc: Marcus's into Sarah's. The flow has to land lightly for Marcus and clearly for Sarah at the same moment.

Entry: Tap any item card from map, list, or notification.

Error paths:

• Item no longer available when interest sent: "Someone got there first. Here's what else is nearby." + 3 similar items by distance.
• Seller never responds (48h timeout): Interest auto-expires. Buyer: "This one didn't work out. We'll let you know if it re-lists." Seller: "You have an unanswered interest from [Buyer]. Still want to do this?"
• Network failure on interest: Queued locally. "Interest will be sent when you're back online" + pending indicator.

Success criteria: Listing-to-exchange completion >60%. Median messages per exchange <3. Ghost rate (accepted but not completed) <10%.

Flow 4: Messaging (Unlocked After Mutual Interest)

Primary arc: all three. Diane's organizer arc shapes the moderation defaults; Sarah's seller arc shapes the quick-reply set; Marcus's buyer arc shapes the unlock progression.

Interaction spec:

• Messaging is not a general chat feature. It unlocks only after seller accepts a buyer's interest.
• Default: quick replies only. Pre-written options: "On my way" / "I can pick up now" / "Can you hold until tomorrow?" / "Need to reschedule" / "Never mind, sorry"
• Free-text unlocks after 3 successful exchanges between the same two users. Trust is earned through repeated, completed interactions.
• Auto-delete: Messages delete 48 hours after exchange completes. No conversation history to mine.
• Report button on every message. Reported users lose messaging immediately, pending review.
• State: messaging disabled. If either party has been flagged for harassment, messaging reverts to quick replies only with a silent flag to community organizer.

Navigation Specification

Pattern selected: Hub-and-spoke with spatial primary

• Why this pattern: Nearby's tasks are distinct and self-contained (browse, post, coordinate, manage). Hub-and-spoke keeps each mode clean. The spatial twist: the "hub" is a map, with the user's physical location as the organizing principle.
• Trade-off analysis: Hub-and-spoke means users return to the map between tasks. This is intentional; the map reorients them spatially. But it adds one tap when moving between activity and posting. Acceptable because these transitions are infrequent (most sessions are browse-only or post-only, rarely both).
• Rejected alternative: Flat tab bar with no hierarchy (like Instagram). Rejected because Nearby's modes have fundamentally different interaction models: map browsing vs. feed scrolling vs. form entry. Flat tabs would force visual consistency where interaction divergence is needed.

Bottom tab bar: 5 items. Map is leftmost and default. Post (+) is center with elevated visual treatment (FAB-style).

No hamburger menu. Everything lives in the tab bar or within a screen. Nothing is hidden behind a drawer.

Category Taxonomy

Hierarchy rules: Maximum one level deep. No sub-categories. Items belong to exactly one category. If an item could be two categories (a kid's bike), seller chooses; the system doesn't force polyhierarchy on a 10-category taxonomy. Fewer choices, faster posting.

Search & Browse Strategy

Primary discovery mode: spatial browsing (map). This is a deliberate choice. Most Nearby users don't come looking for a specific item; they come to see what's around. The map serves browse behavior; search serves intent behavior. Browsing is primary.

• Search bar: Available but not prominent. Appears on pull-down in feed view (hidden by default). Not visible on map view; map browsing is the intended path.
• Search behavior: Full-text across titles and descriptions. Results always distance-sorted first, relevance second. No pagination; list loads as you scroll.
• Search empty state: "Nothing matching within walking distance. Try a wider radius, or post a Wanted listing and let it come to you."
• Search analytics: Track what people search for in neighborhoods with no results. This is demand signal for cold-start seeding.

Browse enhancements:

• Filter chips on feed view: category, price range (including Free), posted today / this week. Chips persist across map/list toggle.
• "What's new on your block" daily digest: 3-5 items posted within closest radius. Push notification links to curated card stack.
• Distance grouping in list view: "On your block" / "5-min walk" / "10-min walk," giving spatial structure to a flat list.

Wayfinding Design

Users must always know three things: where they are, what they're seeing, and how to see more.

• Where they are: Neighborhood name in header ("Capitol Hill"). Map centered on their location with subtle location dot.
• What they're seeing: Radius label always visible: "Showing items within a 10-min walk." Item count: "23 items nearby."
• How to see more: Radius adjustment via pinch-to-zoom on map, or tap presets (5 / 10 / 20 min). Items beyond current radius shown as faded pins, visible but clearly "further away," inviting expansion without cluttering the primary view.
• Orientation cue on return: When opening the app after >24 hours, brief overlay: "3 new items since you last checked" with a tap to see them.

Voice Framework: Nearby

Product Voice Attributes

Voice Principles

1. Neighborly. The app is a bulletin board. It speaks like a friendly neighbor.
2. Casual but precise. Friendly tone with clear information. Contractions are fine. Emoji are absent; warmth comes from words.
3. Local. Use neighborhood names whenever available. "New in Capitol Hill" over "New near you." The specificity builds belonging.
4. Brief. Nobody reads instructions in a marketplace app. Say it in one sentence. If you need two, the first one better be worth it.
5. Honest about limitations. Don't pretend the app can do things it can't. "We need your location. That's kind of the whole point" is better than a generic permissions dialog.

Copy Deck: Key Screens

Onboarding (first launch)

• Screen 1: "Nearby shows you what's for sale, for free, or for trade within walking distance of where you live."
• Screen 2: "No star ratings. No shipping. Just neighbors exchanging things."
• Screen 3: "We need your location to show what's nearby." [Allow location] / [Not now: "Without location, Nearby can't show you anything. You can enable it later in Settings."]

Posting flow

• Camera screen: No copy needed. Camera speaks for itself.
• AI title suggestion: "Looks right?" [pre-filled title]
• Price input placeholder: "Name your price, or tap Free"
• Pickup options header: "How should they pick it up?"
• Preview header: "This is what your neighbors will see"
• Publish confirmation: "Live in your neighborhood."

Browse / discovery

• Map header: "[Neighborhood Name]" + "23 items nearby"
• Radius label: "Showing items within a 10-min walk"
• Daily digest notification: "What's new on your block. 4 items posted today"

Empty State Copy

Error Message Design

Each error message has three components: what happened, why it matters, and what to do.

Trust Signal Copy

These replace traditional reputation systems. No stars, no scores, no public reviews.

• Neighborhood tenure: "Your neighbor since March 2025." Displayed on profile cards and item detail. Communicates stability without surveillance.
• Proximity: "Lives about a 3-minute walk from you." Distance without address. Precision: round to nearest minute. Never show exact distance under 1 minute ("nearby" instead).
• Exchange history: "12 exchanges in Capitol Hill." Activity as a count, no rating attached.
• Mutual connection: "Also known to Sarah M." Shown only when mutual contact exists, with both parties' permission. The strongest trust signal available.
• New user: "New to Nearby." Honest badge for accounts under 4 weeks. Transparency builds trust faster than hiding newness.

Microcopy Pattern Library

UX Health Score: 68 / 100 Strong conceptual foundation and information design. Significant gaps in error prevention, onboarding, accessibility, and cold-start resilience. The design is promising but not shippable: the happy path is well-designed, but the other 40% of real-world usage is underspecified.

Anti-Pattern Verdict: Clean No manipulative patterns detected. No false urgency, no dark patterns in the interest flow, no engagement tricks. The design respects user autonomy. One watch item: the daily digest notification could drift toward engagement optimization if not carefully managed. Flag for ongoing review.

Heuristic Evaluation (H1–H10)

Cognitive Walkthrough: "Post Your First Item"

Walkthrough finding: Step 6 needs stronger publish confirmation. The current "Live in your neighborhood" text is easily missed. Recommend: full-screen confirmation with the listing card, a share prompt, and a clear "what happens next" explanation for first-time posters.

Priority Issues

State Inventory Matrix: Item Card Component

Every state the item card can be in, across the full lifecycle: every messy in-between state that real usage produces.

State Inventory Matrix: Posting Flow

Error Recovery Design

Principle: Every error message answers three questions: what happened, why it matters, and what to do next. No generic "Something went wrong." No error codes. No blame.

First-Run Experience Design

The current design drops new users onto an empty map with no guidance. This is a P0 issue from /evaluate. Here's the fix:

Progressive onboarding (3 screens, then value):

1. "Nearby shows you what's for sale, for free, or for trade within walking distance." (Map illustration)
2. "No star ratings. No shipping. Just neighbors exchanging things." (Trust signal illustration)
3. Location permission request with honest framing: "We need your location to show what's nearby. That's the whole point."

Then immediately: Show the map. If items exist nearby, highlight the 3 closest. If no items exist (cold start), show the seeded content or jump to:

Cold start first-run (empty neighborhood):

• "You're early, and that matters. The first neighbors to join set the tone."
• "Post your first item and we'll feature it at the top of your neighbors' feeds for 24 hours."
• Contact import: "See if anyone you know is already on Nearby." (Optional, not required)
• Fallback: Show items from the nearest active neighborhood with transparency: "Nothing in [your neighborhood] yet. Here's what's happening in [nearby neighborhood], 15 min away."

Stress Test Results

Edge Case Catalog

1. Seller Ghosts After Accepting

• Trigger: Seller accepts buyer's interest but doesn't show up or respond to coordination messages.
• Design: If seller doesn't confirm exchange within 2 hours of agreed time, item auto-relists. Buyer gets "This one fell through. We've re-opened it so others can claim it." Seller gets gentle nudge: "Heads up, [Buyer] came by and you weren't available. Want to reschedule or pass it to someone else?"
• Escalation: 3 ghost events in 30 days triggers "Slow mode." Seller's future listings require explicit availability confirmation before going live.

2. Item Misrepresentation

• Trigger: Buyer picks up item and it doesn't match the listing description or photos.
• Design: Post-exchange feedback is optional and binary: "As described" or "Not as described." No public reviews. No star ratings. Three "Not as described" flags in 30 days surface a private prompt to seller: "A few neighbors felt items didn't match descriptions. Adding detailed photos helps build trust."
• No public shaming. This is a neighborhood. Escalation is private and constructive.

3. Cold Start — New Neighborhood

• Trigger: User signs up in a neighborhood with zero active users and zero listings.
• Design: Three-layer seed strategy:
• Personal: Contact import to surface existing Nearby users. "3 of your neighbors are already here."
• Content: Partnership with local Buy Nothing groups to import existing listings (with admin permission and attribution).
• Incentive: "Post your first item and we'll feature it at the top of your neighbors' feeds for 24 hours."
• Fallback: Show items from nearest active neighborhood with distance transparency.

4. Harassment via Messaging

• Trigger: User sends inappropriate content through the messaging system.
• Design: Structurally prevented for most interactions: quick replies only until 3 successful mutual exchanges. Free-text is a privilege earned through trust. Report button on every message. Reported users lose messaging immediately pending review; no appeals process delays the protection.

5. Price Gouging During Emergencies

• Trigger: Declared emergency (power outage, weather event) + item listed at significantly above historical average.
• Design: Price anomaly detection compares to 90-day rolling average for category. Flagged items get visible notice to buyers: "This price is higher than usual for this item." No automatic blocking, but full transparency. Community organizers can escalate.

6. Duplicate Accounts / Sybil Attacks

• Trigger: Bad actor creates multiple accounts to manipulate listings or evade moderation.
• Design: One account per phone number. Neighborhood assignment based on consistent geolocation over 7 days rather than self-reported address. Multiple accounts from same device flagged for review.

7. Abandoned Listings

• Trigger: Item posted but seller becomes inactive.
• Design: Listings expire after 14 days. Seller gets "Still available?" prompt at day 12. No response = auto-archive. Re-posting takes one tap from the archive screen. Expired listings don't count against exchange completion metrics.

Accessibility Audit: Nearby

Screen Reader Experience Design

The map-first interface is fundamentally inaccessible as a primary experience for screen reader users. This is an architectural decision to revisit, not a bug to patch. The list view must be promoted from "toggle alternative" to "equal citizen." When VoiceOver or TalkBack is active, the app should default to list view.

Item card announcement order: `[Item name], [price or "Free"], [walking time] away, posted by [neighbor name], [neighborhood tenure]. [Pickup type].`

Example: "Blue IKEA bookshelf, free, 4 minutes away, posted by Jake, your neighbor since March 2025. Porch pickup."

Screen-by-screen screen reader spec:

Critical requirement: The undo toast ("Interest sent. Undo") must be announced via aria-live and the undo button must be keyboard-focusable for its full 5-second duration. A timed action that screen reader users can't reach is an inaccessible pattern, not a real undo.

Keyboard Navigation Specification

Focus management rules:

• Focus is never lost. When a modal closes, focus returns to the element that opened it. When an item is removed from a list, focus moves to the next item.
• No focus trap outside of modals. Users can always Tab out of any non-modal component.
• Focus indicators are visible in both light and dark mode (3:1 contrast minimum, 2px solid outline).

Cognitive Accessibility

Language simplification:

• All interface copy at 6th-grade reading level or below. Tested via Hemingway Editor.
• No jargon: "listing" becomes "item," "express interest" becomes "I want this," "transaction" never appears.
• Instructions use active voice and short sentences: "Tap the photo to retake it." Over "The photo can be retaken by tapping on it."

Predictable layout:

• Tab bar never moves, never reorders, never hides.
• Map/list toggle is always in the same position (top-right of map view).
• No layout shifts after content loads. Skeleton screens match final layout dimensions exactly.
• Back navigation always returns to the previous screen in the expected state: no re-scrolling, no lost context.

Reduced decision load:

• Maximum 10 categories. No sub-categories. Fewer choices, faster decisions.
• Posting flow: 5 steps maximum. Each step has one primary decision.
• Interest expression: one tap. No message required. The social friction of "what do I say?" is eliminated by design.

Explicit feedback for every action:

• "Posted." "Interest sent." "Exchange complete." No ambiguity.
• No silent state changes. If something happened, the user knows.

No time pressure. Anywhere.

• No countdown timers (the 5-second undo is the one exception, and it's not destructive if missed).
• No "3 others are interested" urgency messaging. Ever. This is a design principle.
• Batched notifications ensure sellers don't feel rushed to respond.

Motor Accessibility

Location-Specific Accessibility Concerns

• Physical mobility: Users who cannot walk to pickups can set "Delivery welcome" flag on their profile. Visible to sellers as: "This neighbor has requested delivery. Can you bring it to them?" Optional for sellers, never required.
• Spatial cognition: Distance shown in both time and distance: "4 min walk (0.2 mi)," serving users who process spatial information differently. On map view, distance is also represented visually by the radius circle.
• Low vision and map readability: Map pins use high-contrast colors with luminance differentiation, not just hue. Price labels on pins use minimum 14px text. "Free" items use a distinct pin shape to be distinguishable without color perception.

Platform Strategy: Nearby

Mobile (Primary Platform)

Mobile is the product. Nearby is designed for someone walking through their neighborhood, phone in hand, glancing at what's around them. The interaction model is built for this context:

• Camera-first posting: Tap "+", camera opens instantly. No menu, no screen selection, no "what kind of post?" The phone's camera is the listing creation tool; everything else (title, price, category) is supporting metadata.
• GPS-powered map: The primary interface leverages the one thing phones do that laptops can't: know where you are in real time. Map pins update as you walk.
• Push notifications: Interest alerts, pickup reminders, daily digest. Notification budget: max 5/day. Batch interest notifications every 15 minutes to prevent alert fatigue.
• Thumb-zone optimization: "I want this" button bottom-aligned on item detail. Post FAB center of tab bar. All primary actions reachable one-handed. No interactions require top-of-screen reach.
• Deep links: "Check out this bookshelf near you" from iMessage/WhatsApp opens directly to item detail. If recipient doesn't have the app, opens web preview with app store link.

What mobile doesn't do well: Long-form descriptions (keyboard is awkward), batch operations (posting 15 items one by one is painful), account management (settings are fine on desktop).

Web (Secondary Platform)

The web experience is a complement. Feature parity is explicitly not a goal. The web version exists for three use cases that mobile handles poorly:

1. Batch posting: Upload 10 photos from a desktop folder, write descriptions with a full keyboard. Drag-and-drop photo upload. Multi-item posting flow with "Post another" shortcut.
2. Larger map canvas: Show more of the neighborhood at once. Hover previews on pins (vs. tap on mobile). Zoom controls + keyboard shortcuts for power browsing.
3. Account management: Settings, notification preferences, privacy controls, exchange history. These are configure-once tasks better served by a larger screen.

Web-specific features:

• Print-friendly view for community boards: "Post this QR code at your coffee shop" generates a branded flyer with QR link to the neighborhood's Nearby page.
• Embeddable widget for neighborhood websites and HOA pages: live feed of recent listings in a specific radius.

What web doesn't do: Push notifications (email digest only). Camera-first posting (file upload instead). Real-time location (address-based, not GPS).

Offline Design Patterns

Nearby must work on sidewalks, in basements, and on subway platforms. "No signal" is a Tuesday, not an error state.

Offline design principle: Never lose user work. Never silently fail. Always show what's happening and what will happen when connectivity returns. The user should trust that their actions are preserved, even without signal.

Cross-Device Continuity

Cross-device anti-pattern avoided: No "continue where you left off" interstitials. The state just syncs. If you open the laptop and the app shows your neighborhood, you don't need a modal telling you it synced. Seamless is the point.

Cultural Adaptation Matrix: Nearby

Trust Signals by Market

Trust is not universal. What builds trust between strangers in Portland, Oregon destroys it in Osaka, Japan. The entire trust model must be locally reconceived, not merely translated.

Payment Patterns

Nearby is platform-agnostic on payment by design. The platform does not process, mediate, or record payments. "Arrange with seller" is the universal default. But payment norms shape the entire exchange experience, and the UI must accommodate them:

RTL Support & Layout Mirroring

Full layout mirroring for Arabic, Hebrew, and Urdu. The entire spatial model flips, not just text direction:

• Navigation: tab bar order reverses (Map on right, Profile on left)
• Map controls: zoom buttons move to left side. Radius presets read right-to-left.
• Item cards: thumbnail moves to right, text aligns right
• Posting flow: step indicator reads right-to-left. "Next" button on left, "Back" on right.
• Swipe gestures: swipe-to-interest reverses direction (swipe left instead of right)
• Numbers: Western Arabic numerals (0-9) for prices in all markets. Eastern Arabic numerals (٠-٩) available as user preference for display.

Text expansion budget:

• German: 30-40% longer than English. "I want this" becomes "Interesse bekunden" (18 to 20 chars, manageable). But "Your neighbor since March 2025" becomes "Ihr Nachbar seit März 2025" or "Dein Nachbar seit..." (formal vs. informal address decision required per market).
• Japanese: Generally shorter in character count but may require different line-height for readability.
• Button labels: designed with 40% expansion headroom. Max English label length: 20 characters; max translated: 28 characters before truncation.

Content & Communication Adaptation

Regulatory Compliance by Market

Measurement Framework: Nearby

North Star Metric

Weekly Exchange Density: Completed exchanges per 1,000 households per week, measured per neighborhood.

• Formula: (Completed exchanges in neighborhood N in week W) / (Estimated households in neighborhood N / 1,000)
• Target: 15+ exchanges/1k households/week in neighborhoods active for 3+ months
• Data source: Server-side exchange completion events, census household estimates per defined neighborhood boundary
• Measurement frequency: Weekly, with 4-week rolling average for trend
• Why this metric: It captures the only thing that matters: are neighbors actually exchanging things? Unlike MAU (which rewards browsing without action), GMV (which values expensive items over community health), or listing count (which rewards posting without outcomes), exchange density measures completed value delivery.

Primary Metrics

Goal-Signal-Metric chains:

1. Goal: Neighbors can quickly find useful items nearby.

Signal: Users browse and express interest within a single session. Metric: Browse-to-interest rate >15% per session; median time from app open to first interest expression <3 minutes.

1. Goal: Posting an item is effortless.

Signal: Users who start posting complete it. Metric: Post-start-to-publish completion rate >85%; median time to post <45 seconds for returning users.

1. Goal: Exchanges actually happen after interest is expressed.

Signal: Accepted interests convert to completed exchanges. Metric: Interest-to-completion rate >70%; ghost rate <10%.

Secondary Metrics: Trust & Community Health

Counter-Metrics (What We Refuse to Optimize)

These are guardrails. If a primary metric improves while a counter-metric degrades, something is wrong. Counter-metrics are reviewed alongside primary metrics in every measurement review. They are not optional.

Experimentation Plan

Experiment governance: No experiment ships without a pre-registered hypothesis, primary metric, counter-metric, and minimum sample size. Results are reviewed by product and design together: "did it go up for the right reasons?" matters as much as "did the number go up?"

Component Spec: Item Card

Variants: Feed card (compact), Detail card (expanded), Map pin (minimal)

Feed Card (Compact)

State definitions:

Detail Card (Expanded)

Map Pin (Minimal)

Interaction Spec: Express Interest

Algorithm Spec: Walking Radius

Purpose: Determine which items are "within walking distance" for a given user. This is the core product differentiator; the algorithm defines Nearby's fundamental unit of experience.

Inputs:

• User latitude/longitude (from device GPS or last-known location)
• Neighborhood density: households per km² (from census data, updated quarterly)
• Street network graph (from OpenStreetMap, updated monthly)
• Physical barriers: highways, rivers, railways, gated communities (from OSM + manual annotation)

Algorithm:

1. Classify density tier:

• High density (>5,000 hh/km²): base radius = 400m (urban core, ~5 min walk)
• Medium density (1,000–5,000 hh/km²): base radius = 800m (~10 min walk)
• Low density (<1,000 hh/km²): base radius = 1,600m (~20 min walk)

1. Apply barrier masking: remove all area beyond physical barriers, even if within straight-line radius. Walking radius follows the street graph.

1. Calculate isochrone: using the street network graph, compute the reachable area within the base walking time (5/10/20 min at 5 km/h average walking speed). This produces an irregular polygon, not a circle.

1. Return: polygon boundary for map rendering + list of item IDs within the polygon.

Fallback logic:

• If street network graph unavailable: use straight-line distance at 1.3x multiplier (empirical correction for non-straight walking paths). Circle rather than isochrone.
• If density data unavailable: default to medium density (800m / 10 min).
• If GPS unavailable: use last-known location. Badge: "Showing items near your last known location."

Performance requirements:

• Radius calculation: <50ms for cached location, <200ms for new location requiring graph query
• Cache: per-user, keyed on location. Invalidate on 200m movement from cached position.
• Density classification: cached per neighborhood, updated weekly
• Barrier data: cached globally, updated monthly

API contract:

``` GET /v1/radius Request: { lat: number, lng: number } Response: { polygon: GeoJSON, radiusMeters: number, densityTier: "high" | "medium" | "low", walkingMinutes: number, itemCount: number, isFallback: boolean } Latency: p50 <50ms, p99 <200ms ```

Update frequency: Density classification updates weekly. Barrier data updates monthly. User radius recalculates on every significant location change (200m movement).