Msw UI System

msw-ui-system

MSW .ui single entry point — design guide + component API + builder invocation + runtime patterns bundled into one skill.

Role division with existing skills:

0. Routing

Branch to sub-references based on request keywords.

1. Basic Workflow

(1) Clarify intent       Layout sketch (ASCII or verbal) + which group to attach to
(2) Check design guide   Match at least one of ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide
(3) Builder Preflight    Read ../msw-general/references/builder-protocol.md (core) + builder-protocol-ui.md §3 (unified call-protocol entry point)
(4) Match recipe          Select the closest template from layout-recipes.md
(5) Invoke builder        Create/patch via scripts/msw_ui_builder.cjs (protocol: builder-protocol-ui.md §3)
(6) Inject bindings       Auto-inject .mlua property default UUIDs via b.write(path, { bind: {...} }) or b.injectBindings(...) (builder-protocol-ui.md §3.6 Binding Injection)
(7) Self-verify           write() auto-runs scripts/ui_lint.cjs (strict ON by default)
(8) Preview               Visual check via scripts/preview_ui_layout.cjs
(9) Sound pass            For any interactive button, offer click/hover SFX wiring (references/ui-sound.md)
(10) Maker Refresh         Apply to engine

2. Global Rules

NEVER

1. Do not directly edit `.ui` JSON — .ui creation/modification must go through scripts/msw_ui_builder.cjs. Manual editing breaks UUID·ValueType·@components consistency and causes silent drops.
2. Read existing `.ui` files through the builder too — Query via UIBuilder.read(filepath) / .find() / .listEntities(). Do not directly grep/parse raw JSON.

• .ui direct Read and shell commands such as cat / type / Get-Content / rg / grep / sed / awk / cp / mv are blocked by the registered guard. Use UIBuilder.read/load/snapshot for reads and b.write() for writes. Deleting an entire .ui file has no builder API — delete it with node -e "require('fs').unlinkSync('ui/<File>.ui')" then refresh (shell rm/cat are guard-blocked; a node -e builder call is not).

1. Set Position directly — Use only anchoredPosition (Position is engine-managed)
2. Express size via OffsetMin/Max on fixed anchors (AnchorsMin == AnchorsMax) while also using anchoredPosition — Do not mix the two modes
3. Builder creates new UUIDs but .mlua property defaults are not updated — Binding breaks

ALWAYS

1. Builder Protocol Preflight — [`../msw-general/references/builder-protocol.md`](../msw-general/references/builder-protocol.md) (core) + [`../msw-general/references/builder-protocol-ui.md`](../msw-general/references/builder-protocol-ui.md) §3 must be in context before any `.ui` mutation (read them only if never loaded this session or lost to compaction) (UIBuilder API, write auto-lint, pos / anchor rules, binding injection, coverage gaps). The core carries the shared contract and cross-builder flow; .map MapBuilder / .model ModelBuilder live in sibling per-builder files — one unified entry point because the cross-flow is interlocked.
2. Check at least one design guide before invoking the builder (ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide)
3. Match a recipe first; build from scratch only as a last resort
4. For edge placement use the formula: pos = ±(margin + size/2)
5. Separate popups and toasts into their own `.ui` root UIGroup, standalone show/hide; use empty() / panel() for inner containers, never nested group()
6. Verify text Alignment default is UpperLeft(0) — 95% of "I centered it but it sticks to the left" issues
7. Button touch target ≥ 88×88 (mobile support)
8. After creating any interactive button — proactively suggest wiring click/hover SFX via `references/ui-sound.md` (default UI SFX RUIDs available). Skip only if the user explicitly opts out or the button is purely decorative.
9. Build the tree nested, not flat. Controls of one unit (window + title/close, row + chip/value, slot + icon/count) must share a parent via "Parent/Child" paths so they move / fade / toggle / bind as a block. Create each parent before its children; missing parents fail lint (L025 ERROR).
10. Do not stack root-level text over a sibling box. ui_lint reports this as L030 WARN. Nest the text under the box, use button() for clickable labeled boxes, or put a direct label on panel() / sprite() via their text options.

3. Sub-documents