Fluent UI Cross-Platform

Fluent UI Cross-Platform

1. Overview

Microsoft Fluent 2 is a cross-platform design system that delivers consistent, accessible, and themeable UI across Web (React), iOS (Swift/UIKit/SwiftUI), and Android (Kotlin/Jetpack Compose). Each platform has its own native implementation that respects platform idioms while maintaining visual and behavioral parity through a shared design token architecture.

The three platform libraries are:

All three libraries target Fluent 2 design language and share the same design token foundations, ensuring that a "Brand Button" on Web looks and feels like its counterpart on iOS and Android, while still respecting each platform's native interaction patterns (e.g., iOS swipe gestures, Android Material ripple effects).

When to use this skill

• Setting up Fluent UI in a native iOS or Android project
• Ensuring design token parity across Web, iOS, and Android
• Building cross-platform apps (e.g., Teams, Outlook) that need consistent Fluent styling
• Mapping Web component APIs to their iOS/Android equivalents
• Integrating Figma design kits for mobile platforms

2. Platform Comparison Table

Component Parity Matrix

Token Parity

Theming Parity

3. Design Token Parity

Fluent 2 defines a shared token taxonomy that maps to platform-native representations:

Token Mapping Across Platforms

Fluent Token Name         Web (CSS Custom Property)           iOS (Swift)                          Android (Kotlin/XML)
---------------------     ----------------------------        ---------------------------------    ------------------------------------
colorBrandBackground      --colorBrandBackground              FluentTheme.color.brand.background   fluentui_color_brand_background
colorNeutralForeground1   --colorNeutralForeground1           FluentTheme.color.foreground1        fluentui_color_neutral_foreground1
fontSizeBase300           --fontSizeBase300                   FluentTheme.typography.body1.size     fluentui_font_size_300
spacingHorizontalM        --spacingHorizontalM                FluentTheme.spacing.medium           fluentui_spacing_horizontal_m
borderRadiusMedium        --borderRadiusMedium                FluentTheme.corner.radius8           fluentui_border_radius_medium
shadow4                   --shadow4                           FluentTheme.shadow.shadow4           fluentui_elevation_4
strokeWidthThin           --strokeWidthThin                   FluentTheme.stroke.widthThin         fluentui_stroke_width_thin
durationNormal            --durationNormal                    FluentTheme.animation.durationNormal fluentui_duration_normal

Brand Color Pipeline

All platforms consume the same brand color ramp (shades 10-160):

Brand Ramp (shared)
  brandColor10  → lightest tint
  brandColor20
  ...
  brandColor80  → primary (default)
  ...
  brandColor160 → darkest shade

Web:   CSS custom properties generated by token pipeline
iOS:   ColorProviding protocol returns UIColor/Color per shade
Android: Theme attributes resolve to @color resources

How Token Updates Propagate

1. Designers update tokens in Figma using the Fluent 2 token plugin
2. Token pipeline exports platform-specific formats:
   • Web: JSON to CSS custom properties
   • iOS: JSON to Swift constants / asset catalogs
   • Android: JSON to XML color/dimen resources
3. Each platform library consumes its native format at build time
4. Runtime theming APIs allow further overrides

4. iOS (fluentui-apple)

Repository and Resources

• GitHub: microsoft/fluentui-apple
• CocoaPods: MicrosoftFluentUI
• Component Gallery: fluent2.microsoft.design/components/ios
• Figma Kit: Fluent 2 iOS UI Kit
• Language: Swift 5.9+
• Minimum Target: iOS 16.0+
• UI Frameworks: UIKit and SwiftUI

Installation

CocoaPods

# Podfile
platform :ios, '16.0'
use_frameworks!

target 'MyApp' do
  pod 'MicrosoftFluentUI', '~> 0.20'
end

Swift Package Manager

https://github.com/microsoft/fluentui-apple.git

In Xcode: File > Add Package Dependencies > paste the URL > select version range.

Available Components

The iOS library ships these major components (organized by category):

Core Controls: Button, Link, Label, Text, ActivityIndicator, ProgressIndicator Data Input: TextField, SearchBar, DateTimePicker, PeoplePicker, PillButtonBar Selection: Checkbox, RadioButton, Switch (Toggle), SegmentedControl, Slider Layout: Card, Divider, DrawerController, SheetController, SideTabBar, TabBarView Status & Info: Avatar, AvatarGroup, Badge, BadgeField, HUD, IndeterminateProgressBar, Notification (Toast/Bar), Shimmer, Tooltip Navigation: NavigationBar, CommandBar, BottomCommandBar, PopupMenuController Lists: ListItem, PersonaListItem, TableViewCell (FluentUI styled)

Theming

import FluentUI

// Apply a custom brand theme globally
let customTheme = FluentTheme()
customTheme.register(tokenSetType: ButtonTokenSet.self) { token, theme in
    switch token {
    case .backgroundColor:
        return .uiColor { theme.color(.brandBackground1) }
    default:
        return nil
    }
}

// Apply to a view hierarchy
view.fluentTheme = customTheme

The FluentTheme object holds all token values. Implement ColorProviding to supply custom brand colors, or use FluentTheme.register(tokenSetType:provider:) for per-component overrides.

Dark Mode

Fluent UI Apple automatically responds to UIUserInterfaceStyle changes. All semantic colors resolve through the token system, so dark mode works without extra code. To force a specific appearance:

view.overrideUserInterfaceStyle = .dark

Accessibility

• Dynamic Type supported on all text-bearing components
• VoiceOver labels and hints set by default
• Minimum 44pt touch targets enforced
• Reduced Motion respected for animations

For the complete iOS reference with full code examples, see references/ios-reference.md.

5. Android (fluentui-android)

Repository and Resources

