bring forward more docs about focus, and about visual regularity.
commit 47bdc80a460a89bc924e509ee7376d8532f4a30c · parent 14d48af967
· browse this tree
warpfork, 2026-10-10 03:50:20 UTC
there was a really funny joke in the previous unreleased version of this doc about "rows are rows" as a pun on "rules are rules", but... it was probably only funny or legible to me, so. i am my own fun police. it's gone now.
diff --git a/docs/precepts-aesthetics.md b/docs/precepts-aesthetics.md index f801e7b..de5fb74 100644 --- a/docs/precepts-aesthetics.md +++ b/docs/precepts-aesthetics.md @@ -7,3 +7,27 @@ Aesthetically, yukey should feel: - Very SCADA - Very functional/brutalist - ... but it's always ready to explain itself. + +And things should have a visual "cadence", +and it should be regular. + +At a high level, that's the vibe. + + +Nitty Gritty Details +-------------------- + +### content of a row has consistent width and fills its container + +... and this explicitly includes the focus box. + +It is visually distressing for the focus box to be erratically sized from one row to the next. + +So: + +- The focusable unit in data rows is sized **consistently, by the container** -- + never by struggle-hugging whatever content happens to be inside. +- Rows in one set of components should generally be the same height and the same width. + (Mechanically: the focus box being drawn on any two neighbors should mean drawing the same shape at the same size, just in a coordinate offset on a single axis.) +- Tabular data should be tabular: columns align, etc; + and like the rules for rows, so too it still applies that the focus box should be regularly and unsurprisingly sized for neighboring elements for tables. diff --git a/docs/precepts-we-love-the-keyboard.md b/docs/precepts-we-love-the-keyboard.md index 2ae3205..6208ec8 100644 --- a/docs/precepts-we-love-the-keyboard.md +++ b/docs/precepts-we-love-the-keyboard.md @@ -273,3 +273,68 @@ It would probably look terrible! And all those decades of UX researchers about "no more than one input region per row" would also be rolling over in their graves! The thing that's hard to do is a thing we shouldn't do anyway; copacetic. + + + +Focus containment and lifecycle +------------------------------- + +Yukey has a concept of "focus" that is... mostly the normal one. +But we have a lot more ways to move it around, rapidly. + + +### Focus is spatial within containers + +This has already been hammered a lot in this document: +the arrow keys generally do what you'd expect, spatially. + +Megacolumns do this, etc, etc. + + +### Focus is tabindex between containers + +When there's top level Yukey components, they have tabindex focus. + +So, if you put two megacolumns next to each other, +you can tab between them. + +Each such component remembers where the focus was inside itself, +so if you tab back to it, the focus is... where it was. + + +### Focus is a stack within complex elements or modals + +Where there are nested components that can receive focus, +or where modals are used, then +focus acts like a stack that is pushed and popped. + +(Modals are... modals. You know them when you see them. +The most common example of nested components that can receive focus, +if you're following our suggestion to accept the megacolumn into your heart +rather than overuse nesting for complex components, +is probably text edit elements.) + +So in mechanical detail: + +- Activating a component that can receive focus pushes onto the stack, + recording the place focus came from. +- Disengaging that component is a pop: focus returns to where it came from + (the row that opened the card, the summary row that popped the overlay, whatever). +- Pop targets can die (the opener unmounted, the row vanished): + in that case, pop skips dead entries and keeps unwinding to the nearest live one. +- The number of times focus should land on "nothing" approximately zero. + Focus falling to `<body>` is pretty much always a bug, unless truly every piece of UI is gone. +- When a component is created by some activation event, that new component should (probably) cause a focus push and receive the focus. + If the user's action summoned it, their attention is on it; focus follows attention. + (Conversely, passive appearances -- data arriving, ambient updates -- should never steal focus. + If it did, that would be effectively a race condition in the UI, which we abhor.) +- Disengaging a component that's a modal generally closes it. +- The Escape key always has the job of disengaging focus from a component (causing a pop). + (The Escape key *always* has this job; the user should never have to hunt for a close or disengage affordance.) + + +### misc focus details + +- **The Tab key should not leave the page and wander into browser chrome.** + It's odd to me that this is normal in (some?) browsers. I've never in my life wanted it. + Yukey makes Tab navigation confined to the page by default.