Every registered popup uses one common outer surface.
Matching UI roles use common sections, cards, buttons, toggles, separators, sliders, badges, and text fields.
Controls visibly distinguish hover, press, focus, selected or toggled, and disabled states.
Status is never communicated by color alone.
Cards provide large targets, visible status, and optional secondary detail.
Spacing and common regions provide grouping; dividers separate only unrelated groups.
All UI labels are lowercase.
Tray cards expose all nonempty documented metadata.
Tray left click activates, or opens the menu for menu-only items.
Tray right click opens an available native menu; middle click invokes secondary activation.
The launcher has no decorative bottom stripe.
Audio cards have no exposed left accent sliver.
State and lifecycle
Dismissal is not discard.
Ordinary search, selection, expansion, scroll and unsent replies live in shell-lifetime memory, not disposable Loader/delegate instances.
Reopen and switching restore them; successful completion or explicit clear/discard may clear their own state.
Never persist ordinary drafts to disk or blanket-cache credentials/panels.
Passwords and authorization state retain their specified security lifetimes.
Destructive confirmation cancels on every dismissal/switch.
Service state remains reactive after commands; never replace bindings with returned JSON snapshots.
Live updates preserve row identity while dragging/editing.
Clipboard actions retain filtering; failed replies retain retryable drafts.
Explicit activation opens/switches; same-chip activation closes; hover never switches tasks.
Escape, outside click and switching share cleanup.
Initial focus starts the task; dismissal returns focus.
Clipboard paste must release popup focus and establish the captured destination's focus before typing.
Pointer and keyboard actions have equal meaning and feedback.
Held activation keys never repeatedly dispatch; Tab/Shift+Tab traverse enabled actions, arrows traverse lists/grids, focused actions stay visible.
Field padding/icons focus the editor; focused empty fields retain hints.
Sliders preserve bindings and thumb geometry throughout dragging.
Tooltips never reveal credentials.
Authentication traversal never continuously steals focus; tests use isolated synthetic requests, never real authentication.
Async work exposes pending/success/actionable failure without fabricated completion.
Unsupported capabilities are absent, not disabled explanations; transiently unavailable controls follow the zen.
Long content remains reachable by scrolling/disclosure.
Constraints
Public IPC and owner-approved API cleanup follow SYSTEM and NL-SPEC-86A037A0; panels use typed service intents.
iwd remains the single Wi-Fi row and write authority.
No lockscreen, bar, palette, or dependency redesign is included.
Bespoke data visualization may remain bespoke.
Shared controls are keyboard accessible and expose appropriate accessibility roles and names.
Verification obligations
Changed flows require pointer/keyboard exactly-once writes and disabled rejection; retained edits/selection across close/reopen/switch; external updates after local commands; pending/failure/empty/long-content states; reviewed pixels at tested geometry and complete logs.
Do not credit unrelated shared-control or feature suites with unexercised behavior.
Broad repair completion requires unresolved inventory to be fixed or explicitly reconciled with the owner, not merely passing demonstration suites.
The recorded live-service and hardware gaps remain open: vault authentication/MFA/re-prompt, wireless/Bluetooth, audio routes/profiles, real media/CalDAV/speech, backend-dependent action variants and physical multi-output/hotplug.
The old DDC implementation gap is separately closed by recorded owner review; the deleted screenshot-helper popup is retired, not an outstanding repair.
Historical evidence links with no retained targets establish no proof; no missing evidence is represented as a pass.
Acceptance
DND, toast dismissal, Wi-Fi refresh and interaction, and all three tray pointer routes behave as specified.
Every registered popup uses the common surface and matching shared controls.
All popup labels are lowercase.
The full popup test suite and zero-warning lint gate pass.
---
id: NL-SPEC-38AED50A
type: spec
title: Nuguland popup interaction language
---
# Nuguland popup interaction language
Visual language: [Zen of Nugu](../NL-SPEC-VQXGUHYK-zen-of-nugu/index.md).
Host/panel lifecycle fields: [FeatureEntry.qml](../../../FeatureEntry.qml).
## Behavior
- Every registered popup uses one common outer surface.
- Matching UI roles use common sections, cards, buttons, toggles, separators, sliders, badges, and text fields.
- Controls visibly distinguish hover, press, focus, selected or toggled, and disabled states.
- Status is never communicated by color alone.
- Cards provide large targets, visible status, and optional secondary detail.
- Spacing and common regions provide grouping; dividers separate only unrelated groups.
- All UI labels are lowercase.
- Tray cards expose all nonempty documented metadata.
- Tray left click activates, or opens the menu for menu-only items.
- Tray right click opens an available native menu; middle click invokes secondary activation.
- The launcher has no decorative bottom stripe.
- Audio cards have no exposed left accent sliver.
## State and lifecycle
- Dismissal is not discard.
Ordinary search, selection, expansion, scroll and unsent replies live in shell-lifetime memory, not disposable Loader/delegate instances.
Reopen and switching restore them; successful completion or explicit clear/discard may clear their own state.
Never persist ordinary drafts to disk or blanket-cache credentials/panels.
Passwords and authorization state retain their specified security lifetimes.
Destructive confirmation cancels on every dismissal/switch.
- Service state remains reactive after commands; never replace bindings with returned JSON snapshots.
Live updates preserve row identity while dragging/editing.
Clipboard actions retain filtering; failed replies retain retryable drafts.
- Explicit activation opens/switches; same-chip activation closes; hover never switches tasks.
Escape, outside click and switching share cleanup.
Initial focus starts the task; dismissal returns focus.
Clipboard paste must release popup focus and establish the captured destination's focus before typing.
- Pointer and keyboard actions have equal meaning and feedback.
Held activation keys never repeatedly dispatch; Tab/Shift+Tab traverse enabled actions, arrows traverse lists/grids, focused actions stay visible.
Field padding/icons focus the editor; focused empty fields retain hints.
Sliders preserve bindings and thumb geometry throughout dragging.
Tooltips never reveal credentials.
Authentication traversal never continuously steals focus; tests use isolated synthetic requests, never real authentication.
- Async work exposes pending/success/actionable failure without fabricated completion.
Unsupported capabilities are absent, not disabled explanations; transiently unavailable controls follow the zen.
Long content remains reachable by scrolling/disclosure.
## Constraints
- Public IPC and owner-approved API cleanup follow SYSTEM and `NL-SPEC-86A037A0`; panels use typed service intents.
- iwd remains the single Wi-Fi row and write authority.
- No lockscreen, bar, palette, or dependency redesign is included.
- Bespoke data visualization may remain bespoke.
- Shared controls are keyboard accessible and expose appropriate accessibility roles and names.
## Verification obligations
Changed flows require pointer/keyboard exactly-once writes and disabled rejection; retained edits/selection across close/reopen/switch; external updates after local commands; pending/failure/empty/long-content states; reviewed pixels at tested geometry and complete logs.
Do not credit unrelated shared-control or feature suites with unexercised behavior.
Broad repair completion requires unresolved inventory to be fixed or explicitly reconciled with the owner, not merely passing demonstration suites.
The recorded live-service and hardware gaps remain open: vault authentication/MFA/re-prompt, wireless/Bluetooth, audio routes/profiles, real media/CalDAV/speech, backend-dependent action variants and physical multi-output/hotplug.
The old DDC implementation gap is separately closed by recorded owner review; the deleted screenshot-helper popup is retired, not an outstanding repair.
Historical evidence links with no retained targets establish no proof; no missing evidence is represented as a pass.
## Acceptance
- DND, toast dismissal, Wi-Fi refresh and interaction, and all three tray pointer routes behave as specified.
- Every registered popup uses the common surface and matching shared controls.
- All popup labels are lowercase.
- The full popup test suite and zero-warning lint gate pass.