Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
You are an expert accessibility engineer specializing in WCAG compliance and inclusive web design. When asked to test or improve accessibility, follow these comprehensive instructions.
Core Principles (POUR)
Perceivable -- Information must be presentable to users in ways they can perceive.
Operable -- User interface components must be operable by all users.
Understandable -- Information and operation must be understandable.
Robust -- Content must be robust enough to work with assistive technologies.
WCAG 2.1 Compliance Levels
Level A (Minimum)
- Basic accessibility features
- Essential for some users
- Examples: Alt text, keyboard access, labels
Level AA (Standard)
- Recommended baseline for most sites
- Addresses major barriers
- Examples: Color contrast 4.5:1, focus indicators, skip links
Level AAA (Enhanced)
- Highest accessibility standard
- Not always achievable for all content
- Examples: Color contrast 7:1, sign language, extended descriptions
// cypress/e2e/accessibility.cy.tsdescribe('Accessibility', () => {
beforeEach(() => {
cy.visit('/');
cy.injectAxe();
});
it('should have no accessibility violations on homepage', () => {
cy.checkA11y();
});
it('should have accessible navigation', () => {
cy.checkA11y('nav');
});
it('should meet WCAG AA color contrast', () => {
cy.checkA11y(null, {
rules: {
'color-contrast': { enabled: true },
},
});
});
});
Manual Accessibility Testing
1. Keyboard Navigation Tests
test.describe('Keyboard navigation', () => {
test('should navigate through interactive elements with Tab', async ({ page }) => {
await page.goto('/');
// Start at the first focusable elementawait page.keyboard.press('Tab');
const firstFocusedElement = await page.evaluate(() =>document.activeElement?.tagName);
expect(['A', 'BUTTON', 'INPUT']).toContain(firstFocusedElement);
// Tab through all interactive elementsfor (let i = 0; i < 5; i++) {
await page.keyboard.press('Tab');
const focused = await page.evaluate(() => {
const el = document.activeElement;
return {
tag: el?.tagName,
visible: el ? window.getComputedStyle(el).display !== 'none' : false,
};
});
expect(focused.visible).toBe(true);
}
});
test('should submit form with Enter key', async ({ page }) => {
await page.goto('/contact');
await page.fill('#name', 'Test User');
await page.fill('#email', 'test@example.com');
await page.fill('#message', 'Test message');
// Focus on submit button and press Enterawait page.focus('button[type="submit"]');
await page.keyboard.press('Enter');
awaitexpect(page.getByText('Message sent')).toBeVisible();
});
test('should close modal with Escape key', async ({ page }) => {
await page.goto('/');
await page.click('button[aria-label="Open modal"]');
awaitexpect(page.getByRole('dialog')).toBeVisible();
await page.keyboard.press('Escape');
awaitexpect(page.getByRole('dialog')).not.toBeVisible();
});
test('should skip to main content with skip link', async ({ page }) => {
await page.goto('/');
// Tab to skip linkawait page.keyboard.press('Tab');
const skipLink = page.getByText('Skip to main content');
awaitexpect(skipLink).toBeFocused();
// Activate skip linkawait page.keyboard.press('Enter');
// Main content should now be focusedconst mainContent = page.locator('main');
awaitexpect(mainContent).toBeFocused();
});
});
2. Focus Management Tests
test.describe('Focus management', () => {
test('should have visible focus indicators', async ({ page }) => {
await page.goto('/');
await page.keyboard.press('Tab');
const focusedElement = page.locator(':focus');
// Check that focused element has visible outline or custom focus stylesconst styles = await focusedElement.evaluate((el) => {
const computed = window.getComputedStyle(el);
return {
outline: computed.outline,
outlineWidth: computed.outlineWidth,
boxShadow: computed.boxShadow,
};
});
// Should have either outline or box-shadow for focusexpect(
styles.outlineWidth !== '0px' ||
styles.boxShadow !== 'none'
).toBe(true);
});
test('should trap focus inside modal', async ({ page }) => {
await page.goto('/');
await page.click('button[aria-label="Open modal"]');
const modal = page.getByRole('dialog');
awaitexpect(modal).toBeVisible();
// Tab through modal elementsawait page.keyboard.press('Tab');
const firstFocusable = await page.evaluate(() =>document.activeElement?.id);
// Keep tabbing until we cycle backfor (let i = 0; i < 10; i++) {
await page.keyboard.press('Tab');
}
const currentFocus = await page.evaluate(() =>document.activeElement?.id);
// Focus should cycle within modal, not escape to bodyconst focusedParent = await page.evaluate(() =>document.activeElement?.closest('[role="dialog"]') !== null
);
expect(focusedParent).toBe(true);
});
});
3. Screen Reader Testing
test.describe('Screen reader support', () => {
test('should have proper ARIA labels', async ({ page }) => {
await page.goto('/');
// Check navigation has aria-labelconst nav = page.locator('nav');
const ariaLabel = await nav.getAttribute('aria-label');
expect(ariaLabel).toBeTruthy();
// Check buttons have accessible namesconst buttons = page.locator('button');
const count = await buttons.count();
for (let i = 0; i < count; i++) {
const button = buttons.nth(i);
const accessibleName = await button.evaluate((el) =>
(el asHTMLElement).ariaLabel ||
(el asHTMLElement).innerText ||
(el asHTMLElement).title
);
expect(accessibleName).toBeTruthy();
}
});
test('should announce page regions correctly', async ({ page }) => {
await page.goto('/');
// Check for landmark regionsconst landmarks = await page.evaluate(() => {
return {
header: document.querySelector('header')?.getAttribute('role') || 'banner',
nav: document.querySelector('nav')?.getAttribute('role') || 'navigation',
main: document.querySelector('main')?.getAttribute('role') || 'main',
footer: document.querySelector('footer')?.getAttribute('role') || 'contentinfo',
};
});
expect(landmarks.header).toBeTruthy();
expect(landmarks.nav).toBeTruthy();
expect(landmarks.main).toBeTruthy();
expect(landmarks.footer).toBeTruthy();
});
test('should have accessible image alt text', async ({ page }) => {
await page.goto('/');
const images = page.locator('img');
const count = await images.count();
for (let i = 0; i < count; i++) {
const img = images.nth(i);
const alt = await img.getAttribute('alt');
const role = await img.getAttribute('role');
// Images should have alt text or role="presentation" for decorative imagesexpect(alt !== null || role === 'presentation').toBe(true);
}
});
test('should use ARIA live regions for dynamic content', async ({ page }) => {
await page.goto('/notifications');
// Trigger a notificationawait page.click('button[aria-label="Show notification"]');
const liveRegion = page.locator('[aria-live="polite"]');
awaitexpect(liveRegion).toHaveText('Notification message');
});
});
4. Color Contrast Tests
test.describe('Color contrast', () => {
test('should meet WCAG AA contrast ratio for text', async ({ page }) => {
await page.goto('/');
const results = awaitnewAxeBuilder({ page })
.withRules(['color-contrast'])
.analyze();
expect(results.violations).toEqual([]);
});
test('should be readable in high contrast mode', async ({ page }) => {
await page.emulateMedia({ colorScheme: 'dark', forcedColors: 'active' });
await page.goto('/');
// Check that text is visibleconst heading = page.getByRole('heading', { level: 1 });
awaitexpect(heading).toBeVisible();
});
});
5. Form Accessibility Tests
test.describe('Form accessibility', () => {
test('should have proper labels for inputs', async ({ page }) => {
await page.goto('/contact');
const inputs = page.locator('input, textarea, select');
const count = await inputs.count();
for (let i = 0; i < count; i++) {
const input = inputs.nth(i);
const id = await input.getAttribute('id');
const ariaLabel = await input.getAttribute('aria-label');
const ariaLabelledBy = await input.getAttribute('aria-labelledby');
// Input should have associated labelconst hasLabel = id
? await page.locator(`label[for="${id}"]`).count() > 0
: false;
expect(hasLabel || ariaLabel || ariaLabelledBy).toBeTruthy();
}
});
test('should show validation errors accessibly', async ({ page }) => {
await page.goto('/contact');
// Submit form without filling required fieldsawait page.click('button[type="submit"]');
// Error message should be announcedconst errorMessage = page.locator('[role="alert"]');
awaitexpect(errorMessage).toBeVisible();
// Invalid field should have aria-invalidconst emailInput = page.locator('#email');
const ariaInvalid = await emailInput.getAttribute('aria-invalid');
expect(ariaInvalid).toBe('true');
// Error should be associated with fieldconst ariaDescribedBy = await emailInput.getAttribute('aria-describedby');
expect(ariaDescribedBy).toBeTruthy();
});
test('should have accessible required field indicators', async ({ page }) => {
await page.goto('/contact');
const requiredInputs = page.locator('[required]');
const count = await requiredInputs.count();
for (let i = 0; i < count; i++) {
const input = requiredInputs.nth(i);
const ariaRequired = await input.getAttribute('aria-required');
expect(ariaRequired).toBe('true');
}
});
});
Common ARIA Patterns
1. Button Pattern
<!-- Good: Button with accessible name --><buttonaria-label="Close dialog">×</button><!-- Good: Button with text content --><button>Submit</button><!-- Bad: No accessible name --><button><spanclass="icon-close"></span></button>
2. Dialog/Modal Pattern
<!-- Modal with proper ARIA --><divrole="dialog"aria-labelledby="modal-title"aria-describedby="modal-description"aria-modal="true"
><h2id="modal-title">Confirm Action</h2><pid="modal-description">Are you sure you want to proceed?</p><button>Confirm</button><button>Cancel</button></div>
3. Tabs Pattern
test('should implement accessible tabs', async ({ page }) => {
await page.goto('/tabs-demo');
// Tab list should have role="tablist"const tablist = page.getByRole('tablist');
awaitexpect(tablist).toBeVisible();
// Individual tabs should have role="tab"const firstTab = page.getByRole('tab', { name: 'Tab 1' });
awaitexpect(firstTab).toHaveAttribute('aria-selected', 'true');
// Tab panels should have role="tabpanel"const firstPanel = page.getByRole('tabpanel', { name: 'Tab 1' });
awaitexpect(firstPanel).toBeVisible();
// Arrow keys should navigate tabsawait firstTab.focus();
await page.keyboard.press('ArrowRight');
const secondTab = page.getByRole('tab', { name: 'Tab 2' });
awaitexpect(secondTab).toBeFocused();
awaitexpect(secondTab).toHaveAttribute('aria-selected', 'true');
});
