From 5bd97f66f7c58c2c5adc9f7427e5bc3b76c5f7f8 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 22 Oct 2026 22:28:03 +0000
Subject: [PATCH 1/2] Name controls, headings, and the toast region for
 assistive tech.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Card titles default to h2 so a page h1 is not followed by an h3. Generate and flowchart selects, the timer progress bar, and attack options have accessible names, the toast region follows the UI language, and the landing demo leaves the tab order.

Co-authored-by: Gáborjáni-Szabó Ádám <Programcode@users.noreply.github.com>
---
 e2e/navigation-performance.spec.ts            |   2 +-
 src/components/LanguageSwitcher.tsx           |   4 +-
 src/components/features/attack/AttackForm.tsx |  16 ++-
 .../features/attack/AttackResults.tsx         |  10 +-
 .../features/brainstorm/BrainstormResults.tsx |   6 +-
 .../features/factoids/FactoidsResults.tsx     |   6 +-
 .../features/generate/GenerateForm.tsx        |  26 +++-
 .../features/generate/GenerateResults.tsx     |  24 ++--
 src/components/landing/Hero.tsx               |   5 +-
 src/components/ui/card.tsx                    |  13 +-
 src/components/ui/empty-state.tsx             |   2 +-
 src/components/ui/progress.tsx                |   1 +
 src/components/ui/sonner.tsx                  |   1 +
 src/locales/en.json                           |   3 +
 src/locales/es.json                           |   3 +
 src/locales/hu.json                           |   3 +
 src/pages/AdminPage.tsx                       |   4 +-
 src/pages/FlowchartPage.tsx                   |  21 +--
 src/pages/TimerPage.tsx                       |   2 +-
 src/test/a11y/names-and-headings.test.tsx     | 128 ++++++++++++++++++
 20 files changed, 222 insertions(+), 58 deletions(-)
 create mode 100644 src/test/a11y/names-and-headings.test.tsx

diff --git a/e2e/navigation-performance.spec.ts b/e2e/navigation-performance.spec.ts
index 74aa3e07a..b3fb103e0 100644
--- a/e2e/navigation-performance.spec.ts
+++ b/e2e/navigation-performance.spec.ts
@@ -26,7 +26,7 @@ const privateRoutes = [
   ['/app/attack', { selector: 'main h1', text: 'Attack' }],
   ['/app/flowchart', { selector: 'main h1', text: 'Argument Flowchart' }],
   ['/app/history', { selector: 'main h1', text: 'History' }],
-  ['/app/admin', { selector: 'main h3', text: 'Access Denied' }],
+  ['/app/admin', { selector: 'main h1', text: 'Access Denied' }],
 ] as const;
 
 const attackContent: ContentMarker = { selector: 'main h1', text: 'Attack' };
diff --git a/src/components/LanguageSwitcher.tsx b/src/components/LanguageSwitcher.tsx
index d6e4e68c7..1b5e4aade 100644
--- a/src/components/LanguageSwitcher.tsx
+++ b/src/components/LanguageSwitcher.tsx
@@ -47,8 +47,8 @@ export function LanguageSwitcher() {
     <Popover>
       <HeaderTooltip label={t('langSwitcher.title', 'Language')}>
         <PopoverTrigger asChild>
-          <Button variant="ghost" size="icon" className="text-muted-foreground hover:text-foreground" aria-label={t('langSwitcher.label', 'Language settings')}>
-            <Globe className="h-5 w-5" />
+          <Button variant="ghost" size="icon" className="text-muted-foreground hover:text-foreground" aria-label={t('langSwitcher.label', 'Language')}>
+            <Globe className="h-5 w-5" aria-hidden="true" />
           </Button>
         </PopoverTrigger>
       </HeaderTooltip>
diff --git a/src/components/features/attack/AttackForm.tsx b/src/components/features/attack/AttackForm.tsx
index ad0a8f6bd..1992a76a5 100644
--- a/src/components/features/attack/AttackForm.tsx
+++ b/src/components/features/attack/AttackForm.tsx
@@ -94,17 +94,19 @@ export function AttackForm({ onSubmit, isLoading, importedCase, debateContext =
           <ModelSelector feature="attack" showLabel />
 
           <div className="space-y-2">
-            <Label className="text-sm font-medium">{t('attackForm.options')}</Label>
+            <Label id="attack-options-label" htmlFor="attack-options-toggle" className="text-sm font-medium">{t('attackForm.options')}</Label>
             <Button
+              id="attack-options-toggle"
               type="button"
               variant="outline"
               className="h-10 w-full justify-between"
+              aria-labelledby="attack-options-label attack-options-toggle-text"
               aria-expanded={optionsOpen}
               aria-controls="attack-options"
               onClick={() => setOptionsOpen((open) => !open)}
             >
-              <span className="flex items-center gap-2">
-                <SlidersHorizontal className="h-4 w-4" />
+              <span id="attack-options-toggle-text" className="flex items-center gap-2">
+                <SlidersHorizontal className="h-4 w-4" aria-hidden="true" />
                 {t('attackForm.moreOptions')}
               </span>
               <ChevronDown className={`h-4 w-4 transition-transform duration-150 ease-out-strong ${optionsOpen ? 'rotate-180' : ''}`} />
@@ -123,12 +125,12 @@ export function AttackForm({ onSubmit, isLoading, importedCase, debateContext =
               <div className="grid gap-4 sm:grid-cols-2">
                 {/* Aggressiveness */}
                 <div className="space-y-2">
-                  <Label className="text-sm font-medium">{t('attackForm.intensity')}</Label>
+                  <Label id="attack-intensity-label" htmlFor="attack-intensity" className="text-sm font-medium">{t('attackForm.intensity')}</Label>
                   <Select
                     value={currentValues.aggressiveness}
                     onValueChange={(value) => setValue('aggressiveness', value as AttackInput['aggressiveness'])}
                   >
-                    <SelectTrigger>
+                    <SelectTrigger id="attack-intensity" aria-labelledby="attack-intensity-label">
                       <SelectValue />
                     </SelectTrigger>
                     <SelectContent>
@@ -141,12 +143,12 @@ export function AttackForm({ onSubmit, isLoading, importedCase, debateContext =
 
                 {/* Judge Paradigm */}
                 <div className="space-y-2">
-                  <Label className="text-sm font-medium">{t('attackForm.paradigm')}</Label>
+                  <Label id="attack-paradigm-label" htmlFor="attack-paradigm" className="text-sm font-medium">{t('attackForm.paradigm')}</Label>
                   <Select
                     value={currentValues.judgeParadigm}
                     onValueChange={(value) => setValue('judgeParadigm', value as AttackInput['judgeParadigm'])}
                   >
-                    <SelectTrigger>
+                    <SelectTrigger id="attack-paradigm" aria-labelledby="attack-paradigm-label">
                       <SelectValue />
                     </SelectTrigger>
                     <SelectContent>
diff --git a/src/components/features/attack/AttackResults.tsx b/src/components/features/attack/AttackResults.tsx
index 9607fa657..884e48ee2 100644
--- a/src/components/features/attack/AttackResults.tsx
+++ b/src/components/features/attack/AttackResults.tsx
@@ -53,7 +53,7 @@ function WeaknessCard({ weakness }: { weakness: Weakness }) {
                 {t(`attackResults.types.${weakness.type}`, weakness.type)}
               </Badge>
             </div>
-            <h4 className="mt-1 font-medium text-foreground">{weakness.description}</h4>
+            <h3 className="mt-1 font-medium text-foreground">{weakness.description}</h3>
           </div>
         </div>
       </div>
@@ -221,7 +221,7 @@ export function AttackResults({ result, discoveredSources, onDiscuss, onPractice
           </div>
 
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('attackResults.strengths')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('attackResults.strengths')}</h3>
             <ul className="space-y-1">
               {strengthAreas.map((strength, i) => (
                 <li key={i} className="flex items-baseline gap-2 text-sm">
@@ -303,12 +303,12 @@ export function AttackResults({ result, discoveredSources, onDiscuss, onPractice
         >
           <div className="space-y-4">
             <div>
-              <h4 className="text-sm font-medium text-muted-foreground mb-1">{t('attackResults.currentWeighing')}</h4>
+              <h3 className="text-sm font-medium text-muted-foreground mb-1">{t('attackResults.currentWeighing')}</h3>
               <p className="text-foreground">{weighingAnalysis.currentWeighing}</p>
             </div>
             <Separator />
             <div>
-              <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('attackResults.missingComparisons')}</h4>
+              <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('attackResults.missingComparisons')}</h3>
               <ul className="space-y-1">
                 {(weighingAnalysis.missingComparisons ?? []).map((comparison, i) => (
                   <li key={i} className="flex items-start gap-2 text-sm">
@@ -320,7 +320,7 @@ export function AttackResults({ result, discoveredSources, onDiscuss, onPractice
             </div>
             <Separator />
             <div>
-              <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('attackResults.improvements')}</h4>
+              <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('attackResults.improvements')}</h3>
               <ul className="space-y-1">
                 {(weighingAnalysis.improvementSuggestions ?? []).map((suggestion, i) => (
                   <li key={i} className="flex items-start gap-2 text-sm">
diff --git a/src/components/features/brainstorm/BrainstormResults.tsx b/src/components/features/brainstorm/BrainstormResults.tsx
index 1a968aea9..3901e801c 100644
--- a/src/components/features/brainstorm/BrainstormResults.tsx
+++ b/src/components/features/brainstorm/BrainstormResults.tsx
@@ -44,7 +44,7 @@ function IdeaCard({ idea }: { idea: Idea }) {
   return (
     <div className={cn('rounded-lg border p-4 space-y-3 motion-list-item', strengthColors[strength] || strengthColors.moderate)}>
       <div className="flex items-start justify-between gap-2">
-        <h4 className="font-semibold text-foreground">{idea.title || t('brainstormResults.untitled')}</h4>
+        <h3 className="font-semibold text-foreground">{idea.title || t('brainstormResults.untitled')}</h3>
         <div className="flex gap-1 shrink-0">
           <Badge className={cn('text-xs', sideColors[side] || sideColors.neutral)}>
             {side === 'pro' ? t('brainstormResults.pro') : side === 'con' ? t('brainstormResults.con') : t('brainstormResults.neutral')}
@@ -203,10 +203,10 @@ export function BrainstormResults({ result, discoveredSources, onDiscuss }: Brai
           <div className="space-y-6">
             {result.mindmap.map((category, i) => (
               <div key={i}>
-                <h4 className="text-lg font-semibold text-foreground mb-3 flex items-center gap-2">
+                <h3 className="text-lg font-semibold text-foreground mb-3 flex items-center gap-2">
                   <div className="h-2 w-2 rounded-full bg-primary" />
                   {category.category}
-                </h4>
+                </h3>
                 <div className="grid gap-3 sm:grid-cols-2">
                   {category.items && Array.isArray(category.items) && category.items.map((idea) => (
                     <IdeaCard key={idea.id} idea={idea} />
diff --git a/src/components/features/factoids/FactoidsResults.tsx b/src/components/features/factoids/FactoidsResults.tsx
index 8ba14ec74..98e7138ac 100644
--- a/src/components/features/factoids/FactoidsResults.tsx
+++ b/src/components/features/factoids/FactoidsResults.tsx
@@ -54,13 +54,13 @@ function FactoidCard({ factoid, onSave }: { factoid: Factoid, onSave?: FactoidsR
               rel="noopener noreferrer"
               className="group flex items-center gap-2"
             >
-              <h4 className="font-semibold text-foreground group-hover:text-primary transition-colors underline-offset-4 group-hover:underline text-left">
+              <h3 className="font-semibold text-foreground group-hover:text-primary transition-colors underline-offset-4 group-hover:underline text-left">
                 {factoid.shortClaim}
-              </h4>
+              </h3>
               <ExternalLink className="h-3 w-3 shrink-0 opacity-60 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100" aria-hidden="true" />
             </a>
           ) : (
-            <h4 className="font-semibold text-foreground">{factoid.shortClaim}</h4>
+            <h3 className="font-semibold text-foreground">{factoid.shortClaim}</h3>
           )}
           <div className="flex items-center gap-2 mt-1">
             <Badge className={cn('text-xs', config.bg, config.color)}>
diff --git a/src/components/features/generate/GenerateForm.tsx b/src/components/features/generate/GenerateForm.tsx
index f9d65e64a..d3dfd761b 100644
--- a/src/components/features/generate/GenerateForm.tsx
+++ b/src/components/features/generate/GenerateForm.tsx
@@ -33,7 +33,9 @@ interface GenerateFormProps {
   debatePrefill?: boolean;
 }
 
-function OptionSelect<V extends string>({ value, onValueChange, options, triggerClassName }: {
+function OptionSelect<V extends string>({ id, labelId, value, onValueChange, options, triggerClassName }: {
+  id: string;
+  labelId: string;
   value: V;
   onValueChange: (value: V) => void;
   options: { value: V; label: string }[];
@@ -41,7 +43,7 @@ function OptionSelect<V extends string>({ value, onValueChange, options, trigger
 }) {
   return (
     <Select value={value} onValueChange={(next) => onValueChange(next as V)}>
-      <SelectTrigger className={triggerClassName}>
+      <SelectTrigger id={id} aria-labelledby={labelId} className={triggerClassName}>
         <SelectValue />
       </SelectTrigger>
       <SelectContent>
@@ -157,8 +159,10 @@ export function GenerateForm({ onSubmit, isLoading, debatePrefill = true }: Gene
           <div className="grid gap-4 sm:grid-cols-2">
             {/* Side */}
             <div className="space-y-2">
-              <Label className="text-sm font-medium">{t('generateForm.side')}</Label>
+              <Label id="generate-side-label" htmlFor="generate-side" className="text-sm font-medium">{t('generateForm.side')}</Label>
               <OptionSelect
+                id="generate-side"
+                labelId="generate-side-label"
                 value={currentValues.side}
                 onValueChange={(value) => setValue('side', value)}
                 options={[
@@ -170,8 +174,10 @@ export function GenerateForm({ onSubmit, isLoading, debatePrefill = true }: Gene
 
             {/* Role */}
             <div className="space-y-2">
-              <Label className="text-sm font-medium">{t('generateForm.role')}</Label>
+              <Label id="generate-role-label" htmlFor="generate-role" className="text-sm font-medium">{t('generateForm.role')}</Label>
               <OptionSelect
+                id="generate-role"
+                labelId="generate-role-label"
                 value={currentValues.role}
                 onValueChange={(value) => setValue('role', value)}
                 options={[
@@ -215,8 +221,10 @@ export function GenerateForm({ onSubmit, isLoading, debatePrefill = true }: Gene
             <div className="grid gap-4 pt-1 sm:grid-cols-3">
               {/* Length */}
               <div className="space-y-2 min-w-0">
-                <Label className="text-sm font-medium truncate block">{t('generateForm.length')}</Label>
+                <Label id="generate-length-label" htmlFor="generate-length" className="text-sm font-medium truncate block">{t('generateForm.length')}</Label>
                 <OptionSelect
+                  id="generate-length"
+                  labelId="generate-length-label"
                   value={currentValues.length}
                   onValueChange={(value) => setValue('length', value)}
                   triggerClassName="min-w-0"
@@ -230,8 +238,10 @@ export function GenerateForm({ onSubmit, isLoading, debatePrefill = true }: Gene
 
               {/* Audience */}
               <div className="space-y-2 min-w-0">
-                <Label className="text-sm font-medium truncate block">{t('generateForm.audience')}</Label>
+                <Label id="generate-audience-label" htmlFor="generate-audience" className="text-sm font-medium truncate block">{t('generateForm.audience')}</Label>
                 <OptionSelect
+                  id="generate-audience"
+                  labelId="generate-audience-label"
                   value={currentValues.audience}
                   onValueChange={(value) => setValue('audience', value)}
                   triggerClassName="min-w-0"
@@ -245,8 +255,10 @@ export function GenerateForm({ onSubmit, isLoading, debatePrefill = true }: Gene
 
               {/* Tone */}
               <div className="space-y-2 min-w-0">
-                <Label className="text-sm font-medium truncate block">{t('generateForm.tone')}</Label>
+                <Label id="generate-tone-label" htmlFor="generate-tone" className="text-sm font-medium truncate block">{t('generateForm.tone')}</Label>
                 <OptionSelect
+                  id="generate-tone"
+                  labelId="generate-tone-label"
                   value={currentValues.tone}
                   onValueChange={(value) => setValue('tone', value)}
                   triggerClassName="min-w-0"
diff --git a/src/components/features/generate/GenerateResults.tsx b/src/components/features/generate/GenerateResults.tsx
index 50a962168..2385128e8 100644
--- a/src/components/features/generate/GenerateResults.tsx
+++ b/src/components/features/generate/GenerateResults.tsx
@@ -35,10 +35,10 @@ function ArgumentCard({ contention, index, unverified }: { contention: Contentio
   return (
     <div className="rounded-lg border border-border bg-card p-4 space-y-3 motion-list-item">
       <div className="flex items-start justify-between gap-2">
-        <h4 className="font-semibold text-foreground">
+        <h3 className="font-semibold text-foreground">
           <span className="text-primary mr-2">#{index + 1}</span>
           {contention.claim}
-        </h4>
+        </h3>
         {contention.needsSource && (
           <Badge variant="outline" className="shrink-0 border-amber-500 text-amber-600">
             <AlertTriangle className="mr-1 h-3 w-3" />
@@ -173,7 +173,7 @@ export function GenerateResults({ result, discoveredSources, onRegenerateSection
   if (!result?.caseStructure || !result?.contentions || !result?.predictedOpponentCase || !result?.counters) {
     return (
       <div className="rounded-lg border border-destructive/50 bg-destructive/5 p-6 text-center">
-        <h3 className="text-lg font-semibold text-destructive mb-2">{t('generateResults.incomplete')}</h3>
+        <h2 className="text-lg font-semibold text-destructive mb-2">{t('generateResults.incomplete')}</h2>
         <p className="text-sm text-muted-foreground">
           {t('generateResults.incompleteDesc')}
         </p>
@@ -265,12 +265,12 @@ export function GenerateResults({ result, discoveredSources, onRegenerateSection
         >
           <div className="space-y-4">
             <div>
-              <h4 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.hook')}</h4>
+              <h3 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.hook')}</h3>
               <p className="text-foreground italic">{result.exordio.hook}</p>
             </div>
             <Separator />
             <div>
-              <h4 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.transition')}</h4>
+              <h3 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.transition')}</h3>
               <p className="text-foreground">{result.exordio.transition}</p>
             </div>
           </div>
@@ -287,21 +287,21 @@ export function GenerateResults({ result, discoveredSources, onRegenerateSection
       >
         <div className="space-y-4">
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.thesis')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.thesis')}</h3>
             <Markdown>{result.caseStructure.thesis}</Markdown>
           </div>
           <Separator />
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.framework')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.framework')}</h3>
             <Markdown>{result.caseStructure.framework}</Markdown>
           </div>
           <Separator />
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.burdenOfProof')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-1">{t('generateResults.burdenOfProof')}</h3>
             <Markdown>{result.caseStructure.burdenOfProof}</Markdown>
           </div>
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.keyDefinitions')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.keyDefinitions')}</h3>
             <ul className="list-disc list-inside space-y-1 text-sm text-foreground">
               {result.caseStructure.keyDefinitions?.map((def, i) => (
                 <li key={i}>{def}</li>
@@ -336,7 +336,7 @@ export function GenerateResults({ result, discoveredSources, onRegenerateSection
       >
         <div className="space-y-4">
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.likelyArguments')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.likelyArguments')}</h3>
             <ul className="space-y-2">
               {result.predictedOpponentCase?.likelyArguments?.map((arg, i) => (
                 <li key={i} className="flex items-start gap-2 text-sm">
@@ -348,7 +348,7 @@ export function GenerateResults({ result, discoveredSources, onRegenerateSection
           </div>
           <Separator />
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.strategicWeaknesses')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.strategicWeaknesses')}</h3>
             <ul className="space-y-2">
               {result.predictedOpponentCase?.strategicWeaknesses?.map((weakness, i) => (
                 <li key={i} className="flex items-start gap-2 text-sm">
@@ -360,7 +360,7 @@ export function GenerateResults({ result, discoveredSources, onRegenerateSection
           </div>
           <Separator />
           <div>
-            <h4 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.keyClashes')}</h4>
+            <h3 className="text-sm font-medium text-muted-foreground mb-2">{t('generateResults.keyClashes')}</h3>
             <div className="flex flex-wrap gap-2">
               {result.predictedOpponentCase?.keyClashes?.map((clash, i) => (
                 <Badge key={i} variant="outline">{clash}</Badge>
diff --git a/src/components/landing/Hero.tsx b/src/components/landing/Hero.tsx
index 0e59e00e4..449c8673a 100644
--- a/src/components/landing/Hero.tsx
+++ b/src/components/landing/Hero.tsx
@@ -163,7 +163,7 @@ const HeroPreview = () => {
                             </div>
                         </div>
 
-                        <div className="space-y-3">
+                        <div className="space-y-3" aria-hidden="true" {...{ inert: '' }}>
                             <div className="space-y-1.5">
                                 <label htmlFor="hero-motion" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
                                     {t('hero.preview.topicLabel')}
@@ -173,6 +173,7 @@ const HeroPreview = () => {
                                     type="text"
                                     value={motionText}
                                     readOnly
+                                    tabIndex={-1}
                                     className="w-full rounded-md border border-border/70 bg-background px-3 py-2 text-sm text-foreground outline-none transition-colors placeholder:text-muted-foreground focus:border-primary focus:ring-2 focus:ring-primary/20"
                                 />
                             </div>
@@ -191,7 +192,7 @@ const HeroPreview = () => {
                         </div>
                     </div>
 
-                    <div className="space-y-3 rounded-xl border border-border/70 bg-card p-4">
+                    <div className="space-y-3 rounded-xl border border-border/70 bg-card p-4" aria-hidden="true">
                         <div>
                             <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">{sample.title}</p>
                         </div>
diff --git a/src/components/ui/card.tsx b/src/components/ui/card.tsx
index ee1622766..192afafee 100644
--- a/src/components/ui/card.tsx
+++ b/src/components/ui/card.tsx
@@ -14,9 +14,16 @@ const CardHeader = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDiv
 );
 CardHeader.displayName = "CardHeader";
 
-const CardTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(
-  ({ className, ...props }, ref) => (
-    <h3 ref={ref} className={cn("text-lg font-semibold leading-tight tracking-[-0.014em]", className)} {...props} />
+type HeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+type CardTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+  /** Heading level. h2 sits directly under a page h1 without skipping a level. */
+  as?: HeadingLevel;
+};
+
+const CardTitle = React.forwardRef<HTMLHeadingElement, CardTitleProps>(
+  ({ className, as: Heading = "h2", ...props }, ref) => (
+    <Heading ref={ref} className={cn("text-lg font-semibold leading-tight tracking-[-0.014em]", className)} {...props} />
   ),
 );
 CardTitle.displayName = "CardTitle";
diff --git a/src/components/ui/empty-state.tsx b/src/components/ui/empty-state.tsx
index 228edc272..dcb29739b 100644
--- a/src/components/ui/empty-state.tsx
+++ b/src/components/ui/empty-state.tsx
@@ -13,7 +13,7 @@ export function EmptyState({ icon: Icon, title, description, actionLabel, onActi
   return (
     <div className="flex flex-col items-center justify-center rounded-lg border-2 border-dashed border-border bg-card/50 px-6 py-12 text-center">
       <Icon className="mb-4 h-10 w-10 text-muted-foreground/40" />
-      <h3 className="text-base font-semibold text-foreground">{title}</h3>
+      <h2 className="text-base font-semibold text-foreground">{title}</h2>
       {description && <p className="mt-1 max-w-sm text-sm text-muted-foreground">{description}</p>}
       {actionLabel && onAction && (
         <Button className="mt-4" variant="outline" onClick={onAction}>
diff --git a/src/components/ui/progress.tsx b/src/components/ui/progress.tsx
index 9bb1339cb..e95dd5782 100644
--- a/src/components/ui/progress.tsx
+++ b/src/components/ui/progress.tsx
@@ -10,6 +10,7 @@ const Progress = React.forwardRef<
   <ProgressPrimitive.Root
     ref={ref}
     className={cn("relative h-4 w-full overflow-hidden rounded-full bg-secondary", className)}
+    value={value}
     {...props}
   >
     <ProgressPrimitive.Indicator
diff --git a/src/components/ui/sonner.tsx b/src/components/ui/sonner.tsx
index bf352ad6a..cfeffede9 100644
--- a/src/components/ui/sonner.tsx
+++ b/src/components/ui/sonner.tsx
@@ -28,6 +28,7 @@ const Toaster = ({ ...props }: ToasterProps) => {
         },
       }}
       {...props}
+      containerAriaLabel={t("common.notifications")}
     />
   );
 };
diff --git a/src/locales/en.json b/src/locales/en.json
index 83acb026f..cc44ac72b 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -231,6 +231,7 @@
     "openingPage": "Opening {{page}}",
     "page": "Page",
     "close": "Close",
+    "notifications": "Notifications",
     "loading": "Loading",
     "error": "Error",
     "logoAlt": "DebateLab logo",
@@ -1429,6 +1430,7 @@
   "timer": {
     "title": "Debate Timer",
     "displayLabel": "Timer display",
+    "speechProgress": "{{speech}} progress",
     "selectFormat": "Select Format",
     "formatStandard": "Standard (4-6-6-3)",
     "formatLD": "Lincoln-Douglas",
@@ -1548,6 +1550,7 @@
     "autoLayout": "Auto layout",
     "edgeAttack": "Attack",
     "edgeRebuttal": "Rebuttal",
+    "edgeTypeLabel": "Link type",
     "edgeSupport": "Support",
     "exportFailedToast": "Could not export flowchart.",
     "selectedNode": "Selected",
diff --git a/src/locales/es.json b/src/locales/es.json
index fc263f2f4..138d1b8f1 100644
--- a/src/locales/es.json
+++ b/src/locales/es.json
@@ -231,6 +231,7 @@
     "openingPage": "Abriendo {{page}}",
     "page": "Página",
     "close": "Cerrar",
+    "notifications": "Notificaciones",
     "loading": "Cargando",
     "error": "Error",
     "logoAlt": "Logotipo de DebateLab",
@@ -1429,6 +1430,7 @@
   "timer": {
     "title": "Temporizador de debate",
     "displayLabel": "Pantalla del temporizador",
+    "speechProgress": "Progreso de {{speech}}",
     "selectFormat": "Seleccionar formato",
     "formatStandard": "Estándar (4-6-6-3)",
     "formatLD": "Lincoln-Douglas",
@@ -1548,6 +1550,7 @@
     "autoLayout": "Organizar automáticamente",
     "edgeAttack": "Ataque",
     "edgeRebuttal": "Refutación",
+    "edgeTypeLabel": "Tipo de enlace",
     "edgeSupport": "Apoyo",
     "exportFailedToast": "No se pudo exportar el diagrama.",
     "selectedNode": "Seleccionado",
diff --git a/src/locales/hu.json b/src/locales/hu.json
index 53f16ab34..8a31a4620 100644
--- a/src/locales/hu.json
+++ b/src/locales/hu.json
@@ -231,6 +231,7 @@
     "openingPage": "{{page}} megnyitása",
     "page": "Oldal",
     "close": "Bezárás",
+    "notifications": "Értesítések",
     "loading": "Betöltés",
     "error": "Hiba",
     "logoAlt": "DebateLab logó",
@@ -1429,6 +1430,7 @@
   "timer": {
     "title": "Vita időmérő",
     "displayLabel": "Időmérő kijelző",
+    "speechProgress": "{{speech}} előrehaladása",
     "selectFormat": "Formátum választása",
     "formatStandard": "Standard (4-6-6-3)",
     "formatLD": "Lincoln-Douglas",
@@ -1548,6 +1550,7 @@
     "autoLayout": "Automatikus elrendezés",
     "edgeAttack": "Támadás",
     "edgeRebuttal": "Cáfolat",
+    "edgeTypeLabel": "Kapcsolat típusa",
     "edgeSupport": "Alátámasztás",
     "exportFailedToast": "Nem sikerült exportálni a folyamatábrát.",
     "selectedNode": "Kiválasztva",
diff --git a/src/pages/AdminPage.tsx b/src/pages/AdminPage.tsx
index 4056b8069..98cb06a05 100644
--- a/src/pages/AdminPage.tsx
+++ b/src/pages/AdminPage.tsx
@@ -731,8 +731,8 @@ export default function AdminPage() {
             <div className="container py-8 px-4">
                 <Card className="max-w-md mx-auto">
                     <CardHeader>
-                        <CardTitle className="flex items-center gap-2">
-                            <Shield className="h-5 w-5 text-destructive" />
+                        <CardTitle as="h1" className="flex items-center gap-2">
+                            <Shield className="h-5 w-5 text-destructive" aria-hidden="true" />
                             {t('admin.dashboard.accessDenied')}
                         </CardTitle>
                         <CardDescription>
diff --git a/src/pages/FlowchartPage.tsx b/src/pages/FlowchartPage.tsx
index d33da9586..b45cb7018 100644
--- a/src/pages/FlowchartPage.tsx
+++ b/src/pages/FlowchartPage.tsx
@@ -634,8 +634,9 @@ export default function FlowchartPage() {
                                     </DialogHeader>
                                     <div className="space-y-4 py-4">
                                         <div className="space-y-2">
-                                            <Label>{t('flowchart.titleField')}</Label>
+                                            <Label htmlFor="flowchart-save-title">{t('flowchart.titleField')}</Label>
                                             <Input
+                                                id="flowchart-save-title"
                                                 placeholder={t('flowchart.titlePlaceholder')}
                                                 value={saveTitle}
                                                 onChange={(e) => setSaveTitle(e.target.value)}
@@ -664,25 +665,27 @@ export default function FlowchartPage() {
                                     </DialogHeader>
                                     <div className="space-y-4 py-4">
                                         <div className="space-y-2">
-                                            <Label>{t('flowchart.labelField')}</Label>
+                                            <Label htmlFor="flowchart-node-label">{t('flowchart.labelField')}</Label>
                                             <Input
+                                                id="flowchart-node-label"
                                                 placeholder={t('flowchart.labelPlaceholder')}
                                                 value={newNodeLabel}
                                                 onChange={(e) => setNewNodeLabel(e.target.value)}
                                             />
                                         </div>
                                         <div className="space-y-2">
-                                            <Label>{t('flowchart.descriptionField')}</Label>
+                                            <Label htmlFor="flowchart-node-description">{t('flowchart.descriptionField')}</Label>
                                             <Textarea
+                                                id="flowchart-node-description"
                                                 placeholder={t('flowchart.descPlaceholder')}
                                                 value={newNodeDescription}
                                                 onChange={(e) => setNewNodeDescription(e.target.value)}
                                             />
                                         </div>
                                         <div className="space-y-2">
-                                            <Label>{t('flowchart.typeField')}</Label>
+                                            <Label id="flowchart-node-type-label" htmlFor="flowchart-node-type">{t('flowchart.typeField')}</Label>
                                             <Select value={newNodeType} onValueChange={(v) => setNewNodeType(v as NodeType)}>
-                                                <SelectTrigger>
+                                                <SelectTrigger id="flowchart-node-type" aria-labelledby="flowchart-node-type-label">
                                                     <SelectValue />
                                                 </SelectTrigger>
                                                 <SelectContent>
@@ -695,9 +698,9 @@ export default function FlowchartPage() {
                                         </div>
                                         {newNodeType === 'contention' && (
                                             <div className="space-y-2">
-                                                <Label>{t('flowchart.strengthField')}</Label>
+                                                <Label id="flowchart-node-strength-label" htmlFor="flowchart-node-strength">{t('flowchart.strengthField')}</Label>
                                                 <Select value={newNodeStrength} onValueChange={(v) => setNewNodeStrength(v as 'strong' | 'moderate' | 'weak')}>
-                                                    <SelectTrigger>
+                                                    <SelectTrigger id="flowchart-node-strength" aria-labelledby="flowchart-node-strength-label">
                                                         <SelectValue />
                                                     </SelectTrigger>
                                                     <SelectContent>
@@ -736,7 +739,7 @@ export default function FlowchartPage() {
                             )}
 
                             <Select value={selectedEdgeType} onValueChange={(value) => setSelectedEdgeType(value as EdgeKind)}>
-                                <SelectTrigger className="h-9 w-[132px]">
+                                <SelectTrigger className="h-9 w-[132px]" aria-label={t('flowchart.edgeTypeLabel')}>
                                     <SelectValue />
                                 </SelectTrigger>
                                 <SelectContent>
@@ -789,7 +792,7 @@ export default function FlowchartPage() {
                                         <div className="min-w-0">
                                             <div className="flex flex-wrap items-center gap-2">
                                                 <Badge variant="secondary">{t('flowchart.selectedNode', 'Selected')}</Badge>
-                                                <h3 className="truncate text-sm font-semibold">{node.data.label}</h3>
+                                                <h3 aria-level={2} className="truncate text-sm font-semibold">{node.data.label}</h3>
                                             </div>
                                             {node.data.description && (
                                                 <p className="mt-1 line-clamp-2 text-sm text-muted-foreground">{node.data.description}</p>
diff --git a/src/pages/TimerPage.tsx b/src/pages/TimerPage.tsx
index aa92da79a..29d1b908e 100644
--- a/src/pages/TimerPage.tsx
+++ b/src/pages/TimerPage.tsx
@@ -300,7 +300,7 @@ export default function TimerPage() {
               </div>
             </div>
 
-            <Progress value={progress} className="h-2 w-full" />
+            <Progress value={progress} className="h-2 w-full" aria-label={t('timer.speechProgress', { speech: t(currentSpeech.labelKey) })} />
 
             {/* Controls */}
             <div className="flex justify-center gap-4">
diff --git a/src/test/a11y/names-and-headings.test.tsx b/src/test/a11y/names-and-headings.test.tsx
new file mode 100644
index 000000000..b969dc966
--- /dev/null
+++ b/src/test/a11y/names-and-headings.test.tsx
@@ -0,0 +1,128 @@
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MemoryRouter } from 'react-router-dom';
+import i18n from '@/i18n';
+import { CardTitle } from '@/components/ui/card';
+import { Toaster } from '@/components/ui/sonner';
+import { LanguageSwitcher } from '@/components/LanguageSwitcher';
+import { GenerateForm } from '@/components/features/generate/GenerateForm';
+import { AttackForm } from '@/components/features/attack/AttackForm';
+import Hero from '@/components/landing/Hero';
+import TimerPage from '@/pages/TimerPage';
+
+vi.mock('@/hooks/use-subscription', () => ({
+  useSubscription: () => ({ isPro: false, tier: 'trial', loading: false }),
+}));
+
+vi.mock('@/components/layout/HeaderTooltip', () => ({
+  HeaderTooltip: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+vi.mock('@/components/ui/popover', () => ({
+  Popover: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  PopoverTrigger: ({ children }: { children: React.ReactNode }) => children,
+  PopoverContent: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+}));
+
+beforeEach(() => {
+  HTMLElement.prototype.scrollIntoView = () => {};
+  HTMLElement.prototype.hasPointerCapture = () => false;
+  HTMLElement.prototype.setPointerCapture = () => {};
+  HTMLElement.prototype.releasePointerCapture = () => {};
+});
+
+afterEach(async () => {
+  cleanup();
+  await i18n.changeLanguage('en');
+});
+
+describe('accessible names and headings', () => {
+  it('renders CardTitle as an h2 by default and keeps the same classes at another level', () => {
+    const { rerender } = render(<CardTitle>Prepare</CardTitle>);
+    const title = screen.getByRole('heading', { level: 2, name: 'Prepare' });
+    expect(title.className).toContain('text-lg');
+    expect(title.className).toContain('font-semibold');
+    expect(title.className).toContain('leading-tight');
+    expect(title.className).toContain('tracking-[-0.014em]');
+
+    rerender(<CardTitle as="h1">Access Denied</CardTitle>);
+    expect(screen.getByRole('heading', { level: 1, name: 'Access Denied' }).className).toContain('text-lg');
+  });
+
+  it('names the notification region in the active language', async () => {
+    const { rerender } = render(<Toaster />);
+    // Sonner appends the focus shortcut to containerAriaLabel.
+    expect(screen.getByRole('region', { name: 'Notifications alt+T' })).toBeInTheDocument();
+
+    await act(async () => { await i18n.changeLanguage('es'); });
+    rerender(<Toaster />);
+    expect(screen.getByRole('region', { name: 'Notificaciones alt+T' })).toBeInTheDocument();
+
+    await act(async () => { await i18n.changeLanguage('hu'); });
+    rerender(<Toaster />);
+    expect(screen.getByRole('region', { name: 'Értesítések alt+T' })).toBeInTheDocument();
+  });
+
+  it('names the language button and both language groups in English, Spanish and Hungarian', async () => {
+    const { rerender } = render(<LanguageSwitcher />);
+    expect(screen.getByRole('button', { name: 'Language' })).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup', { name: 'Interface language' })).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup', { name: 'AI output language' })).toBeInTheDocument();
+
+    await act(async () => { await i18n.changeLanguage('es'); });
+    rerender(<LanguageSwitcher />);
+    expect(screen.getByRole('button', { name: 'Idioma' })).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup', { name: 'Idioma de la interfaz' })).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup', { name: 'Idioma de salida de IA' })).toBeInTheDocument();
+
+    await act(async () => { await i18n.changeLanguage('hu'); });
+    rerender(<LanguageSwitcher />);
+    expect(screen.getByRole('button', { name: 'Nyelv' })).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup', { name: 'Felület nyelve' })).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup', { name: 'AI kimenet nyelve' })).toBeInTheDocument();
+  });
+
+  it('names Generate selects from their visible labels', () => {
+    render(<GenerateForm onSubmit={() => {}} isLoading={false} debatePrefill={false} />);
+    expect(screen.getByRole('combobox', { name: 'Side' })).toBeInTheDocument();
+    expect(screen.getByRole('combobox', { name: 'Speaker Role' })).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: 'More options' }));
+    expect(screen.getByRole('combobox', { name: 'Case Length' })).toBeInTheDocument();
+    expect(screen.getByRole('combobox', { name: 'Audience Level' })).toBeInTheDocument();
+    expect(screen.getByRole('combobox', { name: 'Tone' })).toBeInTheDocument();
+  });
+
+  it('names Attack switches from their labels and selects from theirs', () => {
+    render(<AttackForm onSubmit={() => {}} isLoading={false} debateContext={false} />);
+    fireEvent.click(screen.getByRole('button', { name: /More options/ }));
+    expect(screen.getByRole('switch', { name: 'Detect Fallacies' })).toHaveAccessibleDescription('Identify logical fallacies in the argument');
+    expect(screen.getByRole('switch', { name: 'Analyze Weighing' })).toHaveAccessibleDescription('Evaluate impact comparison and prioritization');
+    expect(screen.getByRole('combobox', { name: 'Attack Intensity' })).toBeInTheDocument();
+    expect(screen.getByRole('combobox', { name: 'Judge Paradigm' })).toBeInTheDocument();
+  });
+
+  it('names the timer progress bar with the current speech and a numeric value', async () => {
+    const { rerender } = render(<TimerPage />);
+    const bar = screen.getByRole('progressbar', { name: 'Introductor progress' });
+    expect(bar).toHaveAttribute('aria-valuenow', '0');
+    expect(bar).not.toHaveAttribute('data-state', 'indeterminate');
+
+    await act(async () => { await i18n.changeLanguage('es'); });
+    rerender(<TimerPage />);
+    expect(screen.getByRole('progressbar', { name: 'Progreso de Introductor' })).toBeInTheDocument();
+
+    await act(async () => { await i18n.changeLanguage('hu'); });
+    rerender(<TimerPage />);
+    expect(screen.getByRole('progressbar', { name: 'Bevezető előrehaladása' })).toBeInTheDocument();
+  });
+
+  it('keeps the hero mode toggles available and the fake preview out of the tab order', () => {
+    render(<MemoryRouter><Hero /></MemoryRouter>);
+    expect(screen.getByRole('button', { name: 'Generate', pressed: true })).toBeInTheDocument();
+    const motion = document.getElementById('hero-motion');
+    expect(motion).toHaveAttribute('tabindex', '-1');
+    expect(motion?.closest('[aria-hidden="true"]')).toBeTruthy();
+    expect(motion?.closest('[inert]')).toBeTruthy();
+  });
+});

From 23828f3d8beb8dc2a8c986d0842776d1c7596924 Mon Sep 17 00:00:00 2001
From: Adam <adam.gaborjani.szabo@gmail.com>
Date: Thu, 22 Oct 2026 23:16:06 +0000
Subject: [PATCH 2/2] fix(a11y): render the selected flowchart node title as a
 real h2

---
 src/pages/FlowchartPage.tsx | 2 +-
 src/pages/LoginPage.tsx     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pages/FlowchartPage.tsx b/src/pages/FlowchartPage.tsx
index b45cb7018..73197a5cd 100644
--- a/src/pages/FlowchartPage.tsx
+++ b/src/pages/FlowchartPage.tsx
@@ -792,7 +792,7 @@ export default function FlowchartPage() {
                                         <div className="min-w-0">
                                             <div className="flex flex-wrap items-center gap-2">
                                                 <Badge variant="secondary">{t('flowchart.selectedNode', 'Selected')}</Badge>
-                                                <h3 aria-level={2} className="truncate text-sm font-semibold">{node.data.label}</h3>
+                                                <h2 className="truncate text-sm font-semibold">{node.data.label}</h2>
                                             </div>
                                             {node.data.description && (
                                                 <p className="mt-1 line-clamp-2 text-sm text-muted-foreground">{node.data.description}</p>
diff --git a/src/pages/LoginPage.tsx b/src/pages/LoginPage.tsx
index 6d0aebd3c..10ddc1eb3 100644
--- a/src/pages/LoginPage.tsx
+++ b/src/pages/LoginPage.tsx
@@ -186,7 +186,7 @@ export default function LoginPage() {
           <div className="mx-auto mb-3 flex h-12 w-12 items-center justify-center overflow-hidden rounded-lg bg-white dark:bg-slate-800">
             <img src="/favicon-72.png" alt="" width={48} height={48} className="h-full w-full object-cover" />
           </div>
-          {/* The page heading, styled like CardTitle (which renders an h3). */}
+          {/* The page heading, styled like CardTitle (which renders an h2 by default). */}
           <h1 className="text-2xl font-semibold leading-none tracking-tight">{t('login.title')}</h1>
           <CardDescription>{t('login.subtitle')}</CardDescription>
         </CardHeader>