Request for help with an accessible app in Flet and empty elements created in complex windows.

[Ambro86]

Question

Hi everyone,
First of all, thank you for developing Flet. I really love Python, and it's amazing to be able to develop apps for iPhone and Android using this language.
I'm currently working on a text adventure RPG, fully accessible to blind users, with music, sound effects, and more. The project is free and open-source — you can check it out here:
👉 https://github.com/Ambro86/AccessibleIphoneApp/
Right now, the game is only available in Italian, but I plan to add more languages soon.
However, I'm facing an issue and hope someone here can help. When I create windows with several buttons (e.g. 6 or 7), everything works fine on Windows. But on iPhone, when using VoiceOver (the built-in screen reader), I notice that some "empty" elements are detected — meaning VoiceOver reads nothing in those spots. These empty elements appear, for example, before the screen title or between sections.
This behavior affects accessibility, which is a top priority for me as a blind developer. I’ve managed to implement everything else — music, game saving, sound effects, color changes, icons, etc. — but this issue is really blocking me.
Is there any workaround or fix to avoid these empty elements from being generated?
I’ve also opened an issue here:
👉 #5417
Thanks a lot in advance for any help you can provide! I really hope there’s a way around this.
Best regards,
Ambro

Code sample

def crea_vista_gioco(self):
        """Crea la vista principale di gioco"""
        
        # Titolo con Semantics senza label
        titolo = ft.Semantics(
            container=True,
            content=ft.Text(
                "AVVENTURA IN CORSO", 
                size=24, 
                weight=ft.FontWeight.BOLD, 
                text_align=ft.TextAlign.CENTER,
                color=ft.Colors.AMBER_400,
                style=ft.TextThemeStyle.HEADLINE_MEDIUM
            )
        )
        
        # Ottieni i valori attuali dalle variabili globali se esistono
        valore_storia = "🎮 Benvenuto nell'Avventura Incrementale!\n Compagni gatti con abilità speciali\n Raccogli risorse e costruisci\n Combatti mostri e sali di livello\n🍽️ Gestisci cibo e acqua per energia\n🎵 Audio immersivo e feedback aptico\n\nPremi 'Inizia Avventura' per cominciare!"
        if hasattr(self, 'area_storia') and self.area_storia and hasattr(self.area_storia, 'value'):
            valore_storia = self.area_storia.value
        
        valore_stats = f" Statistiche Giocatore:\n Livello {self.livello} •  {self.vita}/{self.vita_massima} HP •  {self.monete} monete\n Attacco: {self.calcola_attacco_totale()} •  Difesa: {self.calcola_difesa_totale()}\n EXP: {self.esperienza}/{self.esperienza_necessaria}"
        if hasattr(self, 'area_stats') and self.area_stats and hasattr(self.area_stats, 'value'):
            valore_stats = self.area_stats.value
        
        # Area storia come gruppo semantico
        area_storia_locale = ft.Semantics(
            container=True,
            content=ft.Container(
                content=ft.Text(
                    valore_storia,
                    size=14,
                    color=ft.Colors.AMBER_100
                ),
                bgcolor=ft.Colors.DEEP_PURPLE_900,
                border_radius=5,
                padding=10,
                expand=True
            )
        )

        # Area statistiche come gruppo semantico con TextField
        area_stats_textfield = ft.TextField(
            value=valore_stats,
            multiline=True,
            read_only=True,
            min_lines=4,
            max_lines=6,
            text_size=14,
            color=ft.Colors.CYAN_100,
            border_color=ft.Colors.TRANSPARENT,
            focused_border_color=ft.Colors.TRANSPARENT,
            bgcolor=ft.Colors.TRANSPARENT
        )
        
        area_stats_locale = ft.Semantics(
            container=True,
            content=ft.Container(
                content=area_stats_textfield,
                bgcolor=ft.Colors.BLUE_GREY_900,
                border_radius=5,
                padding=10
            )
        )
        
        # Aggiorna i riferimenti globali per mantenere la sincronizzazione
        self.area_storia = area_storia_locale
        self.area_stats = area_stats_textfield  # Punta al TextField per aggiornamenti
        
        # Pulsanti di gioco
        pulsanti_gioco = []
        
        # Elemento decorativo per evitare elemento vuoto
        elemento_decorativo = ft.Semantics(
            container=True,
            content=ft.Container(height=1, bgcolor=ft.Colors.TRANSPARENT)
        )
        pulsanti_gioco.append(elemento_decorativo)
        
        # Azioni incrementali senza Semantics
        azioni_incrementali = self.azioni_incrementali_possibili()
        for i, (testo, funzione, tooltip) in enumerate(azioni_incrementali):
            pulsante_incrementale = ft.ElevatedButton(
                text=testo,
                on_click=funzione,
                width=280,
                height=50,
                bgcolor=ft.Colors.GREEN_600,
                color=ft.Colors.WHITE,
                tooltip=tooltip,
                key=f"azione_{i}_{testo.replace(' ', '_')}"
            )
            pulsanti_gioco.append(pulsante_incrementale)
        
        # Pulsante cambio area
        if len(self.aree_sbloccate) > 1:
            pulsante_aree = ft.ElevatedButton(
                text="Cambia Area",
                on_click=lambda e: self.page.go("/aree"),
                width=280,
                height=50,
                bgcolor=ft.Colors.BLUE_600,
                color=ft.Colors.WHITE,
                tooltip="Scegli area da esplorare",
                key="btn_cambia_area"
            )
            pulsanti_gioco.append(pulsante_aree)
        
        # Pulsanti di navigazione
        pulsante_combattimento = ft.ElevatedButton(
            text="Combattimento",
            on_click=lambda e: self.page.go("/combattimento"),
            width=280,
            height=50,
            bgcolor=ft.Colors.RED_600,
            color=ft.Colors.WHITE,
            tooltip="Combatti contro i mostri"
        )
        
        pulsante_negozio = ft.ElevatedButton(
            text="Negozio",
            on_click=lambda e: self.page.go("/negozio"),
            width=280,
            height=50,
            bgcolor=ft.Colors.ORANGE_600,
            color=ft.Colors.WHITE,
            tooltip="Visita il negozio"
        )
        
        pulsante_gatti = ft.ElevatedButton(
            text="Gatti",
            on_click=lambda e: self.page.go("/gatti"),
            width=280,
            height=50,
            bgcolor=ft.Colors.PINK_600,
            color=ft.Colors.WHITE,
            tooltip="Gestisci i tuoi gatti"
        )
        
        pulsanti_gioco.extend([pulsante_combattimento, pulsante_negozio, pulsante_gatti])
        
        # Pulsante boss
        if (self.area_attuale in self.boss_aree and 
            self.boss_aree[self.area_attuale]["nome"] not in self.boss_sconfitti and
            self.progressione_area.get(self.area_attuale, 0) >= 100):
            pulsante_boss = ft.ElevatedButton(
                text="Combatti Boss dell'Area!",
                on_click=self.combatti_boss,
                width=280,
                height=50,
                bgcolor=ft.Colors.DEEP_PURPLE_600,
                color=ft.Colors.WHITE,
                tooltip=f"Affronta il boss: {self.boss_aree[self.area_attuale]['nome']}"
            )
            pulsanti_gioco.append(pulsante_boss)
        
        # Pulsante salva
        pulsante_salva = ft.ElevatedButton(
            text="Salva Partita",
            on_click=self.salva_gioco,
            width=280,
            height=50,
            bgcolor=ft.Colors.PURPLE_600,
            color=ft.Colors.WHITE,
            tooltip="Salva il tuo progresso"
        )
        pulsanti_gioco.append(pulsante_salva)
        
        # Colonna pulsanti senza Semantics per permettere accesso individuale
        lista_pulsanti = ft.Column(
            controls=pulsanti_gioco,
            horizontal_alignment=ft.CrossAxisAlignment.CENTER,
            spacing=15,
            scroll=ft.ScrollMode.AUTO
        )
        
        # Controlli di gioco senza label per preservare il contenuto naturale
        gioco_controls = ft.Column([
            area_storia_locale,
            area_stats_locale,
            lista_pulsanti
        ], spacing=10, tight=False)
        
        # Pulsante menu come gruppo semantico
        pulsante_menu = ft.Semantics(
            container=True,
            content=ft.ElevatedButton(
                text="Torna al Menu",
                on_click=lambda e: self.page.go("/"),
                width=200,
                height=50,
                bgcolor=ft.Colors.GREY_600,
                color=ft.Colors.WHITE,
                tooltip="Torna al menu principale"
            )
        )
        
        # Content principale senza height fisso per evitare contenuto vuoto
        content = ft.Column([
            titolo,
            ft.Container(
                content=gioco_controls,
                bgcolor=ft.Colors.GREY_800,
                border_radius=10,
                padding=10,
                expand=True  # Usa expand invece di height
            ),
            pulsante_menu
        ], scroll=ft.ScrollMode.AUTO, spacing=30, expand=True)
        
        return ft.View(
            "/gioco",
            controls=[
                # Semantics senza label per evitare elemento vuoto ma preservare contenuto
                ft.Semantics(
                    container=True,
                    content=ft.Container(
                        content=content,
                        bgcolor=ft.Colors.GREY_900,
                        padding=20,
                        expand=True
                    )
                )
            ],
            bgcolor=ft.Colors.GREY_900
        )

