Skip to content

Commit d776c90

Browse files
vchelarugitbook-bot
vchelaru
authored and
gitbook-bot
committed
GITBOOK-868: change request with no subject merged in GitBook
1 parent eab90ab commit d776c90

File tree

2 files changed

+167
-0
lines changed

2 files changed

+167
-0
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
## Gum Tool
44

55
* [Introduction](README.md)
6+
* [For Figma Users](gum-tool/readme/for-figma-users.md)
67
* [Setup](gum-tool/setup/README.md)
78
* [Running from Source](gum-tool/setup/running-from-source.md)
89
* [Showcase](gum-tool/showcase.md)

‎docs/gum-tool/readme/for-figma-users.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# For Figma Users
2+
3+
## Introduction
4+
5+
This guide walks through Gum's layout system using Figma as a reference point. The quick reference table below covers the most common mappings. The sections that follow explain the concepts that feel meaningfully different coming from Figma.
6+
7+
## Quick Reference: Figma → Gum
8+
9+
| Figma Concept | Gum Equivalent |
10+
| -------------------------------------- | -------------------------------------------------------------------------------------- |
11+
| Page | _(no equivalent — Screens serve as the organizational unit)_ |
12+
| Top-level Frame (a "screen" or "view") | Screen |
13+
| Frame (layout container) | Container |
14+
| Frame fill/stroke | Child `ColoredRectangle` or `NineSlice` inside the Container |
15+
| Fixed size | Width/Height Units = `Absolute` |
16+
| Fill container | Width/Height Units = `Relative to Parent` (value 0) |
17+
| Hug contents | Width/Height Units = `Relative to Children` |
18+
| Flex grow | Width/Height Units = `Ratio of Parent` |
19+
| Padding | No direct equivalent — use child offsets or `Relative to Parent` with a negative value |
20+
| Constraints (pin left/right) | X Units = `Pixels From Left` or `Pixels From Right` + X Origin |
21+
| Constraints (pin center) | X Units = `Pixels From Center`, X Origin = `Center` |
22+
| Constraints (scale) | X Units = `Percentage Parent Width` |
23+
| Nine-point reference selector | X Origin + Y Origin |
24+
| Auto Layout (vertical) | Children Layout = `Top to Bottom Stack` |
25+
| Auto Layout (horizontal) | Children Layout = `Left to Right Stack` |
26+
| Gap between items | `Stack Spacing` |
27+
| Wrap | `Wraps Children = true` |
28+
| Clip content | `Clips Children = true` |
29+
| Component | Component |
30+
| Component slot | Instance with `Is Slot = true` inside a component |
31+
| Layer order | Tree position (earlier = behind, later = in front) |
32+
| Min/Max width | `Min Width` / `Max Width` properties |
33+
| Aspect ratio lock | Width Units = `Percentage of Height` (or vice versa) |
34+
35+
## Project Organization
36+
37+
In Figma, you organize your work into **Pages**, each containing **Frames** that typically represent individual screens or views. **Components** live alongside your frames and can be used across pages.
38+
39+
Gum splits this into three explicit categories visible in the Project panel:
40+
41+
* **Screens** — represent individual UI states in your game, like a main menu, HUD, or pause screen. You can think of each Screen as a top-level Frame in Figma. Unlike Figma frames though, Screens can't be nested inside other Screens — they're always top-level.
42+
* **Components** — reusable elements like buttons, list items, or windows. These work like Figma components: define once, place instances anywhere.
43+
* **Standard Elements** — the built-in primitives (Sprite, Text, ColoredRectangle, etc.) that you drag into Screens and Components to build your UI.
44+
45+
There's no equivalent to Figma's Pages — Screens serve as the organizational unit directly.
46+
47+
## Elements and Containers (Frames)
48+
49+
Gum's coordinate system works the same as Figma's: X increases to the right, Y increases downward, with (0, 0) at the top-left of the canvas or parent.
50+
51+
In Figma, a **Frame** can hold children and have its own fill and stroke. In Gum, layout containers are called **Containers**, and they are always invisible — there's no fill or stroke to set. You may notice containers showing up with a dotted outline in the editor, but that's just the container outline display (on by default in Gum) and isn't part of the rendered output.
52+
53+
To give a container a visible background, add a `ColoredRectangle` or `NineSlice` as a child. For example, a button component might have a `Container` at the root, a `NineSlice` child for the background, and a `Text` child for the label.
54+
55+
## Positioning: X/Y + Units + Origin
56+
57+
In Figma, you set X and Y and use the nine-point reference selector to control which corner of the object those numbers measure from. In Gum, the same idea is split into three properties:
58+
59+
| Property | What It Does |
60+
| --------------------------- | ----------------------------------------------------- |
61+
| **X** / **Y** | The numeric position value |
62+
| **X Units** / **Y Units** | Which point on the _parent_ to measure from |
63+
| **X Origin** / **Y Origin** | Which point on the _child_ is placed at that position |
64+
65+
**X Units** options:
66+
67+
| Unit | Meaning |
68+
| ---------------------------- | ------------------------------------------------------------------------------ |
69+
| `Pixels From Left` (default) | X=0 is the parent's left edge; positive X moves right |
70+
| `Pixels From Center` | X=0 is the parent's horizontal center |
71+
| `Pixels From Right` | X=0 is the parent's right edge; positive X moves further right (past the edge) |
72+
| `Percentage Parent Width` | X=50 places the origin halfway across the parent's width |
73+
74+
Y Units mirrors this vertically, with positive Y always pointing downward. `Pixels From Right` and `Pixels From Bottom` work the same way — X=0 / Y=0 is at the edge, and positive goes outward past it. To position something _inside_ those edges, use negative values.
75+
76+
**X Origin** / **Y Origin** options are `Left`/`Top` (default), `Center`, and `Right`/`Bottom` — the same as Figma's nine-point reference selector, just set separately per axis.
77+
78+
#### Examples
79+
80+
**Center an element horizontally inside its parent** (like Figma's "center" horizontal constraint):
81+
82+
```
83+
X = 0, X Units = Pixels From Center, X Origin = Center
84+
```
85+
86+
**Pin an element's right edge 10px inside the parent's right edge** (like Figma's right constraint with 10px offset):
87+
88+
```
89+
X = -10, X Units = Pixels From Right, X Origin = Right
90+
```
91+
92+
Note that Gum doesn't pin both sides of an element at once to stretch it. Stretching is handled by **Width/Height Units** instead.
93+
94+
## Sizing: Width/Height Units
95+
96+
Like Figma's Fixed / Fill / Hug, Gum controls sizing through **Width Units** and **Height Units**:
97+
98+
| Gum Unit | Figma Equivalent | What It Does |
99+
| ---------------------------- | ------------------ | ---------------------------------------------------- |
100+
| `Absolute` | Fixed | Fixed pixel size, ignores parent |
101+
| `Relative to Parent` | Fill (with offset) | `0` = same size as parent; `-20` = 20px smaller |
102+
| `Percentage of Parent` | Fill (as %) | `100` = same size as parent |
103+
| `Relative to Children` | Hug | Container grows/shrinks to contain its children |
104+
| `Ratio of Parent` | Flex grow | Siblings share available parent space proportionally |
105+
| `Percentage of Width/Height` | Aspect ratio lock | Ties one dimension to the other |
106+
107+
**Relative to Children** works like Hug. The numeric value adds padding — for example, `Width = 16` with `Relative to Children` adds 8px on each side. Note that children whose size depends on the parent's size are excluded from this calculation to avoid a circular dependency.
108+
109+
**Ratio of Parent** works like CSS flex-grow. Three siblings with ratios of 1, 2, 1 get 25%, 50%, and 25% of the parent's width respectively.
110+
111+
## Anchoring and Docking
112+
113+
The **Alignment tab** has shortcut buttons that set X, Y, Width, and Height variables for common layouts. They don't toggle any state — they just write variables, so you undo them with Ctrl+Z.
114+
115+
**Anchor** sets position variables only (X, Y, and their Units and Origins), similar to Figma's constraint presets. It won't change the element's size.
116+
117+
**Dock** sets both position and size, for "fill a side" patterns — think of it as Figma's "Fill container" combined with a constraint. Options include Top, Bottom, Left, Right, Fill, Fill Horizontally, Fill Vertically, and Size to Children.
118+
119+
## Auto Layout → Children Layout
120+
121+
Figma's **Auto Layout** is called **Children Layout** in Gum, set on the container itself:
122+
123+
| Gum Children Layout | Figma Equivalent |
124+
| ---------------------- | ------------------------- |
125+
| `Regular` (default) | No Auto Layout |
126+
| `Top to Bottom Stack` | Auto Layout, vertical |
127+
| `Left to Right Stack` | Auto Layout, horizontal |
128+
| `Auto Grid Horizontal` | Grid, fills columns first |
129+
| `Auto Grid Vertical` | Grid, fills rows first |
130+
131+
`Stack Spacing` is the same as Figma's **Gap between items**. Negative values cause children to overlap.
132+
133+
In Auto Grid modes, the parent's size is divided equally among cells. The number of columns (or rows) is fixed; additional rows (or columns) are added as needed.
134+
135+
A couple of differences from Figma's Auto Layout worth knowing:
136+
137+
* **No padding.** To approximate padding, size a child with `Relative to Parent` and a negative value, or offset children manually.
138+
* **Cross-axis alignment is per-child.** In a `Top to Bottom Stack`, Gum controls each child's Y automatically, but each child sets its own X. In Figma, alignment (left/center/right) is a single setting on the parent.
139+
140+
## Wrapping
141+
142+
**Wraps Children** works like Figma Auto Layout's **Wrap** mode. Row height is set by the tallest child; column width by the widest.
143+
144+
One constraint: the container's size on the stacking axis can't be `Relative to Children` at the same time — that would be circular. You can still use `Relative to Children` on the cross axis (e.g. height on a horizontal stack). Alternatively, set a `Max Width` on the container — it will grow with its content until hitting the max, then start wrapping.
145+
146+
## Clip Content → Clips Children
147+
148+
Figma's **Clip content** is called **Clips Children** in Gum. Off by default, meaning children can render freely outside their parent's bounds.
149+
150+
## Components and Slots
151+
152+
Gum's **Components** work like Figma's components — define once, place multiple instances, override individual properties per instance.
153+
154+
Gum also has **Is Slot**, which doesn't have a direct Figma equivalent. You can mark child instances inside a component as slots — named attachment points that elements can parent themselves to when the component is placed in a screen. For example, a `Window` component with `Header`, `Body`, and `Footer` slots lets you drop children directly into any of those sections.
155+
156+
## Z-Ordering
157+
158+
Same as Figma: items earlier in the tree render behind items later in the tree. Right-click to **Bring to Front**, **Send to Back**, **Move Forward**, or **Move Backward**. Reordering a parent moves all its children with it.
159+
160+
## Rotation
161+
162+
Rotation is in degrees. One difference from Figma: **positive values rotate counterclockwise** (Figma rotates clockwise). The pivot point is set by X Origin and Y Origin — by default that's the top-left corner, so set both to `Center` if you want to rotate around the middle.
163+
164+
## Min/Max Constraints
165+
166+
`Min Width`, `Max Width`, `Min Height`, and `Max Height` work the same as in Figma — they clamp the effective size after all other calculations. They work with any Width/Height unit type, so you can combine them with `Relative to Parent` or `Relative to Children` layouts.

0 commit comments

Comments
 (0)