cross-platform-design

cross-platform-design — translate idiom, not pixels

Goal: ship one codebase that respects each platform's HIG/Material/Fluent — not a Flutter app that looks like Flutter on every OS.

What This Skill Can Do

• Choose cross-platform stacks and explain tradeoffs across Tauri, Electron, React Native, Flutter, Compose Multiplatform, Avalonia, Uno, and MAUI.
• Translate Apple, Android, Windows, and web patterns by idiom instead of copying pixels.
• Preserve UX briefs, state coverage, action hierarchy, tokens, desktop archetype, originality seed, layout sketch, and product metaphor across platforms.
• Define per-platform navigation, controls, typography, icons, motion, density, and accessibility adaptations.
• Warn when one shared UI will harm platform fit or when a single-platform implementation is the better choice.

Step 0 — Preserve UX and UI decisions

If Stark produced a UX decision brief or UI decision brief, keep both as the source of truth. Translate them per platform instead of pixel-cloning.

Read:

• ../../references/ui-patterns/surface-taxonomy.md
• ../../references/ui-patterns/ui-decision-brief.md
• ../../references/ui-patterns/desktop-app-archetypes.md
• ../../references/ui-patterns/originality-engine.md
• ../../references/ui-patterns/design-recipes.md
• ../../references/ui-patterns/anti-default-contrasts.md
• ../../references/ui-patterns/visual-hierarchy.md
• ../../references/ui-patterns/motion-budget.md

The shared product should preserve job, state coverage, action hierarchy, visual hierarchy, desktop archetype, originality seed, and layout sketch. Navigation, controls, typography, icons, and motion must become platform-specific, but the chosen shape should remain legible: command center stays a command center, library stays a library, workbench stays a workbench, and monitoring cockpit stays a monitoring cockpit. A product-specific metaphor can translate across platforms; exact pixels and custom controls should not.

Step 1 — Pick the right framework for the design intent

User priority	Recommended stack
Native feel + Kotlin codebase + iOS support	Compose Multiplatform 1.8+ (iOS stable since May 2025)
Tiny binary, web team, desktop-first	Tauri 2 (Rust + native webviews; ~3MB)
Native Android views + iOS, large ecosystem	React Native (New Arch + Fabric + Hermes)
Single Skia raster across platforms (custom design system)	Flutter — only if pixel control matters more than native feel
.NET shop, XAML cross-platform	Uno Platform 5+ (reuses WinUI XAML)
.NET shop, mobile-first	.NET MAUI (warn: weaker desktop, weaker iOS feel)
Cross-platform desktop + custom theming	Avalonia 11 with Fluent/Mac themes

Step 2 — Native-feel ranking by platform

When the user picks a stack, state the fidelity tradeoff per platform in one line each.

Compose Multiplatform 1.8+

• Android: native (excellent)
• iOS: stable but Material widgets won't feel HIG — you must implement Cupertino-styled Compose components, or accept a Material aesthetic on iOS
• Desktop: good for Compose-driven design, not native Fluent
• Web (Wasm): experimental

Tauri 2

• Windows: WebView2 chrome — Mica works via window-backdrop API but font rendering and focus rings will look subtly off vs WinUI 3
• macOS: WKWebView — looks like a web app, not an AppKit/SwiftUI app
• Linux: WebKitGTK
• Mobile (iOS/Android): preview, not production-ready

React Native (New Architecture)

• iOS: real UIKit views, decent. Liquid Glass requires expo-glass-effect or native modules; partial adoption.
• Android: real Android views, M3 themable but won't get spring physics or shape morphing without manual work.
• Desktop: react-native-windows / react-native-macos exist, fidelity weaker

Flutter

• All platforms: Skia custom-painted. Never feels native to anyone.
• Material 3 widgets exist but lag platform updates (no spring physics parity, no shape morphing primitives, no real dynamic color).
• Avoid for any project where "native feel" is a stated requirement.

Uno Platform

• Windows: native WinUI (excellent)
• iOS / Android / Mac / Web: reuses XAML rendering — distinctive fidelity but not 1:1 with each platform's idiom
• Best XAML cross-platform path

.NET MAUI

• Windows: weak WinUI integration
• macOS: Catalyst (deprecated direction)
• iOS: looks like Android in costume
• Generally avoid for design-first work

Step 3 — Translation rules: same product, different idiom

Settings screen example:

• iOS → grouped Form with Section { ... } headers, Liquid Glass toolbar, switch toggles
• Android → LargeTopAppBar + LazyColumn with ListItem rows, switches with M3 thumbs
• Windows → NavigationView + scrollable SettingsCard stack with Mica backdrop
• Web → asymmetric grid with sidebar nav and editorial section headers

Tab bar example:

• iOS → bottom TabView (5 tabs max, Liquid Glass)
• Android → NavigationBar (3–5) or NavigationRail adaptive
• Windows → NavigationView Top or Left
• Web → top nav with motion-reveal

List detail example:

• iOS → NavigationSplitView on iPad/Mac, push-pop on iPhone
• Android → ListDetailPaneScaffold (adaptive)
• Windows → Master-detail with Mica
• Web → URL-driven two-pane with View Transitions

Desktop archetype example:

• Command center → Windows NavigationView + CommandBar + status rail, macOS NavigationSplitView + toolbar/search, Tauri/Electron command palette + inspector
• Library / collection → Windows GridView + preview pane, macOS sidebar/content/inspector, web desktop shell with collection grid + detail sheet
• Workbench → Windows command bar + canvas + inspector, macOS document window + toolbar + inspector, web desktop shell with stable toolbars and undo/redo
• Tray/menu-bar utility → Windows tray flyout or compact window, macOS MenuBarExtra, web desktop shells only when background status and settings justify a full app

Never copy the iOS tab bar onto Windows. Never copy the Android FAB onto iOS. Idiom > pixel.

Step 4 — When to route to a single-platform skill

If the user is shipping to one canonical platform first (almost always the case), route to that platform's skill (apple-design, android-design, windows-design, web-design) and translate later. Don't start in cross-platform mode unless they explicitly say "build cross-platform from day one."

Step 5 — Anti-slop ban list (cross-platform-specific)

• Same UI pixel-for-pixel on every platform
• Defaulting to Flutter without warning about non-native feel
• Defaulting to Electron (use Tauri 2 if web stack is mandated)
• Material widgets unmodified on iOS — must Cupertino-skin or accept "Material on iOS" warning
• Cupertino widgets unmodified on Android — same in reverse
• Ignoring per-platform navigation idioms (always-bottom-tabs, always-hamburger)
• One typeface across all platforms — each OS has a system face
• One motion language across all platforms when native motion differs
• One density level across mobile, tablet, desktop, and web

Step 6 — Reference cross-platform apps that translate well

• Notion — web-first but adapts respectably to each native platform
• Telegram — fully native on each platform; same product, different code per OS
• Spotify — same brand, idiomatic per platform
• Linear — desktop via Electron but obsessively polished; web is canonical

Step 7 — Tokens & assets

When generating cross-platform output, ship tokens once and translate:

• Use the DTCG W3C token format as the source of truth
• See ../../scripts/token_export.py to translate one token JSON into Tailwind theme + Compose Material3 ColorScheme + SwiftUI Color extension + Fluent ResourceDictionary
• See ../../assets/tokens/ for per-platform reference token bundles