Search dashboard: adopt the unified @wordpress/ui tab pattern by kangzj · Pull Request #48846 · Automattic/jetpack

kangzj · 2026-05-14T22:25:21Z

Why

The Search dashboard's tab strip didn't follow the unified @wordpress/ui Tabs pattern that the rest of the modernized Jetpack admin pages adopt (Podcast, Newsletter, Scan, VideoPress, Protect). Two specific problems were visible:

Tabs read as the loudest element in the header. <Tabs.Tab> from @wordpress/ui declares font-size: var(--wpds-typography-font-size-md) inside @layer wp-ui-components. wp-admin core ships an unlayered button { font-size: inherit } reset, and unlayered rules win over layered ones, so the tab text was silently inheriting 16px from its surrounding context instead of the 13px the design token specifies. Result: tab labels were taller than the 15px page title — visual hierarchy inverted.
The first tab wasn't aligned with the page header content edge. The shared .jp-admin-page-tabs wrapper adds only 8px of inline padding, designed to compose with the default <Tabs.Tab>'s 16px (8 + 16 = 24px = the admin-ui Page header's 2xl padding). With variant="minimal" the per-tab padding is 0, so the first tab started 16px shy of the title's left edge.

Proposed changes

Wrap <Tabs.List variant="minimal"> in <div className="jp-admin-page-tabs"> — the canonical wrapper from @automattic/jetpack-base-styles/admin-page-layout used by every recently modernized Jetpack admin dashboard. It sticky-pins the strip, applies the --wpds-* border + background tokens that match @wordpress/admin-ui's page-header treatment, and now provides 24px of inline padding so the first tab is flush with the header start across all widths.
Re-apply --wpds-typography-font-size-md to [role="tab"] from an unlayered selector so the design token actually lands. This compensates for wp-admin's button { font-size: inherit } reset shadowing the layered @wordpress/ui declaration.
All var(--wpds-*) usages carry the token's literal value as a fallback, matching the convention in @automattic/jetpack-base-styles and other Jetpack packages.

No changes to <AdminPage> props, the page title, or the subtitle — they all keep their canonical token-driven values.

Screenshots

Before (trunk)	After (this PR)

Related product discussion/links

Linear: RSM-3299 (Jetpack Search blocks project)
Design direction: phcsdm-PK-p2 · fBCpFRsWEkIP0rx9AXNIJt-fi-5677_64248
Same pattern in: Podcast (projects/packages/podcast/src/dashboard/index.tsx), Newsletter (projects/packages/newsletter/_inc/components/newsletter-page.tsx), Scan, VideoPress, Protect.

Does this pull request change what data or activity we track or use?

No.

Testing instructions

On a Jetpack site with Search active, go to Jetpack → Search in wp-admin.
Open DevTools and verify the design tokens are landing:
- Tab text computes to font-size: 13px (the value of --wpds-typography-font-size-md).
- Page title <h1> stays at its native 15px (admin-ui <Text variant="heading-lg">).
- Tab labels are smaller than the title — visual hierarchy is title > tabs.
Check alignment:
- The first tab's left edge is flush with the Jetpack icon at the page header start (24px from the page-content edge).
- Resize the window between mobile (~600px), tablet (~900px), and desktop (1440px+). The alignment holds at every width.
Click each tab (Plan & Usage / Settings / AI Answers (Preview)) and confirm:
- URL tab= query param updates (?tab=plan-usage / ?tab=settings / ?tab=ai-answers).
- Reloading the page on a given tab keeps that tab selected.
- Active-tab indicator slides correctly.
Scroll the content area and confirm the tab strip stays pinned at the top.

github-actions · 2026-05-14T22:26:04Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the atlas/rsm-3299-match-myjetpack-tabs branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack atlas/rsm-3299-match-myjetpack-tabs

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2026-05-14T22:26:27Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

kangzj · 2026-05-15T00:51:51Z

Pivoted per design direction — force-pushed 51700e3b to replace the previous 5 commits with a single, minimal change:

Reverted the @wordpress/components TabPanel swap.
@wordpress/ui Tabs is kept (the IA / UI Unification target).
The only remaining change is showBottomBorder={ false } on AdminPage, which removes the horizontal rule between the page header and the tab strip — that's the visible mismatch with My Jetpack.
All custom SCSS overrides removed; the tab strip's spacing/typography/colors now come entirely from @wordpress/ui's built-in design tokens.

Updated screenshots show the before/after (the change is subtle: just the absence of the separator).

PR body and title updated to reflect the new (much narrower) scope.

kangzj · 2026-05-15T01:20:54Z

Revised approach — force-pushed 48d20603. The earlier showBottomBorder={ false } patch was a workaround, not the canonical solution. The proper Jetpack convention (used by Podcast, Protect, Scan, VideoPress) is to wrap <Tabs.List> in <div className="jp-admin-page-tabs"> and set variant="minimal".

The wrapper, defined in @automattic/jetpack-base-styles/admin-page-layout, handles all of the visual continuity for in-page tab strips: sticky-pinning, the --wpds-* border + background tokens matching admin-ui's page header, and title-aligned start padding.

PR title and body updated; screenshots refreshed.

cc @adamwoodnz — does this look right?

Wraps `Tabs.List` from `@wordpress/ui` in `<div class="jp-admin-page-tabs">` with `variant="minimal"`, matching the pattern used by Podcast, Newsletter, Scan, and the other recently modernized Jetpack admin dashboards. The wrapper (defined in `@automattic/jetpack-base-styles/admin-page-layout`) sticky-pins the strip, applies the `--wpds-*` border + background tokens that match `@wordpress/admin-ui`'s page-header treatment so the strip reads as a visual continuation of the header, and aligns the first tab's start edge with the page title. `variant="minimal"` tightens the per-tab padding for the compact look the other dashboards use. No `AdminPage` prop overrides, no custom SCSS.

- `<Tabs.Tab>` from `@wordpress/ui` declares `font-size: var(--wpds-typography-font-size-md)` inside `@layer wp-ui-components`. wp-admin core ships an unlayered `button { font-size: inherit }` reset that wins over any layered rule, so tabs silently inherit 16px from their surrounding context instead of the 13px the token specifies. Re-apply the token from an unlayered selector so the design system lands as intended (tabs at 13px, smaller than the 15px page title). - `.jp-admin-page-tabs` wrapper padding-inline set to the page header's 2xl (24px) so the first tab's content edge sits flush with the header across all screen widths. Required because `variant="minimal"` drops the per-<Tabs.Tab> 16px inline padding the shared wrapper's 8px default relies on for alignment. - Selectors are scoped under `body.jetpack_page_jetpack-search` to beat the body-prefixed rule from `@automattic/jetpack-base-styles`. All `var()` usages carry the token's literal value as a fallback.

adamwoodnz · 2026-05-15T03:33:52Z

+								{ __( 'AI Answers', 'jetpack-search-pkg' ) }{ ' ' }
+								<span className="jp-search-dashboard-tabs__tab-preview-label">
+									{ __( '(Preview)', 'jetpack-search-pkg' ) }
+								</span>


Can we please insert a space between 'AI Answers' and '(Preview)'? It hurts my eyes 😬

Addressed in follow-up #48850 (commit c8055f2). The new flex-based Tabs.Tab was collapsing the { ' ' } JSX whitespace between the text node and the span, so I moved a   inside the preview-label span — sibling-whitespace collapsing in flex doesn't reach inside the element's own text content, so the gap now renders reliably. 🙏

…eview)" tab label (#48850) The new flex-based `Tabs.Tab` from `@wordpress/components` collapses JSX `{ ' ' }` whitespace between sibling nodes, so the "(Preview)" suffix rendered flush against "AI Answers". Move a non-breaking space inside the preview-label span so it survives the flex layout. Follow-up to #48846 (review comment #3245711759).

kangzj added [Status] Needs Review This PR is ready for review. [Feature] Search For all things related to Search [Status] In Progress and removed [Status] Needs Review This PR is ready for review. labels May 14, 2026

kangzj marked this pull request as draft May 14, 2026 22:25