Overview

Use this skill for production-ready UI work built on @v-miniapp/ui-react.

This skill is the UI-focused counterpart to the broader mini-app workflow. Use it when the task is mainly about screen structure, navigation, theming, component choice, or app-level React configuration. If the task is mainly about CLI bootstrap, login, build/deploy, or @v-miniapp/apis, prefer the dedicated mini-app skill.

Process

Phase 1: Scope the UI Work

Identify whether the task is primarily about one of these areas:
- App shell and page registration
- Routing and navigation
- Localization
- Theming and design tokens
- Choosing or correcting @v-miniapp/ui-react components
First decide whether the current project is a regular mini-app UI or an AI app UI.
Treat it as an AI app when the workspace structure looks like server/, web/, skills/, and app-config.json.
In AI app projects, @v-miniapp/ui-react is usually used inside widgets under web/src/widgets/, so do not assume the project needs App initialization, page registration, or mini-app routing setup.
Read only the relevant reference files instead of loading everything up front.

Phase 2: Apply Framework Conventions

2.1 App structure

Follow App setup for App initialization, pages, layouts, keep-alive, navigation bar, and page layout only for regular mini-apps that actually use the App shell.
Follow Routing for navigation patterns and page params only when the project is using mini-app app-level routing.
If the project is an AI app with UI code inside web/src/widgets/, skip app setup and routing guidance unless the user is explicitly working on a standalone mini-app shell inside that project.
Treat routing as single-level unless the docs say otherwise; prefer params/query-style navigation over invented nested route structures when routing is actually in play.
Follow Locale for AI apps when the project is an AI app with web/src/locales/.
Follow Locale for Mini apps when the task involves translations or language switching in a regular mini-app App shell.

2.2 Component system

Follow Component guidelines before adding or changing UI.
Prefer @v-miniapp/ui-react components over raw HTML or custom-styled replacements.
Verify props and icon names against the matching component reference before finalizing code.
Reuse built-in layout and feedback patterns rather than rebuilding them from scratch.

2.3 Theme and styling

Follow App guidelines for framework limitations and theme expectations.
Follow Design tokens for colors, token usage, and theming.
Keep styling aligned with the SDK design system; prefer component props and token-based styles over ad-hoc CSS.

Phase 3: Validate the Result

Check that every UI element uses the most appropriate @v-miniapp/ui-react primitive available.
Verify component props, icon names, navigation setup, and app config values against the references.
Avoid unsupported routing patterns, duplicated navigation bars, or custom styling that bypasses the design tokens without a reason.
If the task also touches CLI setup or @v-miniapp/apis, coordinate with the dedicated mini-app skill instead of overloading this one.

Reference Files

Use the bundled reference files under packages/skills/ui-react/references/ and load only what matches the task.

Core guidance

Component guidelines - preferred component usage and prop verification.
App guidelines - routing constraints and theme defaults.
Locale guidelines - AI app widget locale setup with web/src/locales/ and initLocales(...).

App framework

App setup - App config, pages, layouts, keep-alive, and app-level options for regular mini-apps, not widget-only AI app UIs.
Routing - links, navigation, page params, and lifecycle patterns when the project actually uses mini-app routing.
Locale - i18n setup for regular mini-apps that pass localesConfig into App.

Design system

Design tokens - token catalog, usage patterns, and theme overrides.

Components

Foundation - typography and icon basics.
Icon names - valid icon identifiers.
Actions - buttons and action affordances.
Form - inputs, text areas, uploaders, calendars, and related controls.
Selections - radio, checkbox, switch, chip, and option items.
Navigation - navigation bar and tab components.
Interface elements - avatar, carousel, and section patterns.
Feedback - toast, alert, and tooltip patterns.
Modal - dialog and sheet usage.
Indicator - badges and state indicators.

v-miniapp-ui-react