Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Working with AI agents

VardUI was designed around one question: what does each step of the “write → check → run → understand what went wrong” loop cost an agent — in tokens, in time, and in the probability of a mistake. Below is what the answer is made of and how to use it.

Principles

PrincipleHow it is implemented
Write it right the first timea small regular language, syntax close to Swift/Kotlin/TS, one form for each thing
Fix without thinkingevery diagnostic is file:line, the line of code, fix:; vard check --fix applies fixes to a fixed point; “habit” tables (VStack → Column, onPress → onTap, "a" + n → "a{n}")
See without visiona semantic tree ≈ 100 tokens; actions print diffs; why explains sizes; lints describe the recipe
Knowledge from one sourcethe reference is compiled into the binary and generated from the element registry — it cannot drift from the compiler
Determinismheadless runtime, bundled font, platform simulator, MVS for versions: same inputs, same result
A person decides outward-facing and risky stepsapproving package capabilities and publishing are not available through MCP

What an agent gets in a project

vard new creates:

  • AGENTS.md (and CLAUDE.md → @AGENTS.md) — the work loop, debugging rules, conventions, and a <!-- vard:packages --> block that the package manager keeps current;
  • .claude/skills/ — vard-app (screen patterns), vard-debug, vard-native, vard-design, vard-packages; packages’ skills are added on install as <package>-<skill>;
  • .mcp.json — the vard mcp server.

Token budget

OperationCost
the full language reference (vard doc)≈ 3k tokens, once per session
the whole screen (tree)≈ 110 tokens (a screenshot: 450–1600)
the result of an action≈ 30 tokens: only the lines that changed
vard check~20 ms; whatever is fixable is fixed without the model
a package: one line in vard doc / vard doc NAME≈ 30 / ≤ 1500 tokens
a package updatean API diff + --fix instead of reading a changelog
  1. Once per session — vard doc (or vard_doc).
  2. Edit .vard → vard check --fix → fix the rest.
  3. vard run --do "…" — the screen and actions; why for sizes, state/log for values.
  4. A test for every feature and bug: tests/*.vtest, vard test.
  5. Need “library” functionality — vard search → vard info → vard add → vard doc NAME. Never guess names; on P008, ask the user.
  6. A screenshot — only to judge how it looks.

Why packages are built this way

The package system continues the same principles (overview):

  • the compiler computes the contract — an agent does not need to trust a description or read code to know a package’s API and capabilities;
  • installation never guesses — protection against hallucinated names;
  • knowledge has a budget — AGENT.md ≤ 6 KB, the API is generated;
  • updates are mechanical — package migrations become fix:es;
  • a package runs headless — [sim] and tests at publish time;
  • risk stays with a person — sensitive capabilities are approved in vard.toml.

Working on the framework itself

Rules for agents changing VardUI are in CLAUDE.md: where the single sources of truth are (element registry, std, explain tables), what must be updated together (knowledge, skills, examples), and how to verify (cargo test --workspace, vard test on the examples and packages).