Add accessibility test library

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

@@ -0,0 +1,179 @@
+---
+name: accessibility-test-selection
+description: Determines which accessibility tests from the test library apply to a VA Design System component based on its features and implementation.
+---
+
+# Accessibility Test Selection
+
+This skill helps identify which accessibility tests from the VA Design System test library apply to a specific component.
+
+## Primary Documentation Source
+
+All test selection rules, subtest priority guidelines, and component-type checklists are documented in:
+
+**`src/_data/accessibility-tests/components/README.md`**
+
+**Required reading sections:**
+- **Test Selection Guidelines** → **Subtest Preference Rule** — Rules for preferring specific subtests over parent tests, how to find subtests in YAML files
+- **Choosing tests by component type** — Complete category-by-category test checklists for all component types
+
+## Additional Documentation
+
+### Test Library Structure
+
+Read these to understand test definitions, IDs, and configuration:
+
+- **`src/_data/accessibility-tests/test-library/README.md`**
+  - Test ID format and structure
+  - WCAG mappings
+  - Test categories and required environments
+  - How to read test entries
+
+- **`src/_data/accessibility-tests/test-library/_config.yml`**
+  - Environment ID definitions (see `environments:` section)
+  - Category definitions (see `categories:` section)
+  - Required environments per category (e.g., `screen_reader`, `mobile`)
+
+- **`src/_data/accessibility-tests/README.md`**
+  - High-level overview of the test library
+  - Directory structure
+  - Links to related documentation
+
+### Test Definition Files
+
+Tests are organized by WCAG principle:
+
+- `src/_data/accessibility-tests/test-library/1-perceivable.yml`
+- `src/_data/accessibility-tests/test-library/2-operable.yml`
+- `src/_data/accessibility-tests/test-library/3-understandable.yml`
+- `src/_data/accessibility-tests/test-library/4-robust.yml`
+
+**To find subtests:** Open these YAML files and look for `subtests:` arrays under each parent test entry.
+
+### Example Component Test Files
+
+Reference these for patterns:
+- `src/_data/accessibility-tests/components/va-link.yml` — Simple interactive component
+- `src/_data/accessibility-tests/components/va-text-input.yml` — Form input
+- `src/_data/accessibility-tests/components/va-accordion.yml` — Dynamic content
+
+## Agent workflow
+
+When invoked to select tests for a component:
+
+1. **Read the components README** at `src/_data/accessibility-tests/components/README.md`
+
+2. **Follow the "Test Selection Guidelines" section**, which includes:
+   - How to analyze your component
+   - Subtest preference rule
+   - Child component inheritance
+   - Determining required test environments
+
+3. **Apply the "Choosing tests by component type" guidelines** to select applicable tests based on component features
+
+4. **Return the complete list** of test IDs:
+   - Sorted numerically by test ID
+   - No duplicates
+   - Specific subtests used instead of parent tests where applicable
+   - Include note about required environments for tests with `screen_reader` or `mobile` categories
+
+## Related Prompts
+
+- **Generate component test files**: `.github/prompts/accessibility-tests-generate-component-tests.prompt.md`
+  - **Depends on this skill** — Calls this skill to select tests for a new component test file
+  - Creates complete YAML test files with pre-populated metadata
+
+- **Audit component test files**: `.github/prompts/accessibility-tests-audit.prompt.md`
+  - **Depends on this skill** — Uses test selection guidelines to verify test coverage completeness
+  - Reviews existing component test files for missing or incorrect tests
+
+## File Paths Quick Reference
+
+### Component Test Files
+- **Directory**: `src/_data/accessibility-tests/components/`
+- **Pattern**: `va-[component-name].yml`
+- **Examples**: `va-button.yml`, `va-text-input.yml`, `va-accordion.yml`
+
+### Test Library Files
+- **Directory**: `src/_data/accessibility-tests/test-library/`
+- **Test definitions**:
+  - `1-perceivable.yml` (WEB-1xx tests)
+  - `2-operable.yml` (WEB-2xx tests)
+  - `3-understandable.yml` (WEB-3xx tests)
+  - `4-robust.yml` (WEB-4xx tests)
+- **Configuration**: `_config.yml` (environments, categories, required environments)
+- **README**: `README.md` (test structure, writing guidelines, WCAG mappings)
+
+### Component Source Code
+- **Repository**: `https://github.com/department-of-veterans-affairs/component-library`
+- **Path**: `packages/web-components/src/components/`
+- **Pattern**: `va-[component-name]/va-[component-name].tsx`
+
+## Implementation Notes
+
+### When to Use This Skill
+
+- Creating a new component test file
+- Reviewing an existing component test file for completeness
+- Answering "what tests should apply to this component?"
+- Auditing test coverage across components
+
+### When NOT to Use This Skill
+
+- **Test result recording** — Use components README "Recording Test Results" section instead
+- **Writing test library entries** — Use the writing-entries skill instead
+- **Understanding WCAG mappings** — Read test-library README directly
+- **Interpreting test results** — This skill selects tests, doesn't validate or interpret results
+
+### Assumptions and Edge Cases
+
+- **Component-specific context required**: Cannot select tests without knowing component features
+- **False positives preferred**: When uncertain, include the test (missing coverage is worse than extra tests)
+- **Child component inheritance**: Parent components should include all applicable tests from their children
+- **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
+
+### Output Format
+
+When returning test selections, provide:
+
+1. **Complete list of test IDs** (sorted numerically)
+2. **Category groupings** (optional, for readability) showing which category each test came from
+3. **Required environments note** for tests with `screen_reader` or `mobile` categories
+4. **Rationale** (brief) for why each test applies to the component
+
+Example output:
+```
+Test IDs for va-button:
+
+All components:
+- WEB-134 (Orientation)
+- WEB-1410 (Reflow)
+
+Components with text:
+- WEB-143 (Contrast - Minimum)
+- WEB-144 (Resize Text)
+- WEB-1412 (Text Spacing)
+
+All interactive elements:
+- VADS-211-002 (Keyboard - form inputs) [Note: button is technically a form control]
+- WEB-1411 (Non-text Contrast) [has subtests - check if specific ones apply]
+- WEB-212 (No Keyboard Trap)
+- WEB-243 (Focus Order)
+- WEB-247 (Focus Visible)
+- WEB-2411 (Focus Not Obscured)
+- VADS-253-001 (Label in Name - screen reader)
+- VADS-258-001 (Target Size - mobile) [required environments: android-chrome, ios-safari]
+- WEB-321 (On Focus)
+- WEB-412 (Name, Role, Value) [has subtests - check if specific ones apply]
+
+Buttons:
+- WEB-412-002 (State announcements) — if button has state
+- WEB-412-003 (Proper element types)
+- VADS-412-002 (Button actions)
+
+Total: [number] tests
+```
+
+## Questions?
+
+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

@@ -0,0 +1,36 @@
+---
+name: writing-test-library-entries
+description: Guidelines for writing accessibility test library entries including tests and subtests with proper descriptions and automation notes
+---
+
+# Writing Test Library Entries
+
+**Use this skill when:** Creating new test entries, editing existing test descriptions, or reviewing test library content for consistency.
+
+**Test library files:**
+- `src/_data/accessibility-tests/test-library/1-perceivable.yml`
+- `src/_data/accessibility-tests/test-library/2-operable.yml`
+- `src/_data/accessibility-tests/test-library/3-understandable.yml`
+- `src/_data/accessibility-tests/test-library/4-robust.yml`
+- `src/_data/accessibility-tests/test-library/_config.yml`
+
+## Complete Guidelines
+
+All guidelines for writing and editing test library entries live in:
+
+**`src/_data/accessibility-tests/test-library/README.md`**
+
+Read the following sections before creating or editing entries:
+
+- **Test Structure** — Required and optional fields for each test entry
+- **Writing Test and Subtest Entries** — Detailed guidelines for `description_short`, `description_full`, and `automation_notes` with good/bad examples
+  - Subsections: description_short, description_full, automation_notes, Plain Language Principles, Finding Good Examples, Review Checklist
+- **Adding New Tests** — Step-by-step workflow for adding new test entries
+
+## Key Reminders for AI Agents
+
+1. **description_short**: Concise, plain language, present tense, no "When you..." format
+2. **description_full**: ALWAYS use "When you [action], you [result]" format
+3. **automation_notes**: Required for `full` and `partial` automation coverage; describe what can be automated and what requires manual testing
+4. **Validate YAML**: Ensure proper YAML syntax before saving changes
+5. **Cross-reference examples**: Check existing entries in the YAML files for patterns

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

@@ -0,0 +1,67 @@
+# generate-accessibility-tests-section
+
+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.
+
+## Usage
+
+### 1. Collect component information
+
+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`)."
+
+**Validate:**
+- Component name must start with `va-`
+- Component name must be lowercase kebab-case
+- Verify the component test file exists at `src/_data/accessibility-tests/components/[component-name].yml`
+- If test file doesn't exist, inform the user and suggest running `/accessibility-tests-generate-component-tests` first
+
+### 2. Read the component documentation file
+
+1. Open `src/_components/[component-name].md` (convert to kebab-case if needed, e.g., `va-text-input` → `text-input.md`)
+2. Parse the YAML front matter
+3. Identify existing sections in the markdown body
+
+### 3. Update the YAML front matter
+
+Add `- anchor: Accessibility tests` to the `anchors:` list in the front matter.
+
+**Placement:**
+- After "Accessibility considerations" (if present)
+- Before "Related" or "Component checklist"
+- If neither of those exist, add at the end of the anchors list
+
+### 4. Add the accessibility tests section to the markdown body
+
+Add the following section to the markdown:
+
+```markdown
+## Accessibility tests
+
+{% include accessibility-test-results.html component_name="[component-name]" %}
+```
+
+Replace `[component-name]` with the component's `web-component` value from the YAML front matter (e.g., `va-accordion`, `va-details`).
+
+**Placement:**
+1. **If "Accessibility considerations" section exists**: Add immediately after it
+2. **If "Related" section exists but no accessibility considerations**: Add before "Related"
+3. **If neither exists**: Add before the component checklist include (e.g., `{% include component-docs/...`)
+4. **If none of the above**: Add at the end of the file before any trailing includes
+
+### 5. Save and confirm
+
+Save the updated component markdown file and display a summary:
+
+```
+Added accessibility tests section to [component-name].md:
+- Added anchor to front matter
+- Added section after [section-name]
+- Using component_name: [web-component-value]
+```
+
+## Resources
+
+- **Generate Test File Prompt**: `.github/prompts/accessibility-tests-generate-component-tests.prompt.md`
+- **Update Metadata Prompt**: `.github/prompts/accessibility-tests-generate-metadata.prompt.md`
+- **Components README**: `src/_data/accessibility-tests/components/README.md#step-5-display-results-on-component-page` (detailed placement guidance)
+- **Component test files**: `src/_data/accessibility-tests/components/va-*.yml`
+- **Component documentation**: `src/_components/*.md`