msw-ui-system

.ui

msw-ui-system

.ui

.ui

references/templates/

.ui

0. Routing

references/ui-fundamentals.md

references/ui-fundamentals.md

references/ui-hierarchy.md

references/runtime-patterns.md

references/component-api.md

references/layout-recipes.md

references/builder-protocol.md

ButtonComponent.Colors

TextComponent.Overflow

SpriteGUIRendererComponent.FillAmount

references/component-api.md

.mlua

AlignmentType

OverflowType

ImageType

UIBasicParticleType

references/component-api.md

references/runtime-patterns.md

.ui

references/builder-protocol.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) Match recipe          Select the closest template from layout-recipes.md
(4) Invoke builder        Create/patch via scripts/msw_ui_builder.cjs (protocol: builder-protocol.md)
(5) Inject bindings       Auto-inject .mlua property default UUIDs via b.write(path, { bind: {...} }) or b.inject_bindings(...) (builder-protocol.md §"Binding Injection")
(6) Self-verify           write() auto-runs scripts/ui_lint.cjs (strict ON by default)
(7) Preview               Visual check via scripts/preview_ui_layout.cjs
(8) 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()

   /

   .list_entities()

   . 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.
3. Set

   Position

   directly — Use only

   anchoredPosition

   (Position is engine-managed)
4. Express size via OffsetMin/Max on fixed anchors (AnchorsMin == AnchorsMax) while also using

   anchoredPosition

   — Do not mix the two modes
5. Builder creates new UUIDs but

   .mlua

   property defaults are not updated — Binding breaks

ALWAYS

1. Check at least one design guide before invoking the builder (

   ui-fundamentals

   /

   ui-hierarchy

   /

   component-api

   §Component Selection Guide)
2. Match a recipe first; build from scratch only as a last resort
3. For edge placement use the formula:

   pos = ±(margin + size/2)

4. Separate popups and toasts into their own UIGroup, standalone show/hide
5. Verify text

   Alignment

   default is

   UpperLeft(0)

   — 95% of "I centered it but it sticks to the left" issues
6. Button touch target ≥ 88×88 (mobile support)

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/builder-protocol.md

  —

  .ui

  CJS builder call protocol (panel/text/sprite/button/slider/scroll/script/group/mask/grid/avatar/touch_receive/skeleton/area_particle/basic_particle, component add/replace/patch/remove, anchor presets, write auto-lint,

  .mlua

  property UUID auto-binding)

• 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

  references/builder-protocol.md

  for the call protocol 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