msw-ui-system

SKILL.md

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:

Skill
Responsibility

msw-ui-system (this skill)
Everything .ui — design (which/when/why), component API/enum (what), builder invocation (how to mutate), runtime mlua patterns. .ui mutations must always go through this skill's builder

references/templates/
Pre-built style bundles — .ui + ruid-map + button handler packages

0. Routing

Branch to sub-references based on request keywords.

Trigger
Reference Document

"anchor/pivot/coordinates/why is the position wrong", "RectTransform", "stretch"
references/ui-fundamentals.md §1–§8

"mobile", "safe area", "1920", "MobileOnly", "ActivePlatform", "touch size", "PC reserved zone", "font size by device"
references/ui-fundamentals.md §9

"UIGroup", "above popup", "z-order", "displayOrder", "CanvasGroup", "opacity propagation", "Enable vs Visible"
references/ui-hierarchy.md; for runtime sibling reorder also read references/runtime-patterns.md §7

"which component", "Sprite vs Text vs Button", "9-slice", "scroll list", "GridView vs ScrollLayoutGroup"
references/component-api.md §"Component Selection Guide"

"make a HUD", "popup placement", "toast", "menu", "inventory grid", "scroll list"
references/layout-recipes.md

"connect .mlua after building with .ui builder", "property default UUID", "binding without drag"
../msw-general/references/builder-protocol.md §3.6 Binding Injection (unified entry point)

Runtime UI component field read/write, component property name/type (ButtonComponent.Colors, TextComponent.Overflow, SpriteGUIRendererComponent.FillAmount…)
references/component-api.md required before every .mlua access to UI component fields

Enum values (AlignmentType, OverflowType, ImageType, UIBasicParticleType…)
references/component-api.md §Enums

Runtime mlua patterns (popup open/close, toast fade, HP bar, GridView, drag, tab, cooldown), Runtime UI Caveats (client-only, server-side nil, etc.)
references/runtime-patterns.md

.ui builder invocation methods (UIBuilder API, anchor presets, write auto-lint, component add/patch/remove)
../msw-general/references/builder-protocol.md §3 UIBuilder (unified entry point — same document as .map MapBuilder / .model ModelBuilder)

"sound", "sfx", "click sound", "hover sound", "button audio", "PlaySound"
references/ui-sound.md

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

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.

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.

Set Position directly — Use only anchoredPosition (Position is engine-managed)

Express size via OffsetMin/Max on fixed anchors (AnchorsMin == AnchorsMax) while also using anchoredPosition — Do not mix the two modes

Builder creates new UUIDs but .mlua property defaults are not updated — Binding breaks

ALWAYS

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.

Check at least one design guide before invoking the builder (ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide)

Match a recipe first; build from scratch only as a last resort

For edge placement use the formula: pos = ±(margin + size/2)

Separate popups and toasts into their own UIGroup, standalone show/hide

Verify text Alignment default is UpperLeft(0) — 95% of "I centered it but it sticks to the left" issues

Button touch target ≥ 88×88 (mobile support)

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