From 59732f37066f3805dc610960fcc4a6d09ff9ef63 Mon Sep 17 00:00:00 2001
From: Nurfog <juan.allende@gmail.com>
Date: Wed, 25 Feb 2026 16:09:54 -0300
Subject: [PATCH] feat: improve accessibility with semantic HTML, ARIA
 attributes, and visible focus states across components.

---
 web/experience/src/app/globals.css            | 10 +++-
 .../components/blocks/AudioResponsePlayer.tsx | 49 ++++++++++++-------
 web/studio/src/app/globals.css                | 10 +++-
 .../src/components/BrandingSettings.tsx       | 32 +++++++-----
 web/studio/src/components/Combobox.tsx        | 39 +++++++++++----
 .../src/components/CourseEditorLayout.tsx     | 32 ++++++------
 web/studio/src/components/Navbar.tsx          | 15 +++---
 7 files changed, 123 insertions(+), 64 deletions(-)

diff --git a/web/experience/src/app/globals.css b/web/experience/src/app/globals.css
index b63fdb2..eeb4216 100644
--- a/web/experience/src/app/globals.css
+++ b/web/experience/src/app/globals.css
@@ -13,8 +13,8 @@
 
   --accent-primary: var(--primary-color);
   --accent-secondary: var(--secondary-color);
-  --glass-bg: rgba(255, 255, 255, 0.03);
-  --glass-border: rgba(255, 255, 255, 0.08);
+  --glass-bg: rgba(255, 255, 255, 0.05); /* Increased slightly for contrast */
+  --glass-border: rgba(255, 255, 255, 0.1);
   --glass-blur: blur(16px);
 }
 
@@ -32,6 +32,12 @@ body {
   border: 1px solid var(--glass-border);
 }
 
+/* Ensure focus states are visible for keyboard navigation */
+:focus-visible {
+  outline: 2px solid var(--accent-primary);
+  outline-offset: 4px;
+}
+
 .glass-card {
   @apply glass rounded-2xl p-4 md:p-6 transition-all duration-300;
 }
