Imported from limczhh/miuix-skill (SKILL.md). Install upstream with npx skills add limczhh/miuix-skill. Copyright stays with the author.

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:

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:

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:

Stop loading evidence

Stop expanding the evidence set when the task has the minimum proof it needs:

• For an explanation, the public purpose and relevant parameters are supported by the pinned documentation and, where behavior is non-obvious, source.
• For a component snippet, the exact signature, imports/dependency, required ancestor, and state/callback contract are known from the doc/demo/source path.
• For a page, the hierarchy, host, state owner, insets, and relevant Example composition are mapped; do not keep reading unrelated component demos.
• For a review, the target code and available visual evidence have been classified, and the applicable static/render/runtime validation level is chosen.
• For a migration, the exact target tag/commit, affected API diff, and target compilation/regression checks are identified.

Reopen already-read references only when a version, platform, or source conflict appears. If the required pinned web evidence is unavailable, stop and report the verification gap instead of silently widening to unpinned sources.

Code Delivery Contract

When the task includes code, this is the authoritative delivery checklist. Reference files add domain-specific guidance; they do not define a second completion contract.

Before returning code:

• Default to the smallest integration-ready snippet that fulfills the interaction. Return a complete root App only when the user asks for a standalone/runnable example or project setup owns the root; include exact imports for standalone code.
• Preserve or explicitly define state ownership. Hoist persistent/business state; keep only transient presentation state such as local popup visibility in remember.
• Make theme, Scaffold, popup-host, and inset ownership explicit according to Resolve Code Context. Never add a bare root MiuixTheme {} when the example is responsible for system theme behavior; use the ThemeController pattern from setup/theme.
• Include dependency lines only when setup is part of the task or the target project is missing them. Respect the target project's Miuix version; this Skill's catalog follows the 0.9.4-rc01 candidate snapshot and must be rechecked when the target uses another version.
• Do not omit callbacks, dismissal paths, disabled behavior, or selected-value updates needed to make the demonstrated interaction work.
• Use Miuix components that match the scenario, consume Scaffold/inset padding, and prefer theme tokens/component Defaults before literal styling. Do not present Example-only helpers as library requirements.
• Report source/API verification, compilation, and visual/device validation as separate facts.

Guardrails

These rules prevent the most common failure mode: fabricating APIs that don't exist.

Why this matters

Miuix is an independent library — its API surface is completely different from Material Design, Material 3, or any other Compose library. Guessing parameter names, icon names, or color tokens from memory of those other libraries will produce code that doesn't compile. Always verify against the actual source files.

Apply these non-negotiable checks:

• Read the evidence depth required by the task: component intent from the upstream Markdown doc, isolated usage from its demo when producing a call shape, integrated composition from the closest Example page when composing a page, and uncertain or version-sensitive contracts from the exact snapshot in Source verification. Do not load every reference or every upstream file by default.
• Treat Example as a reference implementation, not an API contract. Reuse hierarchy and state flow without importing showcase-only helpers or effects.
• When the candidate snapshot has no public Miuix component for the requested interaction, compose it first from Compose Foundation/Layout/Animation primitives under MiuixTheme, reuse Miuix semantic tokens and nearby component Defaults, and keep the custom wrapper application-owned. Mix Material or Material 3 only when the target project intentionally does so or the user explicitly requests it. Disclose the custom behavior and verify its semantics, disabled/error states, and platform behavior.
• Verify BreadcrumbBar, the existing Scaffold.floatingToolbar slot and its candidate snackbar spacing, InputField.color (not SearchBar.color), OverlayDialog/WindowDialog maxWidth/largeScreen/cornerRadius, WindowNavigationEventScope, PullToRefresh progress APIs, RadioButtonPreference.colors, and ProgressiveBlur before giving migration-sensitive examples.
• For miuix-nav, verify NavKey, rememberNavBackStack, NavDisplay's entry<T> { ... } DSL, NavTransitions, and NavDisplayEffects in the candidate source. Do not fabricate androidx.navigation3 scene APIs or a built-in result channel.
• Use only color and typography tokens present in tagged Colors.kt and TextStyles.kt; do not infer Material or Material 3 names.
• For color descriptions such as “蓝色主按钮”“红色警告”“黄色警告”“灰色摘要文字”, read Color semantics and visual lookup. Verify the actual Colors source and the selected component's Defaults; use error only for the candidate's red status role, and use an app-owned semantic token for yellow/non-error warning states instead of fabricating alert/warning/success properties. For named controls such as Switch, Checkbox, RadioButton, Badge, Snackbar, TabRow, ProgressIndicator, ScrollBar, and Tooltip, preserve their state-specific Defaults rather than inferring colors from hue alone.
• For icon dependencies, verified icon names, blur limits, and the actual squircle modifiers, read Styling, icons, and effects.