gum-layout
Reference guide for Gum's layout system — dimension units, position units, children layout modes, layout calculation flow, and layout suspension. Load when working on Width/HeightUnits, XUnits/YUnits, stacking, wrapping, auto-sizing, Anchor/Dock, or GraphicalUiElement layout logic. For deep engine internals (debugging/optimizing UpdateLayout, UpdateChildren, dirty state), see the gum-layout-engine skill instead.
Best use case
gum-layout is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Reference guide for Gum's layout system — dimension units, position units, children layout modes, layout calculation flow, and layout suspension. Load when working on Width/HeightUnits, XUnits/YUnits, stacking, wrapping, auto-sizing, Anchor/Dock, or GraphicalUiElement layout logic. For deep engine internals (debugging/optimizing UpdateLayout, UpdateChildren, dirty state), see the gum-layout-engine skill instead.
Teams using gum-layout should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/gum-layout/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How gum-layout Compares
| Feature / Agent | gum-layout | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Reference guide for Gum's layout system — dimension units, position units, children layout modes, layout calculation flow, and layout suspension. Load when working on Width/HeightUnits, XUnits/YUnits, stacking, wrapping, auto-sizing, Anchor/Dock, or GraphicalUiElement layout logic. For deep engine internals (debugging/optimizing UpdateLayout, UpdateChildren, dirty state), see the gum-layout-engine skill instead.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Gum Layout System Gum's layout is driven by **unit enums** that tell the engine how to interpret numeric Width/Height/X/Y values, plus a **children layout** mode on containers. All layout lives in `GraphicalUiElement` (`GumRuntime/GraphicalUiElement.cs`). ## Key Concepts ### Dimension Units (Width & Height) `DimensionUnitType` enum (`GumDataTypes/DimensionUnitType.cs`) controls how a Width or Height value is interpreted. Units fall into dependency categories: | Dependency | Units | |---|---| | No dependency | Absolute, PercentageOfSourceFile, PercentageOfOtherDimension, MaintainFileAspectRatio, AbsoluteMultipliedByFontScale, ScreenPixel | | Depends on parent | PercentageOfParent, RelativeToParent, RelativeToMaxParentOrChildren* | | Depends on children | RelativeToChildren | | Depends on siblings | Ratio | \* `RelativeToMaxParentOrChildren` is classified as `DependsOnParent` but also depends on children — special-cased throughout the layout engine. See [dimension-units.md](dimension-units.md) for circular dependency handling. See [dimension-units.md](dimension-units.md) for detailed descriptions. ### Position Units (X & Y) `GeneralUnitType` enum (`GumDataTypes/UnitConverter.cs`) controls how X/Y values are measured: from edges, center, baseline, or as percentages. Combined with **XOrigin/YOrigin** (HorizontalAlignment/VerticalAlignment) to set which point on the element is being positioned. See [dimension-units.md](dimension-units.md) for detailed descriptions. ### Children Layout `ChildrenLayout` enum (`Gum/Managers/StandardElementsManager.cs`): - **Regular** — children positioned independently - **TopToBottomStack / LeftToRightStack** — stack children along an axis - **AutoGridHorizontal / AutoGridVertical** — arrange in wrapping grid Related properties: `StackSpacing`, `WrapsChildren`, `AutoGridHorizontalCells`, `AutoGridVerticalCells`, `StackedRowOrColumnDimensions`. ### Anchor & Dock Convenience APIs on `GraphicalUiElement` that set multiple layout properties at once (X, Y, XUnits, YUnits, XOrigin, YOrigin, Width, WidthUnits, etc.). - **Anchor** — 9 positions (TopLeft..BottomRight) + CenterHorizontally/Vertically - **Dock** — Top, Left, Right, Bottom, Fill, FillHorizontally, FillVertically, SizeToChildren ## Layout Engine See [layout-engine.md](layout-engine.md) for the calculation flow, suspension system, dirty tracking, and performance considerations. ### Quick Reference | Method | Purpose | |---|---| | `UpdateLayout()` | Full layout recalculation | | `UpdateLayout(updateParent, childrenUpdateDepth, xOrY)` | Granular control | | `SuspendLayout(recursive)` | Pause layout, queue as dirty | | `ResumeLayout(recursive)` | Resume and apply queued updates | | `GetAbsoluteWidth()` / `GetAbsoluteHeight()` | Final computed dimensions | | `MakeDirty(...)` | Queue deferred update when suspended | ### Key Properties - `IsLayoutSuspended` — instance-level pause - `IsAllLayoutSuspended` — thread-static global pause (background loading) - `GlobalFontScale` — multiplier for AbsoluteMultipliedByFontScale - `CanvasWidth` / `CanvasHeight` — root canvas size
Related Skills
gum-layout-engine
Deep reference for maintainers of the Gum layout engine — the UpdateLayout call chain, UpdateChildren ordering, stacking position pipeline, dirty state tracking, and performance optimizations inside GraphicalUiElement. Load when debugging layout performance, optimizing UpdateLayout/UpdateChildren, working on RefreshParentRowColumnDimensionForThis, GetWhatToStackAfter, MakeDirty, ResumeLayoutUpdateIfDirtyRecursive, or _cachedSiblingIndex.
validate-code-changes
Validate all code changes on the current branch. Spawns QA and refactoring agents in parallel to review for correctness, edge cases, code quality, and pattern adherence. Use when ready to review branch changes before merging.
skills-writer
Creates and updates skill files (.claude/skills/*/SKILL.md) by reading source code and condensing knowledge into concise reference guides. Use when asked to create a new skill, update an existing skill, or document a subsystem for Claude Code agent context.
gum-variable-deep-dive
Deep dive into the full variable lifecycle — from VariableSave on ElementSave through runtime application on GraphicalUiElement and Forms controls. Load this when working on styling, theming, RefreshStyles, or when you need to understand how variable values flow from save data to live visuals.
gum-unit-tests
Reference guide for writing unit tests in the Gum repository. Load this when writing or modifying tests in Gum.ProjectServices.Tests, Gum.Cli.Tests, or any other Gum test project.
gum-tool-viewmodels
Reference guide for Gum tool ViewModel conventions. Load this when working on ViewModels, XAML views, data binding, DependsOn, or visibility properties in the Gum tool.
gum-tool-variable-references
Reference guide for Gum's variable reference system — Excel-like cross-instance/cross-element variable binding using Roslyn-parsed assignment syntax. Load this when working on VariableReferenceLogic, EvaluatedSyntax, ApplyVariableReferences, VariableChangedThroughReference, or the VariableReferences VariableListSave.
gum-tool-variable-grid
Reference guide for Gum's Variables tab and DataUiGrid system. Load this when working on the Variables tab, DataUiGrid control, MemberCategory, InstanceMember, category population, property grid refresh, or category expansion state persistence.
gum-tool-undo
Reference guide for Gum's undo/redo system. Load this when working on undo/redo behavior, the History tab, UndoManager, UndoPlugin, UndoSnapshot, or stale reference issues after undo.
gum-tool-selection
Reference guide for Gum's editor selection system. Load this when working on click/drag selection, the rectangle/marquee selector, input handlers (move, resize, rotate, polygon points), the IsActive flag, locked instance behavior, SelectionManager coordination, or the selection event cascade (plugin events, forced default state, tree view sync).
gum-tool-save-classes
Reference guide for Gum's save/load data model. Load this when working with GumProjectSave, ScreenSave, ComponentSave, StandardElementSave, ElementSave, StateSave, VariableSave, InstanceSave, BehaviorSave, or any serialization/deserialization of Gum project files.
gum-tool-plugins
Reference guide for the Gum tool's plugin system, including visualization plugins (EditorTabPlugin_XNA, TextureCoordinateSelectionPlugin). Load this when working on plugin registration, PluginBase, InternalPlugin, PluginManager, plugin events, visualization/rendering concerns, or finding which internal plugin owns a feature.