dotfiles/plans/01-takemi-design-hierarchy.md

Takemi design hierarchy redesign

Outcome

Turn the existing Persona 5 shell into a three-level visual system:

1. Chrome — quiet, glanceable, and subordinate to applications.
2. Transient — expressive pop-outs with distinct compositions and obvious controls.
3. Cinematic — theatrical power and lock scenes with focused hierarchy.

Preserve the crimson/black/white palette, services, keybinds, one-slab bar/rail, P5Panel, session-lock security, and current functional coverage. This plan changes visual hierarchy and interaction clarity, not the desktop stack.

Non-goals

• Do not replace Quickshell, Hyprland, Fluxo, PAM, or the service layer.
• Do not add new accent hues or generic glass/blur cards.
• Do not reproduce Persona 5 screens literally; keep this a usable desktop shell.
• Do not build a second “control center” that duplicates every existing pop-out.
• Do not rewrite tray-menu recursion or the popup coordinator unless verification exposes a concrete defect.

Definition of done

• Permanent chrome remains readable but no longer competes with application content.
• Each primary rail icon has one obvious click action and a concise hover label.
• Selected, active, destructive, error, and urgent states are distinguishable by treatment as well as color.
• All small text meets WCAG AA; black-on-crimson replaces white-on-crimson where needed.
• Pinned pop-outs and modal controls are keyboard reachable and visibly focused.
• Power actions that end the session require a deliberate confirmation step.
• Lock has idle, editing, busy, failure, and visible success compositions.
• Reduced motion survives process restarts and stops all nonessential loops.
• qmllint, live reload, interaction checks, and 1920×1080 plus 1366×768 visual captures pass without new warnings.

---

Phase 0 — API and pattern lock

Allowed APIs

• Quickshell 0.3.0 PopupWindow: visible, anchor, grabFocus, screen. Configure placement through anchor.item/window, edges, gravity, margins, adjustment; call anchor.updateAnchor() when a visible trigger moves. Official PopupWindow docs and PopupAnchor docs.
• Popup bounds: combine PopupAdjustment.Flip | Slide | Resize where content can genuinely resize. Use QsWindow.mask: Region { item: ... } for transparent overshoot bleed only after testing transformed entry animation. PopupAdjustment, Region.
• Pinned dismissal: current HyprlandFocusGrab.active/windows/onCleared is valid only after a visible window exists (components/Popout.qml:83-97). Do not combine it casually with PopupWindow.grabFocus; choose one owner per opening mode. HyprlandFocusGrab.
• Durable preferences: FileView + JsonAdapter, using Quickshell.statePath("design-preferences.json"), watchChanges, reload(), and writeAdapter(). PersistentProperties survives reload only, not restart. FileView, JsonAdapter.
• Accessibility: Accessible.role/name/description/focusable/focused/pressed, Accessible.onPressAction, onIncreaseAction, and onDecreaseAction; decorative duplicates use Accessible.ignored: true. Qt Accessible.
• Focus: FocusScope, focusPolicy: Qt.StrongFocus, activeFocusOnTab, KeyNavigation, Keys, and forceActiveFocus(Qt.PopupFocusReason). Qt focus model.
• Disabled controls: disable the root Item; this suppresses pointer and keyboard input and propagates to children. Explicitly bind HoverHandler.enabled when a disabled control must not react visually. Qt Item.
• System contrast: Application.styleHints.accessibility.contrastPreference === Qt.HighContrast. Qt 6.11 has no documented reduced-motion preference, so motion policy is owned by Preferences.
• Secure lock: retain WlSessionLock/WlSessionLockSurface in lock/Lock.qml:12-28; Overlay + Exclusive is not a secure replacement. WlSessionLock.

Repository patterns to copy

• Copy singleton structure from config/Theme.qml:1-16 and services/Actions.qml:1-10.
• Copy popup show/hide ownership from components/Popout.qml:58-116,150-190.
• Copy keyboard roving selection from overlays/PowerMenu.qml:242-261.
• Copy development-safe lock preview boundary from lock/Lock.qml:7-27 and lockpreview.qml; never style by repeatedly locking the real session.
• Copy one-slab chrome composition from bar/Bar.qml:40-63 and bar/Rail.qml:43-64.

Verification

• Record qs --version and Qt version in the implementation PR: expected Quickshell 0.3.0 and Qt 6.11.1.
• Run qmllint on each copied API in a minimal changed component before broad rollout.
• Use qs ipc show to confirm existing IPC surface before adding typed functions.

Guards

• No deprecated PopupWindow.parentWindow, relativeX, or relativeY.
• No direct QsWindow.width/height; use implicit sizes.
• No WlrKeyboardFocus.Exclusive as a lock substitute.
• No stock QsMenuAnchor or default Qt tooltip visuals inside the custom theme.
• No claimed system reduced-motion detection; it does not exist in the documented API.

---

Phase 1 — Establish the semantic design foundation

1.1 Durable preferences

Create quickshell/config/Preferences.qml using the Phase 0 FileView/JsonAdapter pattern. Persist:

• reducedMotion: false
• tooltips: true
• highIntensityChrome: false only as a migration escape hatch; default remains calm

Expose typed setters through the existing IpcHandler in services/Actions.qml:60-68, such as setReducedMotion(enabled: bool): void. Do not build a settings UI in this phase.

1.2 Three explicit surface presets

• Add components/ChromeSurface.qml: a thin P5Panel preset with opaque flat fill, one keyline, no halftone, no drop, and an active slash only when requested.
• Refine popouts/PopoutSurface.qml:7-23 as the transient preset: halftone becomes opt-in by composition rather than present on every panel; retain the hard offset and stronger border.
• Keep components/P5Backdrop.qml cinematic-only. Bar, rail, tooltips, cards, and OSD must not instantiate it.

Do not add a generic numeric “intensity” prop to P5Panel; explicit presets make the hierarchy visible in code and prevent arbitrary intermediate tiers.

1.3 Semantic treatments

Document and encode in config/Theme.qml:

State	Fill	Mark	Text	Motion
Rest	surface	neutral keyline	white	none
Hover	surface	short red wipe	white	one short lunge
Focus/selected	white	black keyline	black	snap once
Active	surface	persistent red slash	white	none
Destructive/error	solid red	black keyline	black	shake only on error
Urgent	surface	red pulse mark	white	bounded pulse
Disabled	surface	muted outline	muted	none

Replace small white-on-crimson labels with black-on-crimson; measured contrast improves from 3.68:1 to 5.70:1. Do not add a new status color.

1.4 Base-control contract

• Convert components/P5Button.qml to a FocusScope or focusable root with one activation path shared by TapHandler, Enter, Space, and Accessible.onPressAction. Add description, visible focus state, and a real disabled state.
• Replace P5Slider.enabledControl with root enabled and update its call sites. Gate tap, drag, hover, accessible increase/decrease, and left/right keys through the same enabled root.
• Add semantic names and roles to RailIcon, StatusIcon, notification actions, media transport, calendar navigation, and tray-menu rows. Mark split-text ghosts, masks, texture layers, and duplicate glyphs ignored.

Verification

• Focus every base control with Tab and confirm a visible non-color-only state.
• Trigger each through pointer, Enter/Space, and its accessible action; assert one signal per activation.
• Disable each control and assert no clicked/moved signal and no hover animation.
• Recompute all foreground/background contrast pairs; normal text must be ≥4.5:1.
• Restart Quickshell and confirm preferences persist.

Guards

• Do not treat Accessible metadata as keyboard support; implement both.
• Do not attach semantics to every decorative child.
• Do not use MouseArea.enabled as the component-wide disabled gate.
• Do not spread raw state colors through callers; state treatment belongs in base controls.

---

Phase 2 — Quiet and clarify permanent chrome

2.1 Bar

Update bar/Bar.qml and bar/BarPill.qml to use ChromeSurface and remove all always-on texture. Keep the single slab and hairline dividers.

