Repository navigation
UI: Define criteria for a stable 1.0 release #82611
Description
Discussion outcome: Decide the initial scope and criteria to release a 1.0 version of the @wordpress/ui package.
Background:
Starting with the limitations and requirements outlined in #71196, the @WordPress/gutenberg-components team has been building the @wordpress/ui package as a set of low-level UI primitives of the WordPress Design System. The design system's "Introduction" Storybook page and "Working with WordPress Design System packages" developer documentation have more context about how this package relates to existing packages like @wordpress/components.
Until now, the package has been built as "Experimental", with an accompanying warning notice on the package documentation, and incremental releases being published as 0.x releases following semantic versioning specification on "initial development", non-"stable" releases.
The @wordpress/ui package is a "bundled" package, which means that its version carries significance in how changes are communicated. And unlike other packages, it is not "externalized" as a window.wp global.
The purpose of this ticket is to come to agreement on the specific criteria that need to be reached to be confident in publishing the 1.0.0 release of the package and removing the experimental banner from the package.
Related issues:
- Prepare
@wordpress/uifor use in Gutenberg #76135 describes some of the compatibility work in implementing new components to be used alongside existing components within Gutenberg. - Components: New form primitives #74178 is a subset of component planning specifically for new form primitives
Proposal:
The following should be achieved to consider a 1.0 stable release:
- An initial set of components that fulfills baseline expectations of a general-purpose design system component library for building administrative interfaces, and which is also informed by usage of existing components in Gutenberg.
- All
@wordpress/uicomponents should be recommended, as indicated by inclusion in the@wordpress/use-recommended-componentsESLint rule's implementation allowlist and use of the'manifest'Storybook tag to indicate that a component is the canonical recommended design system component to be used for a given use-case
The following is a proposed list of components and their current implementation and recommended status, with logical groupings for readability. The groupings don't currently carry any significance in how the components are currently implemented or documented.
- Actions
- Content
- Feedback
- Overlays
- Layout and structure
- Breadcrumb
- Implementation: #80425
- Recommended
- Card
- Collapsible
- CollapsibleCard
- EmptyState
- Stack
- Tabs
- Breadcrumb
- Date
- Form primitives
- Autocomplete
- Checkbox
- CheckboxGroup
- Combobox
- Implementation: #78399
- Recommended
- ControlWithError
- Implementation: #81574
- Recommended
- Field
- Fieldset
- Input
- InputLayout
- Radio
- RadioGroup
- SearchableChipSelect
- SearchableSelect
- Implementation: #80961
- Recommended
- Select
- Slider
- Implementation
- Recommended
- Switch
- Textarea
- ToggleGroup
- Implementation
- Recommended
- ValidityIndicator
- Form controls
- AutocompleteControl
- Implementation
- Recommended
- CheckboxControl
- ComboboxControl
- Implementation
- Recommended
- InputControl
- RadioGroupControl
- SearchableChipSelectControl
- SearchableSelectControl
- Implementation: #80979
- Recommended
- SelectControl
- SliderControl
- Implementation
- Recommended
- SwitchControl
- TextareaControl
- ToggleGroupControl
- Implementation
- Recommended
- ValidatedInputControl
- Implementation: #81627
- Recommended
- ValidatedTextareaControl
- Implementation: #81984
- Recommended
- AutocompleteControl
- Utilities
cc @WordPress/gutenberg-components
Activity
mirka commentedon Sep 8, 2026
The "recommended" status currently covers somewhat of a range of "recommended-ness":
I would explicitly define 2 as the lowest possible bar for a 1.0.
I also remember we discussed that there may be a bar that is yet another level higher:
aduth commentedon Sep 9, 2026
Can we quantify this so that it's actionable?
mirka commentedon Sep 9, 2026
Setting a number across the board ("5 instances" or "20% of instances") doesn't really make sense since every component and call site has a different risk profile. I mean, we could set a minimum number of instances to the migrated, but in reality it would probably be more of a "use your best judgment for each component".
Not sure if you're looking for a hard quantification here, but if somewhat flexible language is fine, we could say something like "a reasonable number of use cases in Gutenberg has been migrated to confirm API sufficiency" and leave it at that.
aduth commentedon Sep 9, 2026
I guess my point is less about putting a number to it, and more about establishing a clear expectation around what done looks like, since the purpose of the issue is in setting achievable criteria. Part of the "gut check" I would expect to happen at the component's recommendation itself, with Tooltip being an example of where we migrated a large chunk of existing usage before marking it as recommended, or more recently Menu (not yet recommended) and its migrations (example).
mirka commentedon Sep 9, 2026
At least I wasn't treating the recommended status as an indicator for stability per se. A lot of the ones I marked, I haven't personally overseen migrations to confidently say that they're stable. I saw it more as an invitation for contributors to start adopting the components. Which is good to do early, because otherwise they would be bottlenecked by me.
I don't have a strong opinion about how stable exactly the 1.0 should be, but I would err on the side of less stable, than more stable 😄 One goal of
@wordpress/uiis to shed some fear of breaking changes, which was a factor contributing to slow decision making and shipping.jameskoster commentedon Sep 14, 2026
Here are a couple of components that feel like potential gaps for a v1. They already show up as multiple one-off implementations across admin/editor UI, so a shared primitive would pay for itself as a source of truth:
Not arguing these must all block 1.0, more that they’re worth an explicit in/out call beforehand.
ciampo commentedon Sep 14, 2026
We already offer (or plan to) dedicated subcomponents where applicable (eg
Menu).Do you think we'd need a standalone component, here? Especially since the main value would be styles, and we already espose WDPS tokens for the color?
This one should be relatively simple, especially if we're ok with matching base ui's features and behaviour
Last time this was discussed, I remember there wasn't a strong agreement around having / using such a component instead of native scrollbars. We should make sure we have alignment here
Would that be something similar to this?
This may require some technical planning, mostly around understanding if and how
@wordpress/uishould support drag and drop interactions.In short: we may want to include
Avatarin the initial list, but otherwise every other component doesn't feel necessarily ready for development, and would therefore delay the release further.This is not to say that we shouldn't discuss / plan / work on them, though.
ciampo commentedon Sep 24, 2026
Another thought: component naming. I think we're not 100% consistent at the moment: for example, we have
IconButtonto describe a button with only an icon, but then we haveLinkButtonto describe a link that looks like a button; in other words, if we had to follow theIconButtonnaming scheme, we should call itButtonLink, and notLinkButton. Thoughts? Or maybe I'm just paying attention to unimportant details.mirka commentedon Sep 25, 2026
Right, that makes sense! Now is the time to change it.
simison commentedon Sep 29, 2026
In my mind, they're all "Buttons" (they look like such, visually), and the prefix is "Link-" or "Icon-" ("specialises as Icon/Link but looks like Button"), and with that mental model they're consistent with each other and similarly named as form controls. I can see them grouped closer to Icon or Link as per their semantics, too. Or both named
ButtonLinkandButtonIconto stick closer to buttons.Not a strong opinion which way around to go. Overall, I don't think consumers think about semantics as often, and they go by visual appearance instead. :-)
ciampo commentedon Sep 29, 2026
I know they do, and that to them it won't make a big difference, but I think (and hope) that consistent naming can also contribute to greater clarity on the consumer side, in this case hopefully realizing that they're reaching out for a link that looks like a button, but is ultimately a link.