---

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 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 the current candidate, while the candidate fixes bottom-toolbar spacing so the Snackbar stays above it.
• 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.
• 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
• Example-derived usage patterns

Design and component selection

• Design language and component Defaults
• Color semantics and visual lookup
• Scenario map and basic component catalog
• Overlay and window component catalog
• Preference and dropdown menu catalog

Setup and evidence

• Project setup and theme
• Styling, icons, and effects
• Path conventions, supporting internals, and example app
• miuix-nav routing and transition guide
• v0.9.3 → v0.9.4-rc01 migration notes
• Historical v0.9.2 → v0.9.3 migration notes

Resolve Code Context

Decide which layer the requested code owns before writing it:

| Context | Rule | Read next | |---|---|---| | Existing application screen or component | Inspect the existing root theme and page host. Reuse them; do not add another MiuixTheme or Scaffold unless the requested behavior needs a new page boundary or popup host. | Project setup and theme, then the task-specific reference | | Standalone runnable App or complete example | Own the root explicitly: create a remembered ThemeController, wrap one MiuixTheme, and add Scaffold only when the example needs page slots, insets, snackbar, or Overlay hosting. | Project setup and theme + the selected component/page evidence | | Isolated component snippet | Show the smallest useful call and state its required ancestor context. Include a local Scaffold only when the snippet itself must run and host an Overlay. | Component catalog + doc/demo; source for uncertain APIs |

Working Method

Do not stop after locating a component or source file. Turn the evidence into an implementation:

1. Resolve the target project's Miuix version before using a version-sensitive example: inspect its Gradle files, version catalog, dependency lock, or build output; identify the platform/source set; then choose the matching upstream tag or commit. Treat this Skill's 0.9.4-rc01 snapshot as a fallback reference only when the target version is unknown, and label the mismatch.
2. Resolve the code context above, then understand the user's visual and behavioral goal.
3. Inspect the target project's theme, page shell, hierarchy, state ownership, navigation, insets, and existing conventions when project code is available.
4. For an existing UI review or polish task, follow UI review and improvement workflow. Inspect both code and available visual evidence before changing geometry.
5. Classify the request by scenario, then select Miuix components from the relevant catalog.
6. Load evidence at the required depth. For the current catalog, use the pinned web-source paths in Source verification: read the relevant Markdown doc, demo, Example code, and source from the 0.9.4-rc01 candidate snapshot at commit 4a6b750b; use the historical v0.9.3 tag only when the task explicitly targets that release.
7. Before designing or restructuring a page, read Example-derived usage patterns and Design language and Defaults. Extract the pattern; do not copy the showcase application wholesale.
8. Implement with public Miuix components, semantic theme tokens, and component Defaults first. Customize only for an explicit product need or established project convention.
9. Verify exact APIs against the pinned candidate snapshot in Source verification. Compile code changes and validate visual changes with a render, screenshot, preview, emulator, or device when available.

Evidence Loading Strategy

Load only what the request needs:

| Intent | Read | Use it to | |---|---|---| | Project setup | Project setup and theme, then docs/guide/getting-started.md | Configure modules and the root theme | | Single component explanation | Relevant catalog row + component doc | Explain purpose, states, and parameters | | Single component code | Component doc + matching docs/demo/<Component>Demo.kt; read source for uncertain parameters; add Project setup and theme if the example owns App/theme/host | Produce a minimal, version-correct call in the right ancestor context | | Page creation or redesign | Example-derived usage patterns + Design language and Defaults + the closest page or section under example/shared/; add setup/theme when the code owns the root | Reuse integrated composition and semantic visual roles without duplicating hosts | | Natural-language color or visual styling | Color semantics and visual lookup + Design language and Defaults + tagged Colors.kt and the selected component's Defaults | Resolve hue plus visual role to a real Miuix token/factory, preserve container/on* pairing, and distinguish fixed default samples from dynamic theme output | | Existing UI review or polish | UI review and improvement workflow + Design language and Defaults + target code and available visual evidence | Diagnose hierarchy, styling, state, inset, adaptive, and accessibility problems before editing | | Accessibility, adaptive, or platform-sensitive UI | UI review and improvement workflow + Styling, icons, and effects + target platform evidence | Check semantics, targets, text scaling, RTL, IME, light/dark/dynamic color, and supported platform behavior instead of treating a screenshot as the whole contract | | Popup, dialog, or dropdown | Overlay and window component catalog or Preference and dropdown menu catalog + matching demo + source | Choose the correct host/lifecycle and state model | | Navigation architecture | Example-derived usage patterns + miuix-nav guide + example/shared/.../AppState.kt, AppContent.kt, and navigation/ | Separate NavDisplay routing/back-stack architecture