• bar/Clock.qml: remove permanent seconds; reveal them only inside Calendar.
• bar/Resources.qml: render tiny CPU, MEM, and GPU labels beside values so 2.6G is not contextless; remove the currently dead Metric.label path only after its visible replacement exists.
• bar/MediaPill.qml: keep title/artist but replace the three continuously animated equalizer bars with one static play-state mark in normal mode. Allow the loop only when high-intensity chrome is explicitly enabled and reduced motion is off.
• Preserve active-window elision and current collision calculation in bar/Bar.qml:90-96.

2.2 Rail interaction grammar

Make left click mean open/pin details for network, Bluetooth, audio, battery, notifications, and power. Remove undisclosed right/middle-click state changes from bar/Rail.qml:76-132,151-171; move those actions into their corresponding pop-outs.

Retain scrolling only for volume, microphone, and brightness because it directly maps to a continuous readout. Mention that gesture in the tooltip.

2.3 Persona tooltip

Add components/P5Tooltip.qml as a small anchored PopupWindow, not a stock Qt tooltip. Copy anchor/delay/hide behavior from components/Popout.qml, but use:

• calm ChromeSurface
• 350–450ms delay
• one-line name + current state
• optional second micro-line such as SCROLL TO ADJUST
• no focus grab, no halftone, no scale loop
• PopupAdjustment.Flip | Slide

Add label and hint to RailIcon; tooltips honor Preferences.tooltips and never become the only source of an accessible name.

2.4 Pinned keyboard opening

Add explicit openHover() and openPinned() paths to components/Popout.qml. openPinned() must set its focus mode before mapping; if a hover popup is already visible, close and remap rather than assuming a live grabFocus change works. Start with Audio as the vertical slice. Choose either PopupWindow.grabFocus or the current HyprlandFocusGrab for pinned dismissal after runtime comparison; never leave both owning the same close event.

Verification

• Screenshot clean desktop against both a quiet and high-contrast wallpaper.
• First-time test: identify every rail icon and predict left click from tooltip.
• Verify no secondary pointer action remains unless it is printed in the tooltip.
• Open Audio by hover and click: hover must remain passive; pinned mode must accept keyboard focus, Esc-close, and outside-click close exactly once.
• Move/rescale the rail while a popup is open and call anchor.updateAnchor() from the actual geometry-change path if it drifts.

Guards

• Do not reintroduce separate floating cards into bar or rail.
• Do not increase bar/rail footprint.
• Do not put stripes, halftone, or large display text in permanent chrome.
• Do not make a tooltip interactive.

---

Phase 3 — Give transient surfaces distinct macro-compositions

Retain shared popup lifecycle, width discipline, coordinator, header baseline, and body controls. Redesign one family at a time; capture and approve each family before moving on so a bad motif is not copied eight times.

3.1 Control pop-outs

• Audio (AudioPopout.qml) — make current volume the headline number; output and microphone form two clear bands; applications become a restrained mixer list. Put Mute and Open audio mixer inside the panel.
• Network (NetPopout.qml) — dossier composition: current connection/IP at top, download/upload fully named, network list as clipped paper rows. Use action labels Turn Wi-Fi on/off and Network settings.
• Bluetooth (BtPopout.qml) — share list-row mechanics with Network but not its exact silhouette. Use action copy Turn on/off, Start/stop scanning; pair/connect status must not rely on color alone.
• Battery (BatteryPopout.qml) — oversized percentage crossing one edge, with Plugged in/On battery, remaining time, draw, and health ordered underneath. Keep Suspend as the one explicit action.

3.2 Information pop-outs

• Media (MediaPopout.qml) — let album art define one side of the silhouette; keep metadata in a solid legibility zone; label transport actions accessibly.
• Calendar (CalendarPopout.qml) — large selected day/month as the composition, grid subordinate; move seconds here from the permanent bar; label previous/next.
• Notifications (NotifPopout.qml, NotifCard.qml) — overlapping-paper rhythm only at the list level, not on every inner action. Rename n HELD to n IN HISTORY; make DND copy an action (Silence notifications / Resume notifications).
• System (SysPopout.qml) — treat it as a diagnostic poster: four primary metrics first, hardware detail second. Expand PROCS, MEM, VRAM, Root, and label load averages 1 / 5 / 15 min.

3.3 Shared transient rules

