--- id: NL-SPEC-VQXGUHYK type: spec title: Zen of Nugu --- # Zen of Nugu The user experience law of every Nuguland surface: bar, chips, popups, overlays, toasts, lock and authentication. Distilled on 2026-11-14 from the GNOME and KDE human interface guidelines, Apple and Microsoft desktop guidance, the Nielsen Norman heuristics and WCAG 2.2, filtered through the owner-approved direction in [popup interaction language](../NL-SPEC-38AED50A-popup-interaction-language/index.md): compact, icon-led, one control language, Nugu palette, lowercase. Sources and their disagreements: [research digest](research-digest.md). Round-table results and open owner decisions: [rounds](rounds.md). ## The zen 1. **glance, then go.** The bar answers one question at a glance: does anything need me? Chips show state only when it matters. 2. **one task per surface.** Each popup leads with its primary task; secondary detail waits behind disclosure. 3. **quiet by default.** Neutral surfaces, one accent; colour, borders, badges and motion are spent on state, never on decoration. 4. **few words, human words.** Lowercase, short, specific; verbs on actions, nouns on toggles; no jargon, filler or jokes. 5. **tell the truth about state.** Pending, done, failed, stale and unavailable look different; nothing pretends to finish. 6. **the keyboard is home.** Every action is reachable and visible by keyboard; focus enters where the task starts and returns where it came from. 7. **calm pointer.** Large, spaced targets; nothing hides behind hover; hovering never steals the task. 8. **motion explains, never delays.** Short, cancellable, absent in low-power mode, never perpetual without ongoing work. 9. **leaving loses nothing.** Dismissal is not discard; armed danger disarms when you leave. 10. **interrupt only for what matters.** Overlays echo what you just did; toasts report what happened elsewhere; routine success stays silent. 11. **empty is a state, not a hole.** Empty, loading, unavailable and error states are designed and offer the next step. 12. **same thing, same look.** One spacing scale, one radius family, one icon size per role, shared controls; an icon always has a tooltip and an accessible name. 13. **fit the frame.** Content never clips or overflows; surfaces fit 1366×768 and 2560×1440 with a horizontal or vertical bar. 14. **colour never alone.** State pairs colour with an icon, text or shape, at legible contrast. 15. **light on the machine.** Hidden surfaces cost nothing: no polling, animation or process work for what nobody sees. ## Rules Each rule is checkable on a rendered screenshot, a suite run or the source; numbers in parentheses refer to the zen. - Labels, tooltips and accessible names are lowercase, at most three words for actions, no terminal periods, no acronyms where a plain word exists, no placeholder or joke text (4). - No label, title, tooltip, accessible name, OSD, toast or notification card shows a machine identifier: temp or runtime paths, file uris, uuids, hashes, generated names, bus names and object paths, desktop ids, audio node names, device paths or hardware addresses; it shows the human name, else the kind, e.g. image, file, app or device (4). - Buttons are verbs, toggles are nouns or states; a panel has at most one primary and one destructive action visible (2, 4). - No subtitle repeats its title, the chip, or obvious context (3, 4). - No line, tooltip or accessible name narrates what the interface cannot do or explains it: a control the source can never perform is absent; a control off for a passing state names a short reason in its tooltip; only whole-surface empty, unavailable and error states keep their one sentence and next step (2, 4, 11). - Bar chips: a dot for activity, strong emphasis only for needs-attention, a busy line only while work runs; no chip label changes width on routine updates (1, 3). - Pending work shows within 1 s and states its scope; failures name the problem and the next step in the panel, not only in a toast (5, 11). - Stale data is marked stale; unavailable hardware or services say so in words (5, 11). - Every pointer action has a keyboard path: Tab and Shift+Tab traverse, arrows move within lists and grids, Enter and Space activate, Escape closes; focus is always visible (6). - Search tasks focus their field on open; other popups focus their primary control (6). - Targets are at least 24×24 px with spacing; no action appears only on hover (7). - Transitions last at most 250 ms and are skipped in low-power mode; nothing loops while its surface is idle; a progress or time-left indicator may move for as long as its work lasts (8). - Drafts, selection, expansion and scroll survive close, switch and reopen; destructive confirmations cancel on every dismissal (9). - OSD appears only for user-initiated changes; toasts carry no routine success; critical notifications persist (10). - Empty, loading, unavailable and error states have a sentence and, where one exists, an action; no empty table headers or blank cards (11). - Spacing comes from the theme scale; one radius per surface level; icons 16 px inline and 20–24 px for icon-only buttons (12). - Icon-only controls have a tooltip and an accessible name (12). - Long names elide or wrap inside their region; every action stays reachable by scrolling or disclosure at 1366×768, horizontal and vertical bar (13). - Status never relies on colour alone; text contrast at least 4.5:1, controls and focus rings at least 3:1 (14). - Closed popups run no polling timers or processes beyond what their bar chip shows (15). ## Precedence House law outranks the sources where they disagree: - labels stay lowercase, unlike GNOME, KDE and Apple capitalisation; - the tray chip stays in the bar, unlike KDE's attention-only tray icons; - keep-awake (idle) and do not disturb take strong emphasis while active, because a forgotten inhibitor costs sleep or alerts; - chip order follows usage across sessions and never changes within one; - the aurora backdrop is wallpaper, outside the motion rules for UI surfaces; - system's repair action stays `arrrgh` (owner decision 2026-11-14); - a feature spec outranks this law where it is explicit; the conflict is listed in the round report for the owner to resolve; - Escape, outside click and the same chip close a popup; one click on another chip switches. ## Acceptance A round table of two judges from different model families scores every feature 0–2 per zen principle from rendered screenshots, suite results and source. A feature passes when no principle scores 0 from either judge and each judge's mean is at least 1.7. The zen is achieved when every feature passes in the same round, `just lint` and the full `just ui-test` are green, the agent reviewed the screenshots, and the owner accepts it on the live desktop. At most three rounds; remaining dissent is reported, not averaged away.