unreal-umg-design-system: Instructions file for Codex

AGENTS.md

Guidance for AI coding assistants (Copilot, Cursor, Codex, Claude Code) working in a project that consumes the Unreal UMG Design System plugin, or in this repo itself.

What this project is

A source-only Unreal Engine 5.8 plugin (class prefix Ds) providing design tokens (UDsTheme), 40+ themed UMG widgets, a 125-icon SVG set, runtime theming, focus and screen-reader support, and a W3C design-token pipeline. It ships no content assets; everything is C++.

Three modules: UmgDesignSystem (runtime), UmgDesignSystemEditor, and UmgDesignSystemCommonUI (optional, compiles to nothing without CommonUI).

Golden rules (do not violate)

1. Use Ds widgets, not stock widgets, for anything user-facing. UDsButton instead of UButton + hand styling, UDsText instead of UTextBlock with a hardcoded font, UDsTextBox instead of UEditableTextBox, UDsDropdown instead of UComboBoxString, UDsStack instead of UVerticalBox with typed padding, UDsListView instead of UListView, and so on. The point of the system is that no screen carries literal colours, sizes, or fonts.

2. Never hardcode a colour, radius, spacing, font size, or control height. Resolve the theme and read tokens:

   const UDsTheme& T = ThemeBinding.Resolve(this);   // inside a Ds widget
   const UDsTheme* T = UDsTheme::Resolve(Widget);    // anywhere else
   T->Primary.Base
   T->GetRadius(EDsRadius::MD)
   T->GetSpace(EDsSpace::S4)              // density-scaled; prefer this
   T->GetControlHeight(EDsControlSize::Medium)
   T->GetIconSize(EDsIconSize::MD)
   T->MakeFontInfo(EDsTextRole::Body1)
   

   In Blueprint use UDsStyleLibrary. Reading T->Space4 directly gives the authored value and ignores density — occasionally right, usually not.

3. Sizes are tokens too. Control heights, icon sizes, toggle geometry, and the focus ring live in UDsTheme::Metrics (FDsMetrics). If you need a number the system does not have, add it there — do not write a literal. Tools/lint_ds.py fails the build for literals in the style layer.