AIUI Agent Developer Guide

This guide provides independent and comprehensive context for AI agents developing AIUI applications. It includes project structure, SFC .ink support specifications, and standard API references, designed to help Large Language Models (LLMs) generate accurate AIUI pages and logic code.

1. Project Structure

A standard AIUI application project typically contains the following core files:

• AGENTS.md: The agent manifest, defining the agent's identity and capabilities.
• app.json: Global configuration, including page routes, window settings, etc.
• app.js: Application lifecycle and global logic.
• pages/: Page directory containing the application's pages, primarily using the Single File Component (SFC) .ink format.
• assets/: Directory for storing static resources like images and audio.

1.1 Agent Manifest (AGENTS.md)

The manifest file defines the agent's basic information and required permissions/skills:

# Agent Manifest

## Identity
- **Name**: My AIUI Agent
- **Version**: 1.0.0
- **Description**: A brief application description.
- **Author**: Developer Name

## Capabilities
- **Permissions**:
  - camera
  - microphone
  - network
  - audio
- **Skills**:
  - weather-lookup

1.2 Global Configuration (app.json)

Defines application page paths and global UI styles:

{
  "pages": [
    "pages/index/index"
  ],
  "window": {
    "navigationBarTitleText": "My AIUI Agent",
    "viewport": {
      "width": "device-width"
    }
  }
}

1.3 Application Registration (app.js)

AIUI uses an ES module-based registration system, registering the application by exporting a default configuration object:

export default {
  onLaunch() {
    console.log('App Launch');
  },
  globalData: {
    userInfo: null
  }
};

1.4 Page Configuration (page.json)

In AIUI, each page acts as a Model Context Protocol (MCP) UI component. The configuration for each page is defined in its respective page.json (or within the <script def> block of an .ink file). This configuration declares the page's capabilities and the expected input parameters for rendering.

Key fields in page configuration:

• description: A clear, natural language description of what the page UI represents or what task it accomplishes. This helps the AI or system understand the page's purpose.
• schema: Defines the expected input data structure for rendering the UI.
• data: A JSON Schema object specifying the properties, types, and required fields needed to populate the page's initial state.

Example Page Configuration:

{
  "navigationBarTitleText": "Weather Card",
  "description": "A UI component that displays the current weather conditions for a specific city.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The name of the city"
        },
        "temperature": {
          "type": "number",
          "description": "Current temperature in Celsius"
        },
        "condition": {
          "type": "string",
          "enum": ["sunny", "rainy", "cloudy", "snowy"]
        }
      },
      "required": ["city", "temperature", "condition"]
    }
  }
}

2. Single File Component (SFC) .ink Specification

In AIUI, page development is recommended to use the Single File Component (SFC) format, which is the .ink file. This format centralizes the page's configuration, logic, structure, and style in a single file.

A standard .ink file structure contains four main tag blocks:

1. <script def>: Used to define page-level JSON configuration, such as the navigation bar title.
2. <script setup>: Contains the page's JavaScript logic code, exporting the page configuration object (including data, lifecycle hooks, custom methods, etc.) via export default.
3. <page>: The page's template structure (WXML-like syntax).
4. <style>: The page's stylesheet (CSS).

2.1 .ink Example Code:

<script def>
{
  "navigationBarTitleText": "Home"
}
</script>

<script setup>
import wx from 'wx';

export default {
  data: {
    greeting: 'Hello AIUI!'
  },
  onLoad() {
    console.log('Page loaded');
  },
  handleTap() {
    this.setData({
      greeting: 'Hello, World!'
    });
  }
}
</script>

<page>
  <view class="container">
    <text class="title">{{ greeting }}</text>
    <button bindtap="handleTap">Click Me</button>
  </view>
</page>

<style>
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
}

.title {
  font-size: 24px;
  margin-bottom: 20px;
}
</style>

3. WXML (WeiXin Markup Language) & Components

