Yoga Go Desktop UI

Yoga UI — agent instructions

Module github.com/mirzakhany/yoga. Public UI surface is ui/. Read widgets.md for constructors and examples.md for example/ patterns.

Mental model

Retained app state + per-frame declarative rebuild (SwiftUI @State analogue):

1. App struct holds durable state (lists, strings, *ui.Editor, *ui.Table).
2. Body(c) runs on every drawn wake and returns a ui.View tree. The GPU loop skips present (and the second Body rebuild) when nothing visual changed; idle WaitEvents does no work. There is no host widget cache / React reconciliation.
3. ui.View is Layout(c *ui.Ctx) *layout.Element. *ui.Node implements it.
4. Widget micro-state (hover, caret, scroll, open menu) lives in c.Widget(id, alloc) keyed by a unique-per-window id. App data does not.
5. Do not retain per-frame *ui.Ctx fields across frames. The Ctx pointer is window-lifetime: c.Dialogs(), c.Files(), c.Toasts(), c.Focus(), c.Invalidate(), and c.MarkNeedsPaint() are safe to capture in OnClick. Async work must Invalidate() so the next wake paints.

Heavy widgets (Editor, Table, Tree, FileTree, ListView) are constructed once in Build* and placed with ui.ViewOf(w). Stateless DSL nodes (Column, Button, TextField, …) may be allocated in Body. Dialogs, file picker, and toasts are window services on c — do not construct or thread hosts.

Bootstrap

yoga.Run creates the window/text engine then calls build. Construct widgets that measure text inside build, never before Run.

package main

import (
	"github.com/mirzakhany/yoga"
	"github.com/mirzakhany/yoga/ui"
)

type App struct{ name string }

func Build() *App { return &App{} }

func (a *App) Body(c *ui.Ctx) ui.View {
	th := c.Theme()
	return ui.Column(
		ui.Title("Hello"),
		ui.TextField("name", a.name).
			Placeholder("Your name").
			OnChange(func(s string) { a.name = s }).
			DefaultFocus().
			Grow(1),
		ui.Button("ok", ui.Text("OK")).Primary().OnClick(func() {}),
	).Gap(th.Spacing.M).Padding(th.Spacing.L).Grow(1).Background(ui.TokenSurface)
}

func main() {
	cfg := yoga.Config{Title: "App", Width: 640, Height: 480}
	if err := yoga.Run(cfg, Build); err != nil { panic(err) }
}

Custom title bar (VS Code-style): set `CustomTitleBar: true` in `yoga.Config`, then put menus and tools in `ui.TitleBar(...)` at the top of `Body`. macOS keeps native traffic lights; Windows/Linux get framework min/max/close buttons. Empty title-bar area drags the window; double-click toggles maximize.

GPU entry: //go:build !nogpu + yoga.Run. Headless: //go:build nogpu + shape.NewEngine → yoga.SetResources → ui.BuildFrame. Dual mains live side-by-side in example/*/.

Optional App capabilities (type-asserted by the runtime):

• Close() — release workers/files when the window closes.
• OnKey(c *ui.Ctx, k input.KeyEvent) bool (yoga.KeyHook) — global shortcuts after command Dispatch and before focus routing; return true to consume. Prefer c.Commands().Register for palette-visible actions.

Layout DSL (*ui.Node)

Children are ui.View. Nil children are skipped. Split a pane into helpers that return ui.View.

Fluent modifiers (chain on *Node): Gap, Padding/PaddingXY/PaddingLeft|Right|Top|Bottom, Margin/MarginXY/sides, Wrap, Grow, Shrink, Width, Height, Frame, Size (font size on Text, else square), Align, Justify, Style(Spec), Background(Token), BackgroundColor, Border/BorderTop|Right|Bottom|Left, BorderStyle, Radius/RadiusTopLeft|TopRight|BottomRight|BottomLeft, Disabled, DefaultFocus.

Alignment constants: ui.AlignStart|Center|End|Stretch, ui.JustifyStart|Center|End|Between.

Fill remaining space with .Grow(1) on the expanding child and its ancestors up to the window root. Root Body trees almost always .Grow(1).Background(ui.TokenSurface).

Use c.Theme().Spacing.* (XXS 2 … XXXL 32) — not magic numbers. Common: S 8, M 12, L 16.

Controlled widgets

Pass current value each frame; callbacks mutate the app struct. Stable unique id strings.

ui.TextField("url", app.url).Placeholder("https://…").IconStart(icons.Search).
    OnChange(func(s string) { app.url = s }).OnSubmit(func(s string) { app.go(s) }).Grow(1)

ui.EditableLabel("title", app.title).Placeholder("Untitled").
    OnSave(func(s string) { app.title = s })

ui.Button("send", ui.Text("Send")).Primary().Hint("⌘↵").IconStart(icons.Play).OnClick(app.send)
ui.Checkbox("n", "Notify").Check(app.on).OnToggle(func(v bool) { app.on = v })
ui.Radio("ra", "A").Check(app.radio == 0).OnClick(func() { app.radio = 0 })
ui.Select("lang", opts).Width(200).Selected(i).OnChange(func(v string) { app.lang = v })
ui.Slider("vol", app.vol).Min(0).Max(100).OnFloatChange(func(v float64) { app.vol = v })
ui.Button("tip", ui.Text("Save")).Tooltip("Save document")

Button variants: default Secondary; .Primary() / .Subtle() / .Ghost(). Ghost is text-like (no padding or chrome) for footers; chain .HoverFill() for a hover background. Supports .IconStart() and .Tooltip(). IconButton(id, iconName).

Do not construct NewEditor / NewTable / NewTree inside Body. Construct in Build*, then ui.ViewOf(app.table).Height(220) / .Grow(1).

Theme

theme.Use(name) mutates the live theme in place. Default yoga-dark. theme.Use("system") applies yoga-dark or yoga-light from the OS appearance and keeps syncing while selected. Prefer ui.Token* fills so widgets recolor on switch. c.Theme() for spacing, radius, stroke, typography, semantic colors (th.Success, th.Error, …).

ui.Text("hi").Style(ui.Spec{}.TextColor(ui.TokenForegroundMuted))
ui.Column(...).Background(ui.TokenChrome)

Typography helpers: Text, Title, Subtitle, Caption, Strong, Muted. Color/size inherit from parent env (e.g. a Button’s TextColor).

Select a theme before yoga.Run if the app is not dark-default (example/apitest uses yoga-midnight).