# Iwsdk UI Panel

> Create, place, preview, debug, and connect manifest-backed IWSDK UIKitML assets. Use for spatial panels, browser HUDs, UIKitML layout, fonts, editor previews, or runtime element behavior.

- Skill: `facebook/iwsdk-ui-panel` (Agent Skill)
- Install (CLI): `npx skillmds@latest add facebook/iwsdk-ui-panel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/facebook/iwsdk-ui-panel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: facebook (https://skillmd.com/u/facebook)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/facebook/iwsdk-ui-panel

---


# IWSDK UIKitML Asset Workflow

Treat UIKitML as a first-class renderable asset. Use the managed editor's isolated
renderer for layout, the scene editor for placement, and the application runtime for
behavior. Do not change the scene, camera, or component model merely to inspect a
panel.

## 1. Find the three stable identities

Every scene-authored panel has three different identities:

1. the manifest asset ID, which names the reusable UIKitML definition;
2. the scene node ID, which names one placed instance;
3. element `id` attributes, which name fields and controls inside the document.

Find or add the manifest entry in `src/assets.ts` and keep the source under
`public/ui/`:

```ts
import { AssetType, type AssetManifest } from '@iwsdk/core';

const assets = {
  'welcome-panel': {
    name: 'Welcome panel',
    type: AssetType.UIKitML,
    url: '/ui/welcome.uikitml',
  },
} satisfies AssetManifest;

export default assets;
```

A file under `public/ui/` is not placeable until it is registered. The `.uikitml`
file is the runtime source of truth; never generate an intermediate JSON file.

## 2. Reuse the managed editor

Run commands from the application directory. Reuse a command-ready session instead
of starting a second server or browser:

```bash
npx iwsdk dev status
npx iwsdk dev up --timeout 60000
npx iwsdk ui assets --raw
```

`dev up` owns the managed headed browser. Do not launch a second Playwright browser,
enable Vite's independent opener, or implement a custom UIKit renderer.

## 3. Render the panel in isolation

Use the editor-backed isolated renderer before debugging scene placement:

```bash
npx iwsdk ui render-preview \
  --input-json '{"assetId":"welcome-panel","width":800,"height":600}' \
  --output-file artifacts/welcome-panel.png
```

This renders the real manifest entry through the real UIKitML parser, fonts, layout,
and WebGL path on a neutral background. It waits for UIKit render and resource
signals; do not add fixed frame delays. Re-run the command after every layout change.
Same-URL sources are reloaded without restarting the server.

## 4. Place and inspect it in the scene editor

For a human-authored placement, open the scene and add the UIKitML asset from the
asset drawer. For file authoring, use the same asset-only node contract:

```json
{
  "id": "welcome-panel-instance",
  "name": "Welcome panel",
  "content": { "type": "asset", "asset": "welcome-panel" },
  "transform": {
    "position": [0, 1.4, -1.5],
    "rotationDeg": [0, 180, 0],
    "scale": 0.5
  }
}
```

```bash
npx iwsdk scene render-file \
  --input-json '{"path":"public/scenes/main.iwsdk.scene.json","view":"quarter"}' \
  --output-file artifacts/main-editor.png
npx iwsdk scene open \
  --input-json '{"path":"public/scenes/main.iwsdk.scene.json"}' --raw
```

UIKitML surfaces are single-sided. If the isolated preview works but the placed panel
is invisible, inspect its rotation first. Size a world-space panel with its ordinary
entity transform scale. There is no `maxWidth`/`maxHeight` fitting layer and no
editor-visible `PanelUI` component to configure.

Use `scene screenshot` for editor/scene evidence. `browser screenshot` is intentionally
runtime-only and switches the managed workspace to runtime before capturing.

## 5. Edit UIKitML

UIKitML is HTML/CSS-shaped, but it is not a browser engine. Confirm supported elements
and properties from the installed IWSDK reference before assuming browser behavior.

Key rules:

- numeric UIKit sizes are centimeters (`100` = 100 cm = 1 m);
- use stable `id` attributes for elements application code must manipulate;
- prefer explicit supported declarations over CSS shorthand;
- parser errors include source locations;
- relative and remote font URLs are supported, but font completion can change layout;
- the managed preview settles from UIKit render/font/texture signals, so inspect logs
  instead of compensating with arbitrary waits.

After each edit:

1. rerender with `ui render-preview` and inspect the image;
2. rerender the scene when placement or scale matters;
3. inspect `browser logs` for parser, font, texture, or runtime failures.

## 6. Connect runtime behavior

For a code-owned instance, keep the `UIKitMLAsset` returned by the asset manager:

```ts
import { UIKit, UIKitMLAsset } from '@iwsdk/core';

const panel = await world.assets.instantiate<UIKitMLAsset>('welcome-panel');
const entity = world.createTransformEntity(panel);
const button = panel.requireElementById<UIKit.Text>('xr-button');
button.addEventListener('click', () => world.launchXR());
```

For a scene-authored instance, resolve it by stable scene node ID after the level has
loaded:

```ts
const panel = world.requireSceneObject<UIKitMLAsset>('welcome-panel-instance');
const button = panel.requireElementById<UIKit.Text>('xr-button');
button.setProperties({ text: 'Enter XR' });
```

Do not locate a panel by transient ECS index, manifest URL, or a scan for an internal
`PanelDocument`. Use the scene node ID and element IDs.

## ScreenSpace is product behavior

Add `ScreenSpace` only when the experience genuinely needs a browser-camera HUD:

```ts
entity.addComponent(ScreenSpace, {
  width: '420px',
  height: '240px',
  top: '20px',
  right: '20px',
  zOffset: 0.2,
});
```

Position and size values are CSS strings. In immersive mode the document returns to
its authored world transform. Do not add `ScreenSpace`, a backdrop, or a temporary
camera pose merely to make a panel easier to inspect—the editor already provides the
correct isolated and in-scene render paths.

For immersive XR, default to a world-space panel or attach contextual UI to the
object it controls. Use a thresholded `Follower` targeting `world.player.head`
only when compact global UI must remain discoverable. Do not head-lock menus,
reading surfaces, or persistent panels; reserve direct `world.playerHeadEntity`
parenting for tiny, transient, non-interactive markers that require exact view
alignment. Do not use `ScreenSpace` expecting it to remain camera-attached in
XR. See `docs/concepts/spatial-ui/hud.md` for the placement guidance.

## Completion checklist

- Manifest ID resolves and `ui assets` lists it.
- Isolated preview is nonblank, correctly laid out, and uses the intended fonts.
- Scene preview has correct facing, transform scale, and lighting-independent color.
- Runtime behavior resolves the placed node and required element IDs.
- Browser logs contain no UIKitML parser, resource, or font errors.
- No generated UI JSON, temporary ScreenSpace component, backdrop, or camera hack
  remains.