---
name: nuguland-ui
description: "Use when creating, changing, debugging, or reviewing Nuguland UI: bars, popups, controls, visual hierarchy, focus, input, or desktop interactions in quickshell/nuguland. Requires visual review and nested-niri interaction evidence, not just lint."
---

# Nuguland UI

## Specify before drawing

Primary user action. Observable result.
Per changed interaction: state owner, pending/success/failure feedback, focus entry and return, keyboard activation, dismissal.
States where the feature has them: empty, unavailable, disabled, selected, long content.
Output dimensions and scale from the target setup, never guessed constants.

Layout decisions: load `qml` and `quickshell`; palette work loads `nugu`.
Compare one to four mockup options. Nugu semantic roles and existing control language only; no new palette, no decorative card system.
Iterate until accepted.
Mockup approval covers direction only. Not QML geometry, fonts, input, compositor behavior.
No new design review for logic-only fixes of unchanged layouts.

## Implement one complete interaction

- Shared controls and theme tokens. New primitive only when nothing fits.
- Bind state down, route intent up. No `parent.parent`.
- Accessible names, visible focus, keyboard activation.
  Hover, pressed, checked, disabled, pending distinguishable without color.
- Group by task and relationship. No equal-weight cards, badges, borders, or motion competing with the primary action.
- Lowercase labels, service ownership, existing behavior outside the change stay.
- Exercise the full action before the next component.
  Shared-control changes check all affected callers, not a demo widget.

## Validate

Fixture per change: `controls`, `popouts`, `privilege`, `noko`, `system`, `tasks`, `niri`, `all`.
Add one when the behavior is uncovered.

The lint runtime check may ping or launch a live shell. Never on the parent desktop; fresh loads run isolated.

Inspect the emitted evidence directory: bounded readiness waits, complete stdout/stderr, screenshots at target geometry.
Short recording when stills cannot establish transient behavior.
Evidence lives in the relevant spec's evidence directory: command, versions, geometry, expected/observed.

`.qmlls.ini`: Quickshell generates it. Tooling details in the nested-harness README.