Skip to content

thedaviddias/Front-End-Checklist / skills/audio-descriptions

audio-descriptions

Verified

Use when reviewing rendered HTML, interactive components, or design-system patterns related to Provide audio descriptions for video. Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant.

FileKindSize
SKILL.mdskill md2.1 KB
references/rule.mdmarkdown5.0 KB

references/rule.md

View on GitHub
# Provide audio descriptions for video

> Videos with important visual content include audio descriptions that narrate visual information for blind users.

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

---
Audio descriptions narrate visual information for users who cannot see the video content.

## Code Example

```html
<video controls>
  <source src="product-demo.mp4" type="video/mp4">

  <!-- Captions for deaf users -->
  <track kind="captions" src="captions-en.vtt" srclang="en" label="English">

  <!-- Audio descriptions for blind users -->
  <track kind="descriptions" src="descriptions-en.vtt" srclang="en" label="English Audio Description">
</video>
```

## Why It Matters

Blind users miss critical plot points, product demos, and on-screen information that's only shown visually—audio descriptions provide equal access to the complete experience.

## When Audio Descriptions Are Needed

| Visual Content | Needs Description? |
|----------------|-------------------|
| Character actions/reactions | Yes |
| Scene changes/locations | Yes |
| On-screen text/graphics | Yes |
| Facial expressions conveying emotion | Yes |
| Talking head with no visual action | No |
| Audio-only content (podcast) | No |

## VTT Description File Format

```vtt
WEBVTT

00:00:03.000 --> 00:00:06.000
A woman in business attire enters a modern office lobby.

00:00:15.000 --> 00:00:18.000
She approaches the reception desk where a man looks up from his computer.

00:00:32.000 --> 00:00:35.000
On-screen text reads: "Three months later"

00:01:05.000 --> 00:01:08.000
Close-up of her face showing concern as she reads the document.
```

## React Video Player with Descriptions

```tsx
interface VideoPlayerProps {
  src: string
  captions?: string
  descriptions?: string
  poster?: string
}

function AccessibleVideoPlayer({
  src,
  captions,
  descriptions,
  poster
}: VideoPlayerProps) {
  const [descriptionsEnabled, setDescriptionsEnabled] = useState(false)
  const videoRef = useRef
        <source src={src} type="video/mp4" />

        {captions && (
          <track
            kind="captions"
            src={captions}
            srcLang="en"
            label="English Captions"
            default
          />
        )}

        {descriptions && (
          <track
            kind="descriptions"
            src={descriptions}
            srcLang="en"
            label="Audio Description"
          />
        )}
      </video>

      {descriptions && (
        <button
          onClick={() => setDescriptionsEnabled(!descriptionsEnabled)}
          aria-pressed={descriptionsEnabled}
        >
          {descriptionsEnabled ? 'Disable' : 'Enable'} Audio Descriptions
        </button>
      )}

      <p id="video-description" className="sr-only">
        Video with audio descriptions available. Use the Audio Descriptions button to enable.
      </p>
    </div>
  )
}
```

## Alternative: Extended Description Video

```tsx
// Provide two versions of the video
function VideoWithDescriptionChoice({ standardSrc, extendedSrc }: {
  standardSrc: string
  extendedSrc: string
}) {
  const [useExtended, setUseExtended] = useState(false)

  return (
    <div>
      <div role="group" aria-label="Video version selection">
        <label>
          <input
            type="radio"
            name="video-version"
            checked={!useExtended}
            onChange={() => setUseExtended(false)}
          />
          Standard version
        </label>
        <label>
          <input
            type="radio"
            name="video-version"
            checked={useExtended}
            onChange={() => setUseExtended(true)}
          />
          Version with audio descriptions
        </label>
      </div>

      <video controls key={useExtended ? 'extended' : 'standard'}>
        <source src={useExtended ? extendedSrc : standardSrc} type="video/mp4" />
      </video>
    </div>
  )
}
```

## Writing Good Descriptions

```text
❌ Bad: "A person is there."
✅ Good: "Sarah enters the room looking worried."

❌ Bad: "Something happens on screen."
✅ Good: "The graph shows sales dropping 40% over three months."

❌ Bad: "He reacts."
✅ Good: "Marcus slams his fist on the table in frustration."
```

## Exceptions

- Logos, purely decorative text treatments, and screenshots used as documentation can be valid exceptions when their accessible alternative is still provided appropriately.
- An image or media rule should not force redundant alt text, captions, or transcripts when another nearby mechanism already provides the equivalent information clearly.
- If the media asset fails more than one rule, prioritize the issue that most directly blocks understanding for assistive technology users.

## Verification

### Automated Checks

- Use browser accessibility tooling, axe, Lighthouse, or equivalent automated checks against a representative rendered state.

### Manual Checks

- Watch video with eyes closed—can you follow the story?
- Verify description track appears in player controls
- Check descriptions fit in gaps between dialogue
- Ensure descriptions don't overlap important audio
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