Compose a WordPress Design System interface
Classify before searching
- State the user-visible behaviour, minimum runtime and package versions,
rendering owner, runtime document, and whether each Design System dependency
is bundled or externalized.
- Inspect the changed surface and its nearest same-surface precedent once.
- Choose the narrowest path:
- Lightweight: keep an existing supported component when behaviour,
styling, and document setup do not change.
- Standard: select or compose a public component or token.
- Deep: handle custom UI, a package migration, or another rendering
document such as an iframe, popup, or portal.
Do not reopen component selection on the lightweight path. Verify the existing
contract, make the narrow change, and stop.
Select for the behaviour
When selection is material, write the required interaction contract before
choosing a component. Follow the maintained recommendation sources and
target-version checks in
Working with WordPress Design System packages,
then verify the selected public API in the deployed runtime or installed
version, as applicable.
Choose the smallest public composition that owns exactly the required
behaviour. Do not turn a trigger into a menu, dialog, or state owner merely
because a nearby precedent does. Stop searching when one recommended option
satisfies the behaviour and setup.
Apply conditional setup
- For custom UI, first establish why public composition is insufficient.
- For a migration, preserve observable interaction, styling, accessibility,
and compatibility.
- For a separate document, read the
cross-package document setup guidance
before editing. Make a short per-document ledger for the packages actually
used: static styles, runtime-injected styles, root theming, and overlays.
Mark each applicable requirement verified or blocked; do not add setup for a
package that does not render there.
For a planning task with no concrete host file or state owner, keep the plan
actionable under explicit assumptions. When the request names a target, inspect
that exact target; do not silently plan against another package or active
equivalent. Treat missing context as a verification gap; block only when it
prevents a safe behaviour or API decision.
Use the linked public documentation for API and setup facts. Do not copy its
component mappings, token inventory, or implementation recipes into this
skill.
Finish
Exercise the changed interaction and run focused checks. Before declaring
completion, recheck the behaviour contract and every rendering document.
Report unresolved setup or parity evidence as blocked rather than silently
omitting it.
If no public API meets the need, document the unmet behaviour and affected
consumers. Route package work to design-system-contribution in a local
Gutenberg checkout; otherwise request an upstream Design System change.
1---2name: design-system-ui-composition3description: Use when building or changing a Gutenberg feature, plugin interface, or standalone application UI with public `@wordpress/components`, `@wordpress/ui`, or `@wordpress/theme` APIs, including when the code does not yet use the Design System; do not use to change package source or depend on package-private implementation details.4metadata:5 source: https://skillmd.com/skills/wordpress/design-system-ui-composition6---78# Compose a WordPress Design System interface910## Classify before searching11121. State the user-visible behaviour, minimum runtime and package versions,13 rendering owner, runtime document, and whether each Design System dependency14 is bundled or externalized.152. Inspect the changed surface and its nearest same-surface precedent once.163. Choose the narrowest path:17 - **Lightweight:** keep an existing supported component when behaviour,18 styling, and document setup do not change.19 - **Standard:** select or compose a public component or token.20 - **Deep:** handle custom UI, a package migration, or another rendering21 document such as an iframe, popup, or portal.2223Do not reopen component selection on the lightweight path. Verify the existing24contract, make the narrow change, and stop.2526## Select for the behaviour2728When selection is material, write the required interaction contract before29choosing a component. Follow the maintained recommendation sources and30target-version checks in31[Working with WordPress Design System packages](../../../docs/contributors/design/design-system-packages.md#choose-a-recommended-component),32then verify the selected public API in the deployed runtime or installed33version, as applicable.3435Choose the smallest public composition that owns exactly the required36behaviour. Do not turn a trigger into a menu, dialog, or state owner merely37because a nearby precedent does. Stop searching when one recommended option38satisfies the behaviour and setup.3940## Apply conditional setup4142- For custom UI, first establish why public composition is insufficient.43- For a migration, preserve observable interaction, styling, accessibility,44 and compatibility.45- For a separate document, read the46 [cross-package document setup guidance](../../../docs/contributors/design/design-system-packages.md#setup-depends-on-the-document)47 before editing. Make a short per-document ledger for the packages actually48 used: static styles, runtime-injected styles, root theming, and overlays.49 Mark each applicable requirement verified or blocked; do not add setup for a50 package that does not render there.5152For a planning task with no concrete host file or state owner, keep the plan53actionable under explicit assumptions. When the request names a target, inspect54that exact target; do not silently plan against another package or active55equivalent. Treat missing context as a verification gap; block only when it56prevents a safe behaviour or API decision.5758Use the linked public documentation for API and setup facts. Do not copy its59component mappings, token inventory, or implementation recipes into this60skill.6162## Finish6364Exercise the changed interaction and run focused checks. Before declaring65completion, recheck the behaviour contract and every rendering document.66Report unresolved setup or parity evidence as blocked rather than silently67omitting it.6869If no public API meets the need, document the unmet behaviour and affected70consumers. Route package work to `design-system-contribution` in a local71Gutenberg checkout; otherwise request an upstream Design System change.