Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Support iOS Dynamic Type, dark appearance and contrast
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 →

Support iOS Dynamic Type, dark appearance and contrast

Build a text reader which follows host text scaling and selected appearance, with a separate explicit stronger-border setting.
iOS

What you will build

Keep system appearance and text scaling distinct from app preferences, without claiming an unavailable iOS contrast signal.
Mirror the appearance choice into the active generated theme
Let the host text scaler affect real user-entered content
Expose stronger borders as an app choice rather than pretending it tracks native Increase Contrast
Text size, colour scheme and contrast are related, but they are not one setting. Enlarging a single sample label does not implement Dynamic Type, and switching the background to dark does not establish that every foreground colour remains readable.
We will build a reader for text the user enters. It follows Fission's host text scaler, offers System, Light and Dark appearance choices, and provides an explicit app preference for primary-colour text and stronger borders. There is an important current boundary: Fission exposes system light/dark appearance and text scaling, but this example has no native iOS Increase Contrast signal. The app preference is not presented as automatic synchronization with that setting.

Create the shared reader

Complete iOS setup if needed.
cargo install cargo-fission
fission init ios-support-ios-dynamic-type-dark-appearance-and-contrast
cd ios-support-ios-dynamic-type-dark-appearance-and-contrast
fission add-target ios --project-dir .
cargo add serde_yaml
Keep the generated src/main.rs. The shared library below starts this reader on native and Web targets.

Run the finished example

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

1. Synchronize app choices into one environment

The screen reads colours and sizes from the active theme. It does not keep private light and dark palettes. The app-wide appearance preference belongs to GlobalState, and .with_sync_env(...) resolves that preference into the environment each build.
System means using env.system_theme_mode, not remembering whatever appearance happened to be active at launch. Light and Dark are explicit overrides. The synchronization function rebuilds the theme before applying the optional stronger-contrast changes, so turning that preference off restores the design system rather than leaving modified colours behind.
{"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::ReadingScreen;
pub use state::ReadingState;
{"id":"fission-tabs-1","index":1,"label":"src/app/state.rs","value":"src-app-state-rs"}
use fission::prelude::*;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Appearance {
    System,
    Light,
    Dark,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ReadingState {
    pub locale: Locale,
    pub appearance: Appearance,
    pub stronger_contrast: bool,
}

impl Default for ReadingState {
    fn default() -> Self {
        Self {
            locale: Locale::from("en-US"),
            appearance: Appearance::System,
            stronger_contrast: false,
        }
    }
}

impl GlobalState for ReadingState {}
{"id":"fission-tabs-1","index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"}
use super::state::{Appearance, ReadingState};
use fission::prelude::*;

fission_component! {
    pub ReadingScreen<ReadingState> {
        state {
            title: String = String::new(),
            body: String = String::new(),
        }
    }
    view(reader, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => SafeArea(
        child: Scroll(
            child: Container(Column(gap: tokens.spacing.m, children: [
                Text(cx.tr("reader.heading")).size(tokens.typography.heading2_size),
                Text(cx.tr("reader.explanation")).color(tokens.colors.text_secondary),
                Row(gap: tokens.spacing.s, wrap: ir_op::FlexWrap::Wrap, children: [
                    Button(
                        child: Text(cx.tr("appearance.system")), key: "system",
                        disabled: state.appearance == Appearance::System,
                        on_press: reduce { state.appearance = Appearance::System; },
                    ),
                    Button(
                        child: Text(cx.tr("appearance.light")), key: "light",
                        disabled: state.appearance == Appearance::Light,
                        on_press: reduce { state.appearance = Appearance::Light; },
                    ),
                    Button(
                        child: Text(cx.tr("appearance.dark")), key: "dark",
                        disabled: state.appearance == Appearance::Dark,
                        on_press: reduce { state.appearance = Appearance::Dark; },
                    ),
                ]),
                Button(
                    child: Text(if state.stronger_contrast {
                        cx.tr("appearance.standard_contrast")
                    } else {
                        cx.tr("appearance.stronger_contrast")
                    }),
                    key: "contrast",
                    on_press: reduce { state.stronger_contrast = !state.stronger_contrast; },
                ),
                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"); },
                    ),
                ]),
                TextInput(
                    value: reader.title.clone(), bind(on_input): to(reader.title),
                    label: Some(TextContent::Key("reader.title".into())),
                ),
                TextInput(
                    value: reader.body.clone(), bind(on_input): to(reader.body),
                    label: Some(TextContent::Key("reader.body".into())),
                    multiline: true, keyboard_type: TextInputType::Multiline,
                ),
                Divider(),
                Text(cx.tr("reader.preview")).color(tokens.colors.text_secondary),
                if reader.title.is_empty() && reader.body.is_empty() {
                    Text(cx.tr("reader.empty"))
                } else {
                    Column(gap: tokens.spacing.s, children: [
                        Text(reader.title.clone()).size(tokens.typography.heading2_size),
                        Text(reader.body.clone()).size(tokens.typography.body_medium_size),
                    ])
                },
                Text(cx.tr("reader.session")).color(tokens.colors.text_secondary),
            ]))
            .padding_all(tokens.spacing.l)
            .bg(tokens.colors.surface),
        ),
    )
}
{"id":"fission-tabs-1","index":3,"label":"src/i18n.rs","value":"src-i18n-rs"}
use fission::i18n::{Locale, TranslationBundle};
use fission::prelude::*;
use fission::theme::DesignSystem;
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 reader translations");
        env.i18n.add_bundle(TranslationBundle {
            locale: Locale::from(locale),
            messages,
        });
    }
    env
}