In AIUI, the structure of a page is described using WXML (WeiXin Markup Language), which is used within the <page> tag of an .ink file (or a standalone .wxml file). It allows you to build user interfaces using components, data binding, and conditional rendering.

3.1 Basic Syntax and Data Binding

WXML uses double curly braces {{ }} for data binding. You can bind properties from your page's data object directly to the UI.

<!-- Text binding -->
<view>{{ message }}</view>

<!-- Attribute binding -->
<view class="{{ dynamicClass }}"></view>

<!-- Expression binding -->
<view>{{ count + 1 }}</view>

3.2 Directives (Conditional Rendering and Lists)

AIUI supports conditional rendering using the ink:if, ink:elif, and ink:else directives to control whether a component is rendered based on a condition.

<view ink:if="{{condition === 1}}"> Rendered if condition is 1 </view>
<view ink:elif="{{condition === 2}}"> Rendered if condition is 2 </view>
<view ink:else> Rendered otherwise </view>

AIUI supports basic list rendering with ink:for, allowing you to repeat a component structure for each item in an array.

<view ink:for="{{cities}}" ink:key="name">
  <text>{{item.name}}</text>
  <text>{{item.temperature}}</text>
</view>

Use item to access the current element and index to access its position in the array. Prefer providing a stable ink:key when rendering dynamic collections.

> Current Limitation: Nested ink:for is not supported yet. Keep list rendering to a single level, and flatten data in JavaScript first when you need to present hierarchical content.

3.3 Built-in Components

AIUI provides a set of built-in components that you can use within your WXML templates. These components are mapped to native implementations for optimal performance.

For parameter-by-parameter documentation, event behavior, content model notes, and examples, see components.md. The reference there is intentionally aligned with the current component registry and implementation details in ink-builtin-components.

For runtime API details, constructor behavior, supported overloads, and current implementation limits, see apis.md. Use the linked domain reference files there when you need Canvas, wx, device, media, or AI-specific details.

• <view>: The fundamental layout container, similar to <div> in HTML.
• <text>: Displays text content. Similar to <span> in HTML.
• <icon>: An icon-like text element currently rendered through the text component implementation.
• <image>: Displays local or remote images.
• <button>: A standard clickable button component.
• <canvas>: A component for custom 2D drawing.
• <scroll-view>: A scrollable container for content that exceeds the visible area.
• <chart>: A chart component supporting Line, Area, Pie, and Radar charts.
• <lottie-view>: Renders Lottie animations from inline JSON, local files, or remote URLs.
• <a2ui>: A specialized component for rendering agent-generated UI commands dynamically.
• <error-state>: A compact status component that displays an optional icon with a message.

4. Events

AIUI supports event handling at different levels. Component interaction events are declared in WXML attributes such as bindtap, catchtap, bindinput, and bindchange. Page-level events are defined as methods on the exported page object.

4.1 Page-Level Events

If a page needs to react to framework-delivered hardware key input, define onKeyDown(event) and onKeyUp(event) on the exported page object.

These handlers are page methods, not WXML binding attributes. Put the logic on the page instance and update page state with this.setData(...) when needed.

<script setup>
export default {
  data: {
    lastKeyAction: 'None'
  },
  onKeyDown(event) {
    console.log('Key down:', event);
    this.setData({
      lastKeyAction: 'Key pressed'
    });
  },
  onKeyUp(event) {
    console.log('Key up:', event);
    this.setData({
      lastKeyAction: 'Key released'
    });
  }
}
</script>

<page>
  <view class="container">
    <text>Last key action: {{ lastKeyAction }}</text>
  </view>
</page>

Use this pattern when keyboard input should be handled by the page itself, such as shortcuts, directional navigation, or confirming actions from a hardware key.

5. WXSS (WeiXin Style Sheets)

WXSS is a style language used to describe the visual presentation of components. It is highly compatible with standard CSS and is used within the <style> block of an .ink file (or a standalone .wxss file).

5.1 Features

WXSS extends standard CSS with features tailored for mobile and wearable devices:

