Skill: tlrenhb/vela-dev (version 1.0.0)

--- name: vela-dev description: Build, edit, debug, and package Xiaomi Vela JS quick apps for wearable devices such as Xiaomi Band 10. Use when the user asks to create a Vela 快应用, modify `.ux` pages, fix `npx aiot build` errors, adapt UI for 手环屏幕, or package/send `.rpk` apps. Covers project scaffolding, manifest/app/config creation, Vela component/event/style constraints, and iterative build-debug loops. --- # Vela Dev Use this skill when working on Xiaomi Vela JS wearable quick apps. ## What this skill is for - Create a new Vela quick app from scratch - Edit existing `.ux` pages - Fix build errors from `npx aiot build` - Adapt UI for Xiaomi Band / Watch screens - Package an `.rpk` for delivery ## Workflow 1. Identify whether the user wants a **new app** or edits to an **existing Vela project**. 2. If new, scaffold the minimum required files: - `src/manifest.json` - `src/app.ux` - `src/config-watch.json` - at least one page like `src/pages/<name>/index.ux` 3. Prefer a **single-page app with internal state switching** unless the app clearly benefits from router-based multi-page navigation. 4. Build with: - `cd <project> && npx aiot build` 5. If build fails, inspect the exact error and patch surgically. 6. Only send/package the `.rpk` after a successful build. ## Xiaomi Band / Vela constraints Read `references/vela-notes.md` when you need practical constraints and common fixes. Important defaults: - Xiaomi Band 10 uses a **212x520 跑道屏** style layout. - Frontend apps should feel **foreground-first**: quick open, quick action, quick exit. - Avoid overstuffed home screens. Prefer vertical lists/cards. - Symbol glyph buttons like `↺` `⏸` `▶` `⏭` may not render reliably on device; prefer plain Chinese text. - When in doubt, choose larger touch targets and fewer simultaneous actions. ## Build/debug loop After each meaningful edit: - Run `npx aiot build` - If needed, filter logs with grep for `success|error|Error` - Fix the reported file/line first before changing anything else Common failure classes are documented in `references/vela-notes.md`. ## Event/style rules Read `references/ux-gotchas.md` when build errors point to template/event/CSS issues. Key reminders: - Vela event handlers are strict; avoid unsupported template expression forms in `onclick` - Broken CSS blocks can produce `UxLoader` / `Unexpected }` - Prefer simple, explicit structure over clever templating ## Project template If the user asks for a fresh app, copy or adapt files from `assets/template/`. ## Deliverables Typical successful output includes: - working project folder - successful `npx aiot build` - generated `.rpk` path from `dist/` ## When to read extra files - For practical Vela constraints and prior lessons: read `references/vela-notes.md` - For template/event/style pitfalls: read `references/ux-gotchas.md` - For official documentation entry points and what to consult: read `references/docs-map.md` - For a reusable end-to-end implementation/debug loop: read `references/dev-workflow.md` - For fresh project scaffolding: inspect `assets/template/` ## Documentation-backed behavior When you need authoritative confirmation: 1. Start with `references/docs-map.md` 2. Open the matching official doc page 3. Apply the smallest viable change 4. Rebuild immediately Prefer official docs for: - component capability questions - feature API availability - project structure uncertainty - framework/lifecycle questions Prefer local reference notes for: - previously observed build pitfalls - Band 10-specific practical constraints - project patterns that already worked here

path: assets/template/package.json
content: {
  "name": "vela-app-template",
  "version": "1.0.0",
  "scripts": {
    "build": "aiot build"
  },
  "devDependencies": {
    "aiot-toolkit": "^2.0.5"
  }
}


path: assets/template/src/config-watch.json

path: assets/template/src/manifest.json
content: {
  "package": "com.example.velaapp",
  "name": "VelaApp",
  "versionName": "1.0.0",
  "versionCode": 1,
  "minPlatformVersion": 1000,
  "icon": "/common/logo.png",
  "deviceTypeList": ["watch"],
  "features": [],
  "config": { "logLevel": "log", "designWidth": "device-width" },
  "router": {
    "entry": "pages/index",
    "pages": {
      "pages/index": { "component": "index" }
    }
  }
}


path: references/dev-workflow.md
content: # Dev Workflow

## New project workflow

1. Copy the template from `assets/template/`
2. Rename package/name/page as needed
3. Add required `features` in `manifest.json`
4. Implement UI in a single page first
5. Run build early before polishing

## Existing project workflow

1. Read the current page `.ux`
2. Identify whether the app is single-page state switching or router-based multi-page
3. Make the smallest possible edit
4. Build immediately
5. Fix exact reported errors before broader refactors

## Suggested command sequence

```sh
cd <project>
npx aiot build
```

If logs are noisy:

```sh
cd <project> && npx aiot build 2>&1 | grep -E "success|error|Error"
```

## Debug order

