puter/DESIGN.md

Puter interface rules

Puter is a compact macOS system utility. Its visual hierarchy is the page title, live data, and the selected item's details. Keep the user's attention on those.

Direction

The chosen direction pairs a Liquid Glass navigation layer with a compact, readable data workspace. The earlier flat utility treatment was too bland; a full glass dashboard would distract from the dense process table. Glass belongs to navigation and actions, while resource color and larger values give data hierarchy.

• Use the system font, semantic text styles, and tabular digits for telemetry.
• Use the system accent for selection and actions. Resource/chart colors convey resource identity; status colors also require a text or symbol label.
• Keep data surfaces opaque and readable. Native toolbar controls receive the platform's material treatment; the inset sidebar uses regular Liquid Glass. Related page actions use glass buttons inside a GlassEffectContainer. Never layer glass on table rows or resource readings.
• Honor Reduce Transparency with an opaque sidebar. Older systems use regular material and bordered controls. Resource meters show actual percentages, not decorative or simulated activity.
• Retain macOS 14 support. Newer APIs require macOS availability guards.
• Shared geometry lives in PuterLayout: 20-point page inset, 16-point section spacing, 8-point control spacing. Native control metrics take precedence.

Shell and interaction

• One native toolbar sits above the content. The sidebar is inset eight points below it, with one 16-point rounded navigation surface instead of a hard divider.
• The window uses a unified hidden-title toolbar with native traffic lights and outer corners. A regular-material surround connects the toolbar to the inset, opaque workspace. Launch, refresh, and update actions share a glass container. Do not replace native window chrome with a custom draggable header.
• Compact and expanded navigation use the same List, row heights, and ordering. Width changes are immediate; frequently updated process data is not animated.
• Each page retains its search while switching pages. An explicit "Go to details" clears that destination's filter so it cannot hide the requested process.
• Window-local selection and search belong to ContentView. Shared telemetry remains in the observable monitor; do not add a forwarding view-model layer.
• Appearance is System, Light, or Dark. System is the default.
• Resource summaries adapt to the available width; tables keep their user-sized columns and horizontal scrolling. Search-empty and collecting states are explicit.

Verification

Check both appearances, compact/expanded navigation, the inspector open/closed, search-empty states, keyboard navigation, context menus, and sidebar toggles. Check resizing and motion in the running app. A screenshot verifies the captured layout, not frame rate. Do not claim animation performance without measuring it.