Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Support Android dark theme and user font scaling
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 Android dark theme and user font scaling

Let a handover-note screen follow Android's theme or an explicit override, while preserving the system text scaler and the user's draft.
Android

What you will build

Apply active design-system themes to one note screen without replacing Android's text scaling or losing entered content.
Keep an optional theme override separate from the system theme
Mirror the chosen app-wide theme through with_sync_env
Read visual tokens without hard-coded light and dark widget colours
Preserve the native text scaler and check enlarged text on a real target

Let presentation change without changing the user's work

Dark appearance and larger text are presentation inputs, not separate versions of a screen. If each component maintains its own colours or multiplies font sizes independently, those choices soon disagree. The result is a dark surface with a light input, or text scaled twice in one region and not at all in another.
Here, a handover-note screen uses the generated Fission design system and lets the shell supply text scaling. The app owns only an optional theme override. Without an override, the system appearance applies; choosing Light or Dark replaces that presentation choice without recreating the note.
Start from a new project (optional)

Create the Android project

Complete Android SDK/NDK setup, then start an emulator or connect a phone.
cargo install cargo-fission
fission init android-support-android-dark-theme-and-user-font-scaling
cd android-support-android-dark-theme-and-user-font-scaling
cargo add serde_yaml
fission add-target android --project-dir .
Keep the generated src/main.rs. The native and Web entrypoints below run the same note screen. We use FissionDefaultDesignSystem, which is generated from Fission's default DSP; an application-specific DSP can replace it without teaching each widget another palette.

Run the finished example

fission run --target android --project-dir .

1. Use the host's scale and the active design tokens

The Android shell reads Configuration.fontScale and supplies Env.text_scaler before building a frame. Leave that value alone in with_sync_env. Normal text and controls use the shared scaler; multiplying token font sizes again is not how to support the system preference.
The note has no fixed reading height or line limit. Scroll keeps the form reachable when the keyboard or large text reduces the available space, and SafeArea accounts for device insets rather than guessing padding for a particular phone.
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"src/presentation.rs","value":"src-presentation-rs"},{"index":1,"label":"src/app.rs","value":"src-app-rs"},{"index":2,"label":"src/translations.rs","value":"src-translations-rs"},{"index":3,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"},{"index":4,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"},{"index":5,"label":"src/lib.rs","value":"src-lib-rs"},{"index":6,"label":"preview/lib.rs","value":"preview-lib-rs"}]}
{"id":"fission-tabs-1","index":0,"label":"src/presentation.rs","value":"src-presentation-rs"}
use fission::prelude::*;

#[derive(Debug, Default)]
pub struct ReadingState {
    pub theme_override: Option<DesignMode>,
}
impl GlobalState for ReadingState {}

pub fn sync_env(state: &ReadingState, env: &mut Env) {
    let mode = state.theme_override.unwrap_or(env.system_theme_mode);
    env.theme = FissionDefaultDesignSystem::theme(mode);
    // Keep the host's text_scaler. Do not multiply token font sizes again.
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn automatic_follows_the_host_and_override_does_not_reset_text_scaling() {
        let mut state = ReadingState::default();
        let mut env = Env::default();
        env.system_theme_mode = DesignMode::Dark;
        env.text_scaler = TextScaler::accessibility(1.8);
        let host_scaler = env.text_scaler.clone();
        sync_env(&state, &mut env);
        assert_eq!(env.theme.design_system.mode, DesignMode::Dark);
        state.theme_override = Some(DesignMode::Light);
        sync_env(&state, &mut env);
        assert_eq!(env.theme.design_system.mode, DesignMode::Light);
        assert_eq!(env.text_scaler, host_scaler);
    }
}
{"id":"fission-tabs-1","index":1,"label":"src/app.rs","value":"src-app-rs"}
use fission::prelude::*;
use crate::presentation::ReadingState;

fission_component! {
    pub HandoverNotes<ReadingState> {
        state { note: String = String::new() }
    }
    view(notes, _state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } =>
    SafeArea(
        child: Scroll(
            child: Container(
                child: Column(gap: tokens.spacing.l, children: [
                    Text(cx.tr("reading.title")).size(tokens.typography.heading2_size),
                    Text(cx.tr("reading.context")),

                    TextInput(
                        label: Some(cx.tr("reading.note").into()),
                        helper_text: Some(cx.tr("reading.note_help").into()),
                        multiline: true,
                        bind: notes.note,
                        semantics_identifier: "reading.note".to_string(),
                    ),
                    if notes.note.trim().is_empty() {
                        EmptyState(
                            title: cx.tr("reading.empty"),
                            description: cx.tr("reading.empty_help"),
                        )
                    } else {
                        Card(child: Column(gap: tokens.spacing.s, children: [
                            Text(cx.tr("reading.preview")).weight(tokens.typography.font_weight_semibold),
                            Text(notes.note.clone()),
                        ]))
                    },
                ]),
            ).padding_all(tokens.spacing.l).bg(tokens.colors.background),
        ),
    )
}
{"id":"fission-tabs-1","index":2,"label":"src/translations.rs","value":"src-translations-rs"}
use std::collections::HashMap;
use fission::prelude::*;

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 checked-in translations");
        env.i18n.add_bundle(TranslationBundle { locale: Locale::from(locale), messages });
    }
    env
}
{"id":"fission-tabs-1","index":3,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"}
reading.title: "Read a handover note"
reading.context: "Enter a note and check it in your preferred appearance. The note stays in this screen's memory; it is not saved or sent."
reading.note: "Handover note"
reading.note_help: "Use your own non-sensitive text to check wrapping at the text size you normally use."
reading.empty: "No note to read"
reading.empty_help: "Enter a note above to see the reading view."
reading.preview: "Reading view"
appearance.title: "Appearance"
appearance.system: "Use device appearance"
appearance.light: "Light"
appearance.dark: "Dark"
{"id":"fission-tabs-1","index":4,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
reading.title: "Leer una nota de relevo"
reading.context: "Escribe una nota y compruébala con la apariencia que prefieras. La nota queda en la memoria de esta pantalla; no se guarda ni se envía."
reading.note: "Nota de relevo"
reading.note_help: "Usa tu propio texto no sensible para comprobar los saltos de línea con el tamaño que utilizas normalmente."
reading.empty: "No hay ninguna nota que leer"
reading.empty_help: "Escribe una nota arriba para ver la vista de lectura."
reading.preview: "Vista de lectura"
appearance.title: "Apariencia"
appearance.system: "Usar la apariencia del dispositivo"
appearance.light: "Clara"
appearance.dark: "Oscura"
{"id":"fission-tabs-1","index":5,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod presentation;
mod translations;

use app::HandoverNotes;
use presentation::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(HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env)
        .run()
}
#[cfg(any(target_os = "android", target_os = "ios"))]
fn mobile_app() -> MobileApp<ReadingState, HandoverNotes> {
    let app = MobileApp::<ReadingState, _>::new(HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env);
    #[cfg(all(target_os = "android", debug_assertions))]
    let app = app.with_test_control_port(48761);
    app
}
#[cfg(any(target_os = "android", target_os = "ios"))]
pub fn run_mobile() -> anyhow::Result<()> { mobile_app().run() }

#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app_handle: AndroidApp) {
    let _ = mobile_app().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(HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env)
        .run()
        .map_err(|error| wasm_bindgen::JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":6,"label":"preview/lib.rs","value":"preview-lib-rs"}
mod app;
mod presentation;
mod translations;

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

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<presentation::ReadingState, _>::new(app::HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env)
        .mount("#fission-web-mount")
        .run()
        .map_err(|error| JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1"}
Enter a long, non-sensitive note. Change Android's font size, return to the app and check both the field and reading view. Text should reflow rather than disappear behind a fixed card or become reachable only at the original scale.
The browser preview is useful for width and content checks. It is not evidence that the Android host picked up the system setting.
Show the app preview
Hide the app preview

2. Add a theme override without replacing system scaling

None means use the host's appearance; Some(Light) or Some(Dark) is the user's app-specific override. That makes precedence explicit. Switching the device theme must not defeat a deliberate override, and choosing the device appearance again must remove that override.
The picker changes state through reducers. The existing shell callback selects one complete generated theme, including component recipes, instead of replacing just the page background.
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"src/appearance_picker.rs","value":"src-appearance-picker-rs"},{"index":1,"label":"src/app.rs","value":"src-app-rs"},{"index":2,"label":"src/lib.rs","value":"src-lib-rs"},{"index":3,"label":"preview/lib.rs","value":"preview-lib-rs"}]}
{"id":"fission-tabs-1","index":0,"label":"src/appearance_picker.rs","value":"src-appearance-picker-rs"}
use fission::prelude::*;
use crate::presentation::ReadingState;

fission_component! {
    pub AppearancePicker<ReadingState> {}
    view(_picker, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } =>
    Column(gap: tokens.spacing.s, children: [
        Text(cx.tr("appearance.title")).weight(tokens.typography.font_weight_semibold),
        Wrap(spacing: tokens.spacing.s, children: [
            Button(
                child: Text(cx.tr("appearance.system")),
                key: "appearance-system",
                disabled: state.theme_override.is_none(),
                on_press: reduce { state.theme_override = None; },
            ).semantics_identifier("appearance.system"),
            Button(
                child: Text(cx.tr("appearance.light")),
                key: "appearance-light",
                disabled: state.theme_override == Some(DesignMode::Light),
                on_press: reduce { state.theme_override = Some(DesignMode::Light); },
            ).semantics_identifier("appearance.light"),
            Button(
                child: Text(cx.tr("appearance.dark")),
                key: "appearance-dark",
                disabled: state.theme_override == Some(DesignMode::Dark),
                on_press: reduce { state.theme_override = Some(DesignMode::Dark); },
            ).semantics_identifier("appearance.dark"),
        ]),
    ])
}
{"id":"fission-tabs-1","index":1,"label":"src/app.rs","value":"src-app-rs"}
use fission::prelude::*;
use crate::presentation::ReadingState;
use crate::appearance_picker::AppearancePicker;
fission_component! {
    pub HandoverNotes<ReadingState> {
        state { note: String = String::new() }
    }
    view(notes, _state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } =>
    SafeArea(
        child: Scroll(
            child: Container(
                child: Column(gap: tokens.spacing.l, children: [
                    Text(cx.tr("reading.title")).size(tokens.typography.heading2_size),
                    Text(cx.tr("reading.context")),
                    AppearancePicker(),
                    TextInput(
                        label: Some(cx.tr("reading.note").into()),
                        helper_text: Some(cx.tr("reading.note_help").into()),
                        multiline: true,
                        bind: notes.note,
                        semantics_identifier: "reading.note".to_string(),
                    ),
                    if notes.note.trim().is_empty() {
                        EmptyState(
                            title: cx.tr("reading.empty"),
                            description: cx.tr("reading.empty_help"),
                        )
                    } else {
                        Card(child: Column(gap: tokens.spacing.s, children: [
                            Text(cx.tr("reading.preview")).weight(tokens.typography.font_weight_semibold),
                            Text(notes.note.clone()),
                        ]))
                    },
                ]),
            ).padding_all(tokens.spacing.l).bg(tokens.colors.background),
        ),
    )
}
{"id":"fission-tabs-1","index":2,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod presentation;
mod appearance_picker;
mod translations;

use app::HandoverNotes;
use presentation::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(HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env)
        .run()
}
#[cfg(any(target_os = "android", target_os = "ios"))]
fn mobile_app() -> MobileApp<ReadingState, HandoverNotes> {
    let app = MobileApp::<ReadingState, _>::new(HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env);
    #[cfg(all(target_os = "android", debug_assertions))]
    let app = app.with_test_control_port(48761);
    app
}
#[cfg(any(target_os = "android", target_os = "ios"))]
pub fn run_mobile() -> anyhow::Result<()> { mobile_app().run() }

#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app_handle: AndroidApp) {
    let _ = mobile_app().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(HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env)
        .run()
        .map_err(|error| wasm_bindgen::JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":3,"label":"preview/lib.rs","value":"preview-lib-rs"}
mod app;
mod presentation;
mod appearance_picker;
mod translations;

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

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<presentation::ReadingState, _>::new(app::HandoverNotes::new())
        .with_env(translations::create_env())
        .with_design_system::<FissionDefaultDesignSystem>(DesignMode::Light)
        .with_sync_env(presentation::sync_env)
        .mount("#fission-web-mount")
        .run()
        .map_err(|error| JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1"}
Choose Dark, then Light, then the device appearance. Your note should remain intact and input, button and card styling should agree with the selected theme. Change Android's appearance whilst using the device mode and repeat whilst an explicit override is selected.
Changing theme does not change the text-scale preference. The unit test checks that the environment synchroniser preserves the host's scaler.
Show the app preview
Hide the app preview

3. Check the combinations users actually choose

cargo test
fission doctor android --project-dir .
fission run --target android --project-dir .
fission test --target android --project-dir .
fission build --target android --project-dir . --release
Check light and dark appearance at standard and large system font sizes on an emulator and a phone. Include a long translated label, multiple paragraphs, a visible keyboard, rotation and a narrow split-screen window. Essential content must remain readable and actions must remain reachable.
Do not force a linear multiplier to imitate every Android font-size rule. Fission maps the host factor through its accessibility text scaler, where larger display text grows more gradually than body text. The result still needs rendered review: reading a scale factor is not proof that every widget handles it well.
This example does not implement a separate high-contrast palette or persist the app override. Treat those as explicit requirements if the product needs them, not as capabilities supplied merely by a Light/Dark selector.
The screen now has one theme decision, one host text scaler and flexible content sizing. The source test proves override precedence and scaler preservation; the native checks establish whether this particular layout remains useful on the device.

Current references