Skip to content
This repository is currently being migrated. It's locked while the migration is in progress.

Commit f20ab08

Browse files
amyleademamyleadem
authored
Merge pull request #6118 from department-of-veterans-affairs/5891-accessibility-test-library
Add accessibility test library
2 parents aa1c638 + 93dd74b commit f20ab08

26 files changed

Lines changed: 4680 additions & 147 deletions

‎.claude/skills/accessibility-tests/test-selection/SKILL.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
name: accessibility-test-selection
3+
description: Determines which accessibility tests from the test library apply to a VA Design System component based on its features and implementation.
4+
---
5+
6+
# Accessibility Test Selection
7+
8+
This skill helps identify which accessibility tests from the VA Design System test library apply to a specific component.
9+
10+
## Primary Documentation Source
11+
12+
All test selection rules, subtest priority guidelines, and component-type checklists are documented in:
13+
14+
**`src/_data/accessibility-tests/components/README.md`**
15+
16+
**Required reading sections:**
17+
- **Test Selection Guidelines** → **Subtest Preference Rule** — Rules for preferring specific subtests over parent tests, how to find subtests in YAML files
18+
- **Choosing tests by component type** — Complete category-by-category test checklists for all component types
19+
20+
## Additional Documentation
21+
22+
### Test Library Structure
23+
24+
Read these to understand test definitions, IDs, and configuration:
25+
26+
- **`src/_data/accessibility-tests/test-library/README.md`**
27+
- Test ID format and structure
28+
- WCAG mappings
29+
- Test categories and required environments
30+
- How to read test entries
31+
32+
- **`src/_data/accessibility-tests/test-library/_config.yml`**
33+
- Environment ID definitions (see `environments:` section)
34+
- Category definitions (see `categories:` section)
35+
- Required environments per category (e.g., `screen_reader`, `mobile`)
36+
37+
- **`src/_data/accessibility-tests/README.md`**
38+
- High-level overview of the test library
39+
- Directory structure
40+
- Links to related documentation
41+
42+
### Test Definition Files
43+
44+
Tests are organized by WCAG principle:
45+
46+
- `src/_data/accessibility-tests/test-library/1-perceivable.yml`
47+
- `src/_data/accessibility-tests/test-library/2-operable.yml`
48+
- `src/_data/accessibility-tests/test-library/3-understandable.yml`
49+
- `src/_data/accessibility-tests/test-library/4-robust.yml`
50+
51+
**To find subtests:** Open these YAML files and look for `subtests:` arrays under each parent test entry.
52+
53+
### Example Component Test Files
54+
55+
Reference these for patterns:
56+
- `src/_data/accessibility-tests/components/va-link.yml` — Simple interactive component
57+
- `src/_data/accessibility-tests/components/va-text-input.yml` — Form input
58+
- `src/_data/accessibility-tests/components/va-accordion.yml` — Dynamic content
59+
60+
## Agent workflow
61+
62+
When invoked to select tests for a component:
63+
64+
1. **Read the components README** at `src/_data/accessibility-tests/components/README.md`
65+
66+
2. **Follow the "Test Selection Guidelines" section**, which includes:
67+
- How to analyze your component
68+
- Subtest preference rule
69+
- Child component inheritance
70+
- Determining required test environments
71+
72+
3. **Apply the "Choosing tests by component type" guidelines** to select applicable tests based on component features
73+
74+
4. **Return the complete list** of test IDs:
75+
- Sorted numerically by test ID
76+
- No duplicates
77+
- Specific subtests used instead of parent tests where applicable
78+
- Include note about required environments for tests with `screen_reader` or `mobile` categories
79+
80+
## Related Prompts
81+
82+
- **Generate component test files**: `.github/prompts/accessibility-tests-generate-component-tests.prompt.md`
83+
- **Depends on this skill** — Calls this skill to select tests for a new component test file
84+
- Creates complete YAML test files with pre-populated metadata
85+
86+
- **Audit component test files**: `.github/prompts/accessibility-tests-audit.prompt.md`
87+
- **Depends on this skill** — Uses test selection guidelines to verify test coverage completeness
88+
- Reviews existing component test files for missing or incorrect tests
89+
90+
## File Paths Quick Reference
91+
92+
### Component Test Files
93+
- **Directory**: `src/_data/accessibility-tests/components/`
94+
- **Pattern**: `va-[component-name].yml`
95+
- **Examples**: `va-button.yml`, `va-text-input.yml`, `va-accordion.yml`
96+
97+
### Test Library Files
98+
- **Directory**: `src/_data/accessibility-tests/test-library/`
99+
- **Test definitions**:
100+
- `1-perceivable.yml` (WEB-1xx tests)
101+
- `2-operable.yml` (WEB-2xx tests)
102+
- `3-understandable.yml` (WEB-3xx tests)
103+
- `4-robust.yml` (WEB-4xx tests)
104+
- **Configuration**: `_config.yml` (environments, categories, required environments)
105+
- **README**: `README.md` (test structure, writing guidelines, WCAG mappings)
106+
107+
### Component Source Code
108+
- **Repository**: `https://github.com/department-of-veterans-affairs/component-library`
109+
- **Path**: `packages/web-components/src/components/`
110+
- **Pattern**: `va-[component-name]/va-[component-name].tsx`
111+
112+
## Implementation Notes
113+
114+
### When to Use This Skill
115+
116+
- Creating a new component test file
117+
- Reviewing an existing component test file for completeness
118+
- Answering "what tests should apply to this component?"
119+
- Auditing test coverage across components
120+
121+
### When NOT to Use This Skill
122+
123+
- **Test result recording** — Use components README "Recording Test Results" section instead
124+
- **Writing test library entries** — Use the writing-entries skill instead
125+
- **Understanding WCAG mappings** — Read test-library README directly
126+
- **Interpreting test results** — This skill selects tests, doesn't validate or interpret results
127+
128+
### Assumptions and Edge Cases
129+
130+
- **Component-specific context required**: Cannot select tests without knowing component features
131+
- **False positives preferred**: When uncertain, include the test (missing coverage is worse than extra tests)
132+
- **Child component inheritance**: Parent components should include all applicable tests from their children
133+
- **Implementation-dependent tests**: Some tests (e.g., `WEB-244` Link Purpose) may need to be marked "conditional" if they can only be tested in implementation context
134+
135+
### Output Format
136+
137+
When returning test selections, provide:
138+
139+
1. **Complete list of test IDs** (sorted numerically)
140+
2. **Category groupings** (optional, for readability) showing which category each test came from
141+
3. **Required environments note** for tests with `screen_reader` or `mobile` categories
142+
4. **Rationale** (brief) for why each test applies to the component
143+
144+
Example output:
145+
```
146+
Test IDs for va-button:
147+
148+
All components:
149+
- WEB-134 (Orientation)
150+
- WEB-1410 (Reflow)
151+
152+
Components with text:
153+
- WEB-143 (Contrast - Minimum)
154+
- WEB-144 (Resize Text)
155+
- WEB-1412 (Text Spacing)
156+
157+
All interactive elements:
158+
- VADS-211-002 (Keyboard - form inputs) [Note: button is technically a form control]
159+
- WEB-1411 (Non-text Contrast) [has subtests - check if specific ones apply]
160+
- WEB-212 (No Keyboard Trap)
161+
- WEB-243 (Focus Order)
162+
- WEB-247 (Focus Visible)
163+
- WEB-2411 (Focus Not Obscured)
164+
- VADS-253-001 (Label in Name - screen reader)
165+
- VADS-258-001 (Target Size - mobile) [required environments: android-chrome, ios-safari]
166+
- WEB-321 (On Focus)
167+
- WEB-412 (Name, Role, Value) [has subtests - check if specific ones apply]
168+
169+
Buttons:
170+
- WEB-412-002 (State announcements) — if button has state
171+
- WEB-412-003 (Proper element types)
172+
- VADS-412-002 (Button actions)
173+
174+
Total: [number] tests
175+
```
176+
177+
## Questions?
178+
179+
Contact the Design System team in [#platform-design-system](https://dsva.slack.com/archives/C01K37HRUAH) Slack channel.

‎.claude/skills/accessibility-tests/writing-entries/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: writing-test-library-entries
3+
description: Guidelines for writing accessibility test library entries including tests and subtests with proper descriptions and automation notes
4+
---
5+
6+
# Writing Test Library Entries
7+
8+
**Use this skill when:** Creating new test entries, editing existing test descriptions, or reviewing test library content for consistency.
9+
10+
**Test library files:**
11+
- `src/_data/accessibility-tests/test-library/1-perceivable.yml`
12+
- `src/_data/accessibility-tests/test-library/2-operable.yml`
13+
- `src/_data/accessibility-tests/test-library/3-understandable.yml`
14+
- `src/_data/accessibility-tests/test-library/4-robust.yml`
15+
- `src/_data/accessibility-tests/test-library/_config.yml`
16+
17+
## Complete Guidelines
18+
19+
All guidelines for writing and editing test library entries live in:
20+
21+
**`src/_data/accessibility-tests/test-library/README.md`**
22+
23+
Read the following sections before creating or editing entries:
24+
25+
- **Test Structure** — Required and optional fields for each test entry
26+
- **Writing Test and Subtest Entries** — Detailed guidelines for `description_short`, `description_full`, and `automation_notes` with good/bad examples
27+
- Subsections: description_short, description_full, automation_notes, Plain Language Principles, Finding Good Examples, Review Checklist
28+
- **Adding New Tests** — Step-by-step workflow for adding new test entries
29+
30+
## Key Reminders for AI Agents
31+
32+
1. **description_short**: Concise, plain language, present tense, no "When you..." format
33+
2. **description_full**: ALWAYS use "When you [action], you [result]" format
34+
3. **automation_notes**: Required for `full` and `partial` automation coverage; describe what can be automated and what requires manual testing
35+
4. **Validate YAML**: Ensure proper YAML syntax before saving changes
36+
5. **Cross-reference examples**: Check existing entries in the YAML files for patterns

‎.github/prompts/accessibility-tests-add-to-component-page.prompt.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# generate-accessibility-tests-section
2+
3+
Add the accessibility tests section to a component's documentation page. This displays test results from the component's test file on the public documentation site.
4+
5+
## Usage
6+
7+
### 1. Collect component information
8+
9+
Ask: "Which component would you like to add accessibility tests to? Please provide the component name with the `va-` prefix (e.g., `va-button`, `va-alert`)."
10+
11+
**Validate:**
12+
- Component name must start with `va-`
13+
- Component name must be lowercase kebab-case
14+
- Verify the component test file exists at `src/_data/accessibility-tests/components/[component-name].yml`
15+
- If test file doesn't exist, inform the user and suggest running `/accessibility-tests-generate-component-tests` first
16+
17+
### 2. Read the component documentation file
18+
19+
1. Open `src/_components/[component-name].md` (convert to kebab-case if needed, e.g., `va-text-input` → `text-input.md`)
20+
2. Parse the YAML front matter
21+
3. Identify existing sections in the markdown body
22+
23+
### 3. Update the YAML front matter
24+
25+
Add `- anchor: Accessibility tests` to the `anchors:` list in the front matter.
26+
27+
**Placement:**
28+
- After "Accessibility considerations" (if present)
29+
- Before "Related" or "Component checklist"
30+
- If neither of those exist, add at the end of the anchors list
31+
32+
### 4. Add the accessibility tests section to the markdown body
33+
34+
Add the following section to the markdown:
35+
36+
```markdown
37+
## Accessibility tests
38+
39+
{% include accessibility-test-results.html component_name="[component-name]" %}
40+
```
41+
42+
Replace `[component-name]` with the component's `web-component` value from the YAML front matter (e.g., `va-accordion`, `va-details`).
43+
44+
**Placement:**
45+
1. **If "Accessibility considerations" section exists**: Add immediately after it
46+
2. **If "Related" section exists but no accessibility considerations**: Add before "Related"
47+
3. **If neither exists**: Add before the component checklist include (e.g., `{% include component-docs/...`)
48+
4. **If none of the above**: Add at the end of the file before any trailing includes
49+
50+
### 5. Save and confirm
51+
52+
Save the updated component markdown file and display a summary:
53+
54+
```
55+
Added accessibility tests section to [component-name].md:
56+
- Added anchor to front matter
57+
- Added section after [section-name]
58+
- Using component_name: [web-component-value]
59+
```
60+
61+
## Resources
62+
63+
- **Generate Test File Prompt**: `.github/prompts/accessibility-tests-generate-component-tests.prompt.md`
64+
- **Update Metadata Prompt**: `.github/prompts/accessibility-tests-generate-metadata.prompt.md`
65+
- **Components README**: `src/_data/accessibility-tests/components/README.md#step-5-display-results-on-component-page` (detailed placement guidance)
66+
- **Component test files**: `src/_data/accessibility-tests/components/va-*.yml`
67+
- **Component documentation**: `src/_components/*.md`

0 commit comments

Comments
 (0)