pub fn sync_env(state: &crate::app::ReadingState, env: &mut Env) {
    env.locale = state.locale.clone();
    let mode = match state.appearance {
        crate::app::state::Appearance::System => env.system_theme_mode,
        crate::app::state::Appearance::Light => DesignMode::Light,
        crate::app::state::Appearance::Dark => DesignMode::Dark,
    };
    env.theme = fission::theme::FissionDefaultDesignSystem::theme(mode);
    if state.stronger_contrast {
        let colors = &mut env.theme.tokens.colors;
        colors.text_secondary = colors.text_primary;
        colors.border = colors.text_primary;
    }
}
{"id":"fission-tabs-1","index":4,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod i18n;

use app::{ReadingScreen, ReadingState};
use fission::prelude::*;

#[cfg(not(any(target_arch = "wasm32", target_os = "android", target_os = "ios")))]
pub fn run_desktop() -> anyhow::Result<()> {
    DesktopApp::<ReadingState, _>::new(ReadingScreen)
        .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::<ReadingState, _>::new(ReadingScreen)
        .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::<ReadingState, _>::new(ReadingScreen)
        .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::<ReadingState, _>::new(ReadingScreen)
        .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::ReadingState, _>::new(app::ReadingScreen)
        .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"}
reader.heading: "Reading appearance"
reader.explanation: "Enter text you need to read, then choose the appearance that works for you. Text size follows the host's accessibility scale."
reader.title: "Reading title"
reader.body: "Text to read"
reader.preview: "Reading preview"
reader.empty: "Enter some text above to review its appearance."
reader.session: "Text and preferences last for this session only."
appearance.system: "Use system appearance"
appearance.light: "Light"
appearance.dark: "Dark"
appearance.stronger_contrast: "Use primary text and stronger borders"
appearance.standard_contrast: "Restore standard text and borders"
language.english: "English"
language.spanish: "Español"
{"id":"fission-tabs-1","index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
reader.heading: "Apariencia de lectura"
reader.explanation: "Introduce el texto que necesitas leer y elige la apariencia que te resulte más cómoda. El tamaño sigue la escala de accesibilidad del host."
reader.title: "Título de lectura"
reader.body: "Texto para leer"
reader.preview: "Vista previa de lectura"
reader.empty: "Introduce texto arriba para revisar su apariencia."
reader.session: "El texto y las preferencias duran solo esta sesión."
appearance.system: "Usar apariencia del sistema"
appearance.light: "Claro"
appearance.dark: "Oscuro"
appearance.stronger_contrast: "Usar texto principal y bordes más marcados"
appearance.standard_contrast: "Restaurar texto y bordes normales"
language.english: "Inglés"
language.spanish: "Español"
{"id":"fission-tabs-1"}
Enter several paragraphs and compare Light and Dark. Enable the stronger-border preference, then restore standard colours. Switch languages whilst keeping the text unchanged. The user-entered content must remain intact throughout.
Show the app preview
Hide the app preview

2. Let the host scale text instead of replacing its font size

A Text widget without an explicit scaler uses Env.text_scaler. The current iOS shell reads the preferred content-size category and maps it to an accessibility scale. The authored token size remains the starting size; multiplying every font size in the component as well would apply the adjustment twice.
This is Fission's scaling behavior, not a claim that it reproduces every UIKit text style's scaling curve. Test the actual controls and paragraphs at the largest supported category. A correct scale can still expose a fixed-height container, clipped button label or unreachable action.
The stronger-contrast preference changes secondary text and borders to the theme's primary text colour. Its name describes that concrete change; it does not certify a contrast ratio or implement every iOS contrast option. Measure the foreground/background combinations used by the design, including disabled, focused and error states, before claiming accessibility conformance.
Use a long title and enough text to scroll. Browser zoom can reveal layout pressure, but it does not prove the iOS content-size category is delivered. Keep that distinction when recording the result.
Show the app preview
Hide the app preview

3. Check native preferences and live changes

fission doctor ios --project-dir .
fission devices --project-dir .
fission run --target ios --project-dir .
fission test --target ios --project-dir .
Select a simulator using the simulator guide. With System selected, change iOS appearance and verify the screen changes. Select Light and repeat: the explicit override should remain light. Return to System and verify that it follows the current host value rather than the old one.
Change iOS text size, including accessibility categories, and check titles, paragraphs, inputs and buttons. Repeat on a physical device, with both languages and in landscape. The generated launch smoke test does not perform those checks.
Turn on iOS Increase Contrast too, but do not mistake the app's manual stronger-border button for evidence that this OS setting has been detected. Automatic contrast-preference delivery remains an upstream capability gap; this tutorial makes that boundary explicit rather than silently claiming the full native integration.
The reader keeps its text and preferences in memory. Add persistence separately if they must survive restart; appearance synchronization should remain limited to presentation inputs, not become a place to start storage or network work.