newspack-components 4.10.0 → 4.12.0-alpha.1

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+# newspack-components [4.12.0-alpha.1](https://github.com/Automattic/newspack-workspace/compare/newspack-components@4.11.0...newspack-components@4.12.0-alpha.1) (2026-10-15)
+
+
+### Bug Fixes
+
+* **components:** fit the page header and tabs on mobile (DSGNEWS-237, [#1263](https://github.com/Automattic/newspack-workspace/issues/1263)) ([e5b89f7](https://github.com/Automattic/newspack-workspace/commit/e5b89f719b7d22cd2be0aef33f0d1f9773fadb06))
+* **components:** lay out the drawer with Stack and end-align its actions ([#1258](https://github.com/Automattic/newspack-workspace/issues/1258)) ([e8dfd37](https://github.com/Automattic/newspack-workspace/commit/e8dfd3766e8a12ffd584a6be7f5352aff9a53f19))
+
+
+### Features
+
+* **content-gate:** reorganize Access Control into tabs ([#1164](https://github.com/Automattic/newspack-workspace/issues/1164)) ([f0622f2](https://github.com/Automattic/newspack-workspace/commit/f0622f2a59bdfd0a7064b551ddd2a7a2895281d2))
+
+
+### Dependencies
+
+* **newspack-icons:** upgraded to 1.3.0-alpha.1
+
+# newspack-components [4.11.0](https://github.com/Automattic/newspack-workspace/compare/newspack-components@4.10.0...newspack-components@4.11.0) (2026-10-14)
+
+
+### Features
+
+* **newsletters:** show premium lists in the subscription form ([#1291](https://github.com/Automattic/newspack-workspace/issues/1291)) ([456d762](https://github.com/Automattic/newspack-workspace/commit/456d762ba465aafc6e5be08ed47836acafaad1a6))
+
 # newspack-components [4.10.0](https://github.com/Automattic/newspack-workspace/compare/newspack-components@4.9.2...newspack-components@4.10.0) (2026-10-12)
 
 

package/DEVELOPMENT.md

@@ -22,7 +22,7 @@ Comprehensive developer guidelines for working with the Newspack Components pack
 
 This package provides custom React components designed specifically for Newspack backend/admin interfaces (wizards, settings pages, etc.). These components are built on top of WordPress components and provide Newspack-specific functionality, styling, and patterns.
 
-**In short:** For backend/admin screens use Newspack components first (Card, ActionCard, SectionHeader, etc.), fall back to WordPress components when needed, and follow the spacing scale and hierarchy patterns so UIs stay consistent. For block editor UI use WordPress components (and `AutocompleteTokenField` only when you need autocomplete). For reader-facing UI use Newspack UI or theme components, not this package.
+**In short:** For backend/admin screens use `@wordpress/ui` for primitives (`Stack`, `Card`, `Badge`, `Text`), Newspack components for Newspack patterns (SectionHeader, ActionCard, EmptyState, etc.), and `@wordpress/components` for what neither covers. Follow the spacing scale and hierarchy patterns so UIs stay consistent. For block editor UI use WordPress components (and `AutocompleteTokenField` only when you need autocomplete). For reader-facing UI use Newspack UI or theme components, not this package.
 
 **Design-wise:** Backend UIs should feel consistent with the WordPress admin, with clear visual hierarchy (section → card → controls) and predictable spacing. Use the same components and spacing scale across wizards so design and code stay aligned; when introducing a new pattern or layout, align with design (and designer review) before implementing.
 
@@ -31,8 +31,9 @@ This package provides custom React components designed specifically for Newspack
 ### Decision Tree
 
 **Backend/Admin UI (Wizards, Settings Pages):**
-- ✅ **Use Newspack components first** - Check if a Newspack component exists for your use case
-- ⚠️ **Fallback to WordPress components** - If no Newspack component exists, use `@wordpress/components`
+- ✅ **Use `@wordpress/ui` for primitives** - Layout, surfaces, badges and text come from the WordPress design system: `Stack`, `Card`, `Badge`, `Text`, `Link`, `Popover`, `VisuallyHidden`
+- ✅ **Use Newspack components for Newspack patterns** - Check if a Newspack component exists for your use case; most new ones are built on `@wordpress/ui`
+- ⚠️ **Fallback to WordPress components** - If neither covers it, use `@wordpress/components` (form controls, core `Notice`, `DropdownMenu`)
 - Examples: Dashboard, Settings, Audience Management, Setup Wizard
 
 **Gutenberg Blocks:**
@@ -49,17 +50,21 @@ This package provides custom React components designed specifically for Newspack
 Follow this step-by-step process when selecting a component:
 
 1. **Check Newspack components first**
-   - Review the [Available Components](#available-components) list below
+   - Review the [Available Components](#available-components) list below, skipping entries marked legacy or deprecated
    - Check `packages/components/src/` directory for component implementations
    - Newspack components are optimized for backend/admin workflows
 
-2. **If not available, use WordPress components**
+2. **For primitives, use `@wordpress/ui`**
+   - `Stack`, `Card`, `Badge`, `Text`, `Link`, `Popover`, `Collapsible`, `Tabs`, `VisuallyHidden`
+   - Import them directly from `@wordpress/ui`; see [From @wordpress/ui](#from-wordpressui)
+
+3. **If not available, use WordPress components**
    - Visit [@wordpress/components Storybook](https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page)
    - Check [@wordpress/components npm package](https://www.npmjs.com/package/@wordpress/components)
    - Cross-reference Storybook documentation and NPM package code with the version of `@wordpress/components` installed via `package.json` to confirm that the installed package contains the expected component(s)
    - WordPress components provide standard admin UI patterns
 
-3. **If still not available, flag for designer review**
+4. **If still not available, flag for designer review**
    - Use a placeholder component and request a new component design from the design team
    - Don't create new components without designer review
    - Once approved, follow existing Newspack component patterns (see [Component Patterns](#component-patterns))
@@ -68,17 +73,31 @@ Follow this step-by-step process when selecting a component:
 
 ## Design & layout at a glance
 
-When building a screen, use the **spacing scale** (8px unit: 16, 24, 32, 48, 64) and prefer **VStack** for vertical stacks and **HStack** for related items in a row; use **Grid** for real multi-column layouts. Structure content as **SectionHeader → Card → ActionCard → controls**, with **Divider** between sections and primary actions in **`.newspack-buttons-card`**. Use the same **breakpoints** (e.g. 744px, 1054px) as existing components. Full detail: [Spacing scale](#spacing-scale-design-system), [Layout (HStack / VStack / Grid)](#layout-when-to-use-hstack-vstack-grid), [Responsive breakpoints](#responsive-breakpoints), [Visual hierarchy patterns](#visual-hierarchy-patterns), [Component states](#component-states). For code examples by context and wizard patterns, see [Usage](#usage).
+When building a screen, use the **spacing scale** (8px unit: 16, 24, 32, 48) with **48px** between sections, and use **`Stack`** from `@wordpress/ui` for rows and columns of items; use **Grid** for real multi-column layouts. Structure content as **SectionHeader → Card → ActionCard → controls**, with **Divider** between sections. Settings and edit screens lay each section out as a [two-column section](#layout-when-to-use-stack-or-grid) (title on the left, fields on the right). Settings tabs put Save in the page header; setup flows and wizard steps keep primary actions in **`.newspack-buttons-card`**. Use the same **breakpoints** (e.g. 744px, 1054px) as existing components. Full detail: [Spacing scale](#spacing-scale-design-system), [Layout (Stack / Grid)](#layout-when-to-use-stack-or-grid), [Responsive breakpoints](#responsive-breakpoints), [Visual hierarchy patterns](#visual-hierarchy-patterns), [Component states](#component-states). For code examples by context and wizard patterns, see [Usage](#usage).
 
 ## Available Components
 
+### From `@wordpress/ui`
+
+These come from the WordPress design system rather than this package. Import them from `@wordpress/ui` directly; they are not re-exported from `newspack-components`, and should not be.
+
+- **`Stack`** – Flex row or column. Replaces `__experimentalHStack` / `__experimentalVStack`. `gap` takes a token (`xs`, `sm` 8px, `md` 12px, `lg` 16px, `xl` 24px, `2xl` 32px, `3xl`), not a number, so `VStack spacing={ 6 }` becomes `gap="xl"`. It lays out as a row unless you pass `direction="column"`, and it sets nothing you don't pass: a bare `HStack` or `Flex` gives an 8px gap, centered items and `space-between`, and a bare `VStack` an 8px gap, so carry those over (`gap="sm" align="center" justify="space-between"`, or `gap="sm"`). Children of an `HStack` or a row `Flex` also lose `min-width: 0`, so a child that truncates text may need it back.
+- **`Card`** – Surface with `Card.Root`, `Card.Header`, `Card.Title`, `Card.Content` and `Card.FullBleed`. Use it for new cards rather than the Newspack `Card`.
+- **`Badge`** – Single attention marker or chip. Text is `children`; `intent` is `high`, `medium`, `low`, `stable`, `informational`, `draft` or `none`, chosen by the state behind the label rather than the label itself.
+- **`Text`**, **`Link`**, **`Popover`**, **`Collapsible`**, **`Tabs`**, **`VisuallyHidden`** – Use these where a Newspack component does not already wrap them. `Popover`, `Collapsible` and `Tabs` are sets of parts rather than single components (`Popover.Root`, `.Trigger`, `.Popup`, `.Title`; `Portal` and `Positioner` go in the popup's `portal` and `positioner` props rather than wrapping it), and every popup needs a non-empty `Popover.Title`, visually hidden if need be; development builds throw without one. `InfoButton` is the worked example.
+
+Their class names are hashed CSS modules, so never target them from our stylesheets. Where a wrapper needs to style one, give it one of our own classes.
+
 ### Layout Components
 
-- **`Card`** – Container for a logical block of content; use for grouping related settings. Default vertical margin is 32px so cards stack with consistent rhythm. Use `noBorder` when cards sit inside another card (e.g. ActionCard children).
+- **`Page`** – Admin page shell: header with breadcrumbs, badges, actions and an optional tab bar. `Wizard` and `withWizardScreen` render it for you unless `hideHeader` is set, but neither passes `badges`, so a header with badges uses `Page` directly. The last breadcrumb is the page's only `h1`.
+- **`Breadcrumbs`** – The trail `Page` renders; the last item is the current page and is not a link.
+- **`Card`** – Legacy container for a logical block of content (class component). Prefer `Card` from `@wordpress/ui` in new code. Default vertical margin is 32px so cards stack with consistent rhythm. Use `noBorder` when cards sit inside another card (e.g. ActionCard children).
 - **`Divider`** – Use between logical sections (e.g. between ActionCards) to separate content without another card. Margins are 32px (48px at larger breakpoints) so spacing stays consistent with the rest of the layout.
 - **`EmptyState`** – Use when a list has nothing in it yet, or an onboarding view stands in for a feature that is not set up. Compound: `EmptyState.Root` wraps `EmptyState.Header` and `EmptyState.Actions`. Render it only when the *unfiltered* collection is empty, so a search matching nothing keeps the DataViews "no results" treatment. See [src/empty-state/README.md](src/empty-state/README.md).
-- **`Grid`** – Use for laying out several items in columns (e.g. multiple controls or cards). Default gap is 32px; use `columns` and `gutter` modifiers (8, 16, 24, 32, 48) when you need tighter or looser spacing. For a single row or a simple vertical stack, prefer **VStack** (or HStack) in new code; Grid is still used that way in many places and is fine to leave as-is until we refactor.
+- **`Grid`** – Use for laying out several items in columns (e.g. multiple controls or cards). Default gap is 32px; use `columns` and `gutter` modifiers (8, 16, 24, 32, 48) when you need tighter or looser spacing. For a single row or a simple vertical stack, use **`Stack`** from `@wordpress/ui` in new code; Grid is still used that way in many places and is fine to leave as-is until we refactor.
 - **`SectionHeader`** – Use to start a new section; pair with a short description so the section’s goal is clear. Top margin (48px) and bottom (32px) create clear separation from previous content and the section body.
+- **`Drawer`** – Panel that slides in from the right edge for editing one item without leaving the list. Compound: `Drawer.Root`, `Header`, `Title`, `CloseIcon`, `Content`, `Divider`, `Footer`, `Action`. `isDirty` on the root makes every way of closing it ask before discarding edits. See [src/drawer/README.md](src/drawer/README.md).
 - **`StatCard`** – Use for a single headline figure with a label above it and a description below. Compound: `StatCard.Root` wraps `Label`, `Body` (holding `Value` and an optional `Secondary`) and `Footer`, with `Delta` riding in the `Value`'s `suffix` for a change beside the figure. Format the figure yourself and pass a string; a `null`, `undefined` or blank `value` gets the shared null glyph rather than a misleading zero. The figure is sized by a container query, so give the cards a definite width (a Grid track, a `flex: 1` item) and equal widths across a row to keep one type scale. See [src/stat-card/README.md](src/stat-card/README.md).
 
 ### Form Components
@@ -92,17 +111,25 @@ When building a screen, use the **spacing scale** (8px unit: 16, 24, 32, 48, 64)
 - **`CustomSelectControl`** - Custom select dropdown component
 - **`FormTokenField`** - Token input field for tags/categories; prefer the Newspack component over the core `FormTokenField` because it also supports a `description` prop for help text like other controls.
 - **`ImageUpload`** - Image upload and selection component
+- **`PageControl`** - Picks one page through an autocomplete search
 - **`RadioControl`** - Radio button group control
+- **`ReorderModal`** - Modal for putting a short list of items in order, by dragging or with move buttons; applies on Save
+- **`SelectControl`** - Deprecated; use core `SelectControl`, or `__experimentalToggleGroupControl` for grouped or button-style choices
 - **`TextControl`** - Text input with Newspack styling and required field support
 
 ### Content Components
 
+- **`CardFeature`** – A feature to enable or configure, with a state-driven button and an optional badge and "More" menu. At most two per row. See [src/card-feature/README.md](src/card-feature/README.md).
+- **`CardForm`**, **`CardSettingsGroup`**, **`CardSortableList`** – Cards that reveal a form, collapse a group of settings, or reorder a list. Each has a README in its folder.
 - **`ActionCard`** – Use when one concept (e.g. a feature or setting) can be toggled on/off and may have extra content below. Internal padding (24px default; 16px/8px for isMedium/isSmall) and 24px between regions keep hierarchy clear; expandable content uses 24px top padding and 24px between siblings.
 - **`CollapsibleGroup`** / **`CollapsibleGroup.Item`** – A stack of independently collapsible items, separated by dividers and flush with the surrounding column. Not a W3C accordion: the items do not coordinate.
 - **`Notice`** – Being retired in favour of core’s `Notice` from `@wordpress/components`, which announces itself to assistive technology. Reach for core’s in new work; ours stays for the screens still on it. Where ours is used, vertical margin is 32px so notices don’t collide with cards, and one primary message per area reads best.
+- **`DataViews`** – `@wordpress/dataviews` with Newspack styling, for list screens.
 - **`ProgressBar`** – Progress indicator.
+- **`StatusIndicator`** – Glyph plus label for a Status column in a list, with a shared vocabulary (`active`, `scheduled`, `draft`, `error`, and so on). Use it instead of a badge in every row. See [src/status-indicator/README.md](src/status-indicator/README.md).
 - **`StepsList`** / **`StepsListItem`** – Step-by-step list components.
 - **`StyleCard`** – Style preview card.
+- **`TableCard`** – A table or DataViews inside a `@wordpress/ui` `Card`, edge to edge, with a heading and an actions slot. See [src/table-card/README.md](src/table-card/README.md).
 - **`Waiting`** – Loading state indicator.
 
 ### Wizard Components
@@ -121,6 +148,7 @@ When building a screen, use the **spacing scale** (8px unit: 16, 24, 32, 48, 64)
   - Used in newer wizards like Audience Management
   - Passes props: `renderPrimaryButton`, plus all original component props
 - **`Wizard`** - Main wizard container with tabbed navigation and data fetching
+- **`WizardBanner`** - Fill whose children render above the wizard's sections, for a screen-wide message
 
 ### Plugin Management Components
 
@@ -130,22 +158,26 @@ When building a screen, use the **spacing scale** (8px unit: 16, 24, 32, 48, 64)
 
 ### Utility Components
 
+- **`ConfirmDialog`** - Confirmation modal, with a destructive variant; can also block router navigation. See [src/confirm-dialog/README.md](src/confirm-dialog/README.md)
 - **`DebugBadge`** - Floating indicator that Newspack debug mode is on. Takes no props and renders nothing unless the site defines `WP_NEWSPACK_DEBUG`
 - **`GlobalNotices`** - Global notice system component
-- **`InfoButton`** - Reveals supplementary context from a `description` prop. Anything a reader needs in order to use a control belongs in visible help text instead
+- **`InfoButton`** - Reveals supplementary context from a `description` prop, on `@wordpress/ui` `Popover` so it also opens on touch. Use it rather than a `Tooltip` for descriptions. Anything a reader needs in order to use a control belongs in visible help text instead
 - **`Modal`** - Modal dialog component
+- **`IntegrationIcon`** - Logo for a third-party integration, picked by `provider`. It is `aria-hidden` and renders nothing for an unknown provider, so keep the provider's name in visible text beside it
 - **`NewspackIcon`** - Newspack icon wrapper component
-- **`Popover`** - Popover component
+- **`Popover`** - Legacy popover wrapper (class component); use `Popover` from `@wordpress/ui` in new code (see [From @wordpress/ui](#from-wordpressui) for its parts)
 - **`WebPreview`** - Web preview iframe component
 
 ### Settings Components
 
 - **`Settings`** - Settings container component
-- **`SortableNewsletterListControl`** - Sortable newsletter list selector
+- **`SortableNewsletterListControl`** - Sortable newsletter list selector. Not exported from the barrel; import it from its own folder
 
 ### Utilities & Hooks
 
 - **`hooks`** - Custom React hooks (e.g., `useObjectState`, `usePrompt`, `useOnClickOutside`)
+- **`useConfirmDialog`** - Hook form of `ConfirmDialog`: returns `{ confirmDialog, requestConfirm, cancelConfirm }`
+- **`useUnsavedChangesDialog`** - Asks before the user leaves a screen with unsaved changes, by link or by closing the tab. Render the `confirmDialog` it returns, or links do nothing while it is active; one active instance per screen
 - **`Router`** - Proxied React Router import (use instead of direct `react-router-dom` import)
   - Note: This package currently uses [React Router v5](https://v5.reactrouter.com/). Please refer to v5 documentation for API details.
 - **`utils`** - Utility functions (e.g., `confirmAction`, color utilities)
@@ -246,7 +278,7 @@ This section shows how to use components **by context** (backend, blocks, fronte
 
 ### Backend/Admin UI
 
-**Rule:** Use Newspack components as the primary choice, falling back to WordPress components when needed.
+**Rule:** Use `@wordpress/ui` primitives and Newspack components, falling back to WordPress components when needed. The examples below show existing screens, several on the legacy Newspack `Card`; new code uses `Card` from `@wordpress/ui`, imported as `Card as UICard` in a file that still needs ours.
 
 **Common import pattern:**
 ```jsx
@@ -518,9 +550,7 @@ When Newspack components don't provide what you need, use these WordPress compon
 
 ### Layout
 
-- **`__experimentalHStack as HStack`** – Horizontal stack (in use, e.g. Audience > Subscriptions)
-- **`__experimentalVStack as VStack`** – Vertical stack (preferred for new layout when you need vertical stacking; use same import pattern as HStack)
-- **`Flex`** / **`FlexItem`** – Flex layout (used in Nextdoor sidebar; consider HStack/VStack for new code when appropriate)
+- Use **`Stack`** from `@wordpress/ui` (see [From @wordpress/ui](#from-wordpressui)). `__experimentalHStack`, `__experimentalVStack` and `Flex` / `FlexItem` are still in older screens; replace them when you rework that layout, and don't add new ones.
 
 ### Panels and structure (blocks and admin)
 
@@ -540,11 +570,11 @@ When Newspack components don't provide what you need, use these WordPress compon
 ### Feedback and overlays
 
 - **`Spinner`** – Loading spinner
-- **`Notice`** – Inline notice (success/error/warning); prefer this over the Newspack `Notice`, which is being retired
+- **`Notice`** – Inline notice (success/error/warning); prefer this over the Newspack `Notice`, which is being retired, and over `@wordpress/ui`'s `Notice`, which we have not adopted
 - **`Placeholder`** – Empty state in blocks
 - **`Modal`** – Modal dialog
-- **`Popover`** – Popover (e.g. webhooks endpoint actions, corrections modal)
-- **`Tooltip`** – Tooltip (e.g. site statuses, info)
+- **`Popover`** – Popover (e.g. webhooks endpoint actions, corrections modal); prefer `Popover` from `@wordpress/ui` in new code, which is a set of parts rather than a drop-in
+- **`Tooltip`** – Tooltip for a short label on hover (e.g. site statuses). It opens on hover and keyboard focus but never on touch, so use `InfoButton` for descriptions
 
 ### Block editor UI
 
@@ -562,29 +592,23 @@ When Newspack components don't provide what you need, use these WordPress compon
 
 ### Importing experimental components
 
-Experimental components (e.g. `HStack`, `VStack`, `NumberControl`, `ToggleGroupControl`, `Heading`) live under `@wordpress/components` and may be prefixed with `__experimental`. Use the same import style as the rest of the codebase and add an eslint disable for unsafe APIs when required:
+Experimental components (e.g. `NumberControl`, `ToggleGroupControl`, `Heading`) live under `@wordpress/components` and may be prefixed with `__experimental`. Use the same import style as the rest of the codebase and add an eslint disable for unsafe APIs when required:
 
 ```jsx
 import {
-	__experimentalHStack as HStack, // eslint-disable-line @wordpress/no-unsafe-wp-apis
 	__experimentalNumberControl as NumberControl, // eslint-disable-line @wordpress/no-unsafe-wp-apis
-	__experimentalVStack as VStack, // eslint-disable-line @wordpress/no-unsafe-wp-apis
 	ExternalLink,
 } from '@wordpress/components';
 ```
 
 **Example – form controls and layout:**
 ```jsx
-import {
-	CheckboxControl,
-	ExternalLink,
-	__experimentalHStack as HStack, // eslint-disable-line @wordpress/no-unsafe-wp-apis
-	RangeControl,
-} from '@wordpress/components';
-import { ActionCard, Card } from '../../../../../packages/components/src';
+import { CheckboxControl, RangeControl } from '@wordpress/components';
+import { Stack } from '@wordpress/ui';
+import { ActionCard } from '../../../../../packages/components/src';
 
 <ActionCard title="Settings">
-	<HStack>
+	<Stack gap="lg">
 		<RangeControl
 			label={ __( 'Value', 'newspack-plugin' ) }
 			value={ config.value }
@@ -595,7 +619,7 @@ import { ActionCard, Card } from '../../../../../packages/components/src';
 			checked={ config.enabled }
 			onChange={ value => updateConfig( 'enabled', value ) }
 		/>
-	</HStack>
+	</Stack>
 </ActionCard>
 ```
 
@@ -627,11 +651,28 @@ Spacing is based on an **8px unit**. Use these values so new styles match existi
 
 **In code:** Card uses `margin: 32px 0` and `padding: 16px 48px` (32px 64px at 744px+). ActionCard uses 24px for region padding and 24px between regions; region-children use `padding: 0 24px 24px` (0 32px 32px for is-medium). Grid uses `grid-gap: 32px` and `margin: 32px 0` by default, with optional gutter classes (`__gutter-8`, `__gutter-16`, etc.). When adding new components or overrides, prefer these values (or 8px multiples) instead of ad-hoc spacing.
 
-### Layout: when to use HStack, VStack, Grid
+### Layout: when to use Stack or Grid
+
+- **`Stack`** from `@wordpress/ui` – A few related items in a row (e.g. label + control), or a single column of items, lists of settings, or stacked sections. Use `gap` for the spacing instead of margins on the children. A column needs `direction="column"`; without it, `Stack` lays out as a row.
+- **Grid (Newspack)** – A set of items in columns (e.g. multiple cards or form groups). Default 32px gap; use `columns` and gutter modifiers. Use when the layout is genuinely a grid of items (multiple columns). There are many existing examples where Grid is used as a single row. That is fine to leave, but new code uses `Stack` for it.
+
+**Two-column sections** are the standard layout for a section of a settings or edit screen: what the section is on the left, its fields on the right. Settings tabs use it, and so do the Access Control editors (gates, metering, content gifting, institutions), the integration and experimental tool configure views, and the pricing rule and product forms. Use it for any new screen made of named groups of settings:
+
+```jsx
+<>
+	<Grid columns={ 2 } gutter={ 32 } noMargin>
+		<SectionHeader heading={ 2 } noMargin title={ … } description={ … } />
+		<Stack direction="column" gap="xl">
+			{ /* fields */ }
+		</Stack>
+	</Grid>
+	<Divider alignment="full-width" variant="tertiary" />
+</>
+```
+
+The `Grid` collapses to one column below 744px, so the header sits above its fields on narrow screens. Fields drop their own bottom margin so the `Stack` gap is the only spacing: Newspack `TextControl` takes `withMargin={ false }` plus `__nextHasNoMarginBottom` and `__next40pxDefaultSize`; core `ToggleControl` and `CheckboxControl` take `__nextHasNoMarginBottom`. Content that needs the full width (logs, card pickers, tables) stacks its `SectionHeader` above it instead. Some existing editors predate this: their right column is a `VStack` (`spacing={ 4 }` or `{ 6 }`) and their `SectionHeader` has no `noMargin`. New and reworked sections follow the example. A grid of cards that each open their own screen is a different pattern and has no `SectionHeader` column.
 
-- **HStack** – A few related items in a row (e.g. label + control, or two related controls). Use when the relationship is “these belong together horizontally.”
-- **VStack** – Stack blocks vertically with consistent spacing. **Prefer VStack** for a single column of items, lists of settings, or stacked sections when you want vertical rhythm without custom margins. For new code, favour VStack over using Grid as a single row.
-- **Grid (Newspack)** – A set of items in columns (e.g. multiple cards or form groups). Default 32px gap; use `columns` and gutter modifiers. Use when the layout is genuinely a grid of items (multiple columns). There are many existing examples where Grid is used as a single row—that’s not wrong, but we’d use VStack (or HStack) for that in new code and may update those over time.
+**Settings tabs** are built from two-column sections. Save sits in the page header, published with `setHeaderData( { actions } )` from the wizard store and disabled until something changes. The header keeps whichever callback it was handed, so read the latest handler from a ref; passing the save function directly saves stale state. Pair it with `useUnsavedChangesDialog`. See `plugins/newspack-plugin/src/wizards/newspack/views/settings/seo/index.tsx`.
 
 Prefer these patterns (and the spacing scale above) over one-off margins so layout stays consistent with Card, ActionCard, and SectionHeader.
 
@@ -656,14 +697,14 @@ Prefer these values over new breakpoints so behaviour stays consistent with Card
 
 Common composition patterns keep screens predictable. Use these as a reference when building new wizards or settings:
 
-**Settings screen (Wizard-based):**
+**Setup screen (Wizard-based):**
 ```
 Wizard
   GlobalNotices
   SectionHeader          ← 48px top margin
   Card                   ← 32px margin
     ActionCard            ← 24px padding, optional toggle
-      Grid or VStack      ← 32px gap
+      Grid or Stack       ← 32px gap (Grid default; Stack gap="2xl")
         TextControl / SelectControl / etc.
     Divider              ← 32px / 48px margin
     ActionCard
@@ -684,7 +725,7 @@ withWizardScreen
     Button
 ```
 
-**Form group:** Use `Grid columns={4}` (or VStack) with TextControl, SelectControl, CheckboxControl, etc. inside a Card or ActionCard; spacing between controls follows the [spacing scale](#spacing-scale-design-system) (e.g. 16px for related rows).
+**Form group:** Use `Grid columns={4}` (or `Stack`) with TextControl, SelectControl, CheckboxControl, etc. inside a Card or ActionCard; spacing between controls follows the [spacing scale](#spacing-scale-design-system) (e.g. 16px for related rows).
 
 ### Component states
 
@@ -721,6 +762,7 @@ When adding new interactive components, preserve focus visibility and use the sa
 
 - **[newspack-colors](../colors/)** – Color palette used by components (via WordPress design system)
 - **[newspack-icons](../icons/)** – Custom icons used in components
+- **[@wordpress/ui](https://www.npmjs.com/package/@wordpress/ui)** – WordPress design system components (`Stack`, `Card`, `Badge`, `Text` and more); first choice for primitives
 - **[@wordpress/components](https://www.npmjs.com/package/@wordpress/components)** – WordPress component library (fallback when Newspack components don’t exist)
 - **[@wordpress/base-styles](https://www.npmjs.com/package/@wordpress/base-styles)** – WordPress Design System styles and colors
 

package/dist/cjs/breadcrumbs/index.js

@@ -94,6 +94,7 @@ var Breadcrumbs = function Breadcrumbs(_ref3) {
       render: /*#__PURE__*/(0, _jsxRuntime.jsx)("ul", {}),
       direction: "row",
       align: "center",
+      wrap: "wrap",
       className: "newspack-breadcrumbs__list",
       children: [preceding.map(function (item, index) {
         return /*#__PURE__*/(0, _jsxRuntime.jsxs)("li", {

package/dist/cjs/breadcrumbs/style.scss

@@ -7,8 +7,8 @@
 	padding: 0;
 
 	> li {
-		flex-shrink: 0;
 		margin: 0;
+		min-width: 0;
 
 		a {
 			color: wp-colors.$gray-900;
@@ -20,11 +20,6 @@
 			}
 		}
 	}
-
-	> li:last-child {
-		flex-shrink: 1;
-		min-width: 0;
-	}
 }
 
 .newspack-breadcrumbs__count {
@@ -39,9 +34,7 @@
 }
 
 .newspack-breadcrumbs__list h1.newspack-breadcrumbs__current {
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
+	overflow-wrap: break-word;
 	padding: 0;
-	line-height: normal;
+	line-height: var(--wpds-typography-line-height-md, #{wp-vars.$grid-unit-30});
 }

package/dist/cjs/card/style-core.scss

@@ -221,7 +221,7 @@
 				color: inherit;
 				text-decoration: none;
 				&:hover {
-					text-decoration: underline;
+					color: var(--wp-admin-theme-color);
 				}
 			}
 		}

package/dist/cjs/card-sortable-list/index.js

@@ -8,23 +8,23 @@ exports["default"] = void 0;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _classnames = _interopRequireDefault(require("classnames"));
 var _components = require("@wordpress/components");
 var _element = require("@wordpress/element");
 var _ui = require("@wordpress/ui");
-var _ = require("../");
+var _card = _interopRequireDefault(require("../card"));
+var _tooltipBadge = _interopRequireDefault(require("../tooltip-badge"));
 require("./style.scss");
-var _classnames = _interopRequireDefault(require("classnames"));
 var _jsxRuntime = require("react/jsx-runtime");
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2["default"])(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; } /**
  * Card - Sortable list component.
  */ /**
+ * External dependencies
+ */ /**
  * WordPress dependencies.
- */ // eslint-disable-line @wordpress/no-unsafe-wp-apis
-/**
- * Internal dependencies
  */ /**
- * External dependencies
+ * Internal dependencies
  */
 var DROP_ANIMATION_DURATION = 400; // ms — must match $drop-duration in style.scss
 var BUTTON_MOVE_DURATION = 200; // ms — must match $shift-duration in style.scss
@@ -347,13 +347,14 @@ var CardSortableList = function CardSortableList(_ref) {
     return 0;
   };
   var isDragging = draggingIndex !== null;
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.__experimentalVStack, {
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ui.Stack, {
+    direction: "column",
+    gap: "lg",
     ref: listRef,
     className: (0, _classnames["default"])('newspack-card--core--sortable-list', disabled && 'newspack-card--core--sortable-list__is-disabled', isDragging && 'newspack-card--core--sortable-list__is-dragging'),
     style: measurements ? {
       height: measurements.lockedHeight
     } : undefined,
-    spacing: 4,
     children: sortedItems.map(function (item, index) {
       var translateY = getTranslateY(index);
       return /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Disabled, {
@@ -385,10 +386,10 @@ var CardSortableList = function CardSortableList(_ref) {
             onDragEnd: handleDragEnd,
             appendToOwnerDocument: true,
             children: function children(_ref2) {
-              var _item$badge, _item$badge$intent;
+              var _item$badge, _item$badge$intent, _item$secondaryBadge, _item$secondaryBadge$;
               var onDraggableStart = _ref2.onDraggableStart,
                 onDraggableEnd = _ref2.onDraggableEnd;
-              return /*#__PURE__*/(0, _jsxRuntime.jsx)(_.Card, {
+              return /*#__PURE__*/(0, _jsxRuntime.jsx)(_card["default"], {
                 isSmall: true,
                 draggable: true,
                 onDragStart: onDraggableStart,
@@ -400,7 +401,14 @@ var CardSortableList = function CardSortableList(_ref) {
                       children: [item.title, ((_item$badge = item.badge) === null || _item$badge === void 0 ? void 0 : _item$badge.label) && /*#__PURE__*/(0, _jsxRuntime.jsx)(_ui.Badge, {
                         intent: (_item$badge$intent = item.badge.intent) !== null && _item$badge$intent !== void 0 ? _item$badge$intent : 'none',
                         children: item.badge.label
-                      })]
+                      }), ((_item$secondaryBadge = item.secondaryBadge) === null || _item$secondaryBadge === void 0 ? void 0 : _item$secondaryBadge.label) && (item.secondaryBadge.tooltip ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_tooltipBadge["default"], {
+                        label: item.secondaryBadge.label,
+                        tooltip: item.secondaryBadge.tooltip,
+                        intent: item.secondaryBadge.intent
+                      }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_ui.Badge, {
+                        intent: (_item$secondaryBadge$ = item.secondaryBadge.intent) !== null && _item$secondaryBadge$ !== void 0 ? _item$secondaryBadge$ : 'none',
+                        children: item.secondaryBadge.label
+                      }))]
                     }), item.description && /*#__PURE__*/(0, _jsxRuntime.jsx)("p", {
                       children: item.description
                     })]
@@ -413,7 +421,10 @@ var CardSortableList = function CardSortableList(_ref) {
                 }, item.onToggleChange !== undefined && {
                   actionType: 'toggle',
                   isActive: item.toggleChecked,
-                  onToggle: item.onToggleChange
+                  onToggle: item.onToggleChange,
+                  // Names the toggle for assistive tech. The card hides this
+                  // label, since the header already shows the title.
+                  title: item.title
                 }), item.actions !== undefined && {
                   actions: item.actions
                 })

package/dist/cjs/card-sortable-list/index.test.js

@@ -47,4 +47,25 @@ describe('CardSortableList', function () {
     // An unguarded Badge would still emit an empty span, so assert on element children.
     expect(container.querySelector('h3').children).toHaveLength(0);
   });
+  it('names each toggle after its item', function () {
+    (0, _react.render)(/*#__PURE__*/(0, _jsxRuntime.jsx)(_["default"], {
+      items: [{
+        id: 1,
+        title: 'Homepage',
+        toggleChecked: true,
+        onToggleChange: function onToggleChange() {}
+      }, {
+        id: 2,
+        title: 'About',
+        toggleChecked: false,
+        onToggleChange: function onToggleChange() {}
+      }]
+    }));
+    expect(_react.screen.getByRole('checkbox', {
+      name: 'Homepage'
+    })).toBeChecked();
+    expect(_react.screen.getByRole('checkbox', {
+      name: 'About'
+    })).not.toBeChecked();
+  });
 });

package/dist/cjs/card-sortable-list/style.scss

@@ -6,6 +6,14 @@ $drop-duration: 400ms; /* must match DROP_ANIMATION_DURATION in index.tsx */
 	&__item {
 		cursor: grab;
 
+		/*
+		 * Keep a card's title in the case it was written in. The block editor
+		 * sidebar uppercases every h3 (`.interface-complementary-area h3`).
+		 */
+		.newspack-card--core__header-content h3 {
+			text-transform: none;
+		}
+
 		/*
 		 * Animate items sliding to fill/make space around the dragged item.
 		 */

package/dist/cjs/drawer/body.js

@@ -6,14 +6,13 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports["default"] = void 0;
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
-var _components = require("@wordpress/components");
 var _element = require("@wordpress/element");
 var _i18n = require("@wordpress/i18n");
+var _ui = require("@wordpress/ui");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * WordPress dependencies.
  */
-// eslint-disable-line @wordpress/no-unsafe-wp-apis
 
 /**
  * Internal dependencies.
@@ -63,11 +62,10 @@ var Body = function Body(_ref) {
       mutation.disconnect();
     };
   }, [node]);
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.__experimentalVStack, {
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ui.Stack, {
     ref: setNode,
-    className: "newspack-drawer__body",
-    spacing: 0,
-    justify: "flex-start"
+    direction: "column",
+    className: "newspack-drawer__body"
     // A bare div is role=generic, where ARIA prohibits an author name.
     ,
     role: isScrollable ? 'group' : undefined,

package/dist/cjs/drawer/content.js

@@ -5,14 +5,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports["default"] = void 0;
-var _components = require("@wordpress/components");
-var _element = require("@wordpress/element");
+var _ui = require("@wordpress/ui");
 var _classnames = _interopRequireDefault(require("classnames"));
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * WordPress dependencies.
  */
-// eslint-disable-line @wordpress/no-unsafe-wp-apis
 
 /**
  * External dependencies.
@@ -22,51 +20,23 @@ var _jsxRuntime = require("react/jsx-runtime");
  * Internal dependencies.
  */
 
-// VStack drops non-elements, a lone string aside. A run shares one wrapper so
-// `Edited by { name }` is one row, not three.
-var asRows = function asRows(children) {
-  if ('string' === typeof children) {
-    return children;
-  }
-  var rows = [];
-  var text = [];
-  var flushText = function flushText() {
-    if (text.some(function (part) {
-      return '' !== String(part).trim();
-    })) {
-      rows.push(/*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
-        children: text
-      }, "text-".concat(rows.length)));
-    }
-    text = [];
-  };
-  _element.Children.toArray(children).forEach(function (child) {
-    if ((0, _element.isValidElement)(child)) {
-      flushText();
-      rows.push(child);
-    } else {
-      text.push(child);
-    }
-  });
-  flushText();
-  return rows;
-};
 var Content = function Content(_ref) {
   var _ref$padding = _ref.padding,
     padding = _ref$padding === void 0 ? 6 : _ref$padding,
     _ref$gap = _ref.gap,
-    gap = _ref$gap === void 0 ? 4 : _ref$gap,
+    gap = _ref$gap === void 0 ? 'lg' : _ref$gap,
     className = _ref.className,
     children = _ref.children;
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.__experimentalVStack, {
-    className: (0, _classnames["default"])('newspack-drawer__content', className),
-    spacing: gap
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ui.Stack, {
+    direction: "column",
+    gap: gap,
+    className: (0, _classnames["default"])('newspack-drawer__content', className)
     // A custom property, not inline padding, so the stylesheet's seam rules win.
     ,
     style: {
       '--newspack-drawer-content-padding': "".concat(padding * 4, "px")
     },
-    children: asRows(children)
+    children: children
   });
 };
 var _default = exports["default"] = Content;