Visual Studio and WinUI tooling
- Visual Studio with .NET desktop development
- Windows application development workload
- .NET 10 SDK
- Git and GitHub access
Prima Facie Widget SDK
Build your first widget.
Start with the supported widget repository, define the package manifest, implement the SDK runtime contract, validate the experience in Heads Up, and submit the source for review.
Current compatibility
Developer preview baseline
- Framework
- .NET 10
- UI platform
- WinUI 3
- Windows App SDK
- 2.2.0
- Windows
- 10 2004+
- Architecture
- x64 preview
- SDK
- Prima Facie Preview
AnyCPU support is targeted for version 1.0.
01 / Prerequisites
Begin with the supported environment.
The preview workflow deliberately controls the SDK, project configuration, and host environment so widget development remains aligned with Heads Up.
Supported Windows host
- Windows 10 version 2004 or later
- x64 development environment
- Current Heads Up development build
- Supported local widget host
WinUI component development
- C# and .NET application development
- WinUI 3 controls and XAML
- MVVM-oriented presentation logic
- Asynchronous and cancellation-aware operations
02 / Repository
Work inside the supported widget repository.
The repository is the supported development boundary. It supplies the pinned SDK binary, documentation, reference widgets, and build configuration used during review and integration.
Prima Facie Widgets
Developer preview
- docs SDK and workflow documentation
- lib PrimaFacie.SDK.dll
- samples Reference widget implementations
- widgets First-party and submitted widgets
- Directory.Build.props Shared build configuration
Pinned to the host contract
Widgets reference the SDK binary supplied by the repository. They do not reference Heads Up application, infrastructure, persistence, or Core assemblies.
Working implementations
The sample and first-party widgets demonstrate manifests, runtime behavior, commands, widget settings, private persistence, error handling, attention requests, responsive presentation, and deterministic resource cleanup.
One package pipeline
Accepted packages are installed beneath
%LocalAppData%\PrimaFacie\HeadsUp\Widgets.
First-party and externally supplied widgets use
the same manifest, package, discovery, and
activation pipeline.
Published with the developer preview
Clone instructions and the public repository URL will be added when the developer repository is ready for external contributions.
03 / Contract
Declare the package. Implement the runtime boundary.
The manifest is the authoritative package declaration. The SDK defines how the runtime widget collaborates with Heads Up. The host owns registration, instance state, dashboard composition, live workspace caching, refresh scheduling, and shutdown orchestration.
Heads Up owns
- User-level package installation and discovery
- Manifest validation and host-owned definitions
- Widget instance identity and persistence
- Dashboard placement and effective layout
- Live dashboard workspace caching
- Refresh scheduling and shutdown orchestration
- Viewport, density, and global settings
- Shell-managed error and attention services
Prima Facie SDK
Explicit contract
No host-internal dependencies
Your contribution owns
- Package manifest declaration
- IWidget and widget-facing lifecycle implementation
- WinUI presentation and focused domain behavior
- View-model and command implementation
- Widget settings and settings experience
- Data model and persistence strategy
- Responsive information density
- Timer, subscription, sampling, and resource cleanup
manifest.json
Defines identity, description, author, version, capabilities, size, theme, logo, assembly, and runtime type.
IWidget
Participates in initialization, refresh, and shutdown and responds to effective layout and viewport changes.
WidgetContext
Supplies instance identity, widget and global settings, the private data directory, error reporting, attention services, theme, and layout.
WidgetViewport
Supplies the effective layout, width, height, and Small, Compact, or Normal density available to the widget.
Host composition
From declaration to dashboard- 01 Declare The developer defines the package manifest.
- 02 Discover Heads Up validates the package.
- 03 Define The host registers its widget definition.
- 04 Instantiate The host creates instance state and runtime behavior.
- 05 Compose The dashboard combines and retains the definition, instance, and live widget runtime.
04 / Implementation
Build focused behavior. Use host services deliberately.
A widget should remain cohesive and independently understandable while participating consistently in the broader Heads Up environment.
Create the WinUI surface
Implement the widget as a focused WinUI control. Keep presentation responsive to the effective dimensions supplied by the host.
Match execution semantics
Use RelayCommand for synchronous work
and AsyncRelayCommand for asynchronous,
cancellation-aware operations.
Own the widget settings model
Define widget settings and an optional settings experience. Global settings are supplied by Control Center for the widget to observe; the widget does not define them.
Own the persistence strategy
Heads Up supplies instance identity and a private data-directory boundary. The widget owns its data model, serialization, and recovery decisions.
Report protected operations
Route operational failures through the SDK error boundary so the host can isolate the widget and preserve structured diagnostics.
Request, never control
Request user attention through the SDK attention service. Heads Up decides how the shell and taskbar express that request.
05 / Responsive behavior
Design for the widget’s effective on-screen space.
Dashboard reflow can change a widget’s effective position and available dimensions. Presentation decisions must use the current viewport supplied by Heads Up.
06 / Validation
Validate inside the real host environment.
A successful project build is necessary, but it is not sufficient. The manifest and runtime widget must remain correct across initialization, refresh, dashboard switching, responsive reflow, persistence, shutdown, and host service boundaries.
Manifest
Identity, author, version, runtime type, capabilities, size constraints, theme, and required assets are complete and valid.
Runtime contract
Initialization, refresh, layout changes, viewport changes, cancellation, and shutdown behave predictably.
Multiple instances
Independent widget instances do not accidentally share widget settings, private data, or mutable runtime state.
Persistence
State survives restart, invalid state is handled deliberately, and recovery is safe.
Resize and reflow
Small, Compact, and Normal presentations remain usable after movement, resizing, and responsive dashboard reflow.
Lifecycle and continuity
Meaningful runtime state survives dashboard switches, inactive presentation work is controlled, and returning to the dashboard restores the live experience.
Shutdown and cleanup
Timers, subscriptions, sampling operations,
cancellation sources, and owned resources
are released through
ShutdownAsync.
Failure isolation
Operational and shutdown failures are reported without destabilizing the dashboard or preventing the host from completing its work.
07 / Submission
Submit a complete widget contribution.
Preview widgets enter Heads Up through the curated repository and pull-request process. Submission is the start of product integration review, not an independent distribution mechanism.
Complete implementation
Include the widget project, WinUI surface, view model, models, widget settings experience, and required assets.
Complete manifest
Supply stable identity, author, version, capabilities, sizing, theme, logo, assembly, and runtime type declarations.
Validation results
Document the host scenarios exercised, known constraints, and responsive states reviewed.
Pull request
Submit the contribution for architectural, product, reliability, accessibility, and integration review.