Merge pull request #54 from TaskarCenterAtUW/feat/docs-accessmap/3072-add-accessmap-um

Add AccessMap User Manual

Author: uw-amy-bordenave

.github/copilot-instructions.md

@@ -135,6 +135,38 @@ cd util
 
 **Why**: Navigation structure and guide indices aren't hand-maintained. These scripts parse `/docs` structure, extract frontmatter titles, and generate the Markdown files accordingly. Generation of the nav section of `zensical.toml` is done afterwards to ensure all files are included.
 
+### Process Screenshots
+
+The `process-screenshot.py` utility generates themed light/dark variants of screenshots with borders and drop shadows, saved as maximally-compressed lossless PNGs:
+
+```powershell
+# Ensure venv is activated first!
+..\.venv\Scripts\Activate.ps1
+
+# Process a single screenshot
+python .\util\process-screenshot.py docs\resources\images\example\screenshot.png
+
+# Process all images in a directory (optionally --recurse for subdirs)
+python .\util\process-screenshot.py docs\resources\images\example\
+
+# Apply a named custom profile
+python .\util\process-screenshot.py screenshot.png --profile uw-purple
+
+# Regenerate existing output files
+python .\util\process-screenshot.py screenshot.png --overwrite
+```
+
+**Output**: For each input `image.png`, produces `image-light.png` (dark border + shadow for light pages) and `image-dark.png` (light border + glow for dark pages). Mode-tagged sources (e.g., `image.light.png`) produce only the matching variant.
+
+**Markdown usage**:
+
+```markdown
+![Alt text](path/to/image-light.png#only-light)
+![Alt text](path/to/image-dark.png#only-dark)
+```
+
+Run with `--help` for all options including per-variant color, shadow, and blur overrides.
+
 ### Validate Links
 
 ```powershell
@@ -345,5 +377,6 @@ Refer to the official Zensical documentation, which is hosted online at https://
 - `util/generate-nav.Tests.ps1`: Pester tests for nav generator
 - `util/check-links.ps1`: PowerShell validation of links (not standard CI integration)
 - `util/check-links.Tests.ps1`: Pester tests for link checker
+- `util/process-screenshot.py`: Generates themed light/dark screenshot variants with borders, shadows, and maximum lossless PNG compression
 - `/includes/abbreviations.md`: Global acronym definitions
 - `/resources/stylesheets/extra.css`: Theming

.github/instructions/main.instructions.md

@@ -0,0 +1,8 @@
+---
+description: Project-wide instructions for the TCAT Wiki workspace
+applyTo: "**"
+---
+
+<!-- @format -->
+
+IMPORTANT: This project uses a Python virtual environment (`.venv/`). ALWAYS run `.\.venv\Scripts\Activate.ps1` before ANY terminal command (zensical, pip, python, utility scripts, etc.). Never assume the venv is already activated.

CONTRIBUTING.md

@@ -192,25 +192,53 @@ For creating screenshots with a consistent style, Firefox DevTools is to be used
 
 3. Add custom device profiles:
     1. Name: `[Screenshot] Web - Portrait`
-        1. Size: `671`x`1196`
+        1. Size: `810`x`1440`
 
         2. Device Pixel Ratio: `1`
 
         3. User Agent String: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0`
 
     2. Name: `[Screenshot] Web - Landscape`
-        1. Size: `1196`x`671`
+        1. Size: `1440`x`810`
 
         2. Device Pixel Ratio: `1`
 
         3. User Agent String: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0`
 
-4. Resulting screenshots will fit exactly within the 2px outside border present in the following screenshot templates:
-    1. [Landscape (Desktop) - templates/images/screenshots/landscape-desktop.png](https://github.com/TaskarCenterAtUW/tcat-wiki/blob/main/templates/images/screenshots/landscape-desktop.png)
+4. It is recommended to remove all embedded metadata, such as with the use of [ExifToolGUI](https://exiftool.org/gui/).
 
-    2. [Portrait (Desktop) - templates/images/screenshots/portrait-desktop.png](https://github.com/TaskarCenterAtUW/tcat-wiki/blob/main/templates/images/screenshots/portrait-desktop.png)
+5. Process screenshots with the `process-screenshot.py` utility to generate themed light/dark variants with borders and drop shadows:
 
-5. It is recommended to remove all embedded metadata, such as with the use of [ExifToolGUI](https://exiftool.org/gui/).
+    ```powershell
+    # Ensure venv is activated first!
+    ..\.venv\Scripts\Activate.ps1
+
+    # Process a single screenshot
+    python .\util\process-screenshot.py docs\resources\images\example\screenshot.png
+
+    # Process all images in a directory
+    python .\util\process-screenshot.py docs\resources\images\example\
+
+    # Process recursively with a custom profile
+    python .\util\process-screenshot.py docs\resources\images\ --recurse --profile uw-purple
+
+    # Regenerate existing output files
+    python .\util\process-screenshot.py screenshot.png --overwrite
+    ```
+
+    The script produces two variants per input image, saved as maximally-compressed lossless PNGs:
+
+    - `{name}-light.png` — dark border + drop shadow for light theme pages
+    - `{name}-dark.png` — light border + glow for dark theme pages
+
+    Reference them in Markdown with Zensical's theme-switching fragments:
+
+    ```markdown
+    ![Alt text](path/to/image-light.png#only-light)
+    ![Alt text](path/to/image-dark.png#only-dark)
+    ```
+
+    Mode-tagged source files (e.g., `image.light.png`, `image.dark.png`) generate only the matching variant. Run with `--help` for all options including per-variant color/shadow overrides.
 
 ##### Image Annotations
 

docs/accessmap/index.md

@@ -6,7 +6,10 @@ title: AccessMap
 
 ## AccessMap
 
-AccessMap ([https://accessmap.app](https://accessmap.app)) provides detailed information in select cities on pedestrian paths, transit stations, elevation changes, curb ramps, and more to enable accessibility-focused multimodal routing.
+AccessMap ([accessmap.app](https://accessmap.app)) is a web app that provides detailed information in select cities on pedestrian paths, transit stations, elevation changes, curb ramps, and more to enable accessibility-focused multimodal routing.
+
+![AccessMap](../resources/images/accessmap/accessmap-light.png#only-light)
+![AccessMap](../resources/images/accessmap/accessmap-dark.png#only-dark)
 
 ---
 
@@ -18,4 +21,4 @@ _For a list of all guides on the TCAT Wiki, refer to the [Guides List](../guides
 
 #### [AccessMap User Manual](user-manual/index.md)
 
-This user manual explains how to use the AccessMap application.
+This user manual explains how to use the AccessMap web application.

docs/accessmap/user-manual/feedback.md

@@ -0,0 +1,89 @@
+---
+title: Leaving Feedback
+nav_order: 7
+tags:
+    - Guide
+    - External
+    - User
+# exclude-from-main-guides-list
+---
+
+<!-- @format -->
+
+## Leaving Feedback
+
+This section explains how to leave comments on map features to report observations and help improve the data.
+
+_For a list of all guides on the TCAT Wiki, refer to the [Guides List](../../guides-list/index.md)._
+
+---
+
+### Overview
+
+AccessMap allows you to **share feedback** about routing directions and about specific features in and around the pedestrian network, such as sidewalks, crossings, curb ramps, or landmarks.
+
+Feedback helps TCAT and community contributors identify issues in the underlying pedestrian data and prioritize improvements.
+
+---
+
+### Feature Feedback
+
+To report an issue with a specific map feature (such as a sidewalk, crossing, or curb ramp), tap or click on or near the feature to open a [details popup](interface.md#inspecting-a-feature), then select **Share Feedback**. This opens the **Share feedback about this feature** form.
+
+Select one or more issue types by checking the relevant boxes:
+
+| Checkbox                                  | Use When                                                        |
+|:------------------------------------------|:----------------------------------------------------------------|
+| **The feature is located somewhere else** | The feature exists but is mapped in the wrong location          |
+| **Inaccurate information**                | An attribute is incorrect (e.g., wrong surface type or incline) |
+| **Add something that's missing**          | A real-world feature is not represented in the data             |
+
+Optionally, add details in the **Comments** text field, then select **Submit** to send your feedback (or **Cancel** to dismiss).
+
+![Share feedback about this feature form](../../resources/images/accessmap/user-manual/feedback/feature-popup-light.png#only-light)
+![Share feedback about this feature form](../../resources/images/accessmap/user-manual/feedback/feature-popup-dark.png#only-dark)
+
+---
+
+### Step Feedback
+
+To report an issue with a specific segment of a planned route, open the [Directions panel](navigation.md#directions-panel) and select the **Share Feedback** link on any direction card. This opens the **Share feedback about this step** form.
+
+Select one or more issue types by checking the relevant boxes:
+
+| Checkbox                                | Use When                                                         |
+|:----------------------------------------|:-----------------------------------------------------------------|
+| **Inaccurate GPS**                      | Your GPS position does not align with the route shown on the map |
+| **This part of the path is inaccurate** | The described path segment does not match real-world conditions  |
+| **Add something that's missing**        | Relevant information about the step is absent                    |
+
+Optionally, add details in the **Comments** text field, then select **Submit** to send your feedback (or **Cancel** to dismiss).
+
+![Share feedback about this step form](../../resources/images/accessmap/user-manual/feedback/route-popup-light.png#only-light)
+![Share feedback about this step form](../../resources/images/accessmap/user-manual/feedback/route-popup-dark.png#only-dark)
+
+!!! tip "Writing Effective Comments"
+
+    Be concise and specific. Good examples:
+
+    - _"This crossing does not have markings"_
+    - _"Surface is gravel, not concrete"_
+    - _"There is a newly installed curb ramp at this corner"_
+    - _"There is not a bench here"_
+    - _"The path here is blocked by a tree"_
+
+---
+
+### What Happens to Your Feedback
+
+Comments submitted through AccessMap are collected by TCAT and used to assess data quality and guide future data corrections.
+
+---
+
+!!! success "Thank you for using AccessMap!"
+
+---
+
+Previous: [Navigation](navigation.md)
+
+Return: [AccessMap User Manual](index.md)

docs/accessmap/user-manual/getting-started.md

@@ -0,0 +1,66 @@
+---
+title: Getting Started
+nav_order: 2
+tags:
+    - Guide
+    - External
+    - User
+# exclude-from-main-guides-list
+---
+
+<!-- @format -->
+
+## Getting Started
+
+This section explains how to access AccessMap, select a region, and take the built-in tour.
+
+_For a list of all guides on the TCAT Wiki, refer to the [Guides List](../../guides-list/index.md)._
+
+---
+
+### Accessing AccessMap
+
+AccessMap is a web application, so **no download or installation is required**. It runs directly in your browser on any device, including phone, tablet, or desktop.
+
+1. Open your preferred web browser (e.g., Chrome, Firefox, Safari, Edge)
+
+2. Navigate to [AccessMap.app](https://accessmap.app)
+
+![AccessMap landing page](../../resources/images/accessmap/user-manual/getting-started/landing-light.png#only-light)
+![AccessMap landing page](../../resources/images/accessmap/user-manual/getting-started/landing-dark.png#only-dark)
+
+---
+
+### Selecting a Region
+
+AccessMap is available in a number of regions across Washington State and beyond. When you first open AccessMap, the map will be centered on the default region. To switch to a different region:
+
+1. Select the **region name** displayed in a box at the top of the left sidebar (e.g., "Seattle, WA")
+
+2. A **Regions** dialog will appear with a filterable list of all available regions
+
+3. Scroll through or type in the **filter** field to narrow the list
+
+4. Select the region you want to explore
+
+![Regions dialog with filter](../../resources/images/accessmap/user-manual/getting-started/region-light.png#only-light)
+![Regions dialog with filter](../../resources/images/accessmap/user-manual/getting-started/region-dark.png#only-dark)
+
+!!! info "Coverage"
+
+    AccessMap coverage depends on available pedestrian network data. Coverage outside Washington State varies by region and depends on local data availability.
+
+---
+
+### Taking the Tour
+
+If you are new to AccessMap, select the **Take a tour** button (top right of the map) for a quick guided walkthrough of the interface. The tour opens a series of popups that highlight key features and provide an introduction to planning your first route.
+
+![Tour popup](../../resources/images/accessmap/user-manual/getting-started/tour-light.png#only-light)
+![Tour popup](../../resources/images/accessmap/user-manual/getting-started/tour-dark.png#only-dark)
+
+---
+
+Previous: [AccessMap User Manual](index.md)
+
+Next: [Interface Overview](interface.md)

docs/accessmap/user-manual/index.md

@@ -1,5 +1,6 @@
 ---
 title: AccessMap User Manual
+nav_order: 1
 tags:
     - User Manual
     - External
@@ -10,10 +11,67 @@ tags:
 
 ## AccessMap User Manual
 
-This user manual explains how to use the AccessMap application.
+This user manual explains how to use the AccessMap web application.
 
 _For a list of all guides on the TCAT Wiki, refer to the [Guides List](../../guides-list/index.md)._
 
 ---
 
-_Coming soon!_
+### About AccessMap
+
+[AccessMap](https://accessmap.app) is a free, web-based pedestrian trip planner developed by the Taskar Center for Accessible Technology (TCAT) at the University of Washington. Unlike general-purpose navigation apps, AccessMap is designed to support the full diversity of how pedestrians travel — accounting for mobility aids, vision, and physical ability — and to give users meaningful control over their route.
+
+AccessMap provides:
+
+- **Pedestrian-specific routing** — routes on sidewalks, crossings, and footways rather than roadways
+- **Elevation awareness** — color-coded visualization of incline grades along paths
+- **Barrier and curb ramp information** — identification and optional avoidance of raised curbs and stairs
+- **Customizable mobility profiles** — tailored routing for manual wheelchair users, powered wheelchair users, support cane users, and blind/low-vision users, as well as a fully customizable profile
+- **Screen reader support** — step-by-step directions with landmark-based alerts for non-visual navigation
+- **Feedback** — the ability to leave comments on map features to help improve the underlying data
+
+AccessMap is powered by [OpenSidewalks](../../opensidewalks/index.md) and [OpenStreetMap](https://welcome.openstreetmap.org/) data.
+
+---
+
+### Quick Start
+
+1. **Open** your web browser and navigate to [AccessMap.app](https://accessmap.app)
+2. **Select** a region from the region selector in the top bar
+3. **Choose** a mobility profile that fits your needs, or customize your own!
+4. **Search** for or select a starting point and destination to plan your route
+
+---
+
+![AccessMap](../../resources/images/accessmap/user-manual/index/accessmap-light.png#only-light)
+![AccessMap](../../resources/images/accessmap/user-manual/index/accessmap-dark.png#only-dark)
+
+---
+
+### Table of Contents
+
+AccessMap User Manual Table of Contents
+
+#### [Getting Started](getting-started.md)
+
+This section explains how to access AccessMap, select a region, and take the built-in tour.
+
+#### [Interface Overview](interface.md)
+
+This section introduces the AccessMap interface, including the sidebar, map controls, and legend.
+
+#### [Mobility Profiles and Preferences](profiles.md)
+
+This section explains how to select a pre-defined mobility profile and how to customize individual routing preferences.
+
+#### [Planning a Route](route-planning.md)
+
+This section explains how to set a starting point and destination, plan a route, and read the route display.
+
+#### [Navigation](navigation.md)
+
+This section explains how to follow step-by-step directions and use screen reader alerts for non-visual navigation.
+
+#### [Leaving Feedback](feedback.md)
+
+This section explains how to leave comments on map features to report observations and help improve the data.