---
name: makepad-ui-craft
description: Emil Kowalski + Jakub Krehel design-engineering doctrine translated to Makepad 2.0 (script_mod! DSL, Animator, Ease). Use when building or reviewing any Makepad UI — buttons, sheets, toasts, drawers, page transitions, hover/press states, radii, shadows, typography, color tokens. Kills AI-slop UI: state snaps, missing press feedback, ease-in, scale(0) entries, mismatched nested radii.
---

# Makepad UI Craft

Interfaces feel great because of a pile of small, mostly invisible details that compound.
In a world where everyone's software is *good enough*, this is the differentiator. Every rule
below is a specific value, not a range to approximate — `0.96` is not `0.95`.

**The Makepad ground rule that changes everything:** Makepad's `Animator` retargets from the
*current* interpolated value when you `animator_play` a new state — like CSS transitions, not
keyframes. Every animator-driven state change is interruptible by construction. `set_visible`,
`script_apply_eval!` of a final value, and `refresh_chrome`-style full snaps are the Makepad
equivalents of "no transition at all" — they are the #1 slop tell in this codebase family.

## 1. The Animation Decision Framework (Emil)

Answer these **in order** before writing any animation:

### 1a. Should it animate at all?

| Frequency | Decision |
|---|---|
| 100+ times/day (keyboard shortcuts, command-palette toggle, canvas pan/zoom) | **No animation. Ever.** |
| Tens of times/day (hover, list navigation, tab/page switches in a work tool) | Remove or drastically reduce — instant feedback or ≤0.15s opacity/color |
| Occasional (modals, sheets, drawers, toasts) | Standard animation |
| Rare / first-time (onboarding, success, empty states) | Can add delight, stagger, springs |

**Never animate keyboard-initiated actions.** **Direct-manipulation must track 1:1** — pan, zoom-at-cursor,
and drag follow the pointer with zero smoothing (the koboyo canvas is correct to be instant while
dragging). But *button-triggered camera jumps* (zoom-to-fit, reset-zoom) are occasional → animate them.

### 1b. What's the purpose?

Valid: spatial consistency, state indication, feedback, preventing jarring appearance/disappearance,
explanation. Invalid: "looks cool" on anything seen often. Motion is **never the only feedback
channel** (Jakub) — every animated state change also needs a static cue (color, icon, label) so it
reads when the animation doesn't run.

### 1c. What easing?

Decision order (Makepad names — full table in [EASING.md](EASING.md)):

- Entering or exiting → **`OutQuart`** or `Ease.Bezier {cp0: 0.23, cp1: 1.0, cp2: 0.32, cp3: 1.0}` (starts fast — the frame the user is watching)
- Moving/morphing on screen → **`InOutCubic`** / `Ease.Bezier {cp0: 0.77, cp1: 0.0, cp2: 0.175, cp3: 1.0}`
- Hover / color mix → **`OutQuad`** (what upstream `check_box.rs` ships)
- Constant motion (spinner, marquee, `Loop`) → **`Linear`**
- Momentum / "alive" settle → **`Ease.ExpDecay {d1: 0.82, d2: 0.97}`** (upstream `file_tree.rs`/`fold_button.rs` range: d1 0.80–0.98, d2 0.95–0.97)

**Never `In*` easing on UI.** `InQuad` at 0.3s *feels* slower than `OutQuad` at 0.3s because it
delays the initial movement. The default built-ins are weak; prefer `OutQuart`/`OutQuint`/`OutExp`
or an explicit `Bezier` for punch.

### 1d. How fast?

Makepad `Play::Forward {duration}` is in **seconds**:

| Element | Duration |
|---|---|
| Press feedback (down) | `Snap` (instant) on press, `0.1–0.16` on release |
| Hover on/off | `0.0–0.1` |
| Tooltips, small popovers | `0.125–0.2` |
| Dropdowns, drawers (side), selects | `0.15–0.25` |
| Modals, bottom sheets, toasts | `0.2–0.5` |
| **Hard ceiling for UI** | **0.3** (only sheets/modals may reach 0.5) |

## 2. Press, hover, focus — the responsiveness contract (Emil + Apple)

