gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/roblox-ui
roblox-ui
VerifiedRoblox 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
- Inspect before designing. Inventory existing
ScreenGuis, UI modules, fonts, colors, icon family, spacing, corners, strokes, animation timing, naming, and anyStyleSheet/StyleLinktokens. Capture two viewports (screen_captureover Studio MCP, or ask the user for screenshots). Extend that language. - Define ownership and lifecycle.
StarterGuiis the authored template; Roblox clones it into eachPlayerGui. Decide perScreenGuiwhether it survives respawn (ResetOnSpawn = false) and never keep references to a destroyed clone. - 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.
- Build responsive structure.
UDim2scale for placement, bounded offsets for components, matchingAnchorPoints, layouts, padding, and size constraints. Design an explicit narrow arrangement instead of shrinking the desktop panel. - Handle obstructions. Keep interactive UI inside
CoreUISafeInsets(theScreenInsetsdefault) and away from the touch movement and jump controls; allow for TV overscan. - Wire state and input. Render from a small view state. Use
Activatedfor buttons, explicit selected states, and a reachable gamepad path. Bind screen actions only while the screen owns them. - Polish with restraint. Hover, pressed, selected, disabled. Animate state changes, honor
GuiService.ReducedMotionEnabled, and cancel tweens and connections on close. - Check before reporting. Build-level:
rojo build <project>.project.json -o out.rbxlxmust succeed for Rojo projects. Live, with the Studio MCP server connected: start play, open the screen fromexecute_luauon theClientdatamodel, printGuiService.SelectedObjectand theAbsoluteSizeof the root and scroll canvas, thenscreen_capture; Studio's built-inrbx-device-simulator-luaskill (through theskilltool) switches device presets for the viewport matrix. Without MCP, ask the user to check the matrix inreferences/responsive-layout.mdwith 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() then
GuiService.SelectedObject = firstItemButton
end
end)
end
local function openInventory()
root.Visible = true
focusFirstItem()
end
local function closeInventory()
GuiService.SelectedObject = nil
root.Visible = false
end
-- Owned by the screen lifecycle; disconnect on teardown.
local inputConnection = UserInputService:GetPropertyChangedSignal("PreferredInput"):Connect(function()
if root.Visible and GuiService.SelectedObject == nil then focusFirstItem() end
end)
firstItemButton.Activated:Connect(function()
selectItem(firstItemButton:GetAttribute("ItemId"))
end)
Choose input-dependent UI from UserInputService.PreferredInput, which follows the player's
primary device. TouchEnabled and GamepadEnabled are capabilities (a touch laptop reports
touch), and GetLastInputType() flips on every stray input. Set NextSelection* where automatic
navigation is ambiguous (grids, sidebars, modals). A modal traps focus with
SelectionGroup = true plus SelectionBehavior* set to Stop, and restores a sensible selection
on close. If the default selection adornment overwhelms the design, give it a project-owned
SelectionImageObject; do not remove focus feedback.
State transition without animation noise
local TweenService = game:GetService("TweenService")
local GuiService = game:GetService("GuiService")
local fade = TweenInfo.new(0.14, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)
local activeTween: Tween? = nil
local function setPanelVisible(visible: boolean)
if activeTween then activeTween:Cancel(); activeTween = nil end
local target = if visible then 0 else 1
panel.Visible = true -- panel is a CanvasGroup
if GuiService.ReducedMotionEnabled then
panel.GroupTransparency = target
panel.Visible = visible
return
end
local tween = TweenService:Create(panel, fade, { GroupTransparency = target })
activeTween = tween
tween.Completed:Once(function(state)
if state == Enum.PlaybackState.Completed and not visible then panel.Visible = false end
end)
tween:Play()
end
Animate the panel once, not every descendant, and cancel the previous tween so a fast open and close cannot leave the panel invisible but interactive.
Visual quality gates
- Build hierarchy with size, weight, contrast, grouping and whitespace before decoration. Use a small spacing scale and align to it.
- Keep the game's fonts, palette, icons, radii and strokes. In a styled project, change tokens and
StyleRules, not per-instance properties. With no system in place, define a compact token set (a tokenStyleSheetor module) instead of improvising per component. - Corners where the form calls for them, not on every nested
Frame. Avoid card-on-card shells, universal pills, arbitrary gradients, glows, neon outlines, heavy transparency or blur, oversized headings, meaningless icons, and huge empty panels. - Buttons of different importance look different: primary, secondary, quiet, destructive, plus selected, pressed, hover and disabled states only as needed.
- Motion explains open and close, focus, confirmation, or spatial relationships. Keep it short and interruptible; no perpetual motion.
- On touch, keep bottom actions clear of the movement and jump controls, and show hints only for
the current
PreferredInput.
Gotchas
| Symptom | Likely cause | Remedy |
|---|---|---|
| UI disappears or duplicates after respawn | wrong ResetOnSpawn policy or stale clone | choose the policy; reacquire from PlayerGui; clean old bindings |
| phone layout clips | desktop offsets or one global scale used as layout | narrow composition, layouts, bounds, Device Simulator checks |
| content under the topbar or notch | insets ignored or ScreenInsets = None | CoreUISafeInsets for interactive UI; bleed only decoration |
| scroll ends early | fixed CanvasSize | AutomaticCanvasSize or the layout's AbsoluteContentSize |
| controller gets stuck or escapes a modal | no entry selection or bad neighbor graph | set SelectedObject; define edges; SelectionGroup with Stop |
| panel invisible but still blocks clicks | interrupted tween left Visible = true | cancel the previous tween; hide on Completed |
| UI looks generated | decoration substituted for hierarchy | remove effects; align, reduce nesting, fix density and roles |
| Explorer shows only one script | whole interface built at runtime | author the shell as named Instances |
| connection or tween count keeps rising | screen rebinds without cleanup | own connections per screen; disconnect and cancel on teardown |
Resources
- Read
references/responsive-layout.mdwhen a screen must adapt across viewports or a layout defect appears: layout primitives, flex, insets, density, and the required viewport matrix. - Read
references/input-navigation.mdwhen implementing gamepad or touch focus, modals,ContextActionServiceor Input Action bindings, or motion preferences. - Build
assets/inventory-quality-test.project.jsonwith Rojo when you need an editable Instance fixture for layout review:rojo build assets/inventory-quality-test.project.json -o inventory-test.rbxlxfrom the skill directory. It is a test baseline, not a style to ship.
Related skills
game-ui-ux: information hierarchy, screen flow, accessibility, and design rules.input-systems: gameplay action mapping and device switching.roblox-networking: server-authoritative requests started from UI.roblox-studio-workflow: Explorer-first editing and Studio verification.
Version notes
Last verified: 2026-11-11.
StyleQueryand enhanced styling reached full release in May 2026; styling transitions are also fully released.Enum.PreferredInputvalues:KeyboardAndMouse,Gamepad,Touch,MicroGamepad(a gamepad without a thumbstick, such as a TV remote).GuiBase2d.SelectionGroupandSelectionBehaviorUp/Down/Left/Rightare the property-based way to contain navigation.GuiService:AddSelectionParent()andAddSelectionTuple()still exist and were not marked deprecated in the API reference on the verification date.- Rojo 7.7.1 builds the bundled fixture.
- To re-check an API: append
.mdto its Creator Hub URL, or start fromhttps://create.roblox.com/docs/llms.txt.
Sources: https://create.roblox.com/docs/ui/on-screen-containers,
https://create.roblox.com/docs/ui/position-and-size,
https://create.roblox.com/docs/ui/size-modifiers,
https://create.roblox.com/docs/reference/engine/enums/PreferredInput,
https://create.roblox.com/docs/reference/engine/classes/GuiService,
https://create.roblox.com/docs/assistant/skills (built-in Studio skills),
https://devforum.roblox.com/t/full-release-stylequery-more-styling-features/4566519.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |