version: "1.0.2" name: mcbe-json-ui-ir-authoring description: Use when the user asks for layout, positioning, alignment, symmetry, equal spacing, or pixel-correct sizing of Bedrock JSON UI elements. Translates the user's intent (prompt or annotated image) into the IR YAML described in docs/41-ir-spec.md and schemas/ir.schema.json. Pairs with mcbe-json-ui-tools-runner to compile the IR into JSON UI.

MCBE JSON UI IR Authoring

Use this skill when the user's primary need is correct layout — positions, sizes, alignment, symmetry, gaps. For dynamic bindings, animations, or Script API wiring, use the knowledge layer skills (mcbe-json-ui-logic, mcbe-json-ui-hud-and-chat, etc.) instead, then patch the compiled ui.json directly.

Evidence first, skill second

Research the real evidence before applying anything written in this skill, and say which step answered:

1. The target pack itself: its _ui_defs.json, manifests, the files the request names, and the current Content Log.
2. Pinned official vanilla evidence: references/official/bedrock-samples-ui at the revision in references/official/bedrock-samples-ui.lock.json, node tools/vanilla-name-check.mjs <name> for any control, #binding, $variable, button id, renderer or screen file, the full local mirror under references/upstreams/bedrock-samples when present, and docs/83-vanilla-ui-1.26.50-diff.md for names that moved or disappeared.
3. Registered upstream sources and their cards: node tools/design-library.mjs sources --source ID and node tools/design-library.mjs patterns --source ID for the official docs, Wiki snapshots, schemas and sample addons pinned in config/design-research-lock.json (commit-pinned raw URLs for every file), then the repository docs/.
4. Only when steps 1–3 do not answer: this skill's own references. Label such guidance "inferred from skill guidance", never "confirmed".

A name, offset, selector or rule found in steps 1–3 overrides this skill. Older third-party references and example packs stay valid pattern evidence; do not delete or rewrite them because a vanilla name moved. Without this repository checkout, follow the same order with the official samples and docs you can reach and report which steps were unavailable.

Contract

• Input: target profile, root bounds, element roles, visual evidence or recipe IDs, and explicit layout intent.
• Output: workspace/<screen>/ir.yaml, declared constraints, assumptions, and the next non-geometry handoff.
• Success: the IR validates, all visible relationships are constrained, solved geometry is stable, and unresolved dynamic values remain outside the solver.

If data/skill-tool-profiles.json exists, read only the mcbe-json-ui-ir-authoring entry. Confirm referenced tools exist before invocation; if the catalog or prompt helpers are unavailable, author from verified repository schemas and record that limitation.

For new UI planning where the user has not supplied a complete spec, read docs/52-json-ui-intake-questionnaire.md first, then translate the chosen layout constraints into IR.

When to choose IR vs raw JSON

If unsure, ask the user one short question.

Workflow

1. Identify the target screen name (snake_case).
2. Decompose the requested layout into elements (panel/image/label/button/stack_h/stack_v/grid/collection_grid or collection_panel/scroll).
3. Choose base_resolution (default [1920, 1080]) and gui_scale (default 3).
4. For root and each element, declare px-only pos and size. If the final Bedrock JSON must use %/%c/fill, solve with equivalent pixels first and add those dynamic units during the hand-finish JSON patch.

• For labels whose size depends on visible text, use auto_size.mode: text.
• For images with one unknown axis, use auto_size.mode: image_aspect.
• For server-form/HUD repeated data grids, use kind: collection_grid with collection.dimensions, collection.item_size, and auto_size.mode: collection_grid.

1. Add constraints for every intent the user expressed or that is visually obvious:

• left/right or top/bottom pair → symmetric_x / symmetric_y
• row/column of repeating items → same_size + equal_gap_x / equal_gap_y
• centered row/cluster → center_group_x / center_group_y after equal-gap and same-size constraints
• any "aligned with" intent → align_x / align_y
• exact edge match → edge_eq
• exact offset between edges → edge_offset with delta

1. Save as workspace/<screen>/ir.yaml.
2. Hand off to mcbe-json-ui-tools-runner (or directly call node tools/run.mjs).

Hard rules

• Pixels in IR. Never put %, %c, %cm, fill, or default into solver-stage size values; add dynamic Bedrock units only after solved.json is stable.
• Every visible pair/row/group with implied symmetry or alignment must declare a constraint. Do not rely on hand-tuned pos values.
• Every centered row or card cluster must declare center_group_x or center_group_y; do not eyeball the group's first pos.
• For server form button grids, HUD lists, score rows, and item slots, model the repeated area as collection_grid first, then hand-finish the item template and bindings.
• Constraint ids must reference existing elements. No floating ids.
• Do not edit the compiled ui.json to fix layout. Edit ir.yaml and recompile.
• Bindings, animations, and Script API are out of scope for IR. Add them to the compiled ui.json afterward as a separate patch.
• The solved layout from solved.json or compiled ui.json is the geometry source of truth. Do not reinterpret or approximate positions/sizes during the hand-finish phase.
• Treat report.json geometry warnings as layout failures unless the IR intentionally defines a clipped viewport.

Output expectations

Hand back:

• the path to workspace/<screen>/ir.yaml
• a one-paragraph explanation of which constraints were declared and why
• a note on which knowledge-layer skill should run next if bindings/animation are also needed

References

• references/intent-to-constraint.md
• docs/41-ir-spec.md
• schemas/ir.schema.json