Miuix Skill

---
name: miuix
description: "Miuix (HyperOS) Compose 专家。用于 Miuix/HyperOS UI 构建、审查、重构；在 Miuix 项目或点名组件/API 时触发：MiuixTheme、ThemeController、miuix-ui、miuix-preference、miuix-blur、miuix-nav；NavigationBar/navigation bar、FloatingNavigationBar/floating navigation bar、NavigationRail、TopAppBar/top app bar、Scaffold、TabRow、Button/TextButton/IconButton、FloatingActionButton/FloatingToolbar、Card、TextField/text field、InputField、SearchBar/search bar、Switch/Checkbox/RadioButton、Slider/slider、SliderPreference/Overscroll、ProgressIndicator、Snackbar、Tooltip/TooltipBox/PlainTooltip/RichTooltip、Badge/BadgedBox、BreadcrumbBar/breadcrumb bar、PullToRefresh/pull to refresh、ColorPicker、OverlayDialog/OverlayBottomSheet/OverlayListPopup、WindowDialog/WindowBottomSheet、ArrowPreference/SwitchPreference/CheckboxPreference/RadioButtonPreference、Dropdown/Spinner、ProgressiveBlur、WindowNavigationEventScope、NavDisplay/NavController/NavKey/NavTransitions/NavDisplayEffects。覆盖设置、弹窗、导航、表单、主题、颜色、无障碍、自适应；指定 Material 3/MD3/其他系统时不触发；无 Miuix 上下文的通用 button/card/slider 不触发。"
---

# Miuix Skill

## What Miuix Is

Miuix is a Compose Multiplatform UI component library that implements Xiaomi HyperOS design language. It targets Android, iOS, Desktop (JVM), macOS, and Web (Wasm/JS) from a single Kotlin codebase.

**Modules:**
| Module | Purpose | Dependency |
|--------|---------|------------|
| `miuix-ui` | Core UI components — Button, Switch, TextField, NavigationBar, Scaffold, dialogs, etc. | — (root module, includes miuix-core, miuix-squircle) |
| `miuix-preference` | Settings-screen components — SwitchPreference, CheckboxPreference, SliderPreference, dropdown selectors, etc. | depends on miuix-ui |
| `miuix-icons` | 100+ extended icons in 5 weights (Light/Normal/Regular/Medium/Demibold) | includes miuix-core |
| `miuix-blur` | Backdrop blur, texture effects, and progressive blur (Android effect paths require RuntimeShader/API 33) | includes miuix-shader |
| `miuix-shader` | RuntimeShader abstraction layer (cross-platform shader support) | — (transitively included by miuix-blur / miuix-squircle) |
| `miuix-squircle` | Squircle shape — continuous-curvature corners that look smoother than RoundedCornerShape on screen. Auto-falls back to RoundedCornerShape below API 33. | — (transitively included by miuix-ui) |
| `miuix-nav` | Self-contained Compose Multiplatform navigation runtime with a serializable back stack, continuous-depth transitions, and predictive/edge back handling | independent of `miuix-ui`; uses `miuix-squircle`, lifecycle/ViewModel, navigation-event, and kotlinx serialization APIs internally |

Most projects start with `miuix-ui` and add `miuix-preference` for settings rows. Add `miuix-icons`, `miuix-blur`, or `miuix-nav` explicitly when those features are used. `miuix-ui` already brings in `miuix-core` and `miuix-squircle`; `miuix-shader` arrives transitively through `miuix-blur` or `miuix-squircle`. `miuix-nav` is the current navigation module; do not infer `androidx.navigation3` APIs from the older module name.

**Key concepts:**
- The application UI subtree must be under an ancestor `MiuixTheme`, which provides `MiuixTheme.colorScheme.*` and `MiuixTheme.textStyles.*`; individual screens should not duplicate the root theme
- Natural-language color requests need role lookup: read [Color semantics and visual lookup](references/color-lookup.md) and map the user's visual description to a verified token or component `*Defaults` factory; do not invent `warning`/`alert` tokens or equate a default blue sample with a permanent semantic hue
- Overlay components (OverlayDialog, OverlayBottomSheet, etc.) render inside `Scaffold`'s popup layer — they follow the page lifecycle and need a `Scaffold` ancestor. Window components (WindowDialog, WindowBottomSheet, etc.) render in an independent window layer — they're standalone, ideal for cross-page global popups.
- `Scaffold` can host a `floatingToolbar` with a `ToolbarPosition`; this slot predates 0.9.4, while the current stable layout keeps the `Snackbar` above a bottom-positioned toolbar.
- `PullToRefresh` keeps `isRefreshing` hoisted, while `rememberPullToRefreshState(refreshThreshold = ...)` owns indicator mechanics and exposes full-range progress for optional observers.
- `miuix-nav` separates route/back-stack ownership from `NavigationBar`/`NavigationRail` chrome. `rememberNavBackStack` requires `@Serializable` route keys for save/restore; the v1 runtime is a flat stack, does not provide dialog scenes or a built-in result channel, and defaults transition input blocking off.
- In stable `0.9.4`, `NavigationRail` has separate fixed-layout and non-null expandable-state overloads; `state = null` is no longer a valid compatibility call. `NavigationBarItem` and `FloatingNavigationBarItem` accept a shared `NavigationBarItemColors` value before `badge`.
- Stable `miuix-nav` provides `LocalNavTransitionScope` inside each entry, adds the composition-safe `NavTransitionScope.isRunning` signal, and passes the parent saved-state creation context into entry ViewModels so `SavedStateHandle`/Hilt integrations can work without custom owner plumbing.
- Stable `miuix-ui` includes `PagerGestureUtils` for `HorizontalPager`/nested-list conflicts, including `pagerGestureOverride`, explicit interception modes, and spring page navigation. `TabRow` now contains horizontal nested scroll/overscroll instead of forwarding it to a parent pager.
- Treat an exact Miuix English component name or its common spaced form as a direct signal: map `navigation bar`, `floating navigation bar`, `slider`, `search bar`, and similar names to the component catalog before applying generic Compose UI advice.
- Public components generally follow a recognizable parameter order, but exact signatures must be verified in docs/demo/source rather than inferred
- Many configurable components expose a dedicated `*Defaults` object for supported dimensions, shapes, colors, and state styling

## References

Read only the reference files required for the task:

**Workflows**

- [Existing UI review and improvement workflow](references/ui-review-workflow.md)