[jeltehomminga]

The custom fonts guide overrides the default font with @theme { --font-sans: ... }, but in 5.0.0-rc.0 that has no effect on iOS and Android, see nativewind/nativewind#1876. A :root block after the imports works on both, so this switches the example to that and adds one line on why.

Checked with Courier in the repro from that issue, on an iOS 26.5 simulator and an Android 17 emulator: font-sans resolves to Courier with :root, and to System / SystemAndroid with @theme. I didn't check web.

If the issue gets a code fix, this is easy to revert, or I can drop the last sentence.

pnpm test:llm and pnpm build pass.

[vercel]

@jeltehomminga is attempting to deploy a commit to the nativewind Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

🟢 Approval recommended

The focused documentation change reflects the reported native-platform workaround, with no identified blocking issues.

No open issues 🎉

What changed in this PR

Updates the v5 custom fonts guide to document a working override for default fonts on iOS and Android in the current release candidate.

Changes:

• Replaces @theme with a :root block and instructs readers to place it after imports.
• Explains why Nativewind’s platform defaults prevent the @theme override from taking effect.

File	Description
content/​v5/​guides/​custom-fonts.mdx	Updates the default-font override example and explains the release-candidate limitation.

_{Review effort: Balanced}