From acd3c0c78bf800f092b8a6971e1fecf77f4d3040 Mon Sep 17 00:00:00 2001 From: vickydotbat Date: Sat, 1 Aug 2026 20:23:34 +0200 Subject: [PATCH] ui design 101 skill --- .agents/skills/ui-design-101/SKILL.md | 133 ++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 .agents/skills/ui-design-101/SKILL.md diff --git a/.agents/skills/ui-design-101/SKILL.md b/.agents/skills/ui-design-101/SKILL.md new file mode 100644 index 0000000..52da8b7 --- /dev/null +++ b/.agents/skills/ui-design-101/SKILL.md @@ -0,0 +1,133 @@ +--- +name: ui-design-101 +description: Design the actions in an interface — buttons, confirmations, destructive operations, bulk edits, admin and moderation tools. Use when building or reviewing anything a user clicks repeatedly, anything that deletes or hides data, any list of rows with per-row actions, or when the user says a tool is tedious, asks for a confirmation dialog, or reports an interface that "does nothing". +--- + +# UI Design 101: actions + +Visual design is a different skill. This one is about what happens when someone +clicks — and, above all, what happens when they click **the hundredth time**. + +Every rule here is a checkable property of an interface. Apply all of them to +whatever you are building; an interface that fails any one of them is not done. + +## Price every action at its hundredth use + +Design for the hundredth click, not the first. An extra dialog, an extra +scroll, an extra page load is nothing once and unbearable a hundred times. Ask +directly: how many times will one person do this in one sitting? If the answer +is more than a handful, the per-use cost is the whole design problem. + +The failure has a shape: a tool that is *pleasant to demo and brutal to use*. +Nobody notices it while building, because builders click things twice. + +## Ceremony follows reversibility + +Undo beats confirm. A confirmation asks the user to be certain in advance; an +undo lets them be wrong cheaply. Prefer the second. + +- **Reversible action** (hide, archive, mark, tag): no confirmation. Ever. Do + it, show it happened, offer the undo in the same spot. +- **Irreversible action** (purge, permanent delete, send, publish): confirm + once, and say plainly that it cannot be undone. + +Ceremony on a reversible action is worse than useless: it trains the user to +dismiss dialogs without reading, so the one dialog that matters gets dismissed +too. + +## Spend one confirmation per intent + +The confirmation budget is per *intent*, not per *item*. A user removing a +hundred things decided once; charge them once. A hundred dialogs for a hundred +items is the same as no dialogs at all, minus an hour of their life. + +When one confirmation covers many items, make it carry its weight: name the +scope and the exact count ("Purge 143 pages in Skills — this cannot be +undone"), and for the genuinely dangerous ones, require typing something +deliberate rather than a single click. + +## Let the reversible state be the selection + +Where a flow is *choose many, then commit*, the reversible action is the +selection mechanism. Mark → review → commit. No parallel checkbox concept +required. + +Marking beats checkboxes on properties, not just tokens: the marks survive a +reload, they are visible to a colleague looking at the same screen, they can be +undone one at a time, and the user sees the staged set accumulate as they go. + +## Act in place + +An action reports its result where the user is standing. Re-render the row, the +card, the item. Keep scroll position, keep focus, keep their place in a long +list. + +A full page reload after each action is a scroll-position bug wearing a +navigation costume. If the user must find their place again after every click, +the hundredth click costs a hundred scrolls. + +## Make silence impossible + +Every action ends in an observable outcome: success shown, or failure shown +with a reason. An action that can quietly do nothing is the worst bug class in +interface design, because the user keeps working and only later discovers that +none of it happened. + +Own your dialogs for the same reason. Browsers let a user permanently suppress +native `alert`/`confirm`/`prompt` dialogs ("prevent this page from creating +additional dialogs"). Code that reads a suppressed `confirm` sees "cancelled" +and correctly does nothing — forever, silently, until a reload. Use the +platform's or framework's own modal component so the confirmation is yours to +control. + +## Give bulk work a bulk path + +Wherever the data can hold hundreds of items, the interface offers an action +over the whole set — a filtered set, a marked set, or a namespace. A per-item +action is not a bulk feature no matter how fast the loop. + +Bulk operations are partial by nature. Design for it up front: + +- Process items independently; one failure does not abandon the rest. +- Report per item: succeeded, failed with a reason, skipped with a reason. +- Show progress while it runs, and let the user cancel between items. +- Leave every item either fully done or fully untouched — never half-applied. +- Chunk the work so a large set cannot time out the request. + +## Finish the user's job + +Match the actions to the *goal*, not to the data model. If the user's goal is +"make this gone" and the tool only offers "make this quiet", the tool is +incomplete even though every button works. Hidden is not deleted; unpublished +is not removed; archived is not gone. + +Where a two-step model exists for safety (hide, then remove), both steps belong +on the screen where the work happens. A second step reachable only from a +different page, one item at a time, is a step that will not be taken. + +## Show the outstanding work + +Surface the counts that tell the user how much is left: how many items are +marked, how many remain, how many failed. A cleanup task needs a visible +ending, otherwise it is just scrolling. + +## Explain a missing action + +When a control is absent because of a permission, a state, or a rule, say so in +its place. An unexplained gap reads as a bug and sends the user hunting. State +the reason and, where there is one, the path to earning the action. + +## Design check + +Before calling an interface done, walk it as a user with a hundred items: + +1. Count the interactions for one item. Multiply by a hundred. Is that a + working afternoon? +2. Which actions prompt? Is every one of them irreversible? +3. Which actions are irreversible? Does each state that plainly, once, with the + count? +4. After each action, did the user keep their place? +5. Can any action fail silently? What does the user see when it does? +6. Is there a path that handles the whole set in one decision? +7. Does the tool reach the user's actual goal, or stop at the model's halfway + state?