Error message

No response

------------------------------------------------------

• I have searched for answers to my question both in the issues and in previous discussions.

[GianSandoval5]

Hola Ambro, gracias por tu reporte y por los detalles que compartiste.

Entendemos la situación y la importancia de brindar una experiencia accesible desde el inicio de la aplicación. En este caso, el comportamiento que describes (el VoiceOver leyendo automáticamente el contenido sin tocar la pantalla) está relacionado con cómo se gestiona el foco accesible en iOS cuando se presenta la pantalla principal.

Para ayudarte mejor, queremos confirmar algunos puntos:

¿El widget principal (Scaffold, MaterialApp, etc.) está envuelto con algún Semantics o Focus específico?

¿Has probado usar Semantics con focusable: true y explicitChildNodes: true para forzar el foco accesible inicial en un widget específico?

¿El contenido que deseas que se lea primero tiene un label accesible correctamente definido?

Si lo deseas, podemos trabajar en una solución o proporcionar un ejemplo mínimo reproducible con ese comportamiento.

Quedo atento a tu respuesta para avanzar con esto.

Saludos cordiales,
Gian Sandoval

[Ambro86]

Estimado Gian Sandoval,

Espero que este mensaje te encuentre bien. Te escribo nuevamente porque he descubierto un problema crítico con la solución de accesibilidad que implementamos anteriormente para nuestra aplicación "Avventura Epica".

PROBLEMA ACTUAL - REGRESIÓN DE ACCESIBILIDAD:
Después de tu valioso feedback inicial, conseguimos resolver el problema de VoiceOver con elementos vacíos usando autofocus=True en los elementos principales. La solución funcionaba perfectamente cuando ejecutaba la app en modo desarrollo con flet run --ios. Sin embargo, ahora he descubierto que cuando compilo la aplicación para distribución (usando flet build ipa), el problema de accesibilidad regresa: VoiceOver vuelve a detectar contenido vacío y no lee automáticamente los elementos.

UBICACIÓN ESPECÍFICA DEL ELEMENTO VACÍO:
En la build compilada, VoiceOver detecta un elemento vacío que aparece:

• DESPUÉS del título "AVVENTURA IN CORSO"
• ANTES del área de historia que contiene el texto "Un tranquillo villaggio di campagna con case di pietra. Gli abitanti ti salutano calorosamente..."

Este elemento vacío no existe cuando ejecuto flet run --ios en modo desarrollo, pero aparece consistentemente en todas las builds compiladas (release y profile mode).

DIFERENCIA CRÍTICA DESCUBIERTA:

• ✅ flet run --ios (modo debug): VoiceOver funciona perfectamente, autofocus=True es respetado
• ❌ flet build ipa (modo release/profile): VoiceOver encuentra contenido vacío, autofocus=True parece ignorado

