Roblox UI
Implement deliberate, editable Roblox UI that preserves the experience's visual language and
works across supported devices. Targets Roblox's rolling platform APIs. Pair with game-ui-ux
for engine-neutral information architecture and UX; this skill owns Roblox Instances and APIs.
When to use
- Use for authored
ScreenGui interfaces, Roblox layout/constraint APIs, UI lifecycle, input,
focus, animation, performance, or responsive/device fixes.
- Use to replace brittle pixel layouts, runtime-created Instance tangles, mouse-only menus, or
generic generated styling with a maintainable hierarchy.
When not to use: general UX flow and accessibility principles belong to game-ui-ux; raw
gameplay action mapping belongs to input-systems; server trust belongs to roblox-networking.
Workflow
- Inspect before designing. In Explorer, inventory existing
ScreenGuis, UI modules,
fonts, colors, icon family, spacing, corners, strokes, animation timing, naming, and reusable
components, including any StyleSheet/StyleLink styling, tokens and themes. Capture
representative screenshots at two viewports. Extend that language.
- Define ownership and lifecycle.
StarterGui is the authored template; Roblox clones it
into each player's PlayerGui. Decide whether each ScreenGui should persist across respawn
with ResetOnSpawn = false; never keep stale references to a destroyed clone.
- Author a readable hierarchy. Prefer meaningful editable Instances and small behavior
modules. A normal screen should be understandable in Explorer; procedural generation is for
genuinely data-driven repetition, not the whole shell.
- Build responsive structure. Combine
UDim2 scale for placement with bounded offsets,
correct AnchorPoints, layouts, padding, content sizing, and constraints. Choose explicit
narrow/wide arrangements instead of shrinking a desktop panel until it technically fits.
- Handle platform obstructions. Keep interactive UI in
CoreUISafeInsets (the recommended
ScreenGui.ScreenInsets default), and account for touch controls and TV distance/overscan.
- Wire state and input. Render from a small view state; update on events. Use
Activated for
GuiButtons, explicit selected states, and reachable gamepad navigation. Bind non-widget
actions with ContextActionService only while the screen owns them.
- Polish with restraint. Implement hover, pressed, selected, and disabled states. Animate
state changes, not decoration; honor
GuiService.ReducedMotionEnabled and clean up tweens and
connections when the screen closes or is replaced.
- Verify the real interface. Use Device Simulator and Controller Emulator. Test desktop,
narrow portrait, mobile landscape, tablet-like, and console/gamepad; then respawn. Record
clipping, overlap, text, scroll, safe-area, focus path, touch target, and lifecycle results.
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 temporary positions. Keep repeated item cells as templates or
components, but keep the authored shell visible in Explorer.
Patterns
Layout that survives content and viewport changes
-- Authored properties on ItemGrid (ScrollingFrame):
-- AutomaticCanvasSize = Enum.AutomaticSize.Y
-- CanvasSize = UDim2.fromOffset(0, 0)
-- Children: UIPadding + UIGridLayout
local grid = itemGrid.UIGridLayout
local projectBreakpoint = 700 -- derive from where this composition stops being usable
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 -- open details as a separate narrow-screen 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()
Use UIListLayout for one-dimensional flow, UIGridLayout for uniform cells, and
UITableLayout only when row/column alignment is truly tabular. AutomaticSize fits content;
AutomaticCanvasSize fits scroll content. Bound extremes with UISizeConstraint,
UIAspectRatioConstraint, or UITextSizeConstraint rather than one global UIScale guess.
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() -- selection 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)
Decide input-dependent UI from UserInputService.PreferredInput, which follows the player's
primary device; TouchEnabled/GamepadEnabled are capabilities (a touch laptop reports touch)
and GetLastInputType() thrashes. Prefer Activated over separate mouse/touch handlers. Set NextSelectionUp/Down/Left/Right
when automatic navigation is ambiguous, especially around grids, sidebars, and modals. A modal
must trap focus inside itself and restore a sensible selection when it closes.
For cross-device action binding, the Input Action System (InputContext/InputAction/
InputBinding) is the modern edit-time layer; see references/input-navigation.md.
Inspect Roblox's default selection adornment in context. If it overwhelms the interface, assign a
project-owned SelectionImageObject or selected-state treatment; keep it visible, valid, and
restrained rather than disabling 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 function setPanelVisible(visible: boolean)
panel.Visible = true -- panel is a CanvasGroup
if GuiService.ReducedMotionEnabled then
panel.GroupTransparency = if visible then 0 else 1
else
TweenService:Create(panel, fade, {
GroupTransparency = if visible then 0 else 1,
}):Play()
end
if not visible then
task.delay(fade.Time, function()
if panel.GroupTransparency == 1 then panel.Visible = false end
end)
end
end
Animate a panel or state boundary once. Do not independently bounce every descendant.
Visual quality gates
- Establish hierarchy through size, weight, contrast, grouping, and whitespace before adding
decoration. Use a small spacing scale and align to it.
- Preserve the game's fonts, palette, icons, radii, and strokes. If the project uses UI styling,
change tokens and
StyleRules rather than per-instance properties; the Properties window
marks styled properties with ⚠ and names the style on hover. If nothing exists, define a compact token set (a token StyleSheet or module); do not improvise per
component.
- Use corners where the material/form calls for them, not on every nested
Frame. Avoid nested
card-on-card shells, universal pills, arbitrary gradients/glows/shadows, neon outlines,
excessive transparency/blur, oversized headings, meaningless icons, and huge empty panels.
- Buttons with different importance should not look identical. Define primary, secondary,
quiet, destructive, selected, pressed, hover, and disabled treatment only as needed.
- Motion communicates open/close, focus, confirmation, or spatial relationship. Keep it short,
interruptible, and subtle; avoid perpetual motion and decorative tween chains.
- On touch devices, reserve the default movement/jump corners. Move or recompose bottom actions
that overlap them, and show only the hints for the current
PreferredInput.
Common failures
| Symptom |
Likely cause |
Remedy |
| UI disappears or duplicates after respawn |
wrong ResetOnSpawn policy or stale clone |
choose policy; reacquire from PlayerGui; clean old bindings |
| Phone layout clips |
desktop offsets/global scale used as layout |
add narrow composition, layouts, bounds, and Device Simulator checks |
| Content hidden under topbar/notch |
insets ignored or ScreenInsets = None |
use CoreUISafeInsets for interactive UI; inspect intentional bleed |
| Scroll ends early |
fixed CanvasSize |
use AutomaticCanvasSize or layout AbsoluteContentSize |
| Controller gets stuck |
no entry selection or bad neighbor graph |
set initial SelectedObject; define and test focus edges/modal trap |
| UI looks generated |
decoration substituted for hierarchy |
remove effects; align, reduce nesting, fix density and component roles |
| Explorer contains only one script |
entire authored interface is procedural |
author the shell as named Instances; generate repeated content only |
| Increasing connection/tween count |
screen rebinds without cleanup |
own connections per screen lifecycle; disconnect/cancel on teardown |
Resources
- Read
references/responsive-layout.md for layout decisions, inset policy, density, and the
required viewport matrix.
- Read
references/input-navigation.md when implementing gamepad/touch focus, modal behavior,
action binding, or motion preferences.
- Build
assets/inventory-quality-test.project.json with Rojo (it maps the adjacent JSON model)
for an editable Instance fixture used in visual/layout review; it is a test baseline, not a style
template for a shipping game.
Related skills
game-ui-ux — information hierarchy, screen flow, accessibility, and UX validation.
input-systems — gameplay action mapping and device switching.
roblox-networking — server-authoritative requests initiated by UI.
roblox-studio-workflow — Explorer-first editing and Studio verification.
Primary references
- Roblox Creator Hub:
https://create.roblox.com/docs/ui/on-screen-containers
- Roblox Creator Hub:
https://create.roblox.com/docs/ui/position-and-size
- Roblox Creator Hub:
https://create.roblox.com/docs/ui/size-modifiers
- Roblox Creator Hub:
https://create.roblox.com/docs/studio/testing-modes
1---2name: roblox-ui3description: >4 Build production Roblox interfaces with ScreenGui/PlayerGui lifecycle, responsive UDim25 layouts, safe insets, reusable editable Instances, cross-device input and selection, restrained6 motion, cleanup, and multi-viewport verification. Use for Roblox HUDs, inventories, shops,7 settings, ability bars, ScrollingFrames, AutomaticSize, GuiService, gamepad focus, touch UI, or8 UI that clips, resets on respawn, looks generic, or was generated as one giant LocalScript.9metadata:10 source: https://skillmd.com/skills/junmystery/roblox-ui11---1213# Roblox UI1415Implement deliberate, editable Roblox UI that preserves the experience's visual language and16works across supported devices. Targets Roblox's rolling platform APIs. Pair with `game-ui-ux`17for engine-neutral information architecture and UX; this skill owns Roblox Instances and APIs.1819## When to use2021- Use for authored `ScreenGui` interfaces, Roblox layout/constraint APIs, UI lifecycle, input,22 focus, animation, performance, or responsive/device fixes.23- Use to replace brittle pixel layouts, runtime-created Instance tangles, mouse-only menus, or24 generic generated styling with a maintainable hierarchy.2526**When not to use:** general UX flow and accessibility principles belong to `game-ui-ux`; raw27gameplay action mapping belongs to `input-systems`; server trust belongs to `roblox-networking`.2829## Workflow30311. **Inspect before designing.** In Explorer, inventory existing `ScreenGui`s, UI modules,32 fonts, colors, icon family, spacing, corners, strokes, animation timing, naming, and reusable33 components, including any `StyleSheet`/`StyleLink` styling, tokens and themes. Capture34 representative screenshots at two viewports. Extend that language.352. **Define ownership and lifecycle.** `StarterGui` is the authored template; Roblox clones it36 into each player's `PlayerGui`. Decide whether each `ScreenGui` should persist across respawn37 with `ResetOnSpawn = false`; never keep stale references to a destroyed clone.383. **Author a readable hierarchy.** Prefer meaningful editable Instances and small behavior39 modules. A normal screen should be understandable in Explorer; procedural generation is for40 genuinely data-driven repetition, not the whole shell.414. **Build responsive structure.** Combine `UDim2` scale for placement with bounded offsets,42 correct `AnchorPoint`s, layouts, padding, content sizing, and constraints. Choose explicit43 narrow/wide arrangements instead of shrinking a desktop panel until it technically fits.445. **Handle platform obstructions.** Keep interactive UI in `CoreUISafeInsets` (the recommended45 `ScreenGui.ScreenInsets` default), and account for touch controls and TV distance/overscan.466. **Wire state and input.** Render from a small view state; update on events. Use `Activated` for47 `GuiButton`s, explicit selected states, and reachable gamepad navigation. Bind non-widget48 actions with `ContextActionService` only while the screen owns them.497. **Polish with restraint.** Implement hover, pressed, selected, and disabled states. Animate50 state changes, not decoration; honor `GuiService.ReducedMotionEnabled` and clean up tweens and51 connections when the screen closes or is replaced.528. **Verify the real interface.** Use Device Simulator and Controller Emulator. Test desktop,53 narrow portrait, mobile landscape, tablet-like, and console/gamepad; then respawn. Record54 clipping, overlap, text, scroll, safe-area, focus path, touch target, and lifecycle results.5556## Production structure5758```text59StarterGui60└── InventoryGui (ScreenGui; ResetOnSpawn = false)61 ├── Root (Frame)62 │ ├── Header63 │ ├── Content64 │ │ ├── CategoryList65 │ │ ├── ItemGrid (ScrollingFrame)66 │ │ └── DetailsPanel67 │ └── Footer68 └── InventoryController (LocalScript)69ReplicatedStorage70└── UI71 ├── Components72 └── Theme73```7475Names describe roles, not colors or temporary positions. Keep repeated item cells as templates or76components, but keep the authored shell visible in Explorer.7778## Patterns7980### Layout that survives content and viewport changes8182```lua83-- Authored properties on ItemGrid (ScrollingFrame):84-- AutomaticCanvasSize = Enum.AutomaticSize.Y85-- CanvasSize = UDim2.fromOffset(0, 0)86-- Children: UIPadding + UIGridLayout87local grid = itemGrid.UIGridLayout88local projectBreakpoint = 700 -- derive from where this composition stops being usable8990local function applyComposition()91 local narrow = root.AbsoluteSize.X < projectBreakpoint92 categoryList.UIListLayout.FillDirection = if narrow93 then Enum.FillDirection.Horizontal94 else Enum.FillDirection.Vertical95 categoryList.Size = if narrow96 then UDim2.new(1, 0, 0, 40)97 else UDim2.new(0, 148, 1, 0)98 itemGrid.Position = if narrow then UDim2.fromOffset(0, 52) else UDim2.fromOffset(164, 0)99 itemGrid.Size = if narrow100 then UDim2.new(1, 0, 1, -52)101 else UDim2.new(0.58, -164, 1, 0)102 detailsPanel.Visible = not narrow -- open details as a separate narrow-screen state103104 local width = itemGrid.AbsoluteSize.X105 local columns = if width < 520 then 2 elseif width < 820 then 3 else 4106 local gap = 12107 local usable = width - itemGrid.UIPadding.PaddingLeft.Offset108 - itemGrid.UIPadding.PaddingRight.Offset - gap * (columns - 1)109 grid.CellSize = UDim2.fromOffset(math.floor(usable / columns), 112)110 grid.CellPadding = UDim2.fromOffset(gap, gap)111end112113root:GetPropertyChangedSignal("AbsoluteSize"):Connect(applyComposition)114applyComposition()115```116117Use `UIListLayout` for one-dimensional flow, `UIGridLayout` for uniform cells, and118`UITableLayout` only when row/column alignment is truly tabular. `AutomaticSize` fits content;119`AutomaticCanvasSize` fits scroll content. Bound extremes with `UISizeConstraint`,120`UIAspectRatioConstraint`, or `UITextSizeConstraint` rather than one global `UIScale` guess.121122### One activation path and explicit gamepad entry123124```lua125local GuiService = game:GetService("GuiService")126local RunService = game:GetService("RunService")127local UserInputService = game:GetService("UserInputService")128129local function usesDirectionalFocus(): boolean130 local preferred = UserInputService.PreferredInput131 return preferred == Enum.PreferredInput.Gamepad132 or preferred == Enum.PreferredInput.MicroGamepad133end134135local function focusFirstItem()136 task.spawn(function()137 RunService.RenderStepped:Wait() -- selection must be rendered and selectable138 if root.Visible and usesDirectionalFocus() then139 GuiService.SelectedObject = firstItemButton140 end141 end)142end143144local function openInventory()145 root.Visible = true146 focusFirstItem()147end148149local function closeInventory()150 GuiService.SelectedObject = nil151 root.Visible = false152end153154-- Owned by the screen lifecycle; disconnect on teardown.155local inputConnection = UserInputService:GetPropertyChangedSignal("PreferredInput"):Connect(function()156 if root.Visible and GuiService.SelectedObject == nil then focusFirstItem() end157end)158159firstItemButton.Activated:Connect(function()160 selectItem(firstItemButton:GetAttribute("ItemId"))161end)162```163164Decide input-dependent UI from `UserInputService.PreferredInput`, which follows the player's165primary device; `TouchEnabled`/`GamepadEnabled` are capabilities (a touch laptop reports touch)166and `GetLastInputType()` thrashes. Prefer `Activated` over separate mouse/touch handlers. Set `NextSelectionUp/Down/Left/Right`167when automatic navigation is ambiguous, especially around grids, sidebars, and modals. A modal168must trap focus inside itself and restore a sensible selection when it closes.169170For cross-device action binding, the Input Action System (`InputContext`/`InputAction`/171`InputBinding`) is the modern edit-time layer; see `references/input-navigation.md`.172173Inspect Roblox's default selection adornment in context. If it overwhelms the interface, assign a174project-owned `SelectionImageObject` or selected-state treatment; keep it visible, valid, and175restrained rather than disabling focus feedback.176177### State transition without animation noise178179```lua180local TweenService = game:GetService("TweenService")181local GuiService = game:GetService("GuiService")182local fade = TweenInfo.new(0.14, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)183184local function setPanelVisible(visible: boolean)185 panel.Visible = true -- panel is a CanvasGroup186 if GuiService.ReducedMotionEnabled then187 panel.GroupTransparency = if visible then 0 else 1188 else189 TweenService:Create(panel, fade, {190 GroupTransparency = if visible then 0 else 1,191 }):Play()192 end193 if not visible then194 task.delay(fade.Time, function()195 if panel.GroupTransparency == 1 then panel.Visible = false end196 end)197 end198end199```200201Animate a panel or state boundary once. Do not independently bounce every descendant.202203## Visual quality gates204205- Establish hierarchy through size, weight, contrast, grouping, and whitespace before adding206 decoration. Use a small spacing scale and align to it.207- Preserve the game's fonts, palette, icons, radii, and strokes. If the project uses UI styling,208 change tokens and `StyleRule`s rather than per-instance properties; the Properties window209 marks styled properties with ⚠ and names the style on hover. If nothing exists, define a compact token set (a token `StyleSheet` or module); do not improvise per210 component.211- Use corners where the material/form calls for them, not on every nested `Frame`. Avoid nested212 card-on-card shells, universal pills, arbitrary gradients/glows/shadows, neon outlines,213 excessive transparency/blur, oversized headings, meaningless icons, and huge empty panels.214- Buttons with different importance should not look identical. Define primary, secondary,215 quiet, destructive, selected, pressed, hover, and disabled treatment only as needed.216- Motion communicates open/close, focus, confirmation, or spatial relationship. Keep it short,217 interruptible, and subtle; avoid perpetual motion and decorative tween chains.218- On touch devices, reserve the default movement/jump corners. Move or recompose bottom actions219 that overlap them, and show only the hints for the current `PreferredInput`.220221## Common failures222223| Symptom | Likely cause | Remedy |224|---|---|---|225| UI disappears or duplicates after respawn | wrong `ResetOnSpawn` policy or stale clone | choose policy; reacquire from `PlayerGui`; clean old bindings |226| Phone layout clips | desktop offsets/global scale used as layout | add narrow composition, layouts, bounds, and Device Simulator checks |227| Content hidden under topbar/notch | insets ignored or `ScreenInsets = None` | use `CoreUISafeInsets` for interactive UI; inspect intentional bleed |228| Scroll ends early | fixed `CanvasSize` | use `AutomaticCanvasSize` or layout `AbsoluteContentSize` |229| Controller gets stuck | no entry selection or bad neighbor graph | set initial `SelectedObject`; define and test focus edges/modal trap |230| UI looks generated | decoration substituted for hierarchy | remove effects; align, reduce nesting, fix density and component roles |231| Explorer contains only one script | entire authored interface is procedural | author the shell as named Instances; generate repeated content only |232| Increasing connection/tween count | screen rebinds without cleanup | own connections per screen lifecycle; disconnect/cancel on teardown |233234## Resources235236- Read `references/responsive-layout.md` for layout decisions, inset policy, density, and the237 required viewport matrix.238- Read `references/input-navigation.md` when implementing gamepad/touch focus, modal behavior,239 action binding, or motion preferences.240- Build `assets/inventory-quality-test.project.json` with Rojo (it maps the adjacent JSON model)241 for an editable Instance fixture used in visual/layout review; it is a test baseline, not a style242 template for a shipping game.243244## Related skills245246- `game-ui-ux` — information hierarchy, screen flow, accessibility, and UX validation.247- `input-systems` — gameplay action mapping and device switching.248- `roblox-networking` — server-authoritative requests initiated by UI.249- `roblox-studio-workflow` — Explorer-first editing and Studio verification.250251## Primary references252253- Roblox Creator Hub: `https://create.roblox.com/docs/ui/on-screen-containers`254- Roblox Creator Hub: `https://create.roblox.com/docs/ui/position-and-size`255- Roblox Creator Hub: `https://create.roblox.com/docs/ui/size-modifiers`256- Roblox Creator Hub: `https://create.roblox.com/docs/studio/testing-modes`