Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

quickshell/nuguland/.system/specs/NL-SPEC-VQXGUHYK-zen-of-nugu/index.md

Raw
Rendered preview

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

  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.

---
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.