OpenParable
Skip to content
← Back to skills

Team Visual A11y

Design
team-visual-a11y

Team Visual A11y is an Agent Skill for design published in the catlog22/maestro-flow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Unified team skill for visual accessibility QA. OKLCH color contrast, typography readability, focus management, WCAG AA/AAA audit at rendered level. Uses team-worker agent architecture. Triggers on "team visual a11y", "accessibility audit", "visual a11y".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/catlog22/maestro-flow/blob/HEAD/.claude/skills/team-visual-a11y/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/team-visual-a11y, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

<required_reading> @~/.maestro/workflows/run-mode.md </required_reading>

Team Visual Accessibility

Deep visual accessibility QA: OKLCH-based perceptual color contrast, typography readability at all viewports, focus-visible completeness, WCAG AA/AAA audit at rendered level. Built on team-worker agent architecture -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from roles/<role>/role.md.

Architecture

Skill(skill="team-visual-a11y", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze -> dispatch -> spawn workers -> STOP
                                    |
                    +-------+-------+-------+
                    v       v       v       |
           [3 auditors spawn in PARALLEL]   |
        color-auditor  typo-auditor  focus-auditor
                    |       |       |
                    +---+---+---+---+
                        v
               remediation-planner
                        |
                        v
               fix-implementer (inner_loop)
                        |
                        v
               [re-audit: color + focus in PARALLEL]

Role Registry

RolePathPrefixInner Loop
coordinatorroles/coordinator/role.md----
color-auditorroles/color-auditor/role.mdCOLOR-*false
typo-auditorroles/typo-auditor/role.mdTYPO-*false
focus-auditorroles/focus-auditor/role.mdFOCUS-*false
remediation-plannerroles/remediation-planner/role.mdREMED-*false
fix-implementerroles/fix-implementer/role.mdFIX-*true

Pre-load (coordinator, before dispatch)

  1. Codebase docs: If .workflow/codebase/ARCHITECTURE.md exists, read for module boundaries
  2. Specs (ui): maestro load --type spec --category ui — load ui constraints as shared context
  3. Wiki knowledge: maestro search "accessibility WCAG contrast" --json — top 5 entries as prior context
  4. All optional — proceed without if unavailable

Role Router

Parse $ARGUMENTS:

  • Has --role <name> -> Read roles/<name>/role.md, execute Phase 2-4
  • No --role -> @roles/coordinator/role.md, execute entry router

Shared Constants

  • Session prefix: VA
  • Session path: .workflow/.team/VA-<slug>-<date>/
  • team_name: visual-a11y
  • CLI tools: maestro delegate --mode analysis (read-only), maestro delegate --mode write (modifications)
  • Message bus: mcp__maestro__team_msg(session_id=<session-id>, ...)
  • Max GC rounds: 2

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-id>",
  team_name: "visual-a11y",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: visual-a11y
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

CommandAction
check / statusView execution status graph
resume / continueAdvance to next step

Specs Reference

Session Directory

.workflow/.team/VA-<slug>-<date>/
+-- .msg/
|   +-- messages.jsonl         # Team message bus
|   +-- meta.json              # Pipeline config + GC state
+-- audits/
|   +-- color/                 # Color auditor output
|   |   +-- color-audit-001.md
|   +-- typography/            # Typography auditor output
|   |   +-- typo-audit-001.md
|   +-- focus/                 # Focus auditor output
|       +-- focus-audit-001.md
+-- remediation/               # Remediation planner output
|   +-- remediation-plan.md
+-- fixes/                     # Fix implementer output
|   +-- fix-summary-001.md
+-- re-audit/                  # Re-audit output (GC loop)
|   +-- color-audit-002.md
|   +-- focus-audit-002.md
+-- evidence/                  # Screenshots, traces

Error Handling

ScenarioResolution
Unknown commandError with available command list
Role not foundError with role registry
Session corruptionAttempt recovery, fallback to manual
Fast-advance conflictCoordinator reconciles on next callback
Completion action failsDefault to Keep Active
GC loop stuck > 2 roundsEscalate to user: accept / retry / terminate
Chrome DevTools unavailableDegrade to static analysis only