diff --git a/web/experience/src/components/blocks/AudioResponsePlayer.tsx b/web/experience/src/components/blocks/AudioResponsePlayer.tsx
index dbc50da..6235d40 100644
--- a/web/experience/src/components/blocks/AudioResponsePlayer.tsx
+++ b/web/experience/src/components/blocks/AudioResponsePlayer.tsx
@@ -183,7 +183,7 @@ export default function AudioResponsePlayer({
                         <Mic className="w-6 h-6 text-purple-400" />
                     </div>
                     <div className="flex-1">
-                        <p className="text-xl font-bold text-gray-100">{prompt}</p>
+                        <h3 id={`audio-prompt-${id}`} className="text-xl font-bold text-gray-100">{prompt}</h3>
                         {keywords.length > 0 && !submitted && (
                             <div className="flex flex-wrap gap-2 mt-3">
                                 <span className="text-xs text-gray-500 uppercase tracking-wider">Expected topics:</span>
@@ -205,16 +205,23 @@ export default function AudioResponsePlayer({
                                 <button
                                     onClick={startRecording}
                                     className="flex items-center gap-3 px-8 py-4 bg-gradient-to-r from-purple-600 to-pink-600 hover:from-purple-700 hover:to-pink-700 rounded-2xl font-bold text-white shadow-lg shadow-purple-500/30 transition-all"
+                                    aria-label="Start Recording"
+                                    aria-describedby={`audio-prompt-${id}`}
                                 >
-                                    <Mic className="w-5 h-5" />
+                                    <Mic className="w-5 h-5" aria-hidden="true" />
                                     Start Recording
                                 </button>
                             )}
 
                             {isRecording && (
                                 <div className="flex flex-col items-center gap-4">
-                                    <div className="flex items-center gap-3 px-6 py-3 bg-red-500/20 border-2 border-red-500 rounded-2xl animate-pulse">
-                                        <div className="w-3 h-3 bg-red-500 rounded-full animate-pulse" />
+                                    <div
+                                        className="flex items-center gap-3 px-6 py-3 bg-red-500/20 border-2 border-red-500 rounded-2xl animate-pulse"
+                                        role="timer"
+                                        aria-live="polite"
+                                        aria-label={`Recording time: ${formatTime(recordingTime)}`}
+                                    >
+                                        <div className="w-3 h-3 bg-red-500 rounded-full animate-pulse" aria-hidden="true" />
                                         <span className="font-mono text-xl font-bold text-red-400">{formatTime(recordingTime)}</span>
                                         {timeLimit && (
                                             <span className="text-sm text-gray-400">/ {formatTime(timeLimit)}</span>
@@ -222,9 +229,10 @@ export default function AudioResponsePlayer({
                                     </div>
                                     <button
                                         onClick={stopRecording}
-                                        className="flex items-center gap-2 px-6 py-3 bg-red-600 hover:bg-red-700 rounded-xl font-bold text-white transition-all"
+                                        className="flex items-center gap-2 px-6 py-3 bg-red-600 hover:bg-red-700 rounded-xl font-bold text-white transition-all outline-none focus:ring-2 focus:ring-red-500"
+                                        aria-label="Stop Recording"
                                     >
-                                        <Square className="w-4 h-4" />
+                                        <Square className="w-4 h-4" aria-hidden="true" />
                                         Stop Recording
                                     </button>
                                 </div>
@@ -234,16 +242,18 @@ export default function AudioResponsePlayer({
                                 <div className="flex gap-3">
                                     <button
                                         onClick={playRecording}
-                                        className="flex items-center gap-2 px-6 py-3 bg-blue-600 hover:bg-blue-700 rounded-xl font-bold text-white transition-all"
+                                        className="flex items-center gap-2 px-6 py-3 bg-blue-600 hover:bg-blue-700 rounded-xl font-bold text-white transition-all outline-none focus:ring-2 focus:ring-blue-500"
+                                        aria-label="Play back your recording"
                                     >
-                                        <Play className="w-4 h-4" />
+                                        <Play className="w-4 h-4" aria-hidden="true" />
                                         Play Recording
                                     </button>
                                     <button
                                         onClick={reset}
-                                        className="flex items-center gap-2 px-6 py-3 glass hover:bg-white/10 rounded-xl font-bold text-gray-300 transition-all"
+                                        className="flex items-center gap-2 px-6 py-3 glass hover:bg-white/10 rounded-xl font-bold text-gray-300 transition-all outline-none focus:ring-2 focus:ring-white/20"
+                                        aria-label="Delete and re-record"
                                     >
-                                        <RotateCcw className="w-4 h-4" />
+                                        <RotateCcw className="w-4 h-4" aria-hidden="true" />
                                         Re-record
                                     </button>
                                 </div>
@@ -258,11 +268,11 @@ export default function AudioResponsePlayer({
                             </div>
                         )}
 
-                        {/* Submit Button */}
                         {audioBlob && transcript && (
                             <button
                                 onClick={evaluateResponse}
-                                className="w-full py-4 bg-gradient-to-r from-green-600 to-emerald-600 hover:from-green-700 hover:to-emerald-700 rounded-xl font-bold text-white shadow-lg shadow-green-500/30 transition-all"
+                                className="w-full py-4 bg-gradient-to-r from-green-600 to-emerald-600 hover:from-green-700 hover:to-emerald-700 rounded-xl font-bold text-white shadow-lg shadow-green-500/30 transition-all outline-none focus:ring-2 focus:ring-green-500"
+                                aria-label="Submit recording for AI evaluation"
                             >
                                 Submit Response
                             </button>
@@ -273,12 +283,15 @@ export default function AudioResponsePlayer({
                 {/* Evaluation Results */}
                 {submitted && evaluation && (
                     <div className="space-y-4">
-                        <div className={`p-6 rounded-2xl border-2 ${evaluation.score >= 70
-                            ? 'bg-green-500/10 border-green-500'
-                            : evaluation.score >= 40
-                                ? 'bg-yellow-500/10 border-yellow-500'
-                                : 'bg-red-500/10 border-red-500'
-                            }`}>
+                        <div
+                            className={`p-6 rounded-2xl border-2 ${evaluation.score >= 70
+                                ? 'bg-green-500/10 border-green-500'
+                                : evaluation.score >= 40
+                                    ? 'bg-yellow-500/10 border-yellow-500'
+                                    : 'bg-red-500/10 border-red-500'
+                                }`}
+                            aria-live="assertive"
+                        >
                             <div className="flex items-center justify-between mb-4">
                                 <span className="text-sm font-bold uppercase tracking-wider text-gray-400">Your Score</span>
                                 <span className="text-3xl font-black">{evaluation.score}%</span>
diff --git a/web/studio/src/app/globals.css b/web/studio/src/app/globals.css
index 8eb0acc..6f4b70c 100644
--- a/web/studio/src/app/globals.css
+++ b/web/studio/src/app/globals.css
@@ -13,11 +13,17 @@
   /* blue-500 */
   --accent-secondary: #6366f1;
   /* indigo-500 */
-  --glass-bg: rgba(255, 255, 255, 0.03);
-  --glass-border: rgba(255, 255, 255, 0.08);
+  --glass-bg: rgba(255, 255, 255, 0.05);
+  --glass-border: rgba(255, 255, 255, 0.1);
   --glass-blur: blur(16px);
 }
 
+/* Ensure focus states are visible for keyboard navigation */
+:focus-visible {
+  outline: 2px solid var(--accent-primary);
+  outline-offset: 4px;
+}
+
 body {
   color: rgb(var(--foreground-rgb));
   background: var(--background-start-rgb);
diff --git a/web/studio/src/components/BrandingSettings.tsx b/web/studio/src/components/BrandingSettings.tsx
index 3d4ef3a..c09cb6e 100644
--- a/web/studio/src/components/BrandingSettings.tsx
+++ b/web/studio/src/components/BrandingSettings.tsx
@@ -79,7 +79,7 @@ export default function BrandingSettings() {
 
                     {/* Logo Section */}
                     <div className="space-y-4">
-                        <label className="block text-sm font-medium text-gray-400">Logo</label>
+                        <span className="block text-sm font-medium text-gray-400">Logo</span>
                         <div className="p-4 bg-black/20 rounded-xl border border-white/5 flex items-center justify-center min-h-[120px] relative">
                             {org.logo_url ? (
                                 <Image
@@ -110,7 +110,7 @@ export default function BrandingSettings() {
 
                     {/* Favicon Section */}
                     <div className="space-y-4">
-                        <label className="block text-sm font-medium text-gray-400">Favicon</label>
+                        <span className="block text-sm font-medium text-gray-400">Favicon</span>
                         <div className="p-4 bg-black/20 rounded-xl border border-white/5 flex items-center justify-center min-h-[120px] relative">
                             {org.favicon_url ? (
                                 <div className="w-8 h-8 relative">
@@ -143,56 +143,64 @@ export default function BrandingSettings() {
                 </div>
             </div>
 
-            <div className="border border-white/10 rounded-2xl p-6 bg-white/5 backdrop-blur-sm">
-                <h3 className="text-xl font-bold mb-6 flex items-center gap-2">
-                    <span>🌈</span> Brand Colors
-                </h3>
-                <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
+            <fieldset className="border border-white/10 rounded-2xl p-6 bg-white/5 backdrop-blur-sm">
+                <legend className="px-2 text-xl font-bold flex items-center gap-2">
+                    <span aria-hidden="true">🌈</span> Brand Colors
+                </legend>
+                <div className="mt-4 grid grid-cols-1 md:grid-cols-2 gap-8">
                     {/* Primary Color */}
                     <div>
-                        <label className="block text-sm font-medium text-gray-400 mb-2">Primary Color</label>
+                        <label htmlFor="primary-color" className="block text-sm font-medium text-gray-400 mb-2">Primary Color</label>
                         <div className="flex items-center gap-4">
                             <input
+                                id="primary-color-picker"
                                 type="color"
                                 value={formData.primary_color}
                                 onChange={(e) => setFormData({ ...formData, primary_color: e.target.value })}
+                                aria-label="Primary color picker"
                                 className="w-12 h-12 rounded-lg cursor-pointer bg-transparent border-none p-0"
                             />
                             <div className="flex-1">
                                 <input
+                                    id="primary-color"
                                     type="text"
                                     value={formData.primary_color}
                                     onChange={(e) => setFormData({ ...formData, primary_color: e.target.value })}
                                     className="w-full bg-black/20 border border-white/10 rounded-lg px-4 py-2 text-white font-mono uppercase"
+                                    aria-describedby="primary-color-desc"
                                 />
                             </div>
                         </div>
-                        <p className="text-xs text-gray-500 mt-2">Used for main buttons, active states, and highlights.</p>
+                        <p id="primary-color-desc" className="text-xs text-gray-500 mt-2">Used for main buttons, active states, and highlights.</p>
                     </div>
 
                     {/* Secondary Color */}
                     <div>
-                        <label className="block text-sm font-medium text-gray-400 mb-2">Secondary Color</label>
+                        <label htmlFor="secondary-color" className="block text-sm font-medium text-gray-400 mb-2">Secondary Color</label>
                         <div className="flex items-center gap-4">
                             <input
+                                id="secondary-color-picker"
                                 type="color"
                                 value={formData.secondary_color}
                                 onChange={(e) => setFormData({ ...formData, secondary_color: e.target.value })}
+                                aria-label="Secondary color picker"
                                 className="w-12 h-12 rounded-lg cursor-pointer bg-transparent border-none p-0"
                             />
                             <div className="flex-1">
                                 <input
+                                    id="secondary-color"
                                     type="text"
                                     value={formData.secondary_color}
                                     onChange={(e) => setFormData({ ...formData, secondary_color: e.target.value })}
                                     className="w-full bg-black/20 border border-white/10 rounded-lg px-4 py-2 text-white font-mono uppercase"
+                                    aria-describedby="secondary-color-desc"
                                 />
                             </div>
                         </div>
-                        <p className="text-xs text-gray-500 mt-2">Used for accents and gradients.</p>
+                        <p id="secondary-color-desc" className="text-xs text-gray-500 mt-2">Used for accents and gradients.</p>
                     </div>
                 </div>
-            </div>
+            </fieldset>
 
             <div className="flex justify-end">
                 <button
diff --git a/web/studio/src/components/Combobox.tsx b/web/studio/src/components/Combobox.tsx
index 13261d5..dd09cb1 100644
--- a/web/studio/src/components/Combobox.tsx
+++ b/web/studio/src/components/Combobox.tsx
@@ -38,24 +38,31 @@ export default function Combobox({ options, value, onChange, placeholder = "Sear
 
     return (
         <div className="relative" ref={containerRef}>
-            <div
+            <button
+                type="button"
                 onClick={() => setIsOpen(!isOpen)}
-                className="flex items-center justify-between w-full bg-black/40 border border-white/10 rounded-lg px-4 py-2.5 cursor-pointer hover:border-white/20 transition-all focus-within:ring-2 focus-within:ring-blue-500/50"
+                aria-haspopup="listbox"
+                aria-expanded={isOpen}
+                className="flex items-center justify-between w-full bg-black/40 border border-white/10 rounded-lg px-4 py-2.5 cursor-pointer hover:border-white/20 transition-all focus:outline-none focus:ring-2 focus:ring-blue-500/50"
             >
                 <span className={selectedOption ? "text-white" : "text-gray-500"}>
                     {selectedOption ? selectedOption.name : placeholder}
                 </span>
-                <ChevronDown size={18} className={`text-gray-500 transition-transform ${isOpen ? "rotate-180" : ""}`} />
-            </div>
+                <ChevronDown size={18} className={`text-gray-500 transition-transform ${isOpen ? "rotate-180" : ""}`} aria-hidden="true" />
+            </button>
 
             {isOpen && (
                 <div className="absolute top-full left-0 right-0 mt-2 z-[110] bg-[#1a1d23] border border-white/10 rounded-lg shadow-2xl overflow-hidden glass-card animate-in fade-in slide-in-from-top-2 duration-200">
                     <div className="p-2 border-b border-white/5 bg-white/5">
                         <div className="relative">
-                            <Search size={14} className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400" />
+                            <Search size={14} className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400" aria-hidden="true" />
                             <input
                                 autoFocus
                                 type="text"
+                                role="combobox"
+                                aria-autocomplete="list"
+                                aria-expanded="true"
+                                aria-controls="combobox-options"
                                 className="w-full bg-black/20 border-none rounded-md pl-9 pr-4 py-2 text-sm focus:ring-0 placeholder:text-gray-600"
                                 placeholder="Search..."
                                 value={search}
@@ -63,23 +70,37 @@ export default function Combobox({ options, value, onChange, placeholder = "Sear
                             />
                         </div>
                     </div>
-                    <div className="max-h-60 overflow-y-auto p-1 custom-scrollbar">
+                    <div
+                        id="combobox-options"
+                        role="listbox"
+                        className="max-h-60 overflow-y-auto p-1 custom-scrollbar"
+                    >
                         {filteredOptions.length === 0 ? (
-                            <div className="px-4 py-3 text-sm text-gray-500 text-center">No results found</div>
+                            <div className="px-4 py-3 text-sm text-gray-500 text-center" role="option" aria-disabled="true">No results found</div>
                         ) : (
                             filteredOptions.map(option => (
                                 <div
                                     key={option.id}
+                                    role="option"
+                                    aria-selected={value === option.id}
+                                    tabIndex={0}
                                     onClick={() => {
                                         onChange(option.id);
                                         setIsOpen(false);
                                         setSearch("");
                                     }}
-                                    className={`flex items-center justify-between px-3 py-2 rounded-md cursor-pointer transition-colors ${value === option.id ? "bg-blue-600 text-white" : "hover:bg-white/5 text-gray-300"
+                                    onKeyDown={(e) => {
+                                        if (e.key === 'Enter' || e.key === ' ') {
+                                            onChange(option.id);
+                                            setIsOpen(false);
+                                            setSearch("");
+                                        }
+                                    }}
+                                    className={`flex items-center justify-between px-3 py-2 rounded-md cursor-pointer transition-colors outline-none focus:bg-blue-600 focus:text-white ${value === option.id ? "bg-blue-600 text-white" : "hover:bg-white/5 text-gray-300"
                                         }`}
                                 >
                                     <span className="text-sm font-medium">{option.name}</span>
-                                    {value === option.id && <Check size={14} />}
+                                    {value === option.id && <Check size={14} aria-hidden="true" />}
                                 </div>
                             ))
                         )}
diff --git a/web/studio/src/components/CourseEditorLayout.tsx b/web/studio/src/components/CourseEditorLayout.tsx
index b678aa6..683ad23 100644
--- a/web/studio/src/components/CourseEditorLayout.tsx
+++ b/web/studio/src/components/CourseEditorLayout.tsx
@@ -32,27 +32,29 @@ export default function CourseEditorLayout({ children, activeTab }: CourseEditor
     return (
         <div className="space-y-8">
             {/* Tabs Navigation */}
-            <div className="glass p-1">
-                <div className="flex border-b border-white/10 overflow-x-auto scrollbar-thin scrollbar-thumb-white/10 scrollbar-track-transparent">
+            <nav className="glass p-1" aria-label="Course editor tabs">
+                <ul className="flex border-b border-white/10 overflow-x-auto scrollbar-thin scrollbar-thumb-white/10 scrollbar-track-transparent">
                     {tabs.map((tab) => {
                         const Icon = tab.icon;
                         const isActive = tab.key === activeTab;
                         return (
-                            <Link
-                                key={tab.key}
-                                href={tab.href}
-                                className={`flex items-center gap-1.5 px-4 py-3 text-sm font-medium transition-colors whitespace-nowrap flex-shrink-0 ${isActive
-                                    ? "border-b-2 border-blue-500 bg-white/5 text-white"
-                                    : "text-gray-500 hover:text-white"
-                                    }`}
-                            >
-                                <Icon className="w-4 h-4 flex-shrink-0" />
-                                {tab.label}
-                            </Link>
+                            <li key={tab.key} className="flex-shrink-0">
+                                <Link
+                                    href={tab.href}
+                                    aria-current={isActive ? "page" : undefined}
+                                    className={`flex items-center gap-1.5 px-4 py-3 text-sm font-medium transition-colors whitespace-nowrap flex-shrink-0 ${isActive
+                                        ? "border-b-2 border-blue-500 bg-white/5 text-white"
+                                        : "text-gray-500 hover:text-white"
+                                        }`}
+                                >
+                                    <Icon className="w-4 h-4 flex-shrink-0" aria-hidden="true" />
+                                    {tab.label}
+                                </Link>
+                            </li>
                         );
                     })}
-                </div>
-            </div>
+                </ul>
+            </nav>
 
             {/* Content */}
             <div className="space-y-6">
diff --git a/web/studio/src/components/Navbar.tsx b/web/studio/src/components/Navbar.tsx
index 6bf3701..f03f0d0 100644
--- a/web/studio/src/components/Navbar.tsx
+++ b/web/studio/src/components/Navbar.tsx
@@ -12,7 +12,7 @@ export function Navbar() {
     return (
         <nav className="fixed top-0 w-full z-50 glass border-b border-white/10 bg-black/20">
             <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between">
-                <Link href="/" className="flex items-center gap-2">
+                <Link href="/" className="flex items-center gap-2" aria-label="OpenCCB Studio - Inicio">
                     <h1 className="text-xl font-bold tracking-tight">
                         Open<span className="gradient-text">CCB</span> Studio
                     </h1>
@@ -32,7 +32,7 @@ export function Navbar() {
                             href="/library/assets"
                             className="text-sm font-medium text-gray-400 hover:text-blue-400 transition-colors flex items-center gap-2"
                         >
-                            <Library className="w-4 h-4" />
+                            <Library className="w-4 h-4" aria-hidden="true" />
                             {t('nav.library') || 'Library'}
                         </Link>
 
@@ -43,7 +43,7 @@ export function Navbar() {
                                         href="/admin"
                                         className="text-sm font-black text-indigo-400 hover:text-indigo-300 transition-colors flex items-center gap-2 bg-indigo-500/10 px-3 py-1.5 rounded-lg border border-indigo-500/20 shadow-glow-sm"
                                     >
-                                        <ShieldCheck className="w-4 h-4" />
+                                        <ShieldCheck className="w-4 h-4" aria-hidden="true" />
                                         {t('nav.globalControl')}
                                     </Link>
                                 )}
@@ -77,10 +77,12 @@ export function Navbar() {
 
                     {/* Language Switcher */}
                     <div className="flex items-center gap-2">
-                        <Globe className="w-4 h-4 text-gray-500" />
+                        <Globe className="w-4 h-4 text-gray-500" aria-hidden="true" />
                         <select
+                            id="studio-language-selector"
                             value={language}
                             onChange={(e) => setLanguage(e.target.value)}
+                            aria-label={t('nav.selectLanguage') || 'Select Language'}
                             className="bg-transparent text-[10px] font-black uppercase tracking-widest text-gray-400 hover:text-white transition-colors focus:outline-none cursor-pointer"
                         >
                             <option value="en" className="bg-gray-900">EN</option>
@@ -100,9 +102,10 @@ export function Navbar() {
                             <button
                                 onClick={logout}
                                 className="p-2 hover:bg-red-500/10 hover:text-red-400 rounded-lg transition-all text-gray-500"
-                                title="Sign Out"
+                                title={t('nav.signOut') || "Sign Out"}
+                                aria-label={t('nav.signOut') || "Sign Out"}
                             >
-                                <LogOut className="w-4 h-4" />
+                                <LogOut className="w-4 h-4" aria-hidden="true" />
                             </button>
                         </div>
                     ) : (