v-miniapp-ui-react（V miniapp UI React 前端）

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.