• @import: You can use the @import statement to import external style sheets.

@import "./common.wxss";

.box {
  width: 240px;
  height: 100px;
  background-color: #40FF5E;
}

5.2 Selectors

AIUI supports most standard CSS selectors:

• Class Selector (.class): The recommended way to style components.
• ID Selector (#id).
• Type Selector (element): e.g., view, text.
• Combinators: Grouping (A, B), Descendant (A B), Child (A > B).

Recommendation: Prioritize using Class Selectors to ensure optimal rendering performance.

5.3 Layout

AIUI supports both Flexbox and Grid layout through the Ink CSS engine.

• Flexbox is the primary and recommended choice for most one-dimensional layouts such as vertical stacks, horizontal toolbars, centered content, and card internals.
• Grid is supported for two-dimensional layouts where rows and columns need to be controlled together.

Supported Flexbox properties include:

• display: flex
• flex-direction
• flex-wrap
• justify-content
• align-items
• flex-grow
• flex-shrink
• flex-basis
• gap, row-gap, column-gap

Supported Grid properties include:

• display: grid
• grid-template-columns
• grid-template-rows
• grid-auto-columns
• grid-auto-rows
• grid-auto-flow
• grid-column, grid-column-start, grid-column-end
• grid-row, grid-row-start, grid-row-end
• grid-area
• align-content
• justify-items
• align-self
• justify-self
• gap, row-gap, column-gap

Prefer Flexbox when either layout model can work. Use Grid when the UI clearly benefits from explicit row and column placement.

.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12px;
}

.dashboard {
  display: grid;
  grid-template-columns: 1fr 1fr;
  grid-template-rows: auto auto;
  gap: 12px;
}

5.4 Styling

AIUI supports a practical subset of CSS properties for visual styling. When generating styles, stay within the properties that are known to be supported by the Ink CSS engine.

Commonly supported styling properties include:

• Box model and sizing: width, height, min-width, min-height, max-width, max-height, margin, padding, box-sizing
• Positioning and overflow: position, inset, overflow, overflow-x, overflow-y, z-index
• Colors and backgrounds: color, background-color, custom properties, and var(--token) references
• Borders and outlines: border, border-width, border-style, border-color, border-radius, outline, outline-width, outline-style, outline-color, outline-offset
• Typography: font-size, line-height, font-weight, font-family, font-style, font-variant, text-align, white-space, word-break
• Effects and visibility: opacity, visibility, box-shadow, filter, transform, transform-origin
• Motion: transition, transition-property, transition-duration, transition-timing-function, transition-delay, animation, animation-name, animation-duration, animation-timing-function, animation-delay, animation-iteration-count, animation-direction, animation-fill-mode

Prefer simple, production-safe CSS. Do not assume browser-only features or unsupported CSS shorthands beyond what AIUI and Ink CSS explicitly support.

When styling AIUI interfaces:

• Prefer AIUI's built-in theme tokens instead of hardcoding colors, spacing, border widths, or radii
• Reference theme values with var(--token-name)
• Keep custom properties semantically named when introducing new local tokens

Built-in green theme token reference:

5.5 Fonts

AIUI applications can use both system fonts provided by the host platform and bundled custom fonts declared in app.json.

System fonts

For common cases, reference a system font directly in font-family or in a canvas 2D font string:

<text style="font-family: Arial, sans-serif; font-size: 18px;">
  System font example
</text>

const ctx = wx.createCanvasContext('myCanvas');
ctx.font = '18px Arial';
ctx.fillText('Canvas system font example', 12, 40);

Recommendations:

• Prefer a fallback chain such as Arial, sans-serif instead of a single family.
• Do not assume every platform ships the same system fonts.
• Test the final visual result on the actual target host.

Bundled custom fonts

If the UI requires a specific typeface, declare it in app.json under fonts. The runtime bundles the font files with the app and lets both text rendering and canvas rendering reuse the same family name.

