♿️(frontend) improve aria-label with accessible emoji description

replace raw emoji with descriptive label to enhance screen reader support

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to
 - ♿️(frontend) add accessible back button in side panel #881
 - ♿️(frontend) improve participants toggle a11y label #880
 - ♿️(frontend) make carousel image decorative #871
+- ♿️(frontend) reactions are now vocalized and configurable #849
 
 ### Fixed
 

src/frontend/src/features/rooms/livekit/components/ReactionPortal.tsx

@@ -5,6 +5,9 @@ import { css } from '@/styled-system/css'
 import { Participant } from 'livekit-client'
 import { useTranslation } from 'react-i18next'
 import { Reaction } from '@/features/rooms/livekit/components/controls/ReactionsToggle'
+import { getEmojiLabel } from '@/features/rooms/livekit/utils/reactionUtils'
+import { accessibilityStore } from '@/stores/accessibility'
+import { useSnapshot } from 'valtio'
 
 export const ANIMATION_DURATION = 3000
 export const ANIMATION_DISTANCE = 300
@@ -140,11 +143,53 @@ export function ReactionPortal({
   )
 }
 
-export const ReactionPortals = ({ reactions }: { reactions: Reaction[] }) =>
-  reactions.map((instance) => (
-    <ReactionPortal
-      key={instance.id}
-      emoji={instance.emoji}
-      participant={instance.participant}
-    />
-  ))
+export const ReactionPortals = ({ reactions }: { reactions: Reaction[] }) => {
+  const { t } = useTranslation('rooms', { keyPrefix: 'controls.reactions' })
+  const { announceReactions } = useSnapshot(accessibilityStore)
+  const [announcement, setAnnouncement] = useState<string | null>(null)
+  const [lastAnnouncedId, setLastAnnouncedId] = useState<number | null>(null)
+
+  const latestReaction =
+    reactions.length > 0 ? reactions[reactions.length - 1] : undefined
+
+  useEffect(() => {
+    if (!announceReactions) {
+      setAnnouncement(null)
+      return
+    }
+    if (!latestReaction) return
+    const isNewReaction = latestReaction.id !== lastAnnouncedId
+    if (!isNewReaction) return
+
+    const emojiLabel = getEmojiLabel(latestReaction.emoji, t)
+    const participantName = latestReaction.participant?.isLocal
+      ? t('you')
+      : latestReaction.participant?.name?.trim() ||
+        t('someone', { defaultValue: 'Someone' })
+    setAnnouncement(t('announce', { name: participantName, emoji: emojiLabel }))
+    setLastAnnouncedId(latestReaction.id)
+
+    const timer = setTimeout(() => setAnnouncement(null), 1200)
+    return () => clearTimeout(timer)
+  }, [latestReaction, lastAnnouncedId, announceReactions, t])
+
+  return (
+    <>
+      {reactions.map((instance) => (
+        <ReactionPortal
+          key={instance.id}
+          emoji={instance.emoji}
+          participant={instance.participant}
+        />
+      ))}
+      <div
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        className="sr-only"
+      >
+        {announcement ?? ''}
+      </div>
+    </>
+  )
+}

src/frontend/src/features/rooms/livekit/components/controls/ReactionsToggle.tsx

@@ -10,6 +10,7 @@ import {
   ANIMATION_DURATION,
   ReactionPortals,
 } from '@/features/rooms/livekit/components/ReactionPortal'
+import { getEmojiLabel } from '@/features/rooms/livekit/utils/reactionUtils'
 import { Toolbar as RACToolbar } from 'react-aria-components'
 import { Participant } from 'livekit-client'
 import useRateLimiter from '@/hooks/useRateLimiter'
@@ -145,7 +146,7 @@ export const ReactionsToggle = () => {
                 <Button
                   key={index}
                   onPress={() => debouncedSendReaction(emoji)}
-                  aria-label={t('send', { emoji })}
+                  aria-label={t('send', { emoji: getEmojiLabel(emoji, t) })}
                   variant="primaryTextDark"
                   size="sm"
                   square

src/frontend/src/features/rooms/livekit/utils/reactionUtils.ts

@@ -0,0 +1,24 @@
+import { useTranslation } from 'react-i18next'
+
+export const getEmojiLabel = (
+  emoji: string,
+  t: ReturnType<typeof useTranslation>['t']
+) => {
+  const emojiLabels: Record<string, string> = {
+    'thumbs-up': t('emojis.thumbs-up', { defaultValue: 'thumbs up' }),
+    'thumbs-down': t('emojis.thumbs-down', { defaultValue: 'thumbs down' }),
+    'clapping-hands': t('emojis.clapping-hands', {
+      defaultValue: 'clapping hands',
+    }),
+    'red-heart': t('emojis.red-heart', { defaultValue: 'red heart' }),
+    'face-with-tears-of-joy': t('emojis.face-with-tears-of-joy', {
+      defaultValue: 'face with tears of joy',
+    }),
+    'face-with-open-mouth': t('emojis.face-with-open-mouth', {
+      defaultValue: 'surprised face',
+    }),
+    'party-popper': t('emojis.party-popper', { defaultValue: 'party popper' }),
+    'folded-hands': t('emojis.folded-hands', { defaultValue: 'folded hands' }),
+  }
+  return emojiLabels[emoji] ?? emoji
+}

src/frontend/src/features/settings/components/SettingsDialogExtended.tsx

@@ -11,6 +11,7 @@ import {
   RiSettings3Line,
   RiSpeakerLine,
   RiVideoOnLine,
+  RiEyeLine,
 } from '@remixicon/react'
 import { AccountTab } from './tabs/AccountTab'
 import { NotificationsTab } from './tabs/NotificationsTab'
@@ -22,6 +23,7 @@ import { useRef } from 'react'
 import { useMediaQuery } from '@/features/rooms/livekit/hooks/useMediaQuery'
 import { SettingsDialogExtendedKey } from '@/features/settings/type'
 import { useIsAdminOrOwner } from '@/features/rooms/livekit/hooks/useIsAdminOrOwner'
+import AccessibilityTab from './tabs/AccessibilityTab'
 
 const tabsStyle = css({
   maxHeight: '40.625rem', // fixme size copied from meet settings modal
@@ -112,6 +114,11 @@ export const SettingsDialogExtended = (props: SettingsDialogExtended) => {
                   t(`tabs.${SettingsDialogExtendedKey.TRANSCRIPTION}`)}
               </Tab>
             )}
+            <Tab icon highlight id={SettingsDialogExtendedKey.ACCESSIBILITY}>
+              <RiEyeLine />
+              {isWideScreen &&
+                t(`tabs.${SettingsDialogExtendedKey.ACCESSIBILITY}`)}
+            </Tab>
           </TabList>
         </div>
         <div className={tabPanelContainerStyle}>
@@ -125,6 +132,7 @@ export const SettingsDialogExtended = (props: SettingsDialogExtended) => {
           <NotificationsTab id={SettingsDialogExtendedKey.NOTIFICATIONS} />
           {/* Transcription tab won't be accessible if the tab is not active in the tab list */}
           <TranscriptionTab id={SettingsDialogExtendedKey.TRANSCRIPTION} />
+          <AccessibilityTab id={SettingsDialogExtendedKey.ACCESSIBILITY} />
         </div>
       </Tabs>
     </Dialog>

src/frontend/src/features/settings/components/tabs/AccessibilityTab.tsx

@@ -0,0 +1,40 @@
+import { Field, H } from '@/primitives'
+import { TabPanel, TabPanelProps } from '@/primitives/Tabs'
+import { css } from '@/styled-system/css'
+import { useTranslation } from 'react-i18next'
+import { useSnapshot } from 'valtio'
+import { accessibilityStore } from '@/stores/accessibility'
+
+export type AccessibilityTabProps = Pick<TabPanelProps, 'id'>
+
+export const AccessibilityTab = ({ id }: AccessibilityTabProps) => {
+  const { t } = useTranslation('settings')
+  const snap = useSnapshot(accessibilityStore)
+
+  return (
+    <TabPanel padding={'md'} flex id={id}>
+      <H lvl={2}>{t('tabs.accessibility')}</H>
+      <ul
+        className={css({
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '1rem',
+        })}
+      >
+        <li>
+          <Field
+            type="switch"
+            label={t('accessibility.announceReactions.label')}
+            isSelected={snap.announceReactions}
+            onChange={(value) => {
+              accessibilityStore.announceReactions = value
+            }}
+            wrapperProps={{ noMargin: true, fullWidth: true }}
+          />
+        </li>
+      </ul>
+    </TabPanel>
+  )
+}
+
+export default AccessibilityTab

src/frontend/src/features/settings/type.ts

@@ -5,4 +5,5 @@ export enum SettingsDialogExtendedKey {
   GENERAL = 'general',
   NOTIFICATIONS = 'notifications',
   TRANSCRIPTION = 'transcription',
+  ACCESSIBILITY = 'accessibility',
 }

src/frontend/src/locales/de/rooms.json

@@ -208,7 +208,18 @@
     "reactions": {
       "button": "Reaktion senden",
       "send": "Reaktion {{emoji}} senden",
-      "you": "Sie"
+      "announce": "{{name}} : {{emoji}}",
+      "you": "Sie",
+      "emojis": {
+        "thumbs-up": "Daumen hoch",
+        "thumbs-down": "Daumen runter",
+        "clapping-hands": "Klatschende Hände",
+        "red-heart": "rotes Herz",
+        "face-with-tears-of-joy": "Gesicht mit Freudentränen",
+        "face-with-open-mouth": "überraschter Gesichtsausdruck",
+        "party-popper": "Party-Popper",
+        "folded-hands": "gefaltete Hände"
+      }
     }
   },
   "options": {

src/frontend/src/locales/en/rooms.json

@@ -208,7 +208,18 @@
     "reactions": {
       "button": "Send reaction",
       "send": "Send reaction {{emoji}}",
-      "you": "you"
+      "announce": "{{name}} : {{emoji}}",
+      "you": "you",
+      "emojis": {
+        "thumbs-up": "thumbs up",
+        "thumbs-down": "thumbs down",
+        "clapping-hands": "clapping hands",
+        "red-heart": "red heart",
+        "face-with-tears-of-joy": "face with tears of joy",
+        "face-with-open-mouth": "surprised face",
+        "party-popper": "party popper",
+        "folded-hands": "folded hands"
+      }
     }
   },
   "options": {

src/frontend/src/locales/en/settings.json

@@ -108,12 +108,18 @@
     "label": "Language"
   },
   "settingsButtonLabel": "Settings",
+  "accessibility": {
+    "announceReactions": {
+      "label": "Announce reactions aloud"
+    }
+  },
   "tabs": {
     "account": "Profile",
     "audio": "Audio",
     "video": "Video",
     "general": "General",
     "notifications": "Notifications",
+    "accessibility": "Accessibility",
     "transcription": "Transcription"
   }
 }

