--- title: Native UI url: "https://native-sdk.dev/docs/native-ui" docs_index: /llms.txt lastUpdated: 2026-10-05 --- > For an index of all documentation, see [/llms.txt](/llms.txt). The default Native SDK app is native-rendered: the view is a Native markup file (`.native`), the logic is an app core — TypeScript by default, or Zig — and rendering happens through Native SDK's own engine. Scaffold one with `native init my_app` and run it with `native dev`. An app is four things: - `src/app.native` — the entire UI: elements, layout, bindings, and message dispatch. - `Model` — a plain data structure holding your state. - `Msg` — a tagged union of everything that can happen. - `update(model, msg)` — the only place state changes. The runtime owns installation, presentation, resize, event dispatch, timers, and hot reload. In development, `.native` edits refresh the running view while preserving the model and retained state of widgets whose identity remains stable. Zig views can register embedded fragments in `Options.fragment_watch` through `View.fragment("src/header.native")`. Release builds compile markup at comptime and report invalid views with a line and column. The [compiled TypeScript view preview](/docs/typescript#compiled-typescript-views-preview) requires a rebuild after markup edits. ## A complete view ```html title="src/app.native" {t.title} {openCount} open ``` ## Elements
Markup Renders as Notes
`row` , `column` flex containers horizontal / vertical main axis
`stack` , `panel` , `card` overlay containers children layer on top of each other — `gap` can never space them and is a validation error (put a `column` / `row` inside for flow)
`scroll` scroll view wrap multiple children in a `column` inside it
`list` , `grid` list, grid vertical stack / cell grid
`tabs` , `toggle-group` , `button-group` , `radio-group` , `breadcrumb` , `pagination` row containers children flow horizontally (tab buttons, toggle-buttons, radios, ...)
`table` \> `table-row` \> `table-cell` table rows only inside a table, cells only inside a row ( `for` / `if` wrappers are fine); cells are text leaves
`dropdown-menu` menu surface vertical; children are `menu-item` s. `anchor="below|above"` floats it against its parent's frame: a late z-pass above the whole tree, window-clipped (never cropped by a scroll pane), auto-flipping at the window edges, zero flow space — pair with `on-dismiss` so Escape/click-outside close model-side
`accordion` accordion header via the `text` attribute; children show while `selected` , dispatch `on-toggle`
`alert` , `bubble` surfaces `alert` title via the `text` attribute; children stack inside. `bubble` hugs its message up to 80% of the thread ( `ghost` exempt; explicit `width` wins) and takes one `` child — the reaction pill straddling its bottom edge, one text run, dock via `text-alignment` (default `end` ); `text=` on bubble itself is a teaching error (that channel belongs to the pill)
`dialog` , `drawer` , `sheet` modal surfaces root-relative and unaffected by ancestor scroll or clipping: dialogs center in the viewport, drawers span its width and dock to the bottom, and sheets span its height and dock to the right — title via `text` , wrap in `` to show conditionally
`resizable` resizable panel engine-managed drag handle; `width` sets the initial width
`split` two-pane splitter exactly two element children (nest splits for more panes); the engine synthesizes the draggable divider between them. `value` binds the model-owned first-pane fraction, `on-resize` names an f32 Msg variant dispatched with each applied fraction (echo it back through `value` ), `min-width` on the panes bounds the drag, `gap` sets the divider band thickness; the focused divider takes Left/Right (Shift for bigger steps) and Home/End. `resize-duration` (milliseconds, split only) animates model-driven value moves — the runtime eases the rendered fraction to the new value one presented frame at a time instead of snapping, and reduced-motion appearances snap automatically; `resize-easing` ( `linear` / `standard` / `emphasized` / `spring` ) shapes the ramp and needs a nonzero duration beside it
`tree` disclosure tree vertical container whose descendant rows with `role="treeitem"` form one roving keyboard focus set: Up/Down walk visible rows (selection follows focus via `on-change` when bound, otherwise `on-press` ), Left collapses or moves to the parent row, Right expands or moves to the first child row, Home/End jump to the edges, Enter/Space activate; nested rows derive hierarchy structurally, while flat `` rows declare their one-based `tree-level` ; expandable rows bind `expanded` and `on-toggle` , and the model owns both states
`text` , `badge` , `tooltip` text leaves `{}` interpolation allowed in content; `text` takes a line policy via `wrap` ( `"true"` word-wraps; `"false"` /unset paint a single line) and an overflow policy via `overflow` ( `ellipsis` — the default trailing elision — or `clip` ) and the typography rungs via `size="heading"` / `size="display"` (themable token steps above title — section headings, hero stats). `tooltip` with `anchor="above|below"` floats against its parent — the `stack` wrapping trigger + tooltip, the same shape as the anchored `dropdown-menu` — and the runtime owns its visibility through hover intent: it shows after the pointer rests on the trigger for `tooltip-delay` milliseconds (default 600; `"0"` shows instantly), skips the delay during the shared 400ms warm window after a pointer-hovered tooltip hides on leave, and shows immediately when the trigger gains keyboard focus; it hides on pointer leave (the only hide that warms), focus departure, Escape, or a press — the model never hears hover. Without `anchor` it stays a static leaf that paints whenever the view renders it — see Tooltip
`text` \> `span` inline styled runs mixed-style text in one wrapped paragraph: span children style runs with `weight="regular|medium|bold"` , `mono` , `italic` , `scale` (a positive multiplier on the paragraph's base size — inline headings, hero stats), `underline` , `foreground` (a token name); `{bindings}` interpolate inside spans; whitespace between runs collapses to a single space (none = the runs abut); spans do not nest, take no events, and the paragraph announces as one text run — see Rich text
`button` , `toggle-button` , `list-item` , `menu-item` , `toggle` , `switch` , `select` , `avatar` text-bearing controls the label is the element content; `button` , `toggle-button` , `list-item` , and `menu-item` also take `icon="..."` — a vector icon drawn inline (buttons and toggle-buttons before the label, icon-only when the content is empty; list and menu items as a leading slot), one hit target that follows the element's enabled/disabled tint; tab strips use `button` children, lowered to segmented controls; `select` shows its `placeholder` while empty and dispatches `on-press` ; `avatar` renders initials, or a runtime image via `image="{binding}"` . `list-item` alone also accepts element children IN PLACE of the text run (the list-row composite): the children flow horizontally inside the row's flat chrome — transparent at rest, full-width hover/selected washes, one hit target — so composite rows (title + snippet, leading icon + trailing badge) remain list rows instead of bordered boxes; name the row with `label` and never mix a text run with children. Rows that really are cards (a kanban board's draggable cards) opt into the card treatment explicitly with `background` / `radius`
`checkbox` , `radio` , `slider` , `progress` value controls `checked` , `value`
`text-field` , `input` , `search-field` , `combobox` , `textarea` text entry `placeholder` ; edits arrive via `on-input`
`status-bar` status bar content only, no children
`separator` , `spacer` separator, flexible space `separator` is axis-aware — a horizontal rule in a `column` , a thin vertical divider in a `row` ; give `spacer` a `grow`
`skeleton` , `spinner` loading leaves size `skeleton` with `width` / `height`
`icon` vector icon leaf `name` picks the icon: a bare literal is one of the curated stroke-dialect built-ins (compile-checked; including transport, files/folders, arrows/chevrons, panes (panel-left, panel-right), tooling (terminal, wrench), theming, and the full GitHub vocabulary (git-pull-request, git-merge, git-branch, circle-dot, check-circle, x-circle)); `app:` reaches an icon the app registered at boot (verified by `native check` against the model contract), and one `{binding}` defers the choice to model data (an unknown resolved name draws the missing-icon fallback with a Debug warning naming the value - never a silent gap); tint with `foreground` , size with `width` / `height` ; never a press target — decoration inside pressable rows passes clicks through to the row (give the icon its own `on-press` to make it an icon hotspot)
`markdown` rendered markdown leaf; `source` is one `{binding}` — see Rich text
`media-surface` media surface composites a texture produced OUTSIDE the widget tree (video, camera, an external renderer) like any widget; `surface="{binding}"` (required) binds the model-owned `u64` surface id a Zig-tier producer targets — no intrinsic size, display-only, `label` it; goldens and replay see the deterministic id-derived placeholder, never producer frames — see Media Surface and Media Producers
`video` video playback leaf; `src` declares the app's single platform-decoded playback (an assets path or `http(s)` URL, local-first like audio), `autoplay` / `loop` / `muted` shape it, and `controls` composes the house transport chrome — without it the element is the surface alone and your update code drives the video command vocabulary; no intrinsic size, `label` it; goldens and replay see the placeholder, transport is journaled truth — see Video
`stepper` \> `step` stage stepper `active="{index}"` derives each step's completed/active/pending state; steps are text leaves joined by connectors — see Pipeline components
`timeline` \> `timeline-item` ledger/timeline list items are leaves whose `title` / `description` / `meta` / `indicator` attributes carry the content; `on-press` makes the whole item pressable
`segmented-control` exclusive-choice control standalone text-bearing segment; bind `selected` , dispatch `on-press` , and optionally add a vector `icon` ; compose several in a row, or use tabs for the strip-and-panel pattern
`chart` \> `series` data chart each series binds a model `[]const f32` iterable via `values="{binding}"` ( `kind` is `line` / `area` / `bar` , `color` a token name); `y-min` / `y-max` / `grid-lines` / `baseline` shape the plot, `x-labels` / `y-labels` add muted axis ticks, `hover-details` adds the pointer detail card — see Charts
`input-group` \> `textarea` \+ `input-group-actions` grouped input the composer shape: ONE bordered field wrapping exactly one `textarea` (first) plus an optional `input-group-actions` row of controls inside the same border — the group wears the focus ring for its focused descendant and the textarea's own chrome dissolves; put a `` between leading and trailing controls — see Input Group
A tab strip, a select trigger, and a table read the way you would guess: ```html {r.name} {r.qty}
``` `data_grid`, `popover`, and `menu_surface` are not available as markup elements. Use the supported layout, menu, and table elements to compose the view. Vector icon buttons use ` ``` `titlebar = "hidden_inset_tall"` is the same shape with the taller unified band: macOS centers the traffic lights in a 52pt band (the Notes/Linear look) instead of the compact one — pick it when the header row is toolbar-height so the lights sit on its centerline. Fullscreen falls back cleanly in both variants. Windows implements hidden titlebars with DWM non-client handling, and Linux uses GTK client-side decorations. Both report control insets and support drag regions. Mobile hosts use the same chrome channel for safe-area insets; subscribing transfers responsibility for that padding to the app. See [Platform Support](/docs/platform-support) and `examples/markdown-viewer`. `titlebar = "chromeless"` removes ALL OS chrome — the titleband AND the system buttons, on every desktop (macOS borderless, Windows caption-less popup, Linux undecorated). It is an EXPLICIT opt-in for fully-skinned apps whose chassis draws its own working close/minimize controls wired to the real window-action effects (`fx.closeWindow(label)` / `fx.minimizeWindow(label)`); ordinary apps should keep the hidden styles above, which keep the real OS buttons. Drag regions keep working; chrome insets are zero. See `examples/deck` for the full shape. ## Images Images are runtime-registered resources. The app chooses an `ImageId` (`u64`; 0 means no image), registers decoded straight-alpha RGBA8 pixels, and binds that id on `image` or `avatar`. Encoded images use platform decoders: CGImageSource on macOS/iOS, gdk-pixbuf on Linux, WIC on Windows, and BitmapFactory on Android. An embed host without an image service reports `error.UnsupportedService`. Use `fx.loadImage` or `Cmd.imageLoad` to resolve a local or URL source, cache it, decode it, and register it. The result arrives as a message. [Dynamic Images](/docs/dynamic-images) covers cancellation, cache limits, and offline replay. Direct registration is also available when the app already owns encoded bytes or pixels: ```zig .load => fx.fetch(.{ .key = avatar_key, .url = avatar_url, .on_response = Effects.responseMsg(.fetched) }), .fetched => |response| { if (response.outcome == .ok and response.status == 200) { _ = fx.registerImageBytes(avatar_image_id, response.body) catch return; model.avatar_image = avatar_image_id; // only a registered id reaches the view } }, ``` ```zig // in a Zig view: ui.avatar(.{ .image = model.avatar_image, .semantics = .{ .label = "Octocat" } }, "OC"), ui.image(.{ .image = model.chart_image, .width = 120, .height = 80, .semantics = .{ .label = "Chart" } }), ``` ```html OC ``` One registered image can be a texture atlas. `ElementOptions.image_src` is an optional `geometry.RectF` in decoded-image pixel coordinates; Native markup spells the same rectangle with all four source attributes. The widget frame stays the destination, a source rectangle crossing the registered image bounds is clipped, and cropped widgets use nearest sampling so adjacent atlas regions cannot bleed into the tile: ```zig ui.image(.{ .image = model.atlas_image, .image_src = geometry.RectF.init(64, 32, 24, 24), .width = 48, .height = 48, .semantics = .{ .label = "Warning badge" }, }) ``` ```html ``` `fx.registerImage(id, width, height, rgba8)` registers already-decoded pixels (the runtime copies them; your buffer is free on return), `fx.registerImageBytes(id, bytes)` decodes through the platform codec first, and `fx.unregisterImage(id)` frees the slot. Re-registering an id replaces its pixels and every view repaints — GPU caches re-upload off the changed content fingerprint, no invalidation calls. For caches, mint fresh ids (effect-key style, monotonically increasing) and unregister the evictee — never re-key different content onto a live id. Outside `UiApp`, the same registry is `Runtime.registerCanvasImage`/`registerCanvasImageBytes`/`unregisterCanvasImage`. Capacities are fixed and loud (`canvas_limits`): 16 slots with a 1 MiB decoded-pixel target by default. Encoded photos decode aspect-preservingly to fit, while raw `fx.registerImage` pixels remain strict. Image-centric apps may raise the startup-frozen target through app.zon `.images.max_image_pixel_bytes`, up to 8 MiB; storage is lazy per used slot, but filling all 16 ceiling-sized slots is a declared 128 MiB high-water. Every encoded entry point, including direct `fx.registerImageBytes`, shares the flat 8 MiB source bound. `error.ImageRegistryFull`, `error.ImageTooLarge` (encoded source, raw pixels, or a codec-contract violation), `error.ImageDecodeFailed`, and `error.UnsupportedService` are never silent. Registered images render everywhere the canvas does: live presentation, screenshots, and automation. A missing id simply draws its fallback. In tests, the null platform's deterministic strict-PNG decoder also pins exact decode-to-fit dimensions and pixels. ## Rich text: inline spans and markdown Mixed-style text inside one wrapped paragraph is markup's ``: inline children of a `` element, each styling one run with `weight` (`regular`, `medium` — the semibold rung — or `bold`), `mono`, `italic`, `scale` (a positive multiplier on the paragraph's base size), `underline`, and `foreground` (a color token name). `{bindings}` interpolate inside spans like any text, and the whole paragraph word-wraps as one block: ```html Disk {diskUsed} of {diskTotal} — run native doctor if this looks wrong. ``` Whitespace between runs collapses to a single space; runs written with no whitespace between them abut, which is how a mono run takes trailing punctuation (`init.zig.`). Spans do not nest and take no events or keys — layout, identity, and the accessible name stay on the enclosing `` — and the paragraph announces to assistive tech as **one** text run: spans are visual, not structural. Because a span paragraph always word-wraps (reserving its real wrapped height), the single-line `wrap`/`overflow` policies are rejected on it. Both engines lower spans through the same paragraph builder, so a markup span paragraph renders identically to a Zig-built one. `scale` composes with the paragraph's typography: the run draws (and measures — line breaking is size-aware) at the base size times the multiplier, so `` with a `scale="1.5"` span gives heading × 1.5, and the multiplier tracks the themable token steps instead of hard-coding a pixel size. One limit: a paragraph reserves ONE uniform line height sized by its largest scale, and every run sits on that line's shared baseline — mixed-scale paragraphs are for inline headings and hero stats next to their captions, not for stacking independent text sizes (stack separate `` elements for that). Only positive finite multipliers are accepted; zero, negative, and non-numeric scales are teaching errors instead of runs silently drawn at the base size. `underline` is a pure decoration — it does not make the run a link. The full span model — including `strikethrough`, `background` highlights, and link spans — is available from the Zig builder as *spans*: ```zig const spans = [_]canvas.TextSpan{ .{ .text = "Run " }, .{ .text = "zig build test", .monospace = true }, .{ .text = " then read " }, .{ .text = "the guide", .link = "https://example.com/guide" }, }; ui.paragraph(.{ .on_link = Ui.linkMsg(.open_url) }, &spans) ``` Wrapping and measurement are span-aware (the platform text provider measures every run with the font it draws with), stacked paragraphs reserve their real wrapped height, and link spans are interactive: they carry `role=link` semantics in automation snapshots, show the pointing-hand cursor (the only place the engine uses it — controls keep the platform arrow, following native convention rather than the web's), and clicking one dispatches your `Msg` with the link payload. Source presentation is the reusable `ui.code` / `` component. It is deliberately bare: no background, border, radius, shadow, or padding. Wrap it in a `panel`, `card`, or another container when the design needs surface chrome. It wraps by default; `wrap="false"` preserves logical lines inside one horizontal scroll region, and `line-numbers` opts into a muted logical-line gutter. A definite `height` keeps overflow reachable with vertical scrolling (or both axes when wrapping is off): ```html ``` ```zig ui.code(.{ .language = .html, .line_numbers = true, .wrap = false, .width = 480, }, model.component_source) ``` For example, an inset code well is ordinary composition: ```html ``` Recognized languages receive theme-aware syntax color for keywords, types/numbers, strings, and comments: Zig; JavaScript/TypeScript; JSX/TSX; JSON; YAML; shell; Python; Rust; C, C++, C#, Java, Kotlin, and Swift; Go; HTML/XML/SVG; CSS/SCSS/Less; and SQL. HTML-family highlighting distinguishes element and component tags, attributes, strings, comments, and JavaScript/TypeScript expressions. Unknown or omitted tags stay plain monospace, and the bounded highlighting fallback never drops code. See [Code](/docs/components/code). Markdown builds on the same model. `native_sdk.markdown` maps a GitHub-flavored subset — headings, inline styles, links (including bare `http(s)://` URLs, which autolink with trailing punctuation trimmed), bullet/ordered/task lists, fenced code blocks, blockquotes, rules, pipe tables, and `
` collapsibles — onto ordinary widgets: ```zig const Md = native_sdk.markdown.Markdown(Msg); Md.view(ui, issue.body, .{ .images = model.markdown_images, // successful fx.loadImage mappings .on_link = Ui.linkMsg(.open_url), .on_details = Md.detailsMsg(.toggle_details), .details_expanded = &model.details_expanded, // caller-owned flags, elm-style .issue_link_base = "ghissue://", // opt-in: "#123" links to ghissue://123 }) ``` Malformed input degrades to plain text — the build fn never fails. Task-list checkboxes render as disabled (display-only) checkboxes, and `
` expansion is state the caller's model owns. Fenced code preserves every source indentation level and lowers through the same `ui.code` component, including JSX/TSX-aware HTML-family highlighting. Markdown keeps the component defaults: wrapping on, line numbers off. GFM pipe tables map onto the real `table`/`table-row`/`table-cell` widgets: the header row renders bold, the delimiter row's `:---`/`:--:`/`---:` cells set per-column start/center/end alignment, every cell runs the full inline grammar (code, bold, links — links in cells are clickable), `\|` puts a literal pipe in a cell, and cells wrap at their column width (columns share the width equally in v1). A pipe block whose delimiter row is missing or mismatched is not a table and renders as plain paragraphs. In markup, the `` element wires all of this declaratively: ```html ``` `source` (required) is one `{binding}` producing the markdown text — a string field, zero-arg method, or arena-taking method. `images` optionally binds `[]const canvas.markdown.ResolvedImage`: give `canvas.markdown.collectImageSources` a caller-owned `[]canvas.markdown.CollectedImageSource`, consume each canonical source through `value()` while that storage is alive, load it through `fx.loadImage`, and retain the source, successful id, and dimensions in the model. Return those mappings from a model or arena-taking method; the view performs no I/O. `on-link` and `on-details` are bare `Msg` tags (the runtime supplies their payloads: the URL as `[]const u8`, the details index as `usize`), `details-expanded` names a `[]const bool` iterable through the same sources `for each` accepts, and `issue-link-base` (a literal prefix or one `{binding}`) turns `#123` references into links to base ++ number. Everything but `source` is optional — without the details wiring, `
` blocks render collapsed and inert. Both the interpreter and the comptime compiler implement the element identically. ## Pipeline components: stepper, timeline, and nav Pipeline UIs (agent runs, wizards, activity feeds) get three composites. All three are ordinary compositions of existing widgets — same layout, theming, semantics, and hit-testing as hand-written trees. A **stepper** is a horizontal stage track (the house stepper conventions: indicator + title per step, separators as connectors). The model owns the active index; earlier steps render completed (a check badge), later ones pending: ```html Work Triage Review · {review_round} Fix Ready ``` From Zig: `ui.stepper(.{ .active = model.stage_index }, &.{ .{ .label = "Work" }, ... })`. Semantics: a `list` of `listitem`s, the active step `selected`, each label carrying its state (`"Review (active)"`) plus its position, so automation can read the pipeline at a glance. A **timeline** is a ledger list (the house timeline conventions: indicator + separator rail + title/description/meta per item). Items are leaves; the attributes carry the content: ```html ``` The leading badge is a small dot colored by `variant` (map run outcomes: `primary` for done, `destructive` for errors, `outline` for stopped, ...) or carries `indicator` text ("OK"); `connector="false"` ends the rail on the last item. With `on-press`, the item grows a trailing chevron and the press binds to the item's root, focusable with role `listitem` — clicks on the title/description/meta fall through to it, so a click anywhere on the item dispatches the message (dragging still selects the text). There is no built-in hover fill or line-clamping on the description in v1. A **nav** container is the within-pane navigation stack (ledger item → step transcript, back button pops). Zig-only for now — markup swaps views with ``: ```zig ui.nav(.{ .active = model.nav_depth, .retain = true }, .{ ledgerPane(ui, model), transcriptPane(ui, model), }) ``` The model owns the stack (push = set `nav_depth = 1`, pop = back to 0; out-of-range clamps). Pages are index-keyed, so a page's widget ids — and with them engine-owned scroll offsets and text edits — are stable across swaps. `retain = true` keeps inactive pages mounted but hidden: they keep engine state and drop out of rendering, hit-testing, focus traversal, and semantics; the default unmounts them (retained state is dropped). v1 swaps instantly — there is no push/pop animation yet — and focus does not transfer automatically: move it from `update` when the focused widget lives on the outgoing page. ## Charts The `` element is the data-visualization composite: `` children bind model iterables of `f32` and draw through the vector path pipeline with token colors, so charts re-theme with the palette, repaint exactly when their data changes, and report their series in automation snapshots. Three series kinds cover time-series dashboards: ```html ``` - **`line`** — a polyline through the values. A single sample renders as a dot. - **`area`** — a line with a translucent fill down to the baseline (the builder's `fill = true` spelling). - **`bar`** — one bar per value, always anchored at zero (the auto domain forces 0 in; negative values hang below the zero line). A zero value draws nothing — zero looks like zero. Series `values` take one `{binding}` naming a `[]const f32` iterable — a model field, public declaration, or function (arena functions work), the same resolution set as `for each`, slice-valued template args included. Values are y samples at uniform x steps, oldest first; `NaN` marks a missing sample and draws a gap, so pad a filling window with leading `NaN` in a model function and the trace enters from the right. Colors are design-token references (`accent`, `info`, `success`, `warning`, `destructive`, ...), never raw colors, so charts hold up in both themes. The y domain derives from the data per side unless `y-min`/`y-max` pin it (literals or scalar bindings); `grid-lines` draws that many horizontal token hairlines (opt-in — none by default) and `baseline="true"` marks the zero line. Axis tick labels are opt-in and draw in the muted text register inside reserved gutters. `x-labels="{binding}"` names a model iterable of strings — one category label per sample, oldest first — thinned deterministically to every Nth so labels never collide (and dropped entirely when a series downsamples: bucketed indices no longer name the labeled samples). `y-labels="true"` adds numeric ticks on a nice-step lattice (1/2/5 × 10^k, exact at their precision); with `grid-lines` set, the gridlines ride the same lattice, so the grid and its labels can never disagree. `hover-details="true"` adds pointer-hover point details: the pointer snaps to the nearest sample, a hairline cursor marks it (line series get a dot on the hovered point), and a floating card shows the sample's label with every series' name and value. Interaction-only chrome — static renders never show it. Series over 256 points use deterministic index-bucket min/max decimation to stay within the path budget while retaining extrema. This limit describes the rendering algorithm, rather than a measured performance result. Semantics: role `chart`, a generated series summary as the label (`"chart: cpu 3 pts last 0.75"` — describing the source series, pre-decimation) unless you set one, and the first series' latest value as the accessibility value, so automation can assert on live data without pixel access. Charts never claim presses: clicks fall through to the nearest pressable ancestor, so a chart inside a pressable row keeps the row clickable (`hover-details` makes the chart a hover target only). The series set is static — the plot's shape is part of the design and the DATA varies through the bindings. `ui.chart` (the same code the markup lowers through) is the escape hatch for what the grammar deliberately excludes: `.band` envelopes (a min/max band pairs a second lower-edge slice per point) and series sets composed dynamically at view time. See [Chart](/docs/components/chart) for the full attribute tables. ## Accessibility Every interactive element needs an accessible name — the text a screen reader announces and automation snapshots address widgets by. Name sources are the element's text content, the `text` attribute, or `label="..."`; text-entry controls take `label` or `placeholder` (the accessibility bridges announce the placeholder as the fallback name). The sources never combine: an explicit `label` REPLACES the element's text as the accessible name — while a label is set, the visible text is neither announced nor targetable, so never label an element whose visible text your automation greps for. This is a machine check, not a review item. An unnamed control, an icon-only control without a label (the icon name is a drawing instruction, not a label), or a misused role (`role="tree"` on an element that can never hold rows) is a validation error in `native markup check`, both view engines, and the LSP — the rubric is whether a screen reader user is fully blocked. Unnamed images and labels that duplicate the text they shadow degrade rather than block, so they report as warnings (`--strict` promotes them); the explicit `label=""` marks an image decorative on purpose. Zig-built views get the same discipline at tree level: `canvas.expectA11yAuditSweepClean` lays out the real tree and reports interactive widgets announced with no name (including dynamic labels that resolve empty at runtime), focusable widgets keyboard traversal can never reach, and identically labeled sibling controls — adopt it in your test suite next to `canvas.expectLayoutAuditSweepClean`. Contrast checking and focus-visible styling checks are not part of the audit yet. ## Tooling - `native markup check src/app.native` — instant validation with `file:line:column` errors, including the font-coverage tofu guard: literal text with a codepoint outside the bundled face is a teaching error naming the character (it renders as a tofu box on the reference/screenshot and mobile paths — [register a font](/docs/fonts) that covers it and bind the text from the model, or use a vector icon or plain words; the static check knows only the bundled face's coverage). Dynamic strings get the same lesson as a Debug-build diagnostic when the view builds. Accessibility findings ride the same pass: unnamed interactive controls and role misuse are errors, unnamed images and redundant labels are warnings (see [Accessibility](#accessibility)). - `native markup lsp` — diagnostics, completion, and hover in your editor (see `editors/native-markup/` in the repo for VS Code, Helix, and Neovim setup). - The automation harness drives widgets and reads accessibility snapshots and screenshots headlessly — see [Automation](/docs/automation). ### The model–view contract The model-contract artifact — `zig-out/model-contract.zon`, a reflection of your `Model`/`Msg` — is refreshed by `native test` in every app shape (apps that own their build can also run `zig build model-contract` directly). With that artifact fresh, `native check` verifies markup against your app's actual surface — no app compile in the loop: - View → model: every binding path, `for each` iterable, `key` field, message tag, and payload type must exist on the model with the right shape, and expressions type-check with the real binding types — `{count > 'a'}` is an error naming `count` and its core type. Unknown names get a did-you-mean over your model's actual fields. - Model → view: model fields, derived helpers/query functions, and `Msg` tags that no view binds or dispatches are reported as **warnings**. State only `update` or effects logic touches is legitimate, so opt it out in the core's vocabulary: TypeScript declares `export const viewUnbound = ["nextId", "tick"] as const` in `src/core.ts`; Zig declares `pub const view_unbound = .{ "next_id", "tick" };` on `Model` or `Msg`. Use the names exactly as that core authored them. `--strict` promotes the warnings to failures. - Template args are part of a template's interface: the kinds of use-site arguments flow into the template body (a string passed into a `width` arg fails at the use), slot content checks in the consumer's scope, and the check follows the whole `` closure. A missing or stale artifact (the artifact carries a hash of the app's core sources) degrades to structural checking with one loud line ("model contract: not yet built - bindings checked structurally only; run `native test` to enable typed checks") — never a false pass; the compiled engine still enforces the same contract at build time, and a conformance suite holds the two checkers to identical accept/reject sets. Model state consumed only by a Zig-built view needs `view_unbound` too — the markup checker cannot see Zig view reads. For the component catalog and styling model, see [Built-in Components](/docs/built-in-components). For dropping down to the programmatic API, the `canvas.Ui(Msg)` builder produces exactly the same trees the markup compiles to. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)