Captions Toggle

name: "Captions Toggle"
short_description: A CC on/off control with an optional language menu for video captions.
long_visual_description: >
  A small CC button that highlights in the primary colour when captions are on; a
  right-click (or secondary) opens a compact language menu of available caption tracks.

use_cases:
  - Toggle subtitles/captions on a video player.
  - Switch caption language on a stream.
  - Enable accessibility captions in a media UI.
  - Choose from multiple subtitle tracks.
  - Control CC in a custom player control bar.

recommended_for:
  - A captions on/off control within a video player, with language choice.
avoid_for:
  - Full subtitle settings panels (build a dedicated dialog).

markets:
  - Global

example_usage: >
  Place in the player control bar; reflect the on/off state with aria-pressed and offer
  the available languages. Listen for captions:toggle and captions:language.

props:
  enabled: Whether captions are currently on.
  language: The current caption language label.
  languages: The available caption tracks.

example_prompts:
  - "Add a CC toggle with English, Spanish, and French tracks."
  - "Add a captions on/off button to the player."

lifecycle: experimental
content_model: A CC toggle state and a list of available caption languages.

theming:
  tokens_used:
    - --color-surface
    - --color-surface-raised
    - --color-on-surface
    - --color-primary
    - --color-border
    - --radius-control
    - --radius-card
    - --shadow-raised
    - --duration-token

editorial_guidance: >
  Show languages in their own names; keep the CC label standard so it's recognizable.

categorization:
  category: Video
  subcategory: Players
  atomic_type: atom
  usage_type: [media]
  maturity: ai-generated
  wcag:
    level: AA
    notes: The toggle uses aria-pressed; the language menu uses role="menu"/"menuitemradio". A production build should also open the language menu from a keyboard path, not only right-click.
  keyboard_support: Toggle activates on Enter/Space. The language menu currently opens via secondary (right) click.
  seo_score: 15
  text_direction: both