/gaia-validate-design-a11y

user-facing
Category:
Planning
Lifecycle phase:
2 -- Planning
Arguments:
[design target -- Figma URL, doc path, or component name]

What it does

/gaia-validate-design-a11y validates design artifacts for accessibility before implementation begins. It checks WCAG 2.1 design-time concerns: color contrast, semantic structure, keyboard navigation design, ARIA landmark planning, and color-alone meaning. Every finding cites a specific WCAG success criterion. Produces a verdict: APPROVE, REQUEST_CHANGES, or BLOCKED.

When to use it

  • After creating or editing UX design, before moving to architecture or implementation.
  • You want to catch accessibility issues at design time, when they are cheapest to fix.

This is the planning-phase sibling of three accessibility skills: this one reviews designs, /gaia-review-a11y reviews code pre-merge, and /gaia-test-a11y tests post-deployment.

Prerequisites

  • A design artifact to validate. This can be a UX design document, Figma URL, or component spec.

How to invoke

/gaia-validate-design-a11y .gaia/artifacts/planning-artifacts/ux-design.md
/gaia-validate-design-a11y https://figma.com/file/abc123/design
/gaia-validate-design-a11y LoginForm
/gaia-validate-design-a11y

Without an argument, prompts you for the design target.

What it does step by step

  1. Setup Resolves the design target and loads the accessibility rubric.
  2. Discovery Reads the design artifact and identifies interactive components, color palettes, text sizes, and navigation flows.
  3. Analysis Checks color contrast (WCAG 1.4.3, 1.4.11), semantic structure (1.3.1, 2.4.6), keyboard navigation (2.1.1, 2.4.3, 2.4.7), ARIA landmarks (1.3.1, 4.1.2), and color-alone meaning (1.4.1).
  4. Cross-checks Compares design components against the project's component library (if any) and verifies assistive-tech personas are covered.
  5. Verdict Produces APPROVE (no issues), REQUEST_CHANGES (issues found), or BLOCKED (critical barriers).

Inputs

InputSourceDescriptionExample
design-targetPositional argument or interactive promptFigma URL, design document path, or component name./gaia-validate-design-a11y .gaia/artifacts/planning-artifacts/ux-design.md

Outputs

OutputLocationDescription
Findings tableConsole outputEach finding with severity, WCAG criterion, and remediation.
VerdictConsole outputAPPROVE, REQUEST_CHANGES, or BLOCKED.

Example session

> /gaia-validate-design-a11y .gaia/artifacts/planning-artifacts/ux-design.md

Analyzing design for WCAG 2.1 compliance...

| Severity | Finding                              | WCAG      | Remediation                    |
|----------|--------------------------------------|-----------|--------------------------------|
| high     | Button contrast 3.2:1 (needs 4.5:1) | 1.4.3 AA  | Darken button text color       |
| medium   | No focus-visible style on dropdowns  | 2.4.7 AA  | Add visible focus indicator    |
| low      | Heading skip: h2 -> h4              | 1.3.1 A   | Add missing h3 level           |

Verdict: REQUEST_CHANGES (1 high, 1 medium, 1 low)

What to run next

  • /gaia-edit-ux -- fix the accessibility issues in the UX design.
  • Re-run this command after fixes to confirm compliance.

Troubleshooting

Rubric load failed

The accessibility rubric file is missing. This is a framework installation issue -- reinstall or verify the GAIA plugin.