1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
#+TITLE: Transient state-buttons
#+SLUG: transient-state-buttons
#+PRINCIPLE: Put all the levers in one place with their current state and key bindings visible, reachable by one chord from anywhere.
#+PROBLEM: Scattered commands with invisible state force the user to remember what's toggled and which key does what.
#+TAGS: transient menu ui affordances state
#+SOURCE: Craig's magit transient.el reference, handoff note 2026-05-27
#+EXAMPLES: magit transient.el, pearl pearl-menu (C-; L m)
* Problem
A feature accumulates several toggles and actions, each on its own command and keybinding. The state lives in variables the user can't see, and the keys live in muscle memory or a manual. The user has to remember what's currently on and which chord flips it.
* Do
A single popup (magit's =transient.el= is the reference implementation) that shows every lever as a button row: the current state of each toggle, the key that flips it printed inline, summoned by one chord from anywhere. All the affordances are visible at once, and nothing about the current state is hidden.
This is the "all the levers in one place, affordances visible, one chord to get there" shape. The everyday analogue is the music-player transport bar: play, pause, shuffle, repeat state all shown, all reachable.
* Anti-pattern
A set of independent commands whose combined state is invisible, where the user learns what's toggled only by triggering something and watching what happens.
* Applicability
Worth it when a feature has three or more pieces of toggleable state or a cluster of related actions. Overkill for a single command with no state. A light transient (a command menu with no state shown) is a partial step. The full value comes from showing toggle state in the buttons, not just listing actions.
* Related
The visible-affordances half of the root principle (see [[file:README.org][README]]), applied to a control surface rather than a single prompt.
|
