unreal-umg-design-system: Instructions file for GitHub Copilot

GitHub Copilot instructions

This repository follows the cross-tool AGENTS.md standard. Read /AGENTS.md for the full guide: the Ds class prefix, the token rules, the widget lifecycle contract, the validation commands, and the pull-request checklist. /llms.txt is the condensed API map.

The rules that matter most:

• Use Ds widgets, not stock widgets, for anything user-facing. UDsButton instead of UButton + hand styling, UDsText instead of UTextBlock, UDsTextBox instead of UEditableTextBox, UDsDropdown instead of UComboBoxString, UDsStack instead of UVerticalBox with typed padding, UDsListView instead of UListView.
• Never hardcode a colour, radius, spacing, font size, or control height. Resolve tokens: inside a Ds widget const UDsTheme& T = ThemeBinding.Resolve(this), elsewhere UDsTheme::Resolve(Widget). Prefer the scaled accessors — T.GetSpace(EDsSpace::S4), T.GetControlHeight(...), T.GetIconSize(...) — over reading a field directly, which ignores the theme's density.
• Sizes are tokens too. Component geometry lives in UDsTheme::Metrics (FDsMetrics). If the number you need is not there, add it there.
• Variants over custom colours. A destructive action is EDsButtonVariant::Danger. Need a sixth variant? Register it in UDsTheme::ButtonVariants and set CustomVariant — do not edit the enum.
• Signal theme changes with FDsThemeEvents::Broadcast() or RequestBroadcast(), never OnThemeChanged.Broadcast() — that skips the revision counter every widget's early-out depends on.
• Every widget follows the lifecycle contract: ThemeBinding.Bind in RebuildWidget, styles in a private ApplyDsStyle() that early-outs when its Slate widgets are invalid, ThemeBinding.Unbind() and reset Slate pointers in ReleaseSlateResources, GetPaletteCategory returning "Design System".
• Slate setters retain pointers; draw elements copy. Anything passed to SImage::SetImage or SButton::SetButtonStyle must outlive the frame — a UObject member, or a TSharedPtr from FDsStyleCache. A local brush inside OnPaint is fine. Never pass a temporary to a stock UEditableTextBox::SetWidgetStyle: UE 5.8 points Slate at the argument, so it dangles and crashes the next prepass.
• Null .Expose()d slot pointers in ReleaseSlateResources — they die with their panel, and SynchronizeProperties runs whether or not Slate is alive.
• In raw OnPaint code, multiply Brush->GetTint(InWidgetStyle) into the element tint (use DsSlateDraw::DrawBrush). MakeBox does not apply a brush's own tint, and skipping it renders every fill white.
• Accessibility is part of the widget, not a follow-up. A focusable widget draws a focus ring; a widget that shows text calls DsAccessibility::SetLabel, and one that does not calls SetDecorative.
• Icons by name, white paint only. snake_case file names under Resources/Icons/, no extension. A coloured icon ignores its tone.
• No content assets, ever. No .uasset. Palettes are hex in UDsTheme::ApplyPreset, styles are builders, the gallery is code.
• A local named Slot shadows UUserWidget::Slot and fails the build (C4458, warnings-as-errors); call it AddedSlot.

Before proposing a change, run python Tools/lint_ds.py — it enforces most of the above and explains each rule with --list.