# AirGap Docs — UX spec

## Users & primary jobs
- **Field/clinical ops, technical writers** (daily users): record a task while talking, get a guide, fix it, export.
- **IT/Compliance lead** (buyer/admin): install, license, confirm nothing leaves the machine, supply models offline.
- Jobs: (1) turn a recording into a step-by-step guide; (2) guarantee no sensitive data leaks into it; (3) export to Markdown/HTML/PDF/Docx.

## Information architecture
Desktop app, left nav with 3 items: **Library** (home), **New recording**, **Settings** (models, license, storage). Review/Export is a screen reached from a library item or after processing. Persistent "Nothing leaves this device" cue.

## Key flows
1. **First run:** Library empty state with setup check (models, license) → "Record your first guide".
2. **Record:** New recording → pick capture, audio, clean-room options → Start → 3s countdown → floating Pause/Stop control (global shortcut Ctrl/Cmd+Shift+R) → Stop.
3. **Process:** progress panel (save, transcribe, write steps, find sensitive data); user may leave; notification on completion.
4. **Review & export:** Review guide → edit step text, reorder, delete → review every auto-blur (keep/remove/add) → choose formats and folder → Export (enabled once all blurs reviewed) → success with "Show in folder".
5. **Activate license / change model:** Settings.

## Screens
### Library (`mockups/library.html`)
Purpose: find guides, start recording. Content: search, table (title, created, steps, status), primary "Start new recording". Actions: open, export, retry. States: empty/first-run (setup check + CTA), populated, "N blurs to review" badge, failed ("Transcription failed" + Retry), loading (skeleton rows).
### New recording + processing (`mockups/record.html`)
Purpose: configure and start capture, then watch processing. Content: capture radio (full screen/window/region), mic select + level meter, system-audio checkbox, clean-room options. States: ready, permission blocked error (with link to OS settings), recording, processing (progress + 4 stages, cancellable), model-missing error (links to Settings).
### Review guide & export (`mockups/review.html`)
Purpose: edit and sanitize, then export. Content: numbered steps each with editable instruction + screenshot, blur overlays with Keep/Remove/Add, review counter, export panel. States: blurs pending (warning, Export disabled), all reviewed, export success, export error (e.g. Pandoc missing, folder not writable), saving (autosave).
### Settings (`mockups/settings.html`)
Purpose: models, license, storage. Content: Whisper model selector, writing-model source (built-in/local Ollama), import-from-USB, license key activation with expiry, storage folder, delete all data. States: valid license, expiring (<30 days warning), invalid key error, expired (recording disabled, existing guides still exportable), Ollama unreachable error.

## Design system
- Colours: ink #14213D, background #F6F7F9, panel #FFFFFF, border #D5DAE3, primary #1F4FD8 (hover #173CA8), muted text #4B5568, success #116B3A on #E3F4EA, warning #8A4B00 on #FFF1D6, error #A3201A on #FDE7E5, focus ring #FFB800.
- Type: system sans; 24 / 18 / 15 body / 13 meta. Spacing scale 4, 8, 12, 16, 24, 32. Radius 6–8.
- Components: nav, card, table, badge, buttons (primary/secondary/destructive), form fields with visible labels, progress bar, banners (warn/error), screenshot with blur overlay.
- Tone: plain, calm, specific; say what happened and what to do next; reinforce that data stays local.

## Accessibility
- Text contrast ≥ 4.5:1 for all pairs above; status never conveyed by colour alone (icon + text).
- Fully keyboard operable; visible 3px focus ring; skip link; logical focus order (nav → main).
- Every input has a visible label; errors use role="alert", progress uses role="progressbar" and aria-live.
- Screenshots have alt text; blur actions are buttons with text labels; reorder via buttons, not drag only.
- Recording start/stop works via global shortcut and announces state.

## Open questions
1. Should blur review be mandatory before export (as designed) or only recommended? Compliance buyers likely want mandatory.
2. Is the trial a 30-day license key file delivered offline (assumed)?
3. Is ready-to-use model bundling in the installer required (large download) or is USB import acceptable? Designed for both.