Frequently Asked Questions
This page collects common questions that come up while developing with AIUI. Before you begin, read the Quick Start. For questions about a specific capability, also check the relevant component or API documentation.
Where Should I Start Learning AIUI?
If you are new to AIUI, follow this path:
- Read the Introduction to understand where AIUI fits.
- Complete the Quick Start to learn the development, debugging, and publishing workflow.
- Choose AIUI in Chat or Immersive AIUI based on your product experience.
- Read Project Structure to understand how project files are organized.
What Is the Difference Between AIUI in Chat and Immersive AIUI?
AIUI in Chat is designed for lightweight, context-aware interactions inside a conversation. Immersive AIUI is designed for tasks that need a standalone page, sustained interaction, or a richer visual layout. An agent can use both, depending on how much interaction a task requires.
Where Can I Find Component and API Usage?
- For UI elements and their properties, see Components.
- For JavaScript, device, network, media, and AI capabilities, see the API documentation.
- For agent organization and runtime behavior, see Agent Framework and Agent Runtime.
How Should I Troubleshoot Runtime or Display Issues?
First confirm that the project structure and related API usage match the current documentation. Then use Web Simulation Debugging to check logic and UI quickly. For device capabilities, platform differences, or issues that depend on the real runtime environment, continue with Real-Device Debugging.
How Do I Package and Publish an Agent?
Start with the AIX format, then follow Submit for Review and Publish. To work with packages locally, see the CLI guide.
Do Full-Color Glasses Require a Separate Agent?
Full-color adaptation alone does not require a separate agent. Prefer shared business logic, Pages, Widgets, and data services in one project and one AIX. Adapt palettes and assets to display capabilities, and layouts to available space. Consider splitting agents when product positioning or core functionality needs to be independent. See the Full-Color Glasses Adaptation Guide.
Which Device Do the Full-Color Guidelines Cover?
The current guidelines cover Rokid Color, whose Chinese name is 乐奇全彩眼镜. Both names refer to the same device. Its full-color content area has a width of 448 and maximum height of 352; monochrome content also has a maximum height of 352. Continue using Monochrome for the single-green displays of RokidGlasses1 / RokidGlasses2. Verify device APIs and interactions separately; full-color support does not imply identical hardware capabilities.
Is Changing Colors Enough for Full-Color Adaptation?
Also check content space, text and icon sizes, padding, margins, focus states, and assets. Full-color text uses 14–24 dp and icons must be at least 12 × 12. Smaller monochrome text, large fills, and long page layouts need adaptation. The built-in theme supplies defaults but does not automatically correct custom layouts, images, or Canvas content. See the Full-Color Visual Guidelines for exact values.
How Do I Detect Color or Monochrome Output?
On supported runtimes, use @media (color) / @media (monochrome) in styles and window.matchMedia() in page logic. Do not substitute device names, screen width, or target for capability detection. Keep an unknown state when neither query matches instead of assuming monochrome. Retain a base presentation for older runtimes. See the Full-Color Glasses Adaptation Guide for examples.
Why Are Black Backgrounds, Dark Text, or Translucent Content Hard to See?
Pure black appears transparent on the glasses and cannot block the real world. Dark colors are also unsuitable for essential content. Prefer white body text and clear bright colors, keep visible content at the recommended minimum alpha of 40%, and avoid compounding whole-card opacity. The outermost card has no border. Internal cards use a 1px white outline at 30% alpha by default and 100% when selected or focused. These 30% card borders are exempt from the recommended 40% foreground minimum; dividers remain 1px at 40% alpha. Verify against different real backgrounds and lighting conditions. See the Full-Color Optimization Guide.
What If Content Exceeds a Height of 352 or Switches to an Immersive Container?
Prefer summaries with details, pagination, or an operable scroll region, keeping essential actions accessible. _blank changes the presentation container; it does not remove the full-color content constraints of width 448 and maximum height 352. Do not solve overflow by shrinking text, reducing required spacing, or clipping content. Verify reading, scrolling, focus, and the back path on the glasses.