Mac Widget Design

Build or retrofit macOS WidgetKit widgets that run locally, look native on the desktop, and have reliable data internals. Prefer updating an existing widget when the repo already has a carrier app, Widget extension, shared Swift package, or installer; create a new local widget only when no suitable surface exists or the user asks for a fresh widget.

Decision Tree

1. Existing widget present: inspect Package.swift, .xcodeproj, WidgetBundle, WidgetConfiguration, *Widget*.swift, app-group IDs, cache writers, and install scripts. Update the current surface.
2. No widget present: create a native macOS carrier app plus WidgetKit extension. Use SwiftPM for shared core code and preview/test utilities, but do not assume SwiftPM alone can install a WidgetKit extension.
3. Design-only request: still check WidgetKit background behavior and desktop proof; widget design cannot be trusted from static preview alone.
4. Internals-only request: still verify the visible failure states; stale data, dead ring/battery, missing sensor timestamps, and unavailable metrics must be visible.

Load References

• For visual layout and colors, read references/design-system.md.
• For WidgetKit architecture, local running, cache, and data safety, read references/internals.md.
• Before final verification, read references/local-proof.md.

Required Workflow