• GitHub: microsoft/fluentui-android
• Maven: com.microsoft.fluentui group
• Component Gallery: fluent2.microsoft.design/components/android
• Figma Kit: Fluent 2 Android UI Kit
• Language: Kotlin 1.9+
• Minimum SDK: API 21 (Android 5.0)
• UI Frameworks: Android Views (XML) and Jetpack Compose

Installation (Gradle)

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://pkgs.dev.azure.com/nicemi365/nicemi365/_packaging/nicemi365-maven/maven/v1") }
        mavenCentral()
        google()
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.microsoft.fluentui:FluentUI:0.2.+")
    // Or individual modules:
    implementation("com.microsoft.fluentui:fluentui_core:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_controls:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_drawer:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_listitem:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_persona:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_popupmenu:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_topappbars:0.2.+")
    implementation("com.microsoft.fluentui:fluentui_transients:0.2.+")
}

Available Components

Core Controls: Button, FAB (Floating Action Button), Link, Label, Text, ProgressIndicator Data Input: TextField, SearchBar, DateTimePicker, PeoplePicker, PillBar Selection: Checkbox, RadioButton, Switch (Toggle), SegmentedControl (TabLayout) Layout: Card, Divider, Drawer (BottomSheet, Side), ListItem, BasicListItem, PersonaListItem Status & Info: Avatar, AvatarGroup, Badge, Shimmer, Snackbar, Tooltip, ProgressBar Navigation: AppBarLayout (TopAppBar), BottomNavigation, PopupMenu, ContextMenu, BottomSheet Compose: BasicCard, Button, Avatar, Badge, CircularProgressIndicator, LinearProgressIndicator, SearchBar, Shimmer, TextField, ToggleSwitch

Theming

import com.microsoft.fluentui.theme.FluentTheme
import com.microsoft.fluentui.theme.token.AliasTokens

// In your Application class or Activity
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        // Override brand colors
        FluentTheme.updateAliasTokens(
            AliasTokens().apply {
                brandColor = listOf(
                    Color(0xFF0F6CBD),  // shade10
                    // ... full ramp
                )
            }
        )
    }
}

// Jetpack Compose
@Composable
fun MyScreen() {
    FluentTheme {
        // Fluent-styled content
        Button(onClick = { }) {
            Text("Fluent Button")
        }
    }
}

Dark Mode

The library respects AppCompatDelegate.setDefaultNightMode() and the system dark mode setting. All Fluent tokens resolve to dark-mode variants automatically via Android resource qualifiers (values-night/).

Material You Integration

Fluent UI Android can coexist with Material 3 / Material You. The recommended approach:

1. Use Fluent tokens as the primary design language
2. Let Material You dynamic color inform the brand ramp at runtime
3. Fluent components render with Fluent styling; Material components use Material theming

// Extract Material You dynamic color and feed into Fluent brand ramp
val dynamicColor = dynamicDarkColorScheme(context).primary
FluentTheme.updateAliasTokens(
    AliasTokens().apply {
        brandColor = generateBrandRamp(dynamicColor)
    }
)

For the complete Android reference with full code examples, see references/android-reference.md.

6. Cross-Platform Patterns

Pattern 1: Shared Token Source of Truth

Maintain a single tokens.json that feeds all three platform builds:

tokens/
  global.json          # Global color palette, type ramp
  brand-contoso.json   # Brand-specific overrides
  alias.json           # Semantic aliases
scripts/
  build-web.js         # Outputs CSS custom properties
  build-ios.swift      # Outputs Swift constants
  build-android.kt     # Outputs XML resources

Use Style Dictionary or the Fluent token pipeline to transform tokens.json into each platform's native format.

Pattern 2: Component API Alignment

When building the same feature on all platforms, align prop/parameter names:

Fluent Concept    Web (React prop)    iOS (Swift param)       Android (Kotlin param)
--------------    ----------------    -----------------       ----------------------
appearance        appearance          style                   buttonStyle
size              size                size                    size
icon              icon                icon                    icon
disabled          disabled            isDisabled              isEnabled (inverted)

Pattern 3: Platform-Specific Adaptations

Some patterns are intentionally different per platform to respect native conventions:

Pattern 4: Shared Figma Libraries

Use all three Figma kits in a single Figma project to design cross-platform:

1. Web Kit: Fluent 2 Web UI Kit
2. iOS Kit: Fluent 2 iOS UI Kit
3. Android Kit: Fluent 2 Android UI Kit

Create a shared "Specs" page that maps each screen to all three platform variants side by side.

Pattern 5: Accessibility Parity Checklist

Ensure accessibility consistency across platforms:

• All interactive elements have accessible names (aria-label / accessibilityLabel / contentDescription)
• Color contrast meets WCAG 2.1 AA (4.5:1 text, 3:1 UI) on all platforms
• Focus order is logical (tab order / VoiceOver order / TalkBack order)
• Dynamic text sizing works (CSS rem / Dynamic Type / sp units)
• Motion can be reduced (prefers-reduced-motion / UIAccessibility.isReduceMotionEnabled / Settings.Global.ANIMATOR_DURATION_SCALE)
• Touch targets meet minimums (44px Web / 44pt iOS / 48dp Android)

7. Cross-References

• Design Tokens (core): See the main fluent-ui-design SKILL.md for the complete token taxonomy, CSS custom property reference, and Griffel styling patterns.
• Theming & Extensibility: See fluent-extensibility/SKILL.md for advanced theming techniques including custom token sets, theme providers, and design-to-code workflows.
• Component APIs (Web): See fluent-components/SKILL.md for the full React component catalog with prop tables and composition patterns.
• Accessibility: See fluent-accessibility/SKILL.md for WCAG compliance patterns that apply across all platforms.

Reference Files