Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Make a Fission iOS app accessible with VoiceOver
Core concepts
Components
State and effects
Protected routes
Server-side rendering
Styling
Testing
Deployment
Reference
API reference
Cookbook
Fission 0.16.0
Documentation version
Read the changelog →

Make a Fission iOS app accessible with VoiceOver

Build a contact-preference form with real label, help, error and checked-state relationships in the semantic tree.
iOS

What you will build

Make the actual controls and submitted snapshot understandable without relying on their visual arrangement.
Associate name validation and help with the input through FormControl
Expose the contact switch's label and checked state
Check VoiceOver on the native target rather than treating a semantic tree as spoken-output proof
A control can look obvious and still be unusable without sight. A nearby caption is not necessarily its accessible name, a coloured error is not necessarily announced, and a test identifier is not a substitute for either.
We will build a contact-preferences form with a required name, an on/off choice and an explicit result. The task is small enough to navigate completely with VoiceOver, but it exercises real form relationships and state rather than a button whose label merely says that accessibility exists.

Create the app

Complete iOS setup if needed.
cargo install cargo-fission
fission init ios-make-a-fission-ios-app-accessible-with-voiceover
cd ios-make-a-fission-ios-app-accessible-with-voiceover
fission add-target ios --project-dir .
cargo add serde_yaml
Keep the generated src/main.rs. The shared library below starts the same form on native and Web targets; neither shell injects a fake successful preference change.

Run the finished example

fission run --target ios --project-dir .

1. Use controls which already own the interaction

