Huxerui App Development

HuxerUI App Development

Use the installed HuxerUI SDK to create, modify, review, or troubleshoot applications and app-side reusable components. Do not use this skill to change HuxerUI framework internals, renderers, platform adapters, SDK packaging, or the framework's own build.

Recognize the project

Treat the task as HuxerUI SDK application work when the user names HuxerUI or its CLI, or when the project contains one of these signals:

• find_package(HuxerUI CONFIG REQUIRED)
• HuxerUI::huxerui or HuxerUI::huxerui_static
• an include under <huxerui/...>
• import huxerui; in a source or module interface unit
• an mcpp.toml that depends on huxerui.huxerui, beside a build.mcpp that imports huxerui.rules

The last two identify an mcpp project, which huxerui create app <name> --build mcpp produces. It is HuxerUI application work like any other, and the public contracts below apply unchanged -- an mcpp project reaches the same entities through import huxerui; that a CMake project reaches through the umbrella header. What differs is the build: mcpp drives it, not this CLI and not CMake, so mcpp build and mcpp run replace huxerui build and huxerui run, there is no CMakeLists.txt and no platform/ shell to edit, and the SDK discovery below does not apply -- the framework arrives through the dependency edge. See references/mcpp-build.md.

Opening a matching project does not authorize changes or commands by itself.

Establish the SDK truth

Before relying on an API, identify the SDK used by the project. An mcpp project skips this section: it names a package version in mcpp.toml, and mcpp resolves it -- there is no installed SDK prefix to locate.

1. Read HuxerUI_DIR from the active build directory's CMakeCache.txt, then derive the SDK prefix from lib/cmake/HuxerUI.
2. Otherwise use HUXERUI_HOME when it identifies an installed SDK.
3. Otherwise locate huxerui on PATH and run huxerui doctor.
4. If none is available, ask for the SDK location before relying on exact API or build behavior.

Prefer that SDK's include/huxerui and lib/cmake/HuxerUI over this Skill's guidance. Do not scan for a source checkout or read its src, tests, examples, or design documents to fill gaps. Follow the installed public contract without compatibility aliases.

Work from public contracts

• Components are ordinary C++ functions returning View.
• View is a lightweight copy-on-write declaration value. Pass and return it by value; do not add std::move to temporary chains, container children, or return statements as a routine optimization.
• Mark a reusable function [[huxerui::composable]] when it directly calls a composition-bound UseXxx() API or needs its own recomposition lifetime. Do not annotate the application root.
• Keep controlled values authoritative in app state and write emitted changes back for the next composition.
• Use stable semantic keys for dynamic stateful siblings that insert, remove, or reorder.
• Preserve complete TextEditingValue state for TextField.
• Use only public headers, public CMake targets, generated project conventions, and platform-specific public headers.
• Prefer generated ImageResource values for static artwork displayed by HuxerUI components. Keep scalable in-UI artwork as SVG under resources/images; use VectorAsset::Create or Canvas only for genuinely programmatic or dynamic drawing. Platform application and system-tray icons follow their separate packaging contracts.
• Compose built-in layouts and their modifiers before deriving Layout or VirtualLayout. A custom layout is for a genuinely new measurement or placement algorithm, not ordinary alignment, spacing, growth, wrapping, overlay, paging, scrolling, or responsiveness.
• Start application visuals from FlatTheme, FlatDarkTheme, MaterialTheme, or MaterialDarkTheme. Customize their tokens or typed styles instead of recreating a built-in theme with a bare ThemeDefinition.
• Choose the narrowest extension mechanism after exhausting its built-in equivalent. Prefer an ordinary component, existing event or modifier, Environment/Theme value, presentation service, or root service. Use a custom Layout, retained modifier with NodeExtension, PlatformModule, PlatformView, or ExternalTexture only when its distinct geometry, mounted lifetime, or platform boundary is actually required.
• Do not invent APIs, legacy names, private includes, or source-checkout paths.