Offline-capable PWA providing searchable first aid guides with step-by-step instructions. Use when you need to look up first aid steps, search for guides by condition or symptom, manage bookmarks, add emergency contacts, or understand the app's offline capabilities. Triggers include "first aid", "CPR steps", "burn treatment", "choking", "emergency guide", or any query about first aid procedures.
Offline-capable PWA providing searchable first aid guides with step-by-step instructions. Use when you need to look up first aid steps, search for guides by condition or symptom, manage bookmarks, add emergency contacts, or understand the app's offline capabilities. Triggers include "first aid", "CPR steps", "burn treatment", "choking", "emergency guide", or any query about first aid procedures.
first-aid-reference
A Progressive Web App (PWA) that provides offline-capable first aid guides. All content is static JSON bundled at build time. No account required, no data collected.
When to use
Looking up step-by-step first aid instructions for a specific condition
Searching for guides by symptom, keyword, or category
Checking whether a condition is classed as EMERGENCY, URGENT, or ROUTINE
Managing bookmarked guides
Adding or reviewing emergency contacts
Installing the app to a mobile device's home screen
Understanding what is and is not cached for offline use
Base URL
This is a client-side SPA with no API server. All functionality runs in the browser.
Guides are stored in src/data/articles.json. Each guide follows this structure:
{"id":"my-guide-id","category":"burns","title":"My Guide Title","emergency":false,"steps":[{"order":1,"text":"Step one instruction.","note":"Optional clarifying note."}],"doNot":["Do not do this.","Do not do that."],"symptoms":["Symptom one","Symptom two"],"whenToCall":["If condition X occurs"],"tags":["keyword1","keyword2"],"relatedIds":["other-guide-id"]}
After editing articles.json, run pnpm build to rebuild the app.
To validate content structure before building:
pnpm tsx scripts/validate-content.ts
Configuring emergency contacts
Emergency contacts are stored in localStorage under the key first-aid-contacts. They can be managed from the Contacts page (/contacts) in the app. Contacts are never transmitted to any server.
// Read contacts from localStorage (for debugging)JSON.parse(localStorage.getItem('first-aid-contacts') ?? '[]')
Installing on iOS
iOS Safari does not support the beforeinstallprompt event. Manual install instructions:
Open the app URL in Safari
Tap the Share button (box with arrow)
Scroll down and tap "Add to Home Screen"
Tap "Add"
The app will appear as a standalone icon and open without browser chrome.
Installing on Android
Chrome and Edge on Android support automatic install prompts. The InstallPrompt component captures the beforeinstallprompt event and shows an install banner.
Users can also install manually:
Open in Chrome
Tap the three-dot menu
Tap "Add to Home screen"
Accessibility features
All interactive elements are keyboard-accessible with visible focus ring (2px solid --border-focus)
Step numbers have aria-label="Step N of M"
Emergency banner uses role="alert" and aria-live="assertive"
SeverityBadge has role="status" with full text
High contrast mode increases border widths and font weights (toggled in Settings)
Minimum tap target size: 44x44px on mobile
Color is never the sole indicator of status - text labels always accompany color
Environment variables (build time only)
Variable
Default
Description
VITE_APP_NAME
first-aid-reference
App display name in manifest
VITE_APP_VERSION
1.0.0
Shown in Settings page
Medical disclaimer
Every article page displays:
"This information is for general educational purposes only. Always call emergency services (000, 112, or your local emergency number) for life-threatening situations. This app does not replace professional medical advice."
This disclaimer is rendered by DisclaimerBanner.tsx and must never be removed or hidden.
