agentleFS
CodeCaroSCodeCaroS/MythOs_Aegis/.agents/skills/aria-apg-review/SKILL.md

aria-apg-review

Skill0 starsChanged 3 months agoApache-2.0View on GitHub

Review web interfaces against every applicable W3C WAI-ARIA Authoring Practices Guide pattern. Use when auditing UI code or rendered widgets for accessible structure, names, roles, states, properties, keyboard interaction, focus management, composite navigation, or popup and dialog behavior.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 9 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read references/patterns.md before reviewing.

    line 21
  2. Distinctive:

    Treat the current W3C page as authoritative when the bundled routing summary differs.

    line 24
  3. Distinctive:

    Read repository instructions, component primitives, callers, routes, supported states, and existing tests.

    line 33
  4. Distinctive:

    When runtime access exists:

    line 52
  5. Distinctive:

    Run every required APG key interaction in every reachable state and supported orientation.

    line 54
  6. Distinctive:

    Verify focus entry, movement, wrapping, activation, dismissal, return, and recovery after removal or rerender.

    line 55
  7. Distinctive:

    Pass: All applicable required APG behavior was verified.

    line 64
  8. Distinctive:

    Do not claim screen-reader compatibility without testing a named browser, screen reader, and version.

    line 97
  9. Distinctive:

    Keep APG pattern coverage, evidence-backed findings, and unverified runtime risks explicit.

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

WAI-ARIA APG Review

Audit only unless the user explicitly asks for fixes.

Source discipline

  1. Read references/patterns.md before reviewing.
  2. Inventory every interactive widget and landmark in scope, then map each one to the routing matrix.
  3. Open the current W3C page for every matched pattern. Read the entire About, Keyboard Interaction, WAI-ARIA Roles/States/Properties, notes, warnings, and linked dependency patterns.
  4. Treat the current W3C page as authoritative when the bundled routing summary differs.
  5. Distinguish required behavior from optional APG behavior. Missing optional behavior is not a conformance defect unless the product relies on it.

APG is design guidance, not proof of WCAG conformance. Its examples are illustrative code, not production-ready components. Prefer native HTML semantics and behavior before adding ARIA.

Review workflow

1. Establish coverage

  • Read repository instructions, component primitives, callers, routes, supported states, and existing tests.
  • Include repeated and nested widgets, responsive variants, disabled states, empty states, loading states, errors, and dynamically inserted or removed items.
  • Record each applicable pattern instance. Mark patterns that are absent as not applicable; do not invent findings for them.

2. Inspect the implementation

For each mapped pattern, verify:

  • Native element choice and whether custom ARIA is necessary.
  • Required role hierarchy and DOM or aria-owns relationships.
  • Accessible name and description sources.
  • Required states and properties, valid values, valid ID references, and synchronization with visual state.
  • Tab stops, roving tabindex or aria-activedescendant, selection versus focus, orientation, and type-ahead behavior.
  • Popup ownership, hidden or inert content, live regions, busy state, and focus restoration where applicable.

Trace shared primitives before reporting duplicate findings. Report the root cause once and list affected callers.

3. Exercise rendered behavior

When runtime access exists:

  • Run every required APG key interaction in every reachable state and supported orientation.
  • Verify focus entry, movement, wrapping, activation, dismissal, return, and recovery after removal or rerender.
  • Inspect the accessibility tree for computed roles, names, descriptions, states, positions, and relationships.
  • Confirm pointer or touch support does not replace required keyboard behavior.
  • Recheck state after validation errors, async updates, route changes, and reloads.

Static code cannot prove focus order or keyboard behavior. Automated accessibility scans cannot prove APG interaction conformance. If runtime or assistive-technology testing is unavailable, state that limitation instead of claiming a pass.

4. Classify results

  • Pass: All applicable required APG behavior was verified.
  • Fail: A required behavior is demonstrably missing or incorrect.
  • Partial: Static evidence exists, but required runtime behavior was not verified.
  • Not applicable: The pattern does not occur in scope.

Uses the shared severity ladder from output-templates: Critical for blocked access or an inescapable focus trap, High for missing core keyboard/focus/role/state behavior, Medium for a material but non-blocking mismatch, Low for optional enhancements or maintainability risks.

Output

Lead with confirmed findings:

## Findings

1. [High] `file:line` or route — Pattern — broken requirement.
   - Evidence:
   - User impact:
   - Smallest root-cause fix:

## Pattern Coverage

| Pattern | Instance | Static review | Runtime review | Verdict |
|---|---|---|---|---|

## Unverified Risks

- Required check and exact reason it could not be verified.

## Sources

- Current W3C pattern pages used for the review.

Do not claim screen-reader compatibility without testing a named browser, screen reader, and version. If there are no confirmed findings, say so and still show coverage and unverified risks.

Shared output profile

Compose the review profile from output-templates. Keep APG pattern coverage, evidence-backed findings, and unverified runtime risks explicit. Preserve stricter domain rules above, omit empty components, and never fill a component with invented evidence.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.