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 §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.md §3)
(6) Inject bindings       Auto-inject .mlua property default UUIDs via b.write(path, { bind: {...} }) or b.injectBindings(...) (builder-protocol.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 is a separate explicit deletion action, not a builder mutation.

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 — read ../msw-general/references/builder-protocol.md §3 every turn before any .ui mutation (UIBuilder API, write auto-lint, pos / anchor rules, binding injection, coverage gaps). It lives in the same document as .map MapBuilder / .model ModelBuilder — a 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 UIGroup, standalone show/hide
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.

---

3. Sub-documents

• references/ui-fundamentals.md — Coordinate system, RectTransform 3 elements, anchor mode determination (§1–§8) + Resolution·safe area·PC reserved zones·touch targets·font sizes·platform separation (§9)
• references/ui-hierarchy.md — UIGroup / displayOrder / CanvasGroup / Enable vs Visible
• references/component-api.md — §"Component Selection Guide" (which/when/why) + full component property/method/event tables (what) + all UI-related enum values (§Enums)
• references/layout-recipes.md — Layout template collection
• references/runtime-patterns.md — .mlua runtime patterns (popup/toast/HP/grid/drag…) + Runtime UI Caveats
• references/ui-sound.md — UI sound integration (_SoundService:PlaySound, click/hover hook, default UI SFX RUIDs)
• ../msw-general/references/builder-protocol.md §3 — .ui CJS builder call protocol (unified entry point) — same document as .map MapBuilder / .model ModelBuilder. panel / text / sprite / button / slider / scroll / script / group / mask / grid / avatar / touchReceive / skeleton / areaParticle / basicParticle, component CRUD, anchor presets, write auto-lint, and .mlua property UUID auto-binding all live in §3 + §3.6.
• references/templates/templates.md — Pre-built style bundle index (style-N-* .ui, ruid-map.md, Popupbutton.mlua)

4. Scripts

• scripts/msw_ui_builder.cjs — .ui builder core (UIBuilder class). Read ../msw-general/references/builder-protocol.md §3 (unified entry point) before use.
• scripts/preview_ui_layout.cjs — .ui layout visual check + touch target warnings
• scripts/ui_lint.cjs — .ui file self-verification (auto-called by write())
• scripts/ui_recipe.cjs — Recipe-based scaffolding

---

Out of Scope

• .map / .model / .tileset builders — Outside this skill's scope
• .ui JSON schema (raw field shapes, @type/@components wrapping, AlignmentOption 0–15 mapping, etc.) — Handled internally by the builder. Users/AI do not need to know directly
• Accessibility patterns (alt text, screen-reader hints, focus order) — Not covered
• Error-state UI patterns (disabled-button styling beyond Transition.Disabled, validation messages, loading spinners) — Not covered; design ad-hoc per project
• Automated UI testing / layout assertions beyond ui_lint.cjs and preview_ui_layout.cjs — Not provided
• Custom shader materials (MaterialId) — Field is exposed but authoring shaders is outside this skill's scope