Skip to main content
Widget workers render through host-owned Remote DOM elements. Use only elements exported by the installed Widget Worker SDK, and use DeclarativeCapabilityUse for non-callable capabilities.

​
Design for worker constraints

  • Keep worker-boundary values JSON-serializable.
  • Do not assume browser or host application APIs are available.
  • Declare every portal function and capability in uses.
  • Reuse runtime resources across prop updates and clean them up on unmount.
  • Handle missing and malformed inputs without crashing.
Review every package before publication.

​
Prefer Fluid-provided UI

Use worker-safe Fluid components when they match the interaction. They preserve familiar portal behavior, accessibility, spacing, and theme usage across Widget Packages. Import them only from @fluid-app/portal-sdk/widgets/worker:
The public worker UI includes: Do not recreate a Fluid-provided control only to change its appearance. Use its public props and place it within a themed widget layout. If no Fluid component fits, use semantic HTML, accessible interaction patterns, and the portal theme variables below.

​
Use portal theme semantics

Theme compliance is a widget requirement. Widgets share a portal with built-in and third-party content, so each widget must use the active portal theme wherever the theme represents the visual decision. Do not ship a separate light or dark palette. Keep styles in the generated project’s root styles.css. Scope selectors to the widget. Do not depend on global body styles. The portal supplies semantic CSS variables to the widget. Use the variable that describes the role, not the current rendered color. Use paired foreground variables with their surfaces. For example, text on --primary uses --primary-foreground, and text on --card uses --card-foreground.
Do not redefine these variables in widget CSS. Do not add a hardcoded fallback color, font, spacing value, or radius when a semantic variable represents the same intent. A widget-owned visual value is appropriate only when it carries product meaning that the portal theme cannot represent, such as colors intrinsic to supplied content. Use a colorSelect property only when an author must choose among semantic color roles. Avoid literal color fields, font controls, and spacing or radius controls that duplicate the portal theme. Test the widget with each supported portal theme and color mode. Check surface and text pairs, borders, focus indicators, disabled states, charts, and interactive states. The widget should remain visually consistent with surrounding widgets when the active theme changes.

​
Build accessible behavior

Use semantic elements, accessible names, keyboard operation, visible focus, useful alternative text, and logical heading order. Respect reduced-motion preferences. Test:
  • keyboard-only operation;
  • focus entry, order, and restoration;
  • text and control contrast in each theme mode;
  • empty and error states;
  • narrow layouts and content zoom;
  • motion with reduced motion enabled.

​
Inspect through a host

A successful build proves neither visual compatibility nor accessibility. Render the widget in a portal or builder host and inspect the resulting host-owned elements.