- **Respond on finger-down, not on release.** Visual feedback fires on `Hit::FingerDown`;
  the *action commits* on `Hit::FingerUp` **only if the pointer is still over the widget**
  (`is_over`), so users can cancel by dragging away. Committing the action itself on FingerDown
  breaks tap-cancel and is a HIGH finding.
- **Every pressable scales to `0.96` while held.** In Makepad, scale in the SDF shader via a
  `down` instance — never via layout. Enter the down state with `snap(1.0)` (instant), leave it
  with `Forward {duration: 0.15}` + `OutQuad` (asymmetric: press instant, release eased).
  See [RECIPES.md §1](RECIPES.md).
- Hover states change color/opacity only, `≤0.1s`. Gate hover to pointer devices if the app
  targets touch.
- Upstream `Button` in `widgets/src/button.rs` already ships the canonical 3-state
  `hover/on/down` track with `snap(1.0)` entries and `0.1s` exits — copy its structure, don't
  reinvent.

## 3. Enter / exit (Emil + Jakub)

- **Nothing appears from nothing.** Entries start at `opacity 0` + `scale 0.95–0.97` (icon swaps
  may go to 0.25), never `scale 0`, never a visibility pop. In Makepad: animate `draw_bg`/`draw_text`
  instances; `set_visible(true)` then immediately `animator_play(enter.on)`.
- **Exits are subtler and faster than enters.** Small fixed offset (8–12px equivalent), fade,
  `OutQuad`, ~60–70% of the enter duration. Same direction as the enter (spatial consistency —
  a toast that rises from the bottom leaves toward the bottom).
- **Origin-aware growth:** popovers/menus scale from their trigger corner, not center. In SDF space,
  scale around the anchor point instead of `rect_size * 0.5`. Modals are exempt (stay centered).
- **Stagger** infrequent staged entrances (first load of a screen, success/empty states) by
  0.03–0.08s per item — in Makepad use per-item `Play::Forward` start via timer, or a shared
  clock instance + per-item delay uniform. Never stagger routine interactions; never block input
  while a stagger plays.
- **Skip enter animations on app boot** for elements already in their default state (Jakub's
  `initial={false}`): `animator_cut` to the resting state at startup, `animator_play` only on
  later changes.

## 4. Gestures, sheets, momentum (Apple, translated)

The insurance sheet's 1:1 drag with thresholds is the right start. The full contract:

1. **1:1 tracking with grab-offset.** Content sticks to the finger measured from where it was
   grabbed. Use `event.hits_with_capture_overload` so the drag survives leaving the widget bounds
   (pointer capture). Ignore extra touch points after the drag starts.
2. **Velocity history.** Keep the last few (position, time) samples; you need release velocity.
3. **Momentum projection.** Don't snap to the nearest state from the release *point* — project:
   `projected = pos + (v / 1000.0) * rate / (1.0 - rate)` with `rate = 0.998` (0.99 = snappier),
   then pick the snap target nearest the projection.
4. **Velocity handoff.** The settle animation starts at the finger's velocity — no seam between
   drag and animation. Makepad has this built: `rubber_band_bounce(x0, v0, t, touch)` in
   `widgets/src/scroll_motion.rs`, or run an `ExpDecay` from the current value (the animator always
   starts from the *presentation* value, which is the other half of this rule).
5. **Rubber-band past boundaries.** `over * dim * 0.55 / (dim + 0.55 * |over|)` — resistance, not
   a wall.
6. **Interruptible mid-settle.** A new `FingerDown` during the settle grabs the sheet at its
   current position. Never lock input during a transition.
7. Damping defaults: no bounce for UI that just appears; slight bounce (`d1` closer to 0.9, or a
   small overshoot) *only* when the user's gesture carried momentum.

## 5. Surfaces (Jakub)

- **Concentric radii:** `outer_radius = inner_radius + padding` for nested `RoundedView`s with a
  visible even inset. Equal radii on parent and child is the single most common "feels off".
  Past ~24px padding, treat layers as independent.
- **Shadows for elevation, borders for structure.** A border that exists only to fake depth →
  layered translucent shadow. Keep borders that mean something (dividers, selected, focus).
- **Images/avatars get a 1px outline** at 10% opacity — pure black in light mode, pure white in
  dark, never a tinted neutral.
- **Optical alignment beats geometric.** Icon-side padding = text-side padding − 2px; nudge
  glyphs (play triangles, chevrons) that look off-center.
