# UI Basics > UI engine reference - bindings, state management, patterns. Foundation for ui-fast and ui-thorough. Use when this capability is needed. - Skill: `tomevault-io/ui-basics` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ui-basics` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ui-basics/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ui-basics --- # UI Basics Frictionless is a platform for personal software that integrates Claude. Users download, mod, create, and share apps — and **this skill exists so you can help them build and modify their apps.** Load this once for reference, then use `/ui-fast` or `/ui-thorough` for actual work. ## On Skill Load **IMMEDIATELY invoke `/ui` using the Skill tool before doing anything else.** It covers the directory structure, helper script, debugging, and server lifecycle. Then invoke `/frontend-design` using the Skill tool if it is available. Then run this command: ```bash {cmd} patterns ``` ## How Frictionless Works This is not a conventional web framework. It's an **object-oriented system where objects present themselves**. - **Declarative frontend.** HTML uses `ui-*` bindings, not code. JS is only for browser-native capabilities (file I/O, DOM measurement, timing/animation) — see `{ui_dir}/patterns/` for established solutions. - **Backend is source of truth.** State AND logic live in a persistent Lua session. Page refresh restores the view without resetting state. - **The frontend creates most variables, not the backend.** The backend creates the root app variable; viewdef binding paths create the rest by reaching into backend objects. - **Simple paths.** Properties, indexing, methods. No operators. - **Vanilla Lua tables.** `prototype` tracks the schema and all instances (via weak refs); on hot-reload it detects schema changes and calls `mutate()` on every instance. Fields prefixed with `_` are private — not serialized to the frontend. - **Viewdefs present objects.** Factoring the object model breaks large viewdefs into smaller ones. Viewdef namespaces select different presentations for the same object. - **Domain vs Presenter.** Domain objects hold data and core behavior; presenter objects add UI state and actions (e.g., `delete()`, `isEditing`). - **Three execution contexts:** Lua (all behavior whenever possible — fast, responsive), JS (browser APIs, DOM tricks — last resort), Claude (complex logic, external APIs — slow, event loop latency). - **The event loop** (reactivity without subscriptions or signals): 1. User makes a change in the browser 2. Frontend sends variable update to server (binding paths are variables) 3. Server applies the update 4. Server checks ALL variables for changes (including method paths, which are recomputed) 5. Server sends updates only for variables whose values changed 6. Frontend applies updates to the UI This drives a key pattern: bind a method path to a backend computation, make a change on the frontend, the method fires during the variable check, and the frontend receives the result. Variables have `priority` (low/medium/high) because evaluation order can matter for dependent computations or frontend widget updates. ## Core Principles 1. **Use SOLID principles** 2. **Write idiomatic Lua code** ## Why design.md `requirements.md` is the user's spec — what they want. `design.md` is Claude's interpretation — a compact intermediate form between requirements and code that serves multiple roles: - **Verification:** Smaller than code+viewdefs, so the user can quickly read it and confirm their requirements were understood before code is written - **Preview:** Warns the user what Claude is about to do with the code - **Reference:** Quick lookup for event handling, data model, and methods - **Anchor:** Without it, iterative modifications cause **drift** — features silently disappear as code evolves. The `/ui-fast` and `/ui-thorough` workflows enforce: read design → update design → update code → verify against design. This is a 3-level architecture (as with `/mini-spec`): requirements → design → code. Each level is a progressively more detailed reification of the user's intent. ## File Operations **ALWAYS use the Write tool** to create/update files. Do NOT use Bash heredocs. --- # Reactivity & Session Lifecycle ## Hot-Loading Both Lua and viewdefs hot-load from disk: - `apps//app.lua` → re-executed, preserving state - `apps//viewdefs/` → browser updates automatically **Write order matters:** Code first, then viewdefs. ## Change Detection Details - **Arrays:** Compared by-element. In-place mutations (`table.insert`, `table.remove`) are detected — no need to reassign. - **`session.reloading`** is only true for hot-reload (file changes), NOT browser page reloads. - **`ui-code` re-fires on page reload.** Clear `ui-code` properties when their action is complete to prevent stale re-fires. ## Side-Effect Dependencies Between Bindings When one binding's method has a **side effect** (mutating a field on another object) that a second binding reads, you **must** use `priority` to guarantee evaluation order. Without it, the reading binding may evaluate before the writing binding in any given cycle, producing stale values. **Example:** `columns()` computes match counts on FilterChip objects. `chipClass()` reads those counts to determine styling. If `chipClass()` evaluates before `columns()`, it sees stale counts. **Fix:** Give the writing binding higher priority: ```html
``` This is not a visibility issue (public vs private fields) — it's an ordering issue. Making a field public may appear to fix it by accident, but the evaluation order is still undefined without priority. Use priority whenever a binding has downstream dependents. --- # Object Model **App directory structure:** ``` apps/my-app/ ├── app.lua # Main code (loads when user first displays the app) ├── init.lua # Optional startup code (loads on server start) ├── viewdefs/ # HTML viewdefs for this app's types │ ├── MyApp.DEFAULT.html │ └── MyApp.Item.list-item.html ├── icon.html # App icon (Bootstrap Icon) ├── favicon.svg # Browser tab icon └── README.md # App description {ui_dir}/storage/my-app/ # Optional local storage (isolated from app updates) {ui_dir}/html/my-app # Symlink to app dir (serves static files at /my-app/) {ui_dir}/html/my-app-storage # Symlink to storage dir (serves at /my-app-storage/) ``` Use `require("appname.module")` to split code into multiple files (see `mcp` app for examples). ```lua -- App type name is PascalCase; instance global is camelCase of the type name MyApp = session:prototype("MyApp", { items = EMPTY, -- EMPTY: starts nil, tracked for mutation name = "" }) -- Nested prototypes use dotted names MyApp.Item = session:prototype("MyApp.Item", { name = "" }) local Item = MyApp.Item -- local shortcut function MyApp:new(instance) instance = session:create(MyApp, instance) instance.items = instance.items or {} return instance end -- Guard instance creation (idempotent) if not session.reloading then myApp = MyApp:new() -- camelCase instance global end ``` **Key points:** - `session:prototype(name)` sets the `type` field for viewdef resolution - `session.reloading` is true during hot-reload - Each app defines a PascalCase type (`MyApp`) and a camelCase instance (`myApp`) ## Lua Gotchas **Forward references:** `local function` is not visible until the interpreter reaches it. Methods on prototypes (`function MyApp:foo()`) resolve at call time, but `local function helper()` must be defined *above* any code that calls it. If you get `attempt to call a non-function object`, check definition order. **Colon vs dot:** `function MyApp:save()` defines a method — `self` is the implicit first argument. `function MyApp.helper()` defines a plain function on the table — no `self`. Calling `obj:save()` passes `obj` as `self`; calling `obj.helper()` does not. Mixing them up causes subtle bugs: defining with `.` and calling with `:` shifts all arguments by one. **1-based indexing:** Lua arrays start at 1, not 0. `#t` returns the length, `ipairs` iterates from 1. But binding paths in viewdefs are 0-based (`items.0`, `items.1`) — the engine translates. Don't mix these up when working across Lua and viewdefs. ## Hot-Loading Mutations When adding fields to a prototype, `mutate()` updates all live instances to match the new schema: ```lua MyApp = session:prototype("MyApp", { items = EMPTY, newField = EMPTY -- NEW field }) function MyApp:mutate() if self.newField == nil then self.newField = {} end end ``` **Key rules:** - **Mutation must be the last change to a file.** Hot-loading is very fast — making mutation the final edit ensures prototype and `mutate()` arrive together in one hot-load. - **Overwrite `mutate()`, don't accumulate.** Each `mutate()` only handles the current delta — once an instance has been mutated, it already has the field. - **Use atomic writes** when the user may be interacting with the app: ```bash cp app.lua app.lua.tmp # Edit tmp mv app.lua.tmp app.lua # Atomic replace ``` ## Variable Wrappers The `?wrapper=TypeName` property transforms a variable's value through a Lua type. ViewList is a built-in wrapper for arrays. ```lua MyWrapper = session:prototype("MyWrapper", { variable = EMPTY, -- the Variable object value = EMPTY, -- convenience: variable's current value }) function MyWrapper:new(variable) local existing = variable:getWrapper() if existing then existing.value = variable:getValue() return existing end local wrapper = session:create(MyWrapper) wrapper.variable = variable wrapper.value = variable:getValue() return wrapper end ``` The wrapper receives the **variable** (not just the value). Check `variable:getWrapper()` to reuse existing wrappers and preserve state. Child paths navigate from the wrapper object. --- # Bindings | Attribute | Purpose | Example | |-----------|---------|---------| | `ui-value` | Bind value/text | `` | | `ui-action` | Button click | `` | | `ui-event-click` | Any element click | `
` | | `ui-event-*` | Any event | `` | | `ui-event-keypress-*` | Specific key | `` | | `ui-event-keypress-ctrl-*` | Key + modifiers | `` (also `shift`, `alt`, `meta`) | | `ui-view` | Render child/list | `
` | | `ui-attr-*` | HTML attribute | `` | | `ui-class-*` | CSS class toggle | `
` | | `ui-style-*` | CSS style | `
` | | `ui-html` | Inject HTML content | `
` (use `?replace` to replace the element itself) | | `ui-code` | Run JS from property | `
` — binds to a property containing JS, not inline code | | `ui-namespace` | Set viewdef namespace | `
` | ## Common Mistakes | Wrong | Right | |-------|-------| | `ui-action="fn()"` on div | `ui-event-click="fn()"` on div | | `ui-class="hidden:expr"` | `ui-class-hidden="expr"` | | `` | `` | | `` | `` (sl-change doesn't fire) | | `