When build fails:
1. syntax / parser errors
2. event expression errors
3. missing files / wrong paths
4. style/layout polish

## Packaging/delivery

After successful build, check `dist/` for the `.rpk` output.
Only deliver after a green build.

## Product guidance for wearables

Before adding features, ask:
- Is it useful within 3-10 seconds?
- Does it fit a narrow tall screen?
- Does it avoid needing background persistence?
- Would it feel natural on a wrist device?

If not, simplify.


path: references/docs-map.md
content: # Vela Docs Map

## Official doc entry points

- 项目结构: https://iot.mi.com/vela/quickapp/zh/guide/start/project-overview.html
- 框架总览: https://iot.mi.com/vela/quickapp/zh/guide/framework/
- 组件总览: https://iot.mi.com/vela/quickapp/zh/components/
- 接口总览: https://iot.mi.com/vela/quickapp/zh/features/
- 传感器接口: https://iot.mi.com/vela/quickapp/zh/features/system/sensor.html
- AIoT IDE / 快速开始: https://iot.mi.com/vela/quickapp/zh/guide/start/use-ide.html

## What each section is good for

### 项目结构
Use when you need to confirm required files/folders such as:
- `manifest.json`
- `app.ux`
- page `.ux`
- `common/`

### 框架总览
Use when reasoning about:
- routing
- data binding
- page lifecycle
- template/script/style structure

### 组件总览
Use when choosing UI building blocks such as:
- `div`
- `text`
- `image`
- `list`
- `input`
- `textarea`
- other native UI components

### 接口总览
Use when the app needs capabilities like:
- storage
- vibrator
- network
- battery
- brightness
- sensor

### 传感器接口
Use when the user asks about motion / pressure / sensor-triggered app ideas.
Confirmed from current work:
- Xiaomi Band 10 supports accelerometer and pressure APIs in Vela sensor docs
- Heart-rate reading is not exposed through the public Vela sensor API page we checked

## Practical search strategy

When stuck:
1. Start from the nearest official overview page above
2. Open the specific component/feature page
3. Keep project fixes minimal and rebuild immediately

## Notes from fetched docs

- Vela apps are built from `manifest.json` + page `.ux` files
- A `.ux` page typically contains `template`, `style`, and `script`
- Framework provides native components and feature APIs
- `manifest.json` declares app info, feature usage, and page routing


path: references/ux-gotchas.md
content: # UX Gotchas

## Template/event constraints

### Unsupported event pattern
This kind of expression can fail:
- `onclick="goView('" + ($item.v) + "')"`

A known error looks like:
- `Unsupported Event value: "goView('" + ($item.v) + "')"`

Prefer one of these forms instead:
1. direct function name
2. normal call expression like `funName(x, y)` if supported in context
3. simpler static handlers

When dynamic list behavior is needed, prefer index-based handlers or explicit per-item handlers over complex template concatenation.

## CSS parsing failures

A broken or orphaned CSS block may produce:
- `Error: loader error: UxLoader`
- `### Css ### Unexpected }`

Checklist:
- inspect the style block near the reported line
- look for missing selector names
- look for duplicated or stray `}`
- patch the smallest broken region first

## Build workflow

Useful commands:
- `cd <project> && npx aiot build`
- `cd <project> && npx aiot build 2>&1 | grep -E "success|error|Error"`
- `cd <project> && npx aiot build 2>&1 | grep -E "error|Error|:" | tail -20`

## Layout advice

- If a home page needs scrolling, prefer `list`
- Avoid assuming web-style scrolling containers behave the same way
- Test the simplest reliable Vela component first


path: references/vela-notes.md
content: # Vela Notes

## Confirmed environment

- Build with `aiot-toolkit` / `npx aiot build`
- Minimum required project files include:
  - `src/app.ux`
  - `src/config-watch.json`
  - `src/manifest.json`
  - page `.ux` files
- Missing `src/app.ux` or `src/config-watch.json` can trigger app-file-missing style errors

## Screen/device notes

- Xiaomi Band 10 is not round; it is a **212x520 跑道屏**
- Design for vertical space and narrow width
- Large buttons and scrollable lists are usually safer than dense dashboard layouts
- Foreground apps are more reliable than background-heavy concepts

## UI guidance

- Prefer dark background + high contrast text for wearable readability
- Home page should not cram too many options in one static block
- Use scrollable list/card layouts when there are multiple entries
- Keep one primary action per screen when possible

## Text/button caveat

- Device rendering may fail for symbolic buttons such as:
  - `↺`
  - `⏸`
  - `▶`
  - `⏭`
- Use plain text labels instead

## Practical lessons from prior work

- A single-page app with `currentView` switching is often fast to build and stable
- But when the menu gets crowded, switch to a scrollable `list`
- Browser/Figma reference lookup is more reliable through the browser tool than scraping attempts

## Sending builds

After successful build, the output package is typically under:
- `dist/<package>.debug.<version>.rpk`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)