INTENTOS DE SOLUCIÓN REALIZADOS:
He probado múltiples enfoques para resolver esta discrepancia:

1. MODOS DE COMPILACIÓN:

   • --flutter-build-args=--release (producción): Problema de accesibilidad
   • --flutter-build-args=--debug (debug): App se cierra inmediatamente al abrir
   • --flutter-build-args=--profile (intermedio): App funciona pero persiste problema accesibilidad

2. CONFIGURACIONES INFO.PLIST:

   --info-plist "UIAccessibilityEnabled=True"
   --info-plist "UIAccessibilityTraits=True"
   

   Resultado: Sin mejoras en accesibilidad

3. VERSIONES Y DEPENDENCIAS:

   • Verificado que uso exactamente la misma versión de Flet (0.28.3) en desarrollo y CI
   • Flutter versión fija 3.22.1 en ambos entornos
   • Python 3.13 en ambos entornos

4. MODIFICACIONES CÓDIGO:

   • Probado ft.TextField en lugar de ft.Text para títulos
   • Probado contenedores ft.Semantics (no soportados por Flet)
   • Mantenido estrategia autofocus=True en primeros elementos

ARQUITECTURA ACTUAL DE ACCESIBILIDAD:

# Menu Principal
def crea_vista_menu_principale(self):
    titolo = ft.Text("Avventura Epica", ...)  # Sin autofocus
    
    pulsanti = [
        ft.ElevatedButton(
            text="Inizia Gioco",
            autofocus=True,  # ✅ Funciona en desarrollo, ❌ ignorado en build
            ...
        ),
        ...
    ]

# Vista Gioco  
def crea_vista_gioco(self):
    titolo = ft.TextField(
        value="AVVENTURA IN CORSO",
        autofocus=True,  # ✅ Funciona en desarrollo, ❌ ignorado en build
        read_only=True,
        ...
    )

HIPÓTESIS SOBRE EL PROBLEMA:
Sospecho que el problema radica en cómo Flutter/Flet gestiona los metadatos de accesibilidad durante la optimización de release builds. El proceso de compilación podría estar:

• Eliminando metadatos de autofocus como "optimización"
• Reorganizando el árbol de widgets de manera que afecte el orden de focus
• Aplicando optimizaciones que interfieren con la detección VoiceOver

SOLICITUD DE AYUDA:
Como experto en accesibilidad iOS, me gustaría preguntarte:

1. ¿Has encontrado diferencias similares entre debug y release builds en otras aplicaciones Flutter/iOS?

2. ¿Existen configuraciones específicas de iOS Info.plist o entitlements que podrían forzar la preservación de metadatos de accesibilidad en builds optimizadas?

3. ¿Conoces alternativas al autofocus=True que sean más robustas en builds de producción?

4. ¿Sería posible forzar el focus inicial usando llamadas nativas iOS desde Flutter?

URGENCIA:
Este problema afecta directamente a usuarios con discapacidad visual que reciben la app compilada vs. la versión de desarrollo, creando una experiencia inconsistente y potencialmente inaccesible en producción.

WORKFLOW ACTUAL CI/CD:

- name: Build IPA with Flet
  run: |
    flet build ipa \
      --project "avventura-epica" \
      --product "Avventura Epica" \
      --build-version "2.5.0" \
      --build-number ${{ github.run_number }} \
      --org "com.ambrogio.riili" \
      --company "Ambrogio Riili" \
      --flutter-build-args=--profile \
      --info-plist "UIAccessibilityEnabled=True" \
      --info-plist "UIAccessibilityTraits=True"

Cualquier insight o sugerencia que puedas proporcionar será invaluable para resolver esta regresión crítica de accesibilidad.

Muchísimas gracias por tu tiempo y experiencia.

Con gratitud y esperanza de una solución,

Ambro & Claude Code
Desarrolladores de Avventura Epica

---

P.D.: Si consideras que este problema requiere un enfoque completamente diferente o si conoces limitaciones específicas de Flet/Flutter en builds de producción, estaré muy agradecido por cualquier orientación que puedas ofrecer.