{
  "pages": [
    "pages/index/index"
  ],
  "fonts": [
    {
      "family": "Bundled Serif",
      "src": "assets/fonts/NotoSerif-Regular.ttf",
      "weight": 400,
      "style": "normal"
    },
    {
      "family": "Bundled Serif",
      "src": "assets/fonts/NotoSerif-BoldItalic.ttf",
      "weight": 700,
      "style": "italic"
    }
  ]
}

After declaration, reference the family name exactly as declared:

<text style="font-family: 'Bundled Serif', serif; font-size: 20px;">
  Bundled font example
</text>

const ctx = wx.createCanvasContext('myCanvas');
ctx.font = 'italic 700 24px "Bundled Serif"';
ctx.fillText('Canvas uses bundled fonts', 12, 40);

ctx.font = '24px "Bundled Serif"';
ctx.fillText('Missing glyphs still fall back to system fonts', 12, 80);

Bundled font notes:

• font-family and canvas font share the same bundled family name.
• When multiple weights or styles are declared for one family, the nearest matching face is selected automatically.
• If a bundled resource is missing or cannot be parsed, the app falls back to system fonts.
• Store bundled font files under app-owned assets such as assets/fonts/ so they can be packaged with the app.
• Prefer a generic fallback family such as serif or sans-serif after the bundled family name.

When generating AIUI code:

• Use app.json fonts only when the UI explicitly needs a non-system typeface.
• Keep family names consistent between app.json, WXSS, inline style, and canvas font strings.
• Do not assume web font loading patterns such as remote @font-face URLs.

6. Design Guidelines

When developing AIUI applications, especially for wearable devices, it is crucial to follow these design guidelines to ensure a consistent and user-friendly experience.

6.1 Dimensions and Layout

• Width: The application width is strictly 480px.
• Height: The recommended application height is between 120px and 380px. Avoid creating overly tall pages that require excessive scrolling.
• Card Style: It is highly recommended to use a Card Style layout for each page. This provides a clear boundary and better visual focus in the spatial environment.
• Default Background: Use black as the default background color.
• Default Border: Use a 2px border as the default border width for cards and key interactive elements.
• Border Radius: The recommended border radius (e.g., for cards, buttons, and images) is 12px.

6.2 Color Palette

• Theme First: Prefer AIUI's built-in theme tokens as the public styling interface.
• Token Usage: Use var(--color-primary), var(--color-text-primary), var(--color-background), var(--spacing-md), var(--radius-md), and related semantic tokens before introducing hardcoded values.
• Green Theme Reference: If you intentionally target the green wearable visual language, prefer the built-in green theme tokens instead of hardcoding #40FF5E, rgba(64, 255, 94, 0.6), or rgba(64, 255, 94, 0.4) directly.
• Default Text Color: Prefer semantic text tokens such as var(--color-text-primary) or var(--color-text-secondary) unless a specific component token is more appropriate.

6.3 Prohibitions

• DO NOT use emoji in generated UI copy, labels, status text, or decorative content by default. Emoji may only be used when the developer explicitly requests them or the product requirements clearly require them.
• DO NOT use large areas of solid color blocks. This can be visually overwhelming and uncomfortable on wearable displays. Keep backgrounds subtle and use colors primarily for accents, text, and interactive elements.

7. AIUI API Reference

The detailed runtime API index lives in apis.md. It links to domain-specific reference files for Canvas, wx, device, media, and AI APIs.

When generating code:

• Treat apis.md and its linked domain reference files as the source of truth for currently supported API shapes and behaviors.
• Follow the implementation-aligned definitions there instead of assuming standard Web API compatibility.
• Do not infer unlisted overloads, return shapes, or browser semantics.

8. Usage Examples (WeChat APIs)

Take a Photo with Camera

import wx from 'wx';

const camera = wx.media.createCameraContext();
const photo = await camera.takePhoto({ quality: 'high' });
console.log('Image data size:', photo.data.byteLength);

Crypto & UUID Generation

const uuid = crypto.randomUUID();
const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode('hello AIUI'));