UI Delivery Protocol

Tooling Note: Commands use playwright-cli, an internal wrapper around Playwright. If unavailable, use standard Playwright: npx playwright <command>

🎨 MANDATORY FOR ALL UI WORK

Before marking ANY UI task complete, you MUST:

1. Visual Verification (Screenshots)

# Open the page
playwright-cli open <url-or-file-path>

# Screenshot at mobile breakpoint
playwright-cli run-code "window.resizeTo(375, 812)"
playwright-cli screenshot --full-page ./qa-screenshots/mobile.png

# Screenshot at tablet breakpoint  
playwright-cli run-code "window.resizeTo(768, 1024)"
playwright-cli screenshot --full-page ./qa-screenshots/tablet.png

# Screenshot at desktop breakpoint
playwright-cli run-code "window.resizeTo(1440, 900)"
playwright-cli screenshot --full-page ./qa-screenshots/desktop.png

2. Console Error Check

playwright-cli console error

Zero console errors from application code.

What counts as an error:

• console.error() calls from your code
• Uncaught exceptions
• Failed network requests (4xx/5xx)

What may be noted but doesn't block:

• Warnings from third-party libraries (document with link to issue)
• Deprecation warnings

Exception Process: If a known library produces unavoidable errors, add to /docs/known-console-errors.md with ticket link.

3. Build Verification

# For React/Vite projects
npm run build

# Must complete with no errors

4. Accessibility Check (Mandatory)

# Run automated accessibility scan
node scripts/run-axe.mjs <path>

Zero critical or serious violations.

Checks include:

• Color contrast (WCAG AA)
• ARIA labels on interactive elements
• Keyboard navigation
• Focus indicators

If violations exist:

1. Fix critical/serious issues
2. Document minor issues with remediation plan

6. QA Gate (Mandatory)

node scripts/qa-gate.mjs <path> ui

Must exit with code 0 (PASS) before delivery.

Exit codes:

• 0 = ✅ PASS — Ready to ship
• 1 = 🟡 REVISE — Fixable issues, re-run
• 2 = 🔴 REJECT — Fundamental problems, rebuild

7. Adversarial Review (Mandatory)

node scripts/adversarial-review.mjs <deliverable> ui

Must get PASS or REVISE (not REJECT).

Scoring:

• 80-100 = ✅ PASS — Ship it
• 70-79 = 🟡 REVISE — Address issues, re-review
• 0-69 = 🔴 REJECT — Rebuild from scratch

5. Adversarial Review

node scripts/adversarial-review.mjs <deliverable> ui

Must get PASS or REVISE (not REJECT).

---

✅ DELIVERY CHECKLIST

Every UI deliverable must include:

• Mobile screenshot (375px) — saved as [ticket]-mobile.png
• Tablet screenshot (768px) — saved as [ticket]-tablet.png
• Desktop screenshot (1440px) — saved as [ticket]-desktop.png
• Console errors: 0 from app code
• Accessibility: 0 critical/serious violations
• Build: PASS
• QA gate: PASS (exit 0)
• Adversarial review: PASS (80-100) or REVISE (70-79)

Screenshot Naming: ./qa-screenshots/[date]/[ticket-id]-[breakpoint].png

Artifact Storage: Attach screenshots to PR or upload to shared storage.

---

📤 COMPLETION MESSAGE TEMPLATE

✅ [Task Name] Complete

**Screenshots:**
📱 Mobile: ./qa-screenshots/2026-02-15/ABC-123-mobile.png
📱 Tablet: ./qa-screenshots/2026-02-15/ABC-123-tablet.png
🖥️  Desktop: ./qa-screenshots/2026-02-15/ABC-123-desktop.png

**Quality Checks:**
✅ Build: PASS (no errors)
✅ Console: 0 app errors (3 third-party warnings noted)
✅ Accessibility: 0 critical/serious violations
✅ QA Gate: PASS (exit 0)
✅ Adversarial: PASS (82/100)

**Deliverables:**
- /path/to/file1
- /path/to/file2

**Logs:**
- QA Gate: ./logs/qa-gate.log
- Adversarial: ./reports/adversarial-review.md

**Notes:** [any important info]

---

🚫 DO NOT DELIVER IF:

• Screenshots are missing
• Console has errors
• Build fails
• QA gate blocks
• Adversarial review rejects

---

🆘 STUCK?

If you can't get a clean screenshot or build:

1. Try to fix it yourself (30 min max)
2. If still stuck → notify Maria with specific error

./notify-maria.sh "UI issue: [specific problem]. Error: [message]. Help needed."

---

📚 EXAMPLE: Complete UI Workflow

# 1. Build the project
cd /projects/my-dashboard
npm run build

# 2. Open in browser
playwright-cli open ./dist/index.html

# 3. Take screenshots
mkdir -p ./qa-screenshots
playwright-cli run-code "window.resizeTo(375, 812)"
playwright-cli screenshot --full-page ./qa-screenshots/mobile.png

playwright-cli run-code "window.resizeTo(768, 1024)"
playwright-cli screenshot --full-page ./qa-screenshots/tablet.png

playwright-cli run-code "window.resizeTo(1440, 900)"
playwright-cli screenshot --full-page ./qa-screenshots/desktop.png

# 4. Check console
playwright-cli console error

# 5. Run QA gate
node scripts/qa-gate.mjs ./dist/index.html ui

# 6. Deliver with screenshots attached

---

Last Updated: Feb 15, 2026
Enforced By: qa-gate.mjs, adversarial-review.mjs