• PopoutHeader supplies alignment and focus traversal, not the full silhouette.
• Only one dominant numeral/image/headline per panel.
• Maximum one halftone region and one red slash per panel.
• Lists use consistent 32–40px targets and explicit selected/focused/disabled states.
• Empty and loading layouts preserve the panel silhouette instead of collapsing.
• Fix muted OSD honesty: show stored percentage beside MUTED, or omit percentage; never display a fabricated 0%.

Verification

• Capture all eight pop-outs at rest plus empty/loading/error/disabled states where applicable.
• Test with longest realistic SSID, device, track, app, and notification strings.
• Verify list focus order, Enter/Space activation, Esc close, and disabled-row skipping.
• Ensure only one transient window stays open through a rapid rail sweep.
• Test popup bounds at every screen edge and both target resolutions.

Guards

• Do not create eight copies of the same card grid.
• Do not vary edge angle randomly inside one surface.
• Do not use display italic for body copy or dense device lists.
• Do not put action wording in state form (Wi-Fi On) when clicking performs the inverse.

---

Phase 4 — Focus the cinematic scenes

4.1 Power menu

In overlays/PowerMenu.qml:

• Keep the left headline/right action-stack asymmetry.
• Increase backdrop opacity enough that application text no longer competes.
• Use one stripe band or wedge, not a full-screen stripe field plus every other motif.
• Separate Lock/Suspend/Hibernate from Log Out/Reboot/Shut Down with a labeled break and greater spacing.
• Keep white fill/black text for normal selection. Use solid crimson/black text for destructive selection.
• Add pendingAction: the first activation of Log Out/Reboot/Shut Down replaces the action region with CONFIRM LOG OUT, CONFIRM REBOOT, or CONFIRM SHUT DOWN plus Cancel; second activation executes. Escape clears confirmation first and closes the menu only when no action is pending.
• Keep roving Up/Down/J/K navigation and update focus order for confirmation.

4.2 Lock screen

Refactor lock/LockFace.qml into explicit visual states while retaining the single PAM context and WlSessionLock shell:

• Idle: clock is dominant; status is quiet; auth field is present but subordinate.
• Editing: first user edit shifts emphasis to auth and dims/moves clock/status.
• Busy: CHECKING…, disabled input, bounded sweep.
• Failure: PASSWORD INCORRECT or PAM message, solid error treatment, one shake.
• Success: paint a short ACCESS GRANTED state before unlocking; skip delay under reduced motion.

Replace WHO GOES THERE, WRONG, and PAM ERROR with explicit copy. Resolve the username safely from USER then LOGNAME; if both are empty, do not call PAM with a literal placeholder—show AUTHENTICATION USER UNAVAILABLE.

Keep responsive scaling, per-monitor wallpaper, and lockpreview.qml. Ensure the password input exposes Accessible.EditableText, name Password, editable: true, and passwordEdit: true.

Verification

• Power: pointer and keyboard through safe action, destructive confirmation, cancel, outside click, and repeated open/close.
• Lock preview: capture all five states at 1920×1080 and 1366×768.
• Real lock test only after preview and PAM-path review; test wrong password, correct password, empty username environment simulation, and Quickshell reload behavior.
• Confirm WlSessionLock.secure path remains unchanged.

Guards

• Never execute destructive action on the first activation.
• Never fake authentication success in preview or bypass PAM.
• Never replace session lock with a focus-exclusive overlay.
• Do not let theatrical copy obscure what the user must do.

---

Phase 5 — Motion, contrast, and runtime calm

5.1 Motion policy

In Theme.qml, derive motionScale from Preferences.reducedMotion. Apply it to:

• every Behavior
• popup enter/exit sequences
• media equalizer and marquee loops
• icon pulses
• toast countdown/entry
• OSD, power, and lock scene transitions

When reduced motion is on, set final state directly or disable Behavior; do not merely shorten loops to 1ms. Essential progress indicators may remain static with clear text.

5.2 High contrast

Read Application.styleHints.accessibility.contrastPreference. In high contrast:

