CtrlK
BlogDocsLog inGet started
Tessl Logo

testland/aria-authoring-patterns

Reference for the W3C ARIA Authoring Practices Guide (APG) - covers the 31 canonical interactive-widget patterns (Combobox, Dialog, Menu, Tabs, Tree, etc.), their required ARIA roles and states, the keyboard-interaction model per pattern, and the canonical-violations to watch for. Use when authoring a custom interactive widget that doesn't have a native HTML equivalent, or when reviewing one for ARIA correctness.

69

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Overview
Quality
Evals
Security
Files

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-organized reference with executable code and dense failure→fix tables, and no wasted prose. Its main structural weakness is that everything lives in SKILL.md itself — per-pattern detail and the state/failure references belong in a references/ bundle to keep the main file a lean overview — and there is no explicit verification step for reviewing an authored widget.

Suggestions

Split the per-pattern essentials (Combobox/Tabs/Disclosure/Tooltip code plus required-ARIA tables) and the 'ARIA states reference' table into references/patterns.md and references/states.md, leaving SKILL.md as a lean overview with well-signaled one-level-deep pointers (e.g. 'See [patterns.md](references/patterns.md) for per-pattern code').

Trim content Claude already knows — e.g. the 'Common ARIA failures' and 'Anti-patterns' tables largely restate standard ARIA knowledge (positive tabindex, aria-hidden on focusable elements, aria-label overriding visible text); keep only the non-obvious entries.

Add an explicit review-checkpoint step, e.g. a short 'Reviewing a widget' checklist: (1) is a native element possible? (2) does it match an APG pattern exactly? (3) run the failures/anti-patterns tables as a checklist, optionally verifying programmatically with axe-a11y.

DimensionReasoningScore

Conciseness

The body is dense and table-driven with compact, load-bearing code (no padded prose), but the 31-pattern catalog partially duplicates the 'first rule of ARIA' native-fallback table, and the failures/anti-patterns tables restate knowledge Claude already has (e.g. positive 'tabindex="3"' is fragile, 'aria-hidden' on a focusable element is broken). Matches the score-4 anchor (efficient, minor instances of over-explanation that could be trimmed) rather than score 5.

4 / 5

Actionability

Copy-paste-ready HTML for Combobox, Tabs, Disclosure, and Tooltip, each paired with a required-ARIA/keyboard-behavior table, plus concrete failure→fix and anti-pattern→fix pairs covering the common cases. Fully executable and specific, matching the score-5 anchor rather than score 4 (no significant gaps in the guidance given).

5 / 5

Workflow Clarity

A coherent implicit sequence is present — prefer native HTML ('When the visual design demands a custom widget, follow the matching APG pattern exactly'), apply the per-pattern essentials, then check the 'Common ARIA failures' and 'Anti-patterns' tables — but no explicit validation checkpoint (e.g. a review checklist step) for verifying an authored widget. Matches the score-4 anchor (clear sequence, most checkpoints present, minor gaps), not score 5.

4 / 5

Progressive Disclosure

The skill is well-sectioned with clear headers, but there are no bundle files at all: the 31-pattern catalog, per-pattern code, the ARIA states reference, and the failure tables are all inlined in a ~240-line SKILL.md. This matches the score-3 anchor (good structure, but content that should be separate — the per-pattern essentials — is inline) rather than score 4, which requires well-signaled one-level-deep references into actual bundle files.

3 / 5

Total

16

/

20

Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: third-person, concrete, comprehensive on 'what', and explicit on 'when' with actionable trigger phrases. Its only weakness is missing common synonyms ('accessibility', 'a11y', 'screen reader', 'WAI-ARIA') that a user might naturally say when needing this skill.

DimensionReasoningScore

Specificity

Enumerates multiple concrete capabilities — 'covers the 31 canonical interactive-widget patterns (Combobox, Dialog, Menu, Tabs, Tree, etc.)', 'their required ARIA roles and states', 'the keyboard-interaction model per pattern', and 'the canonical-violations to watch for' — comprehensive and specific rather than vague. This matches the score-5 anchor (multiple specific concrete actions, comprehensive coverage) and not score 4, since there are no coverage gaps in describing what the skill provides.

5 / 5

Completeness

Explicitly answers both 'what' (covers the 31 patterns, required ARIA roles and states, keyboard-interaction model, canonical violations) and 'when' with concrete trigger phrases ('Use when authoring a custom interactive widget that doesn't have a native HTML equivalent, or when reviewing one for ARIA correctness'). Matches the score-5 anchor exactly; not score 4 because the 'when' clause is already explicit and specific.

5 / 5

Trigger Term Quality

Good natural keyword coverage — 'authoring a custom interactive widget', 'reviewing one for ARIA correctness', and concrete pattern names (Combobox, Dialog, Menu, Tabs, Tree) users would say — but common synonyms like 'accessibility', 'a11y', 'screen reader', or 'WAI-ARIA' are absent. Matches the score-4 anchor (good coverage, a few natural terms missing) rather than score 5, which requires synonym-level coverage.

4 / 5

Distinctiveness Conflict Risk

Clear niche — the W3C APG patterns for custom widgets — with distinct triggers; the 'doesn't have a native HTML equivalent' qualifier scopes it away from generic accessibility-audit or contrast-checking skills. Minimal conflict risk, matching the score-5 anchor rather than score 4's 'minor overlap risk with closely related skills'.

5 / 5

Total

19

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 3 missing

Warning

Total

15

/

16

Passed

Reviewed

Table of Contents