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: compact, icon-led, one control language, Nugu palette, lowercase.
Sources and their disagreements: research digest. Round-table results and open owner decisions: rounds.
The zen
glance, then go. The bar answers one question at a glance: does anything need me? Chips show state only when it matters.
one task per surface. Each popup leads with its primary task; secondary detail waits behind disclosure.
quiet by default. Neutral surfaces, one accent; colour, borders, badges and motion are spent on state, never on decoration.
few words, human words. Lowercase, short, specific; verbs on actions, nouns on toggles; no jargon, filler or jokes.
tell the truth about state. Pending, done, failed, stale and unavailable look different; nothing pretends to finish.
the keyboard is home. Every action is reachable and visible by keyboard; focus enters where the task starts and returns where it came from.
calm pointer. Large, spaced targets; nothing hides behind hover; hovering never steals the task.
motion explains, never delays. Short, cancellable, absent in low-power mode, never perpetual without ongoing work.
leaving loses nothing. Dismissal is not discard; armed danger disarms when you leave.
interrupt only for what matters. Overlays echo what you just did; toasts report what happened elsewhere; routine success stays silent.
empty is a state, not a hole. Empty, loading, unavailable and error states are designed and offer the next step.
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.
fit the frame. Content never clips or overflows; surfaces fit 1366×768 and 2560×1440 with a horizontal or vertical bar.
colour never alone. State pairs colour with an icon, text or shape, at legible contrast.
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;
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.
---
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.