src/frontend/src/locales/fr/rooms.json

@@ -208,7 +208,18 @@
     "reactions": {
       "button": "Envoyer une réaction",
       "send": "Envoyer la réaction {{emoji}}",
-      "you": "vous"
+      "announce": "{{name}} : {{emoji}}",
+      "you": "vous",
+      "emojis": {
+        "thumbs-up": "pouce levé",
+        "thumbs-down": "pouce baissé",
+        "clapping-hands": "applaudissements",
+        "red-heart": "cœur",
+        "face-with-tears-of-joy": "visage qui rit",
+        "face-with-open-mouth": "visage étonné",
+        "party-popper": "confettis",
+        "folded-hands": "mains jointes"
+      }
     }
   },
   "options": {

src/frontend/src/locales/fr/settings.json

@@ -108,12 +108,18 @@
     "label": "Langue de l'application"
   },
   "settingsButtonLabel": "Paramètres",
+  "accessibility": {
+    "announceReactions": {
+      "label": "Vocaliser les réactions"
+    }
+  },
   "tabs": {
     "account": "Profil",
     "audio": "Audio",
     "video": "Vidéo",
     "general": "Général",
     "notifications": "Notifications",
+    "accessibility": "Accessibilité",
     "transcription": "Transcription"
   }
 }

src/frontend/src/locales/nl/rooms.json

@@ -208,7 +208,18 @@
     "reactions": {
       "button": "Stuur reactie",
       "send": "Stuur reactie {{emoji}}",
-      "you": "U"
+      "announce": "{{name}} : {{emoji}}",
+      "you": "U",
+      "emojis": {
+        "thumbs-up": "duim omhoog",
+        "thumbs-down": "duim omlaag",
+        "clapping-hands": "applaudisserende handen",
+        "red-heart": "rood hart",
+        "face-with-tears-of-joy": "gezicht met tranen van vreugde",
+        "face-with-open-mouth": "verrast gezicht",
+        "party-popper": "feestknaller",
+        "folded-hands": "gevouwen handen"
+      }
     }
   },
   "options": {

src/frontend/src/stores/accessibility.ts

@@ -0,0 +1,76 @@
+import { proxy, subscribe } from 'valtio'
+import { STORAGE_KEYS } from '@/utils/storageKeys'
+import { deserializeToProxyMap } from '@/utils/valtio'
+
+type AccessibilityState = {
+  announceReactions: boolean
+}
+
+const DEFAULT_STATE: AccessibilityState = {
+  announceReactions: false,
+}
+
+function getAccessibilityState(): AccessibilityState {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEYS.ACCESSIBILITY)
+    if (stored) {
+      const parsed = JSON.parse(stored)
+      return {
+        ...DEFAULT_STATE,
+        ...parsed,
+        announceReactions:
+          typeof parsed.announceReactions === 'boolean'
+            ? parsed.announceReactions
+            : DEFAULT_STATE.announceReactions,
+      }
+    }
+
+    // Legacy migration: if the setting was previously stored in notifications
+    const legacy = localStorage.getItem(STORAGE_KEYS.NOTIFICATIONS)
+    if (legacy) {
+      try {
+        const parsedLegacy = JSON.parse(legacy, deserializeToProxyMap)
+        if (typeof parsedLegacy?.announceReactions === 'boolean') {
+          const migratedState: AccessibilityState = {
+            ...DEFAULT_STATE,
+            ...parsedLegacy,
+            announceReactions: parsedLegacy.announceReactions,
+          }
+
+          try {
+            localStorage.setItem(
+              STORAGE_KEYS.ACCESSIBILITY,
+              JSON.stringify(migratedState)
+            )
+            localStorage.removeItem(STORAGE_KEYS.NOTIFICATIONS)
+          } catch {
+            // ignore persistence issues during migration
+          }
+
+          return migratedState
+        }
+      } catch {
+        // ignore legacy parsing issues
+      }
+    }
+
+    return DEFAULT_STATE
+  } catch (error: unknown) {
+    console.error(
+      '[AccessibilityStore] Failed to parse stored settings:',
+      error
+    )
+    return DEFAULT_STATE
+  }
+}
+
+export const accessibilityStore = proxy<AccessibilityState>(
+  getAccessibilityState()
+)
+
+subscribe(accessibilityStore, () => {
+  localStorage.setItem(
+    STORAGE_KEYS.ACCESSIBILITY,
+    JSON.stringify(accessibilityStore)
+  )
+})

src/frontend/src/styles/a11y.ts

@@ -0,0 +1,14 @@
+import { css } from '@/styled-system/css'
+
+// Reusable visually hidden style for screen-reader-only content
+export const srOnly = css({
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: 0,
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+})

src/frontend/src/utils/storageKeys.tsx

@@ -4,4 +4,5 @@
 export const STORAGE_KEYS = {
   NOTIFICATIONS: 'app_notification_settings',
   USER_PREFERENCES: 'app_user_preferences',
+  ACCESSIBILITY: 'app_accessibility_settings',
 } as const