Miuix for Compose Multiplatform: Experimental UI Modules and Kotlin Integration

What Miuix Adds to Compose Multiplatform

Miuix addresses the visual and component layer of applications built with Compose Multiplatform. The repository presents it as a UI library rather than a complete application framework. That distinction matters: it does not replace Compose's state management, build system, navigation architecture, or application entry points. It supplies reusable UI modules and an opinionated visual direction that can be shared across supported targets.

The intended users are Kotlin developers building Compose Multiplatform applications, especially teams that want one codebase to address Android, iOS, macOS, desktop JVM, JsCanvas, and WasmJs. The repository lists Android, iOS, macOS, Desktop, JsCanvas, and WasmJs as supported platforms. The public module split is useful for teams that do not want to install every component. The core library is `miuix-ui`, while preference components are optional through `miuix-preference`.

This is an explicit trade-off. A project can adopt the core visual components without pulling in preference UI, icons, blur effects, navigation, squircle shapes, or shaders. That keeps dependencies narrower, although it also means an application may need other libraries for functionality that Miuix does not include. The README labels the project experimental, and states that APIs may change without notice. That warning should be treated as part of the library's adoption boundary rather than as a minor documentation note.

Miuix Modules and Their Dependency Boundaries

Miuix is organized as a set of separately consumable modules. `miuix-ui` is the core UI component library. `miuix-preference` depends on `miuix-ui`, which makes its dependency relationship explicit. `miuix-icons`, `miuix-blur`, `miuix-squircle`, and `miuix-nav` can each be used independently, according to the README. `miuix-shader` is described as a low-level runtime shader and render effect abstraction.

This structure gives an application some control over its dependency graph. A basic application can begin with `miuix-ui` and add only the modules required by its screens. An application with settings can add `miuix-preference`, while an application that needs additional symbols can add `miuix-icons`. The separation also means the modules have different roles. The squircle module is concerned with smooth rounded corner shapes, not general layout, and the shader module is a rendering abstraction rather than a component library.

The repository layout includes additional directories such as `miuix-core` and `miuix-window` in addition to the modules named in the README. Since the README does not explain those two directories as published artifacts, their packaging and intended use should not be assumed. The documented Maven coordinates are the safer basis for dependency planning.

Theme Configuration and Dynamic Color Flow

Miuix requires the application to provide a color scheme through `MiuixTheme`. The README gives a basic pattern that chooses between `darkColorScheme()` and `lightColorScheme()` according to the system theme, then passes the selected colors to `MiuixTheme`. This keeps theme selection in application code while allowing Miuix components to consume the resulting scheme.

The first-use example is a composable wrapper, not a standalone initialization command. The application creates or obtains its color choice and places the content inside `MiuixTheme`. In a real project, the exact placement depends on the application's Compose entry point and platform source sets, which the README does not specify.

Miuix also documents a second theme path. `ThemeController` manages color-scheme modes and can enable Monet dynamic colors. The example creates the controller with `remember`, selects `ColorSchemeMode.MonetSystem`, and supplies `Color(0xFF3482FF)` as `keyColor`. The controller is then passed to `MiuixTheme`. The distinction between a direct color scheme and a controller matters during integration: the first is a straightforward theme value, while the second adds mode and dynamic-color behavior.

The repository documentation does not describe persistence, platform-specific dynamic-color fallbacks, or controller lifecycle rules. Applications should verify those details against the relevant API documentation rather than assuming that system colors behave identically on every supported target.

Adding Miuix to a Kotlin Multiplatform Project

The README provides a Gradle dependency pattern but does not provide a complete installation command or version-selection procedure. Dependencies are declared in `commonMain.dependencies`, with optional modules shown as separate entries. The placeholder `<version>` must be replaced by the project version being adopted. The following is the documented dependency shape, with the optional comments preserved where they explain module purpose.

commonMain.dependencies {
    implementation("top.yukonga.miuix.kmp:miuix-ui:<version>")
    // Optional: Add miuix-preference for preference components
    implementation("top.yukonga.miuix.kmp:miuix-preference:<version>")
    // Other dependencies...
}

Only add the optional dependency that the application needs. `miuix-icons`, `miuix-blur`, `miuix-squircle`, `miuix-nav`, and `miuix-shader` are separate module choices. The README does not show a shell command for publishing, downloading, or installing the library, so there is no documented installation command to reproduce.

After adding the dependency, the first real use is to wrap the application's composable content in `MiuixTheme`. The repository gives this complete theme pattern:

@Composable
fun AppTheme(
    content: @Composable () -> Unit
) {
    val colors = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
    return MiuixTheme(
        colors = colors,
        content = content
    )
}

