Desktop App

The A11YSmith desktop app is a consultant-facing Electron surface for creating audits, reviewing findings, accessing tools, and managing settings. It complements the existing CLI (engineer-facing) and workbench (server-based) surfaces. All three surfaces share the same underlying packages and canonical JSON report format.

Architecture

The desktop app uses a strict Electron security model with full process isolation. The main process handles IPC, native dialogs, filesystem operations, and persistence. The renderer is sandboxed with no Node API access. All communication passes through a typed bridge exposed via contextBridge in the preload script.

Desktop app packages
Package	Path	Role
`@a11ysmith/desktop-app`	`apps/desktop-app`	Electron main, preload, and renderer
`@a11ysmith/desktop-bridge`	`packages/desktop-bridge`	Typed IPC channels, Zod schemas, TypeScript types

Security model

contextIsolation: true — renderer cannot access Node APIs
nodeIntegration: false — no require() in renderer
sandbox: true — OS-level sandboxing enabled
All IPC payloads validated with Zod at the bridge boundary
Content Security Policy restricts script sources to 'self'

Bridge channels

The bridge exposes eight IPC channels, each with a defined purpose. All methods return a BridgeResult<T> discriminated union.

IPC channel reference
Channel	Behavior
`GET_APP_VERSION`	Returns the Electron app version string
`GET_WORKSPACE_PATH`	Returns the current workspace directory path, or `null`
`OPEN_DIRECTORY_DIALOG`	Opens a native directory picker and returns the chosen path
`OPEN_FILE_DIALOG`	Opens a native file picker with configurable filters
`READ_REPORT_FILE`	Reads and validates an A11YSmith JSON report
`GET_PREFERENCES`	Returns persisted app preferences
`SAVE_PREFERENCES`	Persists app preferences to disk
`GET_RECENT_REPORTS`	Returns the list of recently opened reports

UI pages

The renderer uses hash-based routing with five pages:

Desktop app pages
Page	Purpose
Home	Workspace status, recent reports, quick start guidance
Audits	Audit creation (future: connects to audit runtime)
Findings	Open reports, filter findings, view detail panels
Tools	Lookup, remediation, and standards crosswalk tools
Settings	Workspace directory selection, app version display

Findings interaction layer

Filter bar — severity, platform, needs-review toggle, and search by title, WCAG ID, or finding ID
Findings table — rows with event delegation surviving innerHTML replacement from filter updates
Detail panel — finding metadata, impact statement, suggested fix, and caveats
Focus management — detail heading focused on open, originating row button focused on close
Debounced search — table updates immediately, screen reader announcement debounced at 300ms

Persistence

Preferences and recent reports are stored as JSON files in the Electron userData directory. Opening a report automatically tracks it in the recent reports list (last 20 entries).

Accessibility

The desktop app follows the same WCAG AA standards as the dashboard: semantic HTML before ARIA, keyboard-operable navigation, visible focus indicators, correct heading hierarchy, live region discipline (status vs alert vs passive containers), and contrast ratios meeting 4.5:1 for text and 3:1 for UI components.

Running locally

pnpm install

pnpm turbo build --filter=@a11ysmith/desktop-bridge

pnpm --filter @a11ysmith/desktop-app dev