/roblox-ui

name: roblox-ui
description: >
  Roblox UI with ScreenGui and PlayerGui: ResetOnSpawn, UDim2 scale and offset, UIListLayout flex,
  safe areas, StyleSheet, gamepad selection and touch controls. Use for Roblox HUDs, shops or
  settings menus, or UI that clips on phones, resets on respawn or loses controller focus. Load
  `game-ui-ux` too. Not for input mapping (`input-systems`) or purchase checks
  (`roblox-networking`).

Roblox UI

Build editable Roblox interfaces that keep the experience's visual language and work on every supported device. This skill owns the Roblox Instances and APIs; `game-ui-ux` owns the design rules, so load both for menu and HUD work.

Workflow

1. **Inspect before designing.** Inventory existing `ScreenGui`s, UI modules, fonts, colors, icon family, spacing, corners, strokes, animation timing, naming, and any `StyleSheet`/`StyleLink` tokens. Capture two viewports (`screen_capture` over Studio MCP, or ask the user for screenshots). Extend that language. 2. **Define ownership and lifecycle.** `StarterGui` is the authored template; Roblox clones it into each `PlayerGui`. Decide per `ScreenGui` whether it survives respawn (`ResetOnSpawn = false`) and never keep references to a destroyed clone. 3. **Author a readable hierarchy.** Named, editable Instances plus small behavior modules. A screen should make sense in Explorer; procedural creation is for data-driven repetition only. 4. **Build responsive structure.** `UDim2` scale for placement, bounded offsets for components, matching `AnchorPoint`s, layouts, padding, and size constraints. Design an explicit narrow arrangement instead of shrinking the desktop panel. 5. **Handle obstructions.** Keep interactive UI inside `CoreUISafeInsets` (the `ScreenInsets` default) and away from the touch movement and jump controls; allow for TV overscan. 6. **Wire state and input.** Render from a small view state. Use `Activated` for buttons, explicit selected states, and a reachable gamepad path. Bind screen actions only while the screen owns them. 7. **Polish with restraint.** Hover, pressed, selected, disabled. Animate state changes, honor `GuiService.ReducedMotionEnabled`, and cancel tweens and connections on close. 8. **Check before reporting.** Build-level: `rojo build <project>.project.json -o out.rbxlx` must succeed for Rojo projects. Live, with the Studio MCP server connected: start play, open the screen from `execute_luau` on the `Client` datamodel, print `GuiService.SelectedObject` and the `AbsoluteSize` of the root and scroll canvas, then `screen_capture`; Studio's built-in `rbx-device-simulator-lua` skill (through the `skill` tool) switches device presets for the viewport matrix. Without MCP, ask the user to check the matrix in `references/responsive-layout.md` with Device Simulator and Controller Emulator and report clipping, overlap, focus path, and respawn behavior.

Production structure

StarterGui
└── InventoryGui (ScreenGui; ResetOnSpawn = false)
    ├── Root (Frame)
    │   ├── Header
    │   ├── Content
    │   │   ├── CategoryList
    │   │   ├── ItemGrid (ScrollingFrame)
    │   │   └── DetailsPanel
    │   └── Footer
    └── InventoryController (LocalScript)
ReplicatedStorage
└── UI
    ├── Components
    └── Theme

Names describe roles, not colors or positions. Repeated cells are templates or components; the shell stays visible in Explorer.

Patterns

Layout that survives content and viewport changes

-- Authored on ItemGrid (ScrollingFrame):
--   AutomaticCanvasSize = Enum.AutomaticSize.Y, CanvasSize = UDim2.fromOffset(0, 0)
-- Children: UIPadding + UIGridLayout
local grid = itemGrid.UIGridLayout
local projectBreakpoint = 700 -- where this composition stops being usable, not a device name

local function applyComposition()
    local narrow = root.AbsoluteSize.X < projectBreakpoint
    categoryList.UIListLayout.FillDirection = if narrow
        then Enum.FillDirection.Horizontal
        else Enum.FillDirection.Vertical
    categoryList.Size = if narrow then UDim2.new(1, 0, 0, 40) else UDim2.new(0, 148, 1, 0)
    itemGrid.Position = if narrow then UDim2.fromOffset(0, 52) else UDim2.fromOffset(164, 0)
    itemGrid.Size = if narrow then UDim2.new(1, 0, 1, -52) else UDim2.new(0.58, -164, 1, 0)
    detailsPanel.Visible = not narrow -- narrow screens open details as a separate state

    local width = itemGrid.AbsoluteSize.X
    local columns = if width < 520 then 2 elseif width < 820 then 3 else 4
    local gap = 12
    local usable = width - itemGrid.UIPadding.PaddingLeft.Offset
        - itemGrid.UIPadding.PaddingRight.Offset - gap * (columns - 1)
    grid.CellSize = UDim2.fromOffset(math.floor(usable / columns), 112)
    grid.CellPadding = UDim2.fromOffset(gap, gap)
end

root:GetPropertyChangedSignal("AbsoluteSize"):Connect(applyComposition)
applyComposition()

`UIListLayout` for one-dimensional flow (with flex for shared space), `UIGridLayout` for uniform cells, `UITableLayout` only for real tables. `AutomaticSize` fits content; `AutomaticCanvasSize` fits scroll content. Bound extremes with `UISizeConstraint`, `UIAspectRatioConstraint` or `UITextSizeConstraint` rather than one global `UIScale`. In a styled project, a `StyleQuery` can switch rules at a size breakpoint without a resize script.

One activation path and explicit gamepad entry

local GuiService = game:GetService("GuiService")
local RunService = game:GetService("RunService")
local UserInputService = game:GetService("UserInputService")

local function usesDirectionalFocus(): boolean
    local preferred = UserInputService.PreferredInput
    return preferred == Enum.PreferredInput.Gamepad
        or preferred == Enum.PreferredInput.MicroGamepad
end

local function focusFirstItem()
    task.spawn(function()
        RunService.RenderStepped:Wait() -- the target must be rendered and selectable
        if root.Visible and usesDirectionalFocus() th