The reader should see the application's existing composable content passed through `content`. The README does not define `isSystemInDarkTheme()`, so its import and platform availability must be handled by the surrounding Compose project.

Using ThemeController for Monet Mode

For applications that need controller-based theme management, the README provides a second pattern. The controller is created inside `remember`, receives `ColorSchemeMode.MonetSystem`, and sets a custom seed color with `keyColor`. Passing that controller to `MiuixTheme` is the documented integration path.

@Composable
fun AppTheme(
    content: @Composable () -> Unit
) {
    val controller = remember {
        ThemeController(
            ColorSchemeMode.MonetSystem,
            keyColor = Color(0xFF3482FF)
        )
    }
    return MiuixTheme(
        controller = controller,
        content = content
    )
}

This example is most relevant when the application deliberately wants Monet dynamic colors or centralized scheme-mode handling. It is not interchangeable with the direct color-scheme example without checking the API. The README does not state which platforms expose system Monet colors, how unsupported targets behave, or whether `keyColor` is ignored when dynamic colors are unavailable. Those are concrete compatibility questions for an application targeting both native and web platforms.

The project does not document a runtime theme switch, persistence format, or migration process for changing from direct colors to `ThemeController`. Teams adopting that path should inspect the module source and the target-platform examples before depending on those behaviors.

Miuix Platform Scope and Experimental API Risk

Miuix has a broad declared platform scope, but broad support does not mean that every component or module has identical behavior on every target. The README names Android, iOS, macOS, desktop JVM, JsCanvas, and WasmJs. The repository also contains example directories for Android, desktop, iOS, macOS, shared code, and web. Those directories indicate where examples exist, but the README does not document a compatibility matrix or a guarantee that every module is available on every target.

The experimental status is the clearest limitation. APIs may change without notice, so an application can face source changes when updating Miuix. The repository's recent release history includes `v0.9.4`, `v0.9.4-rc01`, and `v0.9.3`, but release labels alone do not establish a stable compatibility promise. The last push recorded for the repository was on 2026-10-16. That indicates recent repository activity, but it does not remove the stated experimental status.

The web targets deserve particular scrutiny. JsCanvas and WasmJs are separate rendering environments, and the README provides demos for both. It does not document parity for blur, runtime shaders, preferences, icons, or navigation. If a feature is central to the product, its availability and behavior should be checked in the relevant example or module source before adoption.

Miuix Compared With Material 3 and Plain Compose Multiplatform

Miuix is an opinionated component and theming layer over Compose Multiplatform. Material 3, when used through its platform or Compose implementation, follows Google's Material design system and provides a different established design language and ecosystem. Plain Compose Multiplatform gives the application team direct control over components and styling, but requires the team to define more of the visual system itself.

The practical difference is adoption cost versus design control. Miuix supplies named modules for preferences, icons, blur, squircle shapes, navigation, and shaders, plus `MiuixTheme` for color integration. A team can adopt selected pieces instead of constructing an equivalent component vocabulary. The cost is tighter coupling to an experimental API surface and to Miuix's visual conventions.

A team that needs full control over a custom design system may prefer plain Compose primitives. A team that wants a reusable multiplatform visual layer and accepts experimental APIs can use Miuix as a higher-level starting point. The README does not claim API compatibility with Material 3, nor does it document a migration path from Material components.

Apache-2.0 Licensing and Upgrade Cost

Miuix is distributed under the Apache License 2.0, identified by the repository license metadata and the README license badge. That license permits use and modification under its stated terms, subject to the license text and notices. The README does not provide project-specific legal guidance, and this review does not interpret the license beyond identifying the declared license.

Upgrade cost is driven by the experimental API status rather than by a documented migration schedule. The README explicitly warns that APIs may change without notice. Because the project is split into several modules, an application should also check whether an upgrade affects only the modules it uses or whether shared theme, rendering, or platform dependencies require coordinated changes. No compatibility matrix or upgrade guide is included in the documentation shown here.

The repository has recent release entries, but the documented release history is not a guarantee of semantic versioning stability. Before changing a release, inspect the module APIs used by the application, especially `MiuixTheme`, `ThemeController`, icons, blur, shaders, and navigation. The first verification target should be the exact dependency set and the platform-specific examples corresponding to the intended product targets.

Editorial conclusion

Adopt Miuix when a Kotlin team wants to share Compose UI code across native and web targets and can accept experimental APIs. Do not treat it as a stable Material 3 replacement. Verify the exact module versions, platform coverage for the required targets, and migration impact before committing a production application.

Frequently asked questions

Official sources

1. compose-miuix-ui/miuix on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases