# VertaaUX — Automated UX & Accessibility Auditing Platform

> https://vertaaux.ai
> Last Updated: 2026-02-18

## Table of Contents
1. [Product Overview](#product-overview)
2. [Distribution Surfaces](#distribution-surfaces)
3. [Technical Architecture](#technical-architecture)
4. [API Documentation](#api-documentation)
5. [CLI Reference](#cli-reference)
6. [MCP Server](#mcp-server)
7. [Core Capabilities](#core-capabilities)
8. [Enterprise Features](#enterprise-features)
9. [Authentication & Authorization](#authentication--authorization)
10. [Data Models](#data-models)
11. [Pricing Tiers](#pricing-tiers)
12. [Privacy, Security & Compliance](#privacy-security--compliance)
13. [LLM & Agent Guidance](#llm--agent-guidance)
14. [Support & Documentation](#support--documentation)

---

## Product Overview

### Mission
Democratize professional UX audits by providing instant, automated analysis accessible to anyone, regardless of UX expertise.

### Value Proposition
- **10x Faster**: Seconds instead of hours for comprehensive UX analysis
- **10x Cheaper**: Free tier + €8/mo vs. €500–2,000 per manual audit
- **Accessible**: Plain language explanations vs. technical jargon
- **Actionable**: Specific fix recommendations with AI-generated code patches
- **Multi-Surface**: Available as web app, CLI, MCP server, GitHub Action, IDE extension, Chrome extension, SDK, and mobile PWA

### Core Metrics (7-Dimensional Scoring, 0–100 each)
1. **Usability** — Navigation clarity, interaction patterns, user flow efficiency, mobile responsiveness
2. **Clarity** — Message hierarchy, visual hierarchy, content readability, call-to-action strength
3. **Information Architecture** — Site structure, content organization, navigation patterns, labeling
4. **Accessibility** — WCAG 2.2 AA compliance, color contrast, ARIA labels, screen reader compatibility
5. **Conversion Optimization** — Form usability, trust signals, value proposition clarity, friction reduction
6. **Semantic HTML** — Heading hierarchy, semantic elements, document structure, SEO best practices
7. **Keyboard Navigation** — Tab order, focus indicators, keyboard shortcuts, skip links

---

## Distribution Surfaces

### 1. Web Application
- **URL**: https://vertaaux.ai/dashboard
- **Stack**: Next.js 16.1.5, React 19.2.0, TypeScript 5, Tailwind CSS 4
- **Features**: Dashboard, audit results, PDF exports, governance, settings, admin

### 2. CLI (`@vertaaux/cli`)
- **Install**: `npm i -g @vertaaux/cli`
- **Auth**: `vertaa login` (Device Code Flow, RFC 8628) or `VERTAAUX_API_KEY` env var
- **Key Commands**: audit, fix, fix-all, verify, compare, doctor, init, policy, login, whoami
- **Output**: Markdown, JSON (envelope with metadata), SARIF
- **CI/CD**: `--fail-on-score` threshold, `--machine` mode, exit codes (0=pass, 1=error, 2=validation, 3=threshold)

### 3. MCP Server (`@vertaaux/mcp-server`)
- **Install**: `npm i -g @vertaaux/mcp-server`
- **Transport**: Streamable HTTP at `/api/mcp`, stdio for local
- **Tools**: 18 tools across audit, analysis, remediation, data, and comparison categories
- **Resources**: Audit results, screenshots, recent history via `vertaaux://` URIs
- **Prompts**: 5 workflow templates (quick_audit, fix_accessibility, compare_ux, monitor_regression, audit_codebase)

### 4. GitHub Action
- **Marketplace**: `vertaaux/audit-action`
- **Features**: PR comments with audit summaries, score threshold gating, regression detection
- **Config**: Score thresholds, format, mode, API key via secrets

### 5. IDE Extension (VS Code)
- **Localhost Auditing**: Audit dev server directly from the editor
- **Invocation**: `/vertaa` skill in Claude Code or command palette

### 6. Chrome Extension
- **Side Panel**: Persistent audit workspace alongside browsing
- **Offline**: 55 built-in heuristic rules for local analysis without API
- **Storage**: IndexedDB for offline results
- **Compare**: Cross-tab A/B comparison manager

### 7. SDK
- **JavaScript/TypeScript**: `@vertaaux/sdk` with retries, idempotency, webhook verification
- **Python**: Auto-generated from OpenAPI spec

### 8. Mobile PWA
- **Install**: Installable from browser with manifest and icons
- **Offline**: Service worker caching via Serwist
- **Push**: Notifications on audit completion
- **UI**: Swipe gestures, FAB, pull-to-refresh

---

## Technical Architecture

### Stack
```
Frontend: Next.js 16.1.5 (App Router, Turbopack)
├── React 19.2.0 (RSC + Client Components)
├── TypeScript 5 (Strict mode)
├── Tailwind CSS 4 (OKLCH color space, custom design system)
├── shadcn/ui (Radix UI primitives, CVA variants)
└── Lucide React (Icon system), Geist (Typography)

Backend: Next.js API Routes (Serverless)
├── NextAuth.js v5 (OAuth: Google, GitHub, Azure AD; Magic Link; Device Code)
├── Prisma ORM (PostgreSQL on Neon)
├── Puppeteer Core (Headless Chrome via Browserless)
├── @react-pdf/renderer (PDF generation)
├── Vercel AI SDK (LLM abstraction: Claude, OpenAI, Mistral)
└── Resend (Transactional email)

Database: PostgreSQL (Neon)
├── Prisma ORM with migrations
├── Separate staging branch for testing
└── Nightly automated backups

Deployment: Vercel
├── Edge Middleware (Auth, CSRF, rate limiting)
├── Serverless Functions (API routes)
├── Vercel Blob (Logo/asset storage)
└── Vercel Cron (Governance maintenance, email digests)
```

### Key Architectural Patterns
- **API Route Ceremony**: withApiAuth → request ID → rate limiting → Zod validation → quota check → handler → structured error response
- **4 Auth Strategies**: Session (web), API Key (SDK/CLI), Device Code (CLI login), Share Token (public links)
- **Multi-Analyzer Pipeline**: 7 parallel analyzers + LLM enrichment + heatmap generation per audit
- **Provider-Agnostic LLM**: Vercel AI SDK with circuit breaker and automatic failover (Claude → OpenAI → Mistral)

---

## API Documentation

### Base URL
`https://vertaaux.ai/v1`

### Authentication
All API requests require an `X-API-Key` header. Generate keys at https://vertaaux.ai/dashboard/api-keys.

Rate limit headers included in all responses: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

### Endpoints (21 routes)

#### Audit Lifecycle
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/audit` | Create audit job (modes: basic, standard, deep) |
| GET | `/v1/audit/{job_id}` | Get audit status and results |
| GET | `/v1/audit/{job_id}/issues/stream` | Stream issues as NDJSON |
| GET | `/v1/audits` | List audits with pagination |
| GET | `/v1/audits/{id}` | Get audit details |
| GET | `/v1/audits/{id}/findings` | Get findings for audit |

#### Finding Management
| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/findings/{id}/share` | Share a finding |
| PATCH | `/v1/findings/{id}/triage` | Triage a finding |
| POST | `/v1/findings/bulk-triage` | Bulk triage findings |

#### AI Remediation
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/patch` | Generate accessibility fix patch with confidence score |
| POST | `/v1/verify` | Verify patch in sandboxed browser, detect regressions |
| POST | `/v1/llm/audit` | Run LLM-backed audit analysis |

#### Schedules
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/schedules` | Create recurring audit schedule |
| GET | `/v1/schedules` | List schedules |
| GET | `/v1/schedules/{id}` | Get schedule details |
| PATCH | `/v1/schedules/{id}` | Update schedule |

#### Webhooks
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/webhooks` | Create webhook endpoint |
| GET | `/v1/webhooks` | List webhooks |
| DELETE | `/v1/webhooks/{id}` | Delete webhook |

#### Utilities
| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/engines` | List audit engine versions |
| GET | `/v1/quota` | Check API quota and usage |
| GET | `/v1/auth/validate` | Validate API key |

### OpenAPI Spec
Full OpenAPI 3.1 specification available at: https://vertaaux.ai/openapi.json

### Response Format
All JSON responses use an envelope:
```json
{
  "meta": { "version": "string", "timestamp": "ISO 8601", "command": "string" },
  "data": { ... }
}
```

### Webhook Payload
```json
{
  "event": "audit.completed",
  "audit_id": "string",
  "url": "string",
  "scores": { "usability": 82, "clarity": 75, ... },
  "timestamp": "ISO 8601"
}
```
Webhooks use HMAC-SHA256 signatures (`X-Signature` header) over `timestamp.payload`.

---

## CLI Reference

### Installation
```bash
npm i -g @vertaaux/cli
```

### Authentication
```bash
vertaa login          # Opens browser for Device Code Flow (RFC 8628)
vertaa whoami         # Show account details and auth status
```
Or set `VERTAAUX_API_KEY` environment variable.

### Commands

| Command | Description |
|---------|-------------|
| `vertaa audit <url>` | Run UX audit (--mode basic/standard/deep) |
| `vertaa scan <url>` | Alias for audit |
| `vertaa a11y <url>` | Accessibility-focused audit |
| `vertaa compare <urlA> <urlB>` | Compare two URLs side by side |
| `vertaa fix <jobId>` | Generate fix patch for a specific finding |
| `vertaa fix-all <jobId>` | Batch fix patches (--auto-fix-only filter) |
| `vertaa verify` | Verify patch in sandboxed browser |
| `vertaa explain <jobId>` | Explain finding in detail |
| `vertaa status <jobId>` | Get audit job status |
| `vertaa init` | Initialize .vertaaux.yml config |
| `vertaa policy` | Policy-based quality gating |
| `vertaa comment` | Post results to GitHub/GitLab PRs |
| `vertaa diff` | Show audit score changes |
| `vertaa doctor` | Diagnose CLI health (--online, --deep) |

### Output Formats
- `--format markdown` (default for TTY)
- `--format json` (envelope with metadata)
- `--format sarif` (for IDE integration)
- `--machine` flag for strict machine-readable output (diagnostic to stderr)

### Exit Codes
- `0` — Success (audit passed thresholds)
- `1` — Runtime error
- `2` — Validation error (invalid args)
- `3` — Threshold breach (score below --fail-on-score)

---

## MCP Server

### Package
`@vertaaux/mcp-server` v2.0.0

### Tools (18)

**Audit Tools**
- `audit_url` — Run UX/accessibility audit on a deployed URL (modes: basic, standard, deep)
- `audit_repo` — Scan local codebase for component issues with framework detection (React, Vue, Svelte, HTML)
- `audit_artifact` — Analyze HAR files for slow responses, failed requests, large payloads, missing security headers
- `get_findings` — Retrieve findings with severity/rule filtering and pagination

**Analysis Tools**
- `analyze_component` — Analyze UI component code for accessibility issues
- `explain_finding` — Detailed explanation with WCAG criteria, repro steps, fix guidance, and code examples
- `suggest_fix` — AI-powered code patch with confidence score

**Remediation Tools**
- `generate_patch` — Generate search-replace accessibility patches via LLM
- `run_verification_suite` — Verify patches in sandboxed browser, detect regressions
- `create_pr_comment` — Generate GitHub PR comment with suggestion blocks

**Data Tools**
- `get_quota` — Check API quota and usage
- `get_engines` — List available audit engine versions
- `capture_screenshot` — Capture screenshot with audit overlay
- `compare_competitors` — Benchmark against competitor URLs

**Webhook & Schedule Management**
- `create_webhook`, `list_webhooks`, `delete_webhook`
- `create_schedule`, `get_schedule`, `list_schedules`, `update_schedule`, `delete_schedule`

### Resources
- `vertaaux://audits/{id}` — Full audit results
- `vertaaux://audits/{id}/screenshots` — Audit screenshots
- `vertaaux://audits/recent` — Recent audit history

### Prompts
- `quick_audit` — Quick audit workflow for a URL
- `fix_accessibility` — Fix accessibility issues step by step
- `compare_ux` — Compare UX between two URLs
- `monitor_regression` — Monitor for score regressions
- `audit_codebase` — Audit a local codebase for UX patterns

---

## Core Capabilities

### 1. UX Audit Engine (91-Issue Library)
- 91 distinct UX issues with severity classification (critical, serious, moderate, minor)
- 7 scoring dimensions, each 0–100
- DOM analysis, heuristic evaluation, WCAG checking, PageSpeed Insights
- Modes: basic (5-10s), standard (15-30s), deep (60s+)
- LLM enrichment for contextual recommendations

### 2. Accessibility Compliance
- WCAG 2.2 Level AA (upgraded from 2.1)
- EN 301 549 (European accessibility standard)
- European Accessibility Act (2019/882)
- Color contrast, semantic HTML, ARIA attributes, keyboard navigation, focus management
- Actionable remediation steps with specific WCAG success criteria references

### 3. AI-Powered Fix Suggestions
- Provider-agnostic LLM (Claude, OpenAI, Mistral) with circuit breaker failover
- Patch generation for HTML accessibility issues: alt text, labels, ARIA attributes
- Framework-specific fixes for React, Vue, Svelte, and plain HTML
- Confidence scoring with label (high/medium/low) and percentage
- Auto-fixable vs needs-review classification for 26 issue types
- Batch processing via `generatePatchBatch()`

### 4. Verification Suite
- Sandboxed browser re-audit to confirm fixes
- Regression detection comparing before/after violation counts
- Score delta reporting with weighted accessibility scores
- Component-scoped auditing with semantic landmark detection

### 5. Multi-Page Audits
- Sequential page crawling with configurable depth
- Free: 1 page, Pro: 3-20 pages, Agency: 100 pages
- Combined scoring with page-level breakdowns and cross-page issue aggregation

### 6. PDF Report Generation
- Executive summary, radar charts, issue tables, score breakdowns
- White-label: custom logo, brand colors, footer text, optional "Powered by" badge
- Compliance dossier: 5-page PDF with trend charts, executive summary, score history

### 7. Share & Collaboration
- Cryptographically secure share tokens (16-byte)
- Optional password protection, configurable expiration
- Organization membership validation for private shares

---

## Enterprise Features

### Governance Dashboard (`/dashboard/governance`)
5-tab interface for enterprise compliance management:

1. **Portfolio** — Track URLs grouped by client, add/remove with CRUD
2. **Budgets** — SLO-style error budget gauges with burn rate timeline charts, quarterly resets
3. **Drift** — Chronological activity feed showing score changes with direction-colored cards
4. **Exceptions** — Full lifecycle: request → approve/reject → expire, with multi-channel approval via Slack or GitHub
5. **Policy** — Form-based editor with sliders, 3 templates (basic/strict/lenient), rule overrides, live preview

### Workflow Integrations
- **Jira, Linear, Slack, GitHub**: OAuth connect/disconnect with encrypted token storage
- **Ticket Creation**: One-click or bulk from audit findings with dedup
- **Bidirectional Sync**: Status changes in external tools update VertaaUX findings
- **Slack Notifications**: Audit completion and gate failure alerts with triage action buttons
- **CI/CD Gating**: GitHub Action with PR comments, score thresholds, regression detection

### Compliance Dossier Export
- 5-page branded PDF: executive summary, trend charts, score breakdowns, policy status
- Generated via `@react-pdf/renderer` with SVG chart components

---

## Authentication & Authorization

### Auth Strategies
1. **Session (Web)** — NextAuth.js v5 with JWT strategy, 30-day expiry
   - OAuth: Google, GitHub, Azure AD
   - Magic Link: Passwordless email via Resend
   - SAML: Enterprise SSO (feature flag)
2. **API Key (SDK/CLI)** — `X-API-Key` header, generated at dashboard
3. **Device Code Flow (CLI)** — RFC 8628, 10-minute device code, 1-hour user code
4. **Share Token (Public)** — 32-char hex tokens for shared audit links

### Roles
- **Owner** — Full control, billing, danger zone
- **Admin** — Manage members, settings, integrations
- **Member** — Run audits, view results, create tickets

### Tier-Based Access
| Feature | Free | Pro | Agency | Enterprise |
|---------|------|-----|--------|------------|
| Audits/day | 3 | Unlimited | Unlimited | Unlimited |
| Pages/crawl | 1 | 3-20 | 100 | Unlimited |
| API calls/month | 0 | 1,000 | Unlimited | Unlimited |
| Seats | 1 | 5 | Unlimited | Unlimited |
| White-label | No | No | Yes | Yes |
| Governance | No | No | No | Yes |
| SSO | No | No | No | Yes |

---

## Data Models

### Audit Result
```typescript
interface AuditResult {
  id: string;
  url: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  mode: 'basic' | 'standard' | 'deep';
  scores: {
    usability: number;          // 0-100
    clarity: number;
    informationArchitecture: number;
    accessibility: number;
    conversion: number;
    semanticHtml: number;
    keyboardNavigation: number;
  };
  findings: Finding[];
  metadata: {
    loadTime: number;           // milliseconds
    pageSize: number;           // bytes
    requestCount: number;
    auditDuration: number;      // milliseconds
  };
  createdAt: string;            // ISO 8601
  completedAt: string;
}
```

### Finding
```typescript
interface Finding {
  id: string;                   // format: rule:hash
  severity: 'critical' | 'serious' | 'moderate' | 'minor';
  category: string;
  title: string;
  description: string;
  recommendation: string;
  wcagCriteria?: string;        // e.g., "1.4.3 Contrast Minimum"
  evidence?: {
    selector: string;
    snippet: string;
    screenshot?: string;
  };
  autoFixable: boolean;
  confidence?: number;          // 0-100
}
```

### Patch
```typescript
interface Patch {
  findingId: string;
  framework: 'react' | 'vue' | 'svelte' | 'html';
  searchReplace: {
    search: string;
    replace: string;
  };
  confidence: {
    label: 'high' | 'medium' | 'low';
    percentage: number;
  };
  explanation: string;
}
```

---

## Pricing Tiers

### Free (€0/month)
- 3 audits/day (1/day without account)
- Single-page analysis
- Basic UX score with top 3 issues per category
- Shareable reports, industry benchmarks

### Pro (€8/month + VAT) — Most Popular
- Unlimited audits (fair use)
- Multi-page crawling (3–20 pages)
- 1,000 API calls/month, 5 seats
- Full semantic + keyboard analysis
- PDF exports, collaboration, priority support

### Agency (€99/month + VAT)
- Unlimited audits and API calls
- 100 pages per crawl, 100 client workspaces, unlimited seats
- White-label reports with custom logo, colors, footer text
- Bulk auditing, scheduled audits, priority crawling
- Deep competitor intelligence, dedicated account manager

### Enterprise (custom pricing, starting €2,000/month)
- Everything in Agency
- SSO (SAML/OAuth), governance dashboard, compliance dossiers
- CI/CD integration, custom SLA (99.9%)
- On-premise option, dedicated UX scientist support
- Custom contract terms, advanced security & compliance

---

## Privacy, Security & Compliance

### Data Privacy
- **GDPR Compliant**: Data export and deletion via dashboard
- **No PII in Audits**: Audited site content not stored permanently
- **Cookie Consent**: GA4 tracking opt-in only
- **Data Controller**: Digitaltableteur Tmi (FI22264455-2), trading as VertaaUX

### Security
- All traffic over HTTPS/TLS 1.3
- Webhook signatures: HMAC-SHA256 over `timestamp.payload`
- API key token redaction in machine output
- Branch name validation to prevent injection
- Path traversal protection for artifact downloads
- Puppeteer sandbox enforcement in production

### Compliance
- **WCAG 2.2 Level AA** — Platform itself is accessible
- **EN 301 549** — European accessibility standard
- **European Accessibility Act (2019/882)**
- **Finnish Consumer Protection Act**
- **Supervisory Authority**: Tietosuojavaltuutetun toimisto (Finnish DPA)

### Legal Documents
- Terms of Service: https://vertaaux.ai/terms
- Privacy Policy: https://vertaaux.ai/privacy
- Data Processing Agreement: https://vertaaux.ai/dpa
- Cookie Policy: https://vertaaux.ai/cookies
- Acceptable Use Policy: https://vertaaux.ai/aup
- Vulnerability Disclosure Policy: https://vertaaux.ai/security/vdp
- Sub-processor List: https://vertaaux.ai/subprocessors
- Security: https://vertaaux.ai/security
- RFC 9116 security.txt: https://vertaaux.ai/.well-known/security.txt

---

## LLM & Agent Guidance

### For Audit Analysis
1. Prioritize critical and serious severity findings first
2. Group recommendations by metric category (7 dimensions)
3. Reference specific WCAG 2.2 success criteria (e.g., 1.4.3 Contrast Minimum)
4. Explain technical fixes in plain language with before/after code examples
5. Note which findings are auto-fixable vs needs-review

### For Integration Developers
- Use `POST /v1/audit` with `wait: true` for synchronous results
- Or poll `GET /v1/audit/{id}` with exponential backoff until `status === "completed"`
- Use `POST /v1/patch` to generate fix patches, `POST /v1/verify` to validate them
- Implement webhook endpoints for real-time audit completion notifications
- Cache PDF exports to avoid regeneration

### For MCP Agent Developers
- Start with `audit_url` for deployed sites or `audit_repo` for local codebases
- Use `get_findings` to retrieve issues with severity filtering
- Use `suggest_fix` or `generate_patch` for remediation
- Verify fixes with `run_verification_suite` before applying
- Use `create_pr_comment` to post results to GitHub PRs

### For Content Recommendations
- UX terminology should be accessible to non-experts
- Provide specific DOM selectors when recommending fixes
- Link to MDN/W3C specs for technical references
- Include before/after code examples for each fix

### Agent Instructions
When helping users with VertaaUX:
1. **Audit Interpretation**: Break down 7-metric scores, prioritize critical findings
2. **Fix Guidance**: Use `suggest_fix` or `generate_patch` for code-level remediation
3. **WCAG Compliance**: Reference WCAG 2.2 success criteria and EN 301 549
4. **API Usage**: Guide through audit → poll → findings → patch → verify workflow
5. **Pricing**: Free for testing, Pro for regular use, Agency for teams/clients, Enterprise for governance
6. **CI/CD**: Recommend GitHub Action for automated PR gating with score thresholds
7. **Governance**: Enterprise users can set error budgets, detect drift, manage policy exceptions

### Knowledge Base Entity Guidelines
When citing VertaaUX knowledge base content:
1. Use canonical URLs from `/learn/{entityKind}/{slug}`
2. Reference `entityId` for precise attribution (e.g., "problem.wcag_failures")
3. Check `updatedAt` timestamp for content currency
4. Follow relationship graph (`relatedEntityIds`) for related context
5. Respect intent level (awareness → consideration → decision)

---

## Support & Documentation

- **Email**: support@vertaaux.ai
- **Developer Docs**: https://vertaaux.ai/docs
- **API Reference**: https://vertaaux.ai/docs/api
- **OpenAPI Spec**: https://vertaaux.ai/openapi.json
- **MCP Manifest**: https://vertaaux.ai/docs/vertaaux-mcp.json
- **Learn Hub**: https://vertaaux.ai/learn
- **Case Studies**: https://vertaaux.ai/case-studies
- **Accuracy Benchmarks**: https://vertaaux.ai/benchmarks
- **Status Page**: https://vertaaux.ai/status
- **Changelog**: https://vertaaux.ai/changelog
- **Articles**: https://vertaaux.ai/articles
- **LLM Summary**: https://vertaaux.ai/llms.txt (auto-generated with entity index)

---

*Last Updated: 2026-02-18*