TextInput, Switch and Button expose their respective control roles and actions. FormControl adds the visible label, help text and validation relationship to its descendant control. We therefore do not have to duplicate a field's caption into an unrelated semantic wrapper and hope the screen reader associates them.
The switch's checked value is real state, not a colour convention. Applying copies a valid snapshot into application state, whilst the draft remains local to the form. No message is sent and no notification permission is requested by changing a contact preference.
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"src/app.rs","value":"src-app-rs"},{"index":1,"label":"src/app/state.rs","value":"src-app-state-rs"},{"index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"},{"index":3,"label":"src/i18n.rs","value":"src-i18n-rs"},{"index":4,"label":"src/lib.rs","value":"src-lib-rs"},{"index":5,"label":"preview/lib.rs","value":"preview-lib-rs"},{"index":6,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"},{"index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}]}
{"id":"fission-tabs-1","index":0,"label":"src/app.rs","value":"src-app-rs"}
mod screen;
pub mod state;
pub use screen::ContactScreen;
pub use state::ContactState;
{"id":"fission-tabs-1","index":1,"label":"src/app/state.rs","value":"src-app-state-rs"}
use fission::prelude::*;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ContactPreferences {
    pub name: String,
    pub text_messages: bool,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ContactState {
    pub preferences: Option<ContactPreferences>,
    pub locale: Locale,
}

impl Default for ContactState {
    fn default() -> Self {
        Self {
            preferences: None,
            locale: Locale::from("en-US"),
        }
    }
}
impl GlobalState for ContactState {}
{"id":"fission-tabs-1","index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"}
use super::state::{ContactPreferences, ContactState};
use fission::prelude::*;

fission_component! {
    pub ContactScreen<ContactState> {
        state {
            name: String = String::new(),
            text_messages: bool = false,
            attempted: bool = false,
        }
    }
    view(form, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
        let name_error = (form.attempted && form.name.trim().is_empty())
            .then(|| cx.tr("contact.name_required"));
    } => SafeArea(
        child: Scroll(
            child: Container(Column(gap: tokens.spacing.m, children: [
                Text(cx.tr("contact.heading")).size(tokens.typography.heading2_size),
                Text(cx.tr("contact.explanation")),
                Row(gap: tokens.spacing.s, children: [
                    Button(
                        child: Text(cx.tr("language.english")), key: "english",
                        on_press: reduce { state.locale = Locale::from("en-US"); },
                    ),
                    Button(
                        child: Text(cx.tr("language.spanish")), key: "spanish",
                        on_press: reduce { state.locale = Locale::from("es-ES"); },
                    ),
                ]),
                FormControl(
                    label: Some(cx.tr("contact.name")),
                    helper: Some(cx.tr("contact.name_help")),
                    required: true,
                    error: name_error,
                    child: TextInput(
                        value: form.name.clone(), bind(on_input): to(form.name),
                        keyboard_type: TextInputType::Name,
                        semantics_identifier: Some("contact.name".into()),
                    ),
                ),
                FormControl(
                    label: Some(cx.tr("contact.messages")),
                    helper: Some(cx.tr("contact.messages_help")),
                    child: Switch(
                        checked: form.text_messages,
                        bind(on_toggle): to(form.text_messages),
                        semantics_identifier: Some("contact.messages".into()),
                    ),
                ),
                Button(
                    child: Text(cx.tr("contact.apply")), key: "apply-preferences",
                    on_press: reduce {
                        form.attempted = true;
                        if !form.name.trim().is_empty() {
                            state.preferences = Some(ContactPreferences {
                                name: form.name.trim().to_owned(),
                                text_messages: form.text_messages,
                            });
                        }
                    },
                )
                .semantics_identifier("contact.apply"),
                if let Some(preferences) = &state.preferences {
                    SemanticsRegion(
                        identifier: Some("contact.result".into()),
                        role: Role::Status,
                        child: Column(gap: tokens.spacing.s, children: [
                            Text(cx.tr("contact.applied")),
                            Text(preferences.name.clone()),
                            Text(if preferences.text_messages {
                                cx.tr("contact.messages_enabled")
                            } else {
                                cx.tr("contact.messages_disabled")
                            }),
                        ]),
                    )
                },
                Text(cx.tr("contact.session")).color(tokens.colors.text_secondary),
            ]))
            .padding_all(tokens.spacing.l),
        ),
    )
}
{"id":"fission-tabs-1","index":3,"label":"src/i18n.rs","value":"src-i18n-rs"}
use fission::i18n::{Locale, TranslationBundle};
use fission::prelude::*;
use std::collections::HashMap;

pub fn create_env() -> Env {
    let mut env = Env::default();
    env.locale = Locale::from("en-US");
    for (locale, source) in [
        ("en-US", include_str!("../i18n/en-US.yaml")),
        ("es-ES", include_str!("../i18n/es-ES.yaml")),
    ] {
        let messages: HashMap<String, String> =
            serde_yaml::from_str(source).expect("valid contact translations");
        env.i18n.add_bundle(TranslationBundle {
            locale: Locale::from(locale),
            messages,
        });
    }
    env
}

pub fn sync_env(state: &crate::app::ContactState, env: &mut Env) {
    env.locale = state.locale.clone();
}
{"id":"fission-tabs-1","index":4,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod i18n;

use app::{ContactScreen, ContactState};
use fission::prelude::*;

#[cfg(not(any(target_arch = "wasm32", target_os = "android", target_os = "ios")))]
pub fn run_desktop() -> anyhow::Result<()> {
    DesktopApp::<ContactState, _>::new(ContactScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(any(target_os = "android", target_os = "ios"))]
pub fn run_mobile() -> anyhow::Result<()> {
    MobileApp::<ContactState, _>::new(ContactScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app_handle: AndroidApp) {
    let _ = MobileApp::<ContactState, _>::new(ContactScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run_with_android_app(app_handle);
}

#[cfg(target_arch = "wasm32")]
#[wasm_bindgen::prelude::wasm_bindgen(start)]
pub fn run_web() -> Result<(), wasm_bindgen::JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<ContactState, _>::new(ContactScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
        .map_err(|error| wasm_bindgen::JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":5,"label":"preview/lib.rs","value":"preview-lib-rs"}
mod app;
mod i18n;

use fission::prelude::*;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<app::ContactState, _>::new(app::ContactScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .mount("#fission-web-mount")
        .run()
        .map_err(|error| JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":6,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"}
contact.heading: "Contact preferences"
contact.explanation: "Choose the name and contact preference to use for this session."
contact.name: "Your name"
contact.name_help: "Use the name you want shown on your contact record."
contact.name_required: "Enter a name before applying these preferences."
contact.messages: "Allow text-message contact"
contact.messages_help: "This records a preference only; it does not send a message or request notification permission."
contact.apply: "Apply preferences for this session"
contact.applied: "Preferences applied for this session"
contact.messages_enabled: "Text-message contact allowed"
contact.messages_disabled: "Text-message contact not allowed"
contact.session: "Nothing is sent or saved to disk. Closing the app clears these preferences."
language.english: "English"
language.spanish: "Español"
{"id":"fission-tabs-1","index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
contact.heading: "Preferencias de contacto"
contact.explanation: "Elige el nombre y la preferencia de contacto para esta sesión."
contact.name: "Tu nombre"
contact.name_help: "Usa el nombre que quieras mostrar en tu registro de contacto."
contact.name_required: "Introduce un nombre antes de aplicar estas preferencias."
contact.messages: "Permitir contacto por mensaje de texto"
contact.messages_help: "Solo registra una preferencia; no envía mensajes ni solicita permiso para notificaciones."
contact.apply: "Aplicar preferencias para esta sesión"
contact.applied: "Preferencias aplicadas para esta sesión"
contact.messages_enabled: "Contacto por mensaje de texto permitido"
contact.messages_disabled: "Contacto por mensaje de texto no permitido"
contact.session: "No se envía ni guarda nada en disco. Cerrar la aplicación borra estas preferencias."
language.english: "Inglés"
language.spanish: "Español"
{"id":"fission-tabs-1"}
Apply with an empty name and inspect the visible field error. Enter a name, change the switch and apply again. The result must reflect the submitted values. Changing the draft afterwards must not silently change the applied snapshot.
Show the app preview
Hide the app preview

2. Distinguish a semantic contract from native evidence

Stable identifiers such as contact.name let LiveTest select the intended control without depending on its translated label or generated tree position. Labels serve a different audience: the person using the control. Keep both meaningful, but do not assume that a passing identifier lookup proves a useful spoken name.
The source order follows the task: explanation, language, name, contact choice, Apply and result. There is no arbitrary focus-index scheme to keep synchronized with a second visual order. The built-in controls retain their normal keyboard and accessibility actions.
The result uses a status semantic region, and validation is attached through FormControl. Those declarations express what the application means; the actual announcement timing still needs checking. Fission's iOS shell sends its semantic tree through AccessKit's iOS adapter. A browser's accessibility tree exercises a different adapter and cannot qualify that native path.
Switch to Spanish and repeat the invalid and valid paths. Check labels, descriptions, checked state and the submitted result in the browser's accessibility inspector if available. Record that as browser evidence only.
Show the app preview
Hide the app preview

3. Complete the task with VoiceOver rather than inspecting its pixels

fission doctor ios --project-dir .
fission devices --project-dir .
fission run --target ios --project-dir .
fission test --target ios --project-dir .
Use the simulator guide for selection and the iPhone installation guide for a signed physical-device run.
Enable VoiceOver and navigate without relying on the screen. The name field should have a useful name and required/error information. The switch should expose its name and current on/off state, and activation should change that state once. Apply should remain understandable when its longer translated label wraps. Check that the result can be found and that changes are announced usefully; if the platform behavior differs from the declaration, treat that as a defect to investigate, not evidence that the task is complete.
Repeat with the software keyboard open, larger text and both languages. Check that focus does not disappear after applying or get stuck on a decorative container. The generated launch smoke test does not perform these checks, and even a correct semantic tree does not replace listening to the actual VoiceOver result.