# Nuguland UI/UX repair

## Approved direction

Retain every existing feature and the Nugu palette.
Apply the compact, icon-led direction approved in mockup iteration 3.
Use one control language across every widget.
Remove filler subtitles and repetitive instruction labels, not useful status.
Use icons for familiar secondary actions, with useful, Nugu-styled tooltips and accessible names.
Keep primary actions explicit.
Do not copy GNOME branding or Omarchy features into Nuguland.

Reference principles:

- [GNOME design principles](https://developer.gnome.org/hig/principles.html): task simplicity, progressive disclosure, reduced effort, consideration, accessibility.
- [Omarchy Quattro navigation](https://github.com/basecamp/omarchy/blob/quattro/manual/04-navigation.md): complete keyboard operation and direct access.
- [Omarchy Quattro panels](https://github.com/basecamp/omarchy/blob/quattro/manual/05-the-top-bar.md): long-running integrated shell, immediately useful panels, pointer and keyboard actions.

Nuguland resolves conflicts in favor of conventional control traversal: Tab traverses controls, not adjacent panels.
Hover never switches away from an active task.
No new dependencies, feature removals, palette redesign, or parent-desktop testing.

## State and lifecycle contract

Ordinary search, selection, expanded sections, scroll positions and unsent replies belong to shell-lifetime in-memory state, not disposable Loader/delegate instances.
Dismissal is not discard.
Reopening or switching panels restores ordinary state.
Successful completion or an explicit clear/discard action may clear its own state.
Do not persist ordinary drafts to disk.
Passwords and authorization state retain their explicitly defined security lifetimes.
Do not blanket-cache every panel or credential.
Destructive confirmation is cancelled on every dismissal or switch.

Service-derived state remains reactive after local commands.
Commands never replace a view's binding with a returned JSON snapshot.
Live updates preserve row identity while dragging or editing.
Clipboard actions preserve the current filter.
Notification reply failure retains its draft and exposes a retryable outcome.

## Interaction contract

- Explicit activation opens or switches a popup; same-chip activation closes it.
- Each task defines initial focus and returns focus when dismissed.
- Search tasks focus their search editor immediately.
- Escape, outside click and switching use the same lifecycle cleanup route.
- Pointer and keyboard actions have the same meaning and visible feedback.
- Holding activation keys does not repeatedly dispatch commands.
- Tab and Shift+Tab reach all enabled actions without hovering.
- Focused controls are visible, including action rails and notification dismissal.
- Sliders preserve service bindings, full drag sequences and thumb geometry; each has a contextual accessible name.
- Field padding and icon regions focus the editor; empty focused fields retain their hint.
- Capabilities determine whether a control is enabled.
- Async work exposes pending, success or actionable failure, without fabricating completion.
- Clipboard paste must release popup focus and establish destination focus before typing.
- Authentication controls support keyboard traversal without continuous focus theft; no real authentication in tests.

## Visual contract

Use consistent header hierarchy, spacing, radii, icon sizes, action roles and focus treatment.
Neutral surfaces are quiet; primary action, selection, expansion, disabled and error states remain distinct.
Do not border every nested content region.
Status is never color-only.
Tooltips use Nugu surfaces and typography, name the action or explain unavailable state, wrap long text and never show credentials.
Keyboard focus can expose useful tooltips without requiring pointer hover.
All authored labels and tooltip text are lowercase.
Long content stays inside its available geometry and all actions remain reachable by scrolling or disclosure.
Support configured 2560×1440 and 1366×768 outputs at scale 1, horizontal and vertical bars.

## Source-confirmed repair inventory

The initial audit is source evidence, not runtime proof.

1. Loader disposal loses ordinary drafts and scroll state.
2. Hover switching followed by clicking toggles the requested popup closed.
3. Audio, brightness, media, clipboard, power and tray commands sever reactive state bindings.
4. Snapshot array replacement recreates interactive delegates during live updates.
5. Clipboard actions drop filtering; paste has no focus handoff.
6. Hover-only actions and mouse-only rows block keyboard tasks.
7. Custom controls lack standard focus/activation, accessible names, bounded labels and consistent slider geometry.
8. Media exposes unsupported actions as enabled.
9. Power dismissal retains armed destructive confirmation.
10. Launcher details, tray lists and system issues can exceed clipped fixed-height content.
11. Connectivity hides errors; refreshes can destroy the active credential editor.
12. Vault keyboard selection can leave the viewport or retain details after zero matches.
13. Privilege focus retry prevents normal traversal.
14. Brightness DDC setup has no detected-display/completion route; full hardware behavior requires separate verified service work, not a cosmetic success label.

## Acceptance and evidence

Existing checks remain enabled.
Run public `just test`, `just lint` and `just ui-test` gates.
Use `just fmt` and rerun gates after formatting.
Extend the existing nested-niri fixtures for changed flows, with isolated synthetic services.
Do not claim that existing shared-control, Clock/System, Noko-overlay or native-Niri tests cover unexercised panels.

For each repaired flow, record:

- pointer and keyboard activation, disabled behavior and exactly-once writes;
- edits and selection through close/reopen and switching;
- external updates after a local action;
- pending/failure/empty/long-content states;
- actual rendered screenshots, reviewed for clipping, hierarchy, focus and state feedback;
- tested output geometry, commands and retained complete logs.

Track delivered slices and remaining blockers in `repair-progress.md`, not in SYSTEM.md or MISSION.md.
Completion requires the entire inventory to be resolved or explicitly reconciled with the owner, not merely a passing control demonstration.