- **Hit areas:** ≥44×44 logical px on touch, ≥40×40 in dense desktop UI. Extend the hit rect
  beyond the visible rect (Makepad: padding on the handling view), and never let two hit areas
  overlap.

## 6. Color (Jakub)

- **Tokens, not hex.** Components reference semantic roles (`theme.color_bg_app`,
  `theme.color_text_secondary`-style), primitives live in one place. A screen full of literal
  `#7b5cf6` is unthemable and unreviewable — put shared brand values in the `script_mod!` `mod`
  object or theme and reference them.
- One neutral ramp + one accent ramp + only the status ramps actually rendered. Each step exists
  because a role needs it. One color = one meaning.
- Never report a contrast ratio you didn't compute.

## 7. Typography (Emil/Apple + Jakub)

- Tracking is size-specific: slightly negative on large display text, slightly positive on small
  uppercase labels, ~0 for body. Line-height: ~1.1 headings, 1.5–1.6 body, ≥1.4 for anything
  wrapping to 3+ lines.
- Hierarchy = weight + size + leading as a set. Below 18px stay at weight ≥400.
- Tabular figures for anything that ticks (timers, prices, counts) so digits don't shift layout;
  use `…` (the character), not `...`.
- Cap line length ~60–75ch for reading text.
- **Emoji are not icons.** They carry no stroke weight, ignore your palette, and render
  differently per platform. Use SDF-drawn glyphs or an icon set; recolor per state via one
  drawn asset (the `currentColor` rule), outline by default, fill = active.

## 8. Performance (Makepad-specific)

- **Animate shader instances, not layout.** `draw_bg: {t: instance(0.0)}` costs a uniform update
  + repaint; animating `width`/`height`/`margin`/`padding` re-runs layout every frame. For
  high-frequency motion keep it in the `pixel`/`vertex` fn. Occasional sheet/drawer position
  changes may animate walk values — that's the Makepad analog of "transform/opacity only,
  except where you must".
- Respect the `#[repr(C)]`/`#[deref]` field-ordering rule for draw structs (AGENTS.md §16) — a
  misplaced `#[rust]` field corrupts the instance buffer.
- `Loop` tracks run forever; make sure idle screens don't keep a redraw loop alive.

## 9. Reduced motion

There is no OS media-query in Makepad — **own it**: a `reduce_motion: bool` in the app/theme.
When set, replace movement with short cross-fades: same state changes via `animator_cut` (or a
0.1–0.2s opacity-only track), drop overshoot/bounce, keep color/opacity cues. Reduced ≠ zero.

## 10. Review protocol (mandatory format)

When reviewing UI code with this skill, replay interactions mentally at 10% speed and walk every
state: hover, focus, down, loading, empty, error. Findings MUST be a markdown table:

| Severity | Location | Before | After | Why |
| --- | --- | --- | --- | --- |

- `Location` is `path/file.rs:line`. `Why` names the violated principle + user impact.
- Severity: **HIGH** = broken interaction / state change visible only via motion / commit-on-down.
  **MEDIUM** = visible inconsistency (snap where a transition belongs, radius clash). **LOW** = polish.
- One row per root cause, listing every occurrence. End with **Block** (any HIGH) or **Approve**.
- Report anything you couldn't verify as `Not verified`. Never approve coverage you didn't inspect.
- Also say what's already right — restraint that's correct (e.g. unanimated high-frequency
  actions) must not be "fixed".

## Quick slop checklist

| Tell | Fix |
|---|---|
| `set_visible` toggling a toast/sheet/panel | Enter/exit animator track (RECIPES §3) |
| Action commits on `FingerDown` | Feedback on down, commit on up-if-over |
| No `down` state on a pressable | `0.96` shader scale, snap in / 0.15s out |
| `In*` ease anywhere user-facing | `Out*` or Bezier equivalent |
| Entry from nothing (alpha 0→1 only counts) | scale `0.95` + fade, origin-aware |
| Same radius on nested rounded views | outer = inner + padding |
| Release-position snapping on a drag | project momentum, hand off velocity |
| Hex literals per-widget | semantic theme tokens |
| Emoji as UI icons | drawn glyphs, one asset recolored per state |
| Everything animates on boot | `animator_cut` to resting state at startup |