Skip to content

Add README screenshots and demo #108

@jasoneplumb

Description

@jasoneplumb

Parent Epic

#104

Problem

The README has zero visual content. For a mapping app with polished mobile UX, this is a major missed opportunity. Visitors can't see what the app looks like without visiting the live site.

Current State

README is text-only. No screenshots, no GIFs, no diagrams.

Desired State

Add a visual section near the top of the README (after badges, before Features list) showing:

  1. Hero screenshot — the main map view with controls visible (mobile viewport)
  2. Feature gallery (optional) — 2-3 smaller screenshots showing:
    • Trail recording with stats bar visible
    • Search results in the bottom sheet
    • Offline download panel with selection rectangle

Recommended Approach

Option A — Static screenshots (simplest):

  • Take screenshots from a real device or Chrome DevTools mobile emulation
  • Save as optimized PNGs in a docs/images/ directory
  • Reference in README with ![description](docs/images/filename.png)
  • Use a table or flex layout for side-by-side mobile screenshots

Option B — Animated GIF/video (higher impact):

  • Record a ~15-second screen capture showing: open app → locate → start recording → pan map → stop
  • Convert to GIF or use GitHub's video embed (<video> tag in markdown)
  • Keep file size under 5MB

Image Guidelines

  • Mobile viewport (375×812 or similar) — this is a mobile-first app
  • Crop browser chrome out if using DevTools
  • Use a recognizable map location (not middle of the ocean)
  • Show the blue dot and at least one control label visible

Suggested Prompt

I need screenshots for the webmap.dev README. The app is live at 
https://www.webmap.dev. I can't take screenshots programmatically, 
but help me set up the README structure:

1. Create a docs/images/ directory
2. Add a "Preview" section to README.md after the badges and before 
   the Features heading. Use this structure:

   ## Preview

   <!-- TODO: Replace with actual screenshots -->
   <!-- Recommended: mobile viewport (375×812), crop browser chrome -->
   <!-- Save as optimized PNGs in docs/images/ -->

   | Map View | Trail Recording | Search |
   |----------|----------------|--------|
   | ![Map](docs/images/map-view.png) | ![Recording](docs/images/recording.png) | ![Search](docs/images/search.png) |

3. Add a .gitkeep to docs/images/ so the directory is tracked

Commit and push. I'll add the actual screenshot files manually.

Acceptance Criteria

  • README has a Preview/Screenshots section with image placeholders or real images
  • docs/images/ directory exists and is tracked
  • Images are optimized (< 500KB each) if real screenshots are added
  • Mobile viewport used (this is a mobile-first app)

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1Critical — fix immediatelydocumentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions