[Feature] Visual UX/Accessibility consultant — WCAG + design system enforcement

[davesleal]

Context

The agent team has infosec, architect, tester, and output-editor consultants. Missing: a visual UX/accessibility consultant that reviews UI output for accessibility compliance, UX best practices, and design system consistency — while staying aware of the project registry.

What this agent does

A Sonnet-powered consultant that:

• Reviews UI code changes (SwiftUI views, React components, HTML/CSS) for WCAG 2.x compliance
• Checks against UX laws (Fitts's law, Hick's law, Miller's law, Jakob's law)
• Validates that UI code uses registered components from .shellack/registry.md
• When computer use is available ([Feature] Computer Use — visual QA and browser automation #15), can screenshot the actual rendered UI and review visually
• Collaborates bidirectionally with the primary reasoning agent — both can "look at the same thing"

WCAG checks (non-exhaustive)

• Color contrast ratios (4.5:1 for text, 3:1 for large text)
• Touch target sizes (minimum 44x44pt on iOS, 48x48dp on Android)
• Text alternatives for images/icons
• Keyboard/VoiceOver navigability
• Focus indicators
• Motion/animation respects reduced-motion preference
• Semantic HTML / accessibility roles
• Dynamic type / font scaling support

UX law checks

• Fitts's Law — interactive targets are large enough and positioned for easy reach
• Hick's Law — choices presented aren't overwhelming (menus, option lists)
• Miller's Law — information grouped in digestible chunks (max 7±2 items)
• Jakob's Law — UI follows platform conventions (iOS feels like iOS, web feels like web)
• Doherty Threshold — feedback within 400ms for interactions
• Law of Proximity — related elements grouped visually
• Law of Common Region — boundaries/containers used to group related content

Registry integration

The visual consultant reads the Project Registry to know:

• Available UI components (use <Button> not a custom <div onClick>)
• Design tokens (use --color-primary not #3B82F6)
• Platform-specific patterns (SwiftUI NavigationStack not NavigationLink(destination:))
• Architecture rules ("no inline styles", "components must be reusable")

When it finds a violation, the correction flows back through the feedback loop into the registry.

Trigger detection

Add to tools/consultants.py:

_VISUAL_UX_PATTERNS = [
    r"\bview\b", r"\bcomponent\b", r"\blayout\b", r"\bstyle\b",
    r"\bcss\b", r"\btailwind\b", r"\bswiftui\b", r"\breact\b",
    r"\bbutton\b", r"\bmodal\b", r"\bform\b", r"\bnav\b",
    r"\bcolor\b", r"\bfont\b", r"\bspacing\b", r"\bpadding\b",
    r"\baccessib", r"\bwcag\b", r"\ba11y\b", r"\bvoiceover\b",
    r"\b\.tsx\b", r"\b\.vue\b", r"\bView\.swift\b",
]

Computer use collaboration (#15)

When computer use is enabled, the visual consultant and primary agent can both:

1. Primary agent makes UI changes
2. Computer use takes a screenshot
3. Visual consultant reviews the screenshot for WCAG/UX issues
4. Findings feed back to the primary agent for fixes
5. Re-screenshot to verify

This creates a visual feedback loop — the agents "see" the same thing.

Implementation

1. Add visual-ux role to tools/consultants.py with system prompt covering WCAG + UX laws
2. Add trigger patterns for UI-related code changes
3. System prompt includes instruction to check project registry for existing components
4. Registry sections for design tokens and UI components are passed as context
5. Feature-gated via consultants: true (same gate as other consultants)
6. When computer use ([Feature] Computer Use — visual QA and browser automation #15) is available, add screenshot review capability

Priority

Medium — high value for web and iOS projects. Depends on registry being populated with design tokens and components.

Related

• [Feature] Computer Use — visual QA and browser automation #15 — Computer Use (visual QA + browser automation)
• Token Cart spec — consultant dispatch, registry integration, bidirectional communication

[m13v]

the computer use collaboration flow (agent makes changes, screenshot, visual consultant reviews, feedback loop) is where this gets really powerful. we do something similar for automated UI testing using macOS accessibility APIs.

one practical tip: for WCAG contrast ratio checks, reading actual rendered pixel colors via screenshots is more reliable than parsing CSS/SwiftUI color values. computed colors after opacity, blending, and dark mode transformations are often different from what is in the source code. we take a screenshot, sample pixels at the text location and background, then compute the contrast ratio directly.

for touch target sizes (44x44pt minimum), the accessibility tree is more reliable than visual measurement. AXUIElement gives you the exact frame of each interactive element, which accounts for padding and hit testing areas that are not visually apparent. some buttons have larger hit areas than their visual bounds suggest.

the trigger detection patterns look good. consider also matching on accessibility-related build warnings since Xcode flags missing accessibility labels and identifiers during compilation.

[m13v]

our macOS accessibility tree traversal that handles AXUIElement element targeting, frame measurement, and role-based querying for automated WCAG checks: https://github.com/mediar-ai/mcp-server-macos-use/blob/main/Sources/MCPServer/main.swift