• increase keyline/border separation
• disable low-opacity texture behind text
• retain shape/icon differences among selection, active, danger, and urgency
• do not change the three-color identity

5.3 Polling cleanup

After visual behavior is stable, move sysReader from the 2-second batch to the 20-second batch in services/Sys.qml:78-102; uptime/load/process count do not drive permanent animation. Keep CPU/MEM/GPU at 2 seconds because the bar renders them. Measure before making further demand-driven polling changes; do not introduce a consumer-count abstraction without evidence that it materially reduces work.

Verification

• Restart with reduced motion and verify zero infinite animations via source grep and live observation; all final states must still appear.
• Toggle high contrast and re-run contrast checks.
• Compare Fluxo process-launch frequency before/after for 60 seconds.
• Confirm notification timing, popup dismissal, and lock success still complete when animation is disabled.

Guards

• Do not claim to follow an OS reduced-motion setting.
• Do not gate functional timers such as notification lifetime or polling behind motion.
• Do not add blur, gradients, or extra texture to compensate for removed motion.

---

Phase 6 — Integrated verification and cutover

Automated checks

1. qmllint -I quickshell on every changed QML file individually; the current tool can exit 255 without diagnostics on some recursive/singleton batches, so record files and results rather than treating one giant invocation as authoritative.
2. git diff --check.
3. Grep for:
   • white small text on solid accent
   • enabledControl
   • pointer handlers without an accessible name on shared controls
   • infinite animations not gated by reduced motion
   • deprecated popup properties
   • old copy: WHO GOES THERE|PAM error|HELD|PROCS|VRAM
4. Reload through qs ipc call shell reloadConfig and inspect qs log.

Interaction matrix

Test each bar/rail/pop-out action with pointer, keyboard where focusable, outside-click, Esc, disabled state, and service unavailable. Specifically test tray menus with nested submenus, Wi-Fi off, no Bluetooth adapter, no battery, no player, no notifications, and missing album art.

Visual matrix

Capture:

• 1920×1080 and 1366×768
• calm and high-contrast wallpaper
• default, reduced-motion, and high-contrast preferences
• desktop, every pop-out, tray menu, OSD, toast, power normal/confirm, and all lock states

Compare against these invariants:

• Chrome has no texture and never dominates content.
• Transient panels each have one dominant composition.
• Cinematic scenes retain the strongest typography and atmosphere.
• Nothing important is encoded by color alone.
• No text clips, crosses a cut edge, or falls below contrast requirements.

Cutover sequence

Implement in six reviewable commits matching Phases 1–6. Do not delete the old visual path until its phase passes screenshots and interaction tests. Remove migration aliases (enabledControl, high-intensity escape hatch) only in the final cleanup commit after all call sites and preferences have migrated.

Expected file map

New

• quickshell/config/Preferences.qml
• quickshell/components/ChromeSurface.qml
• quickshell/components/P5Tooltip.qml

Foundation edits

• quickshell/config/Theme.qml
• quickshell/components/P5Panel.qml
• quickshell/components/P5Button.qml
• quickshell/components/P5Slider.qml
• quickshell/components/Popout.qml
• quickshell/components/Icon.qml
• quickshell/components/Marquee.qml
• quickshell/services/Actions.qml

Surface edits

• quickshell/bar/{Bar,BarPill,Rail,RailIcon,StatusIcon,Clock,Resources,MediaPill,Tray}.qml
• quickshell/popouts/{PopoutSurface,PopoutHeader,AudioPopout,NetPopout,BtPopout,BatteryPopout,MediaPopout,CalendarPopout,NotifPopout,SysPopout,TrayMenuList}.qml
• quickshell/components/NotifCard.qml
• quickshell/overlays/{Osd,Toasts,PowerMenu}.qml
• quickshell/lock/LockFace.qml
• quickshell/services/Sys.qml

Recommended execution order

Execute Phase 1 first and review its state matrix before any visual restyling. Then use Audio as the full vertical slice through Phases 2–3. Once its tooltip, pinned focus, semantic states, reduced motion, and transient composition pass, repeat that proven pattern across the remaining surfaces. Leave real session-lock testing until the lock preview and power confirmation work are complete.