dwmkerr / dwmkerr/effective-shell
[A11Y] [Low] External links missing accessible context
- Dominant language
- JavaScript
- Stars
- 780
- Forks
- 93
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 3
Description
## Accessibility Issue: External links missing accessible context
**WCAG Level:** A
**Severity:** Low
**Category:** Semantic HTML / ARIA Usage
### Issue Description
Several external links in the application open in new tabs (`target="_blank"`) but do not provide visual or accessible context to users that the link will open in a new window. Screen reader users may be confused when a new window opens unexpectedly.
### User Impact
- **Affected Users:** Screen reader users, users with cognitive disabilities
- **Severity:** Users may be confused when links open in new tabs without warning
### Violations Found
#### File: `src/components/AmazonBookPreview/index.tsx`
**Line:** 9
```tsx
Buy on Amazon
```
#### File: `src/components/ShellwrightRecording/ShellwrightRecording.tsx`
**Lines:** 21, 35
```tsx
Shellwright
```
#### File: `src/components/MigrationInProgress/index.tsx`
**Lines:** 9-10
```tsx
Amazon and{' '}
No Starch Press.
```
**Issue:** Links with `target="_blank"` should indicate they open in a new window, either visually (with an icon) or via accessible text.
---
### Recommended Fix
Option 1 - Add visually hidden text:
```tsx
Buy on Amazon
(opens in new tab)
```
Option 2 - Use aria-label:
```tsx
Buy on Amazon
```
Option 3 - Create a reusable ExternalLink component:
```tsx
interface ExternalLinkProps {
href: string;
children: React.ReactNode;
className?: string;
}
const ExternalLink: React.FC = ({ href, children, className }) => (
{children}
(opens in new tab)
{/* Optional visual indicator */}
);
```
**CSS for visually hidden class:**
```css
.visually-hidden {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
```
### Additional Instances
Files with external links that may need review:
- `src/pages/index.tsx` (Amazon, No Starch, GitHub links)
- Documentation pages with external references
### Testing Instructions
1. Enable a screen reader (NVDA, VoiceOver, JAWS)
2. Navigate to external links
3. Verify the screen reader announces that the link opens in a new tab
4. For visual users, consider adding an external link icon
### Resources
- [WCAG G201: Giving users advanced warning when opening a new window](https://www.w3.org/WAI/WCAG21/Techniques/general/G201)
- [WebAIM: Links and Hypertext](https://webaim.org/techniques/hypertext/hypertext_links#new_window)
### Acceptance Criteria
- [ ] External links indicate they open in new tabs
- [ ] Screen readers announce new tab behavior
- [ ] Consider adding visual external link icons
- [ ] Manual testing with screen reader completed
---
Contributor guide
Assessment
This issue has not been assessed yet.