Skip to content

thedaviddias/Front-End-Checklist / skills/video-accessibility

video-accessibility

Verified

Use when reviewing templates, rendered HTML, or shared components related to Make videos accessible with captions. Validate the final browser-facing markup, not just the source framework abstraction.

FileKindSize
SKILL.mdskill md1.9 KB
references/rule.mdmarkdown9.2 KB

references/rule.md

View on GitHub
# Make videos accessible with captions

> Videos have captions, audio descriptions, transcripts, pause controls, and avoid autoplay for users with hearing, vision, or cognitive impairments.

**Priority:** high · **Difficulty:** intermediate · **Time:** 30 min

---
Accessible videos ensure all users can understand and interact with video content.

## Code Example

```html
<figure>
  <video
    controls
    preload="metadata"
    poster="thumbnail.jpg"
    aria-describedby="video-description"
  >
    <source src="video.mp4" type="video/mp4" />
    <source src="video.webm" type="video/webm" />

    <!-- Captions (for deaf/hard of hearing) -->
    <track
      kind="captions"
      src="captions-en.vtt"
      srclang="en"
      label="English captions"
      default
    />
    <track
      kind="captions"
      src="captions-es.vtt"
      srclang="es"
      label="Spanish captions"
    />

    <!-- Audio descriptions (for blind users) -->
    <track
      kind="descriptions"
      src="descriptions-en.vtt"
      srclang="en"
      label="English audio descriptions"
    />

    <!-- Fallback -->
    <p>
      Your browser doesn't support HTML5 video.
      <a href="video.mp4">Download the video</a>.
    </p>
  </video>

  <figcaption id="video-description">
    Product demonstration showing how to use the dashboard features.
  </figcaption>
</figure>
```

## Why It Matters

Videos without captions exclude deaf and hard-of-hearing users, while videos without audio descriptions exclude blind users from understanding visual content.

## Accessibility Requirements

| Requirement | Implementation |
|-------------|----------------|
| Captions | `<track kind="captions">` for deaf users |
| Audio descriptions | `<track kind="descriptions">` for blind users |
| Transcript | Text alternative for video content |
| Keyboard controls | Accessible play/pause/seek |
| No autoplay | Prevent unwanted playback |

Auto-generated captions are a starting point, not a finished accessibility deliverable. Review them for speaker names, punctuation, technical terms, and meaningful sound effects.

## Caption File Format (WebVTT)

```vtt
WEBVTT

00:00:00.000 --> 00:00:04.000
Welcome to our product demonstration.

00:00:04.500 --> 00:00:08.000
Today we'll show you the key features
of the dashboard.

00:00:08.500 --> 00:00:12.000
[Background music playing]

00:00:12.500 --> 00:00:16.000
First, let's look at the navigation menu.
```

Include non-speech audio such as `[applause]`, `[laughter]`, or `[door closes]` when it changes understanding.

## React Video Component

```tsx

interface VideoTrack {
  kind: 'captions' | 'descriptions' | 'subtitles'
  src: string
  srclang: string
  label: string
  default?: boolean
}

interface AccessibleVideoProps {
  src: string
  poster?: string
  title: string
  description?: string
  tracks?: VideoTrack[]
  transcript?: string
}

  src,
  poster,
  title,
  description,
  tracks = [],
  transcript
}: AccessibleVideoProps) {
  const videoRef = useRef(null)
  const [isPlaying, setIsPlaying] = useState(false)
  const [showTranscript, setShowTranscript] = useState(false)

  // Prevent spacebar from scrolling page
  useEffect(() => {
    const video = videoRef.current
    if (!video) return

    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === ' ' && document.activeElement === video) {
        e.preventDefault()
        if (video.paused) {
          video.play()
        } else {
          video.pause()
        }
      }
    }

    video.addEventListener('keydown', handleKeyDown)
    return () => video.removeEventListener('keydown', handleKeyDown)
  }, [])

  const togglePlay = () => {
    const video = videoRef.current
    if (!video) return

    if (video.paused) {
      video.play()
      setIsPlaying(true)
    } else {
      video.pause()
      setIsPlaying(false)
    }
  }

  return (
    <div className="video-container">
      <figure>
        <video
          ref={videoRef}
          controls
          preload="metadata"
          poster={poster}
          aria-label={title}
          onPlay={() => setIsPlaying(true)}
          onPause={() => setIsPlaying(false)}
        >
          <source src={src} type="video/mp4" />

          {tracks.map((track, index) => (
            <track
              key={index}
              kind={track.kind}
              src={track.src}
              srcLang={track.srclang}
              label={track.label}
              default={track.default}
            />
          ))}
        </video>

        {description && (
          <figcaption className="video-description">
            {description}
          </figcaption>
        )}
      </figure>

      {/* Custom accessible controls */}
      <div className="video-controls" role="group" aria-label="Video controls">
        <button
          type="button"
          onClick={togglePlay}
          aria-label={isPlaying ? 'Pause video' : 'Play video'}
        >
          {isPlaying ? '⏸ Pause' : '▶ Play'}
        </button>
      </div>

      {/* Transcript toggle */}
      {transcript && (
        <div className="video-transcript">
          <button
            type="button"
            onClick={() => setShowTranscript(!showTranscript)}
            aria-expanded={showTranscript}
            aria-controls="transcript"
          >
            {showTranscript ? 'Hide' : 'Show'} Transcript
          </button>

          {showTranscript && (
            <div id="transcript" className="transcript-content">
              {transcript}
            </div>
          )}
        </div>
      )}
    </div>
  )
}
```

## Usage

```tsx

```

## Video with Reduced Motion Support

```tsx
function ResponsiveVideo({ src, poster }: { src: string; poster: string }) {
  const [shouldAutoplay, setShouldAutoplay] = useState(false)

  useEffect(() => {
    const prefersReducedMotion = window.matchMedia(
      '(prefers-reduced-motion: reduce)'
    ).matches

    setShouldAutoplay(!prefersReducedMotion)
  }, [])

  return (
    <video
      controls
      poster={poster}
      autoPlay={shouldAutoplay}
      muted={shouldAutoplay} // Autoplay requires muted
      loop={shouldAutoplay}
    >
      <source src={src} type="video/mp4" />
    </video>
  )
}
```

## Embedded Videos (YouTube/Vimeo)

Third-party players do not remove your accessibility responsibility.

- Verify captions are available and accurate, not only auto-generated.
- Provide a transcript link when the player makes transcript discovery difficult.
- Confirm keyboard users can reach pause, captions, and volume controls.
- Avoid autoplay with sound on embeds even when the provider allows it.

```tsx
interface EmbeddedVideoProps {
  videoId: string
  title: string
  provider: 'youtube' | 'vimeo'
}

  const src = provider === 'youtube'
    ? `https://www.youtube-nocookie.com/embed/${videoId}?cc_load_policy=1`
    : `https://player.vimeo.com/video/${videoId}?texttrack=en`

  return (
    <div className="video-embed">
      <iframe
        src={src}
        title={title}
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
        allowFullScreen
        loading="lazy"
      />
    </div>
  )
}
```

## Caption Best Practices

| Do | Don't |
|----|-------|
| Include speaker identification | Rely on auto-generated captions |
| Describe relevant sounds [door slams] | Censor or summarize dialogue |
| Sync captions with speech | Use all caps for entire captions |
| Include music descriptions [upbeat music] | Overlap captions with visuals |

If the narration does not explain important on-screen actions, pair captions with audio descriptions or a detailed transcript.
| Keep lines short (32-40 characters) | Leave sounds undescribed |

## Styling

```css
.video-container {
  max-width: 800px;
  margin: 0 auto;
}

.video-container video {
  width: 100%;
  display: block;
}

.video-description {
  font-size: 0.875rem;
  color: #666;
  margin-top: 0.5rem;
}

.video-controls {
  display: flex;
  gap: 0.5rem;
  margin-top: 0.5rem;
}

.video-controls button {
  padding: 0.5rem 1rem;
  background: #333;
  color: #fff;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.video-controls button:focus-visible {
  outline: 2px solid #0066cc;
  outline-offset: 2px;
}

.video-transcript button {
  margin-top: 1rem;
  padding: 0.5rem 1rem;
  background: #f5f5f5;
  border: 1px solid #ddd;
  border-radius: 4px;
  cursor: pointer;
}

.transcript-content {
  margin-top: 1rem;
  padding: 1rem;
  background: #f9f9f9;
  border-radius: 4px;
  max-height: 300px;
  overflow-y: auto;
}

/* Responsive embed */
.video-embed {
  position: relative;
  padding-bottom: 56.25%; /* 16:9 */
  height: 0;
  overflow: hidden;
}

.video-embed iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: 0;
}
```

## Verification

1. Verify captions display correctly and are synchronized
2. Test audio descriptions are available and accurate
3. Check transcript is complete and accessible
4. Verify keyboard controls work (space to pause)
5. Test with screen reader (video title announced)
6. Confirm no autoplay with sound
7. Check prefers-reduced-motion is respected

Auto-generated captions from YouTube or other platforms are often inaccurate. WCAG requires captions to be accurate. Always review and edit auto-generated captions or provide professional captions.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall