Skip to content

Fix plugin-card button overlap on Add Plugins screen (#64686) - #12376

Open
369work wants to merge 16 commits into
WordPress:trunkfrom
369work:fix/64686-plugin-card-overlap
Open

369work wants to merge 16 commits into
WordPress:trunkfrom
369work:fix/64686-plugin-card-overlap

Conversation

@369work

@369work 369work commented Jul 1, 2026

Copy link
Copy Markdown

Summary

This patch fixes the plugin-card button overlap reported in #64686 by
replacing the absolute-positioning-based layout of .plugin-card-top
with a flexbox + container query based one, following the direction
agreed in comment:29 (joedolson) and comment:30 (wildworks): no
position: absolute, no legacy fixed-offset CSS, and a layout that
doesn't depend on button label length.

Only src/wp-admin/css/list-tables.css is touched. No PHP/markup
changes are required.

Root cause

The overlap wasn't a single bug — it was two independent, viewport-based
breakpoint systems drifting out of sync:

  1. The outer grid (#the-list) decides how many .plugin-cards fit
    per row (1 column below 782px, 2 columns from 783px, 3 columns from
    1600px, 4 columns from 2300px).
  2. The inner layout of .plugin-card-top (icon / title / description /
    action buttons) previously decided its own layout using viewport
    width
    via @media, not the actual rendered width of the card.

Because a card's real width depends on both the viewport width and the
current column count, a @media rule keyed to viewport width can't
reliably predict how much space is actually available inside a card.
A card in 3-column mode at a wide viewport can be narrower than a card
in 2-column mode at a medium viewport, yet a viewport-based rule treats
them identically. This mismatch is what produced the reported overlaps
at 320px, 481–756px, and again at 1600px+.

Why container queries instead of viewport media queries

container-type: inline-size is added to .plugin-card, and the
internal layout responds to the card's own rendered width via
@container, not the viewport. This removes the dependency on two
unrelated breakpoint systems entirely — the inner layout now always
has an accurate picture of its own available space, regardless of
column count or viewport size.

Browser support: container size queries are supported by all browsers
in Core's official browser support matrix
(last 2 versions of Chrome/Firefox/Safari/Edge/Opera/iOS), so no
fallback is required.

Why 600px as the breakpoint

The action-buttons column only shares a row with the icon+title when
there's enough width for all three to coexist without cramping:

  • Card padding: 32px (16px × 2)
  • Icon: 128px (fixed)
  • Icon–title gap: 20px
  • Title (minimum comfortably readable width): ~150px
  • Title–button gap: ~20px
  • Action button column (accounting for longer translated labels): ~180–200px

Summing these gives roughly 550px as the point where things start to
fit at all, with no margin for longer translations or larger font
settings. 600px was chosen to give a small buffer above that minimum
so the side-by-side layout only activates when there's genuinely
enough room, consistent with the "don't depend on button text length"
principle from comment:29/30.

Icon/title ordering

The icon remains inside the existing <a class="open-plugin-details-modal">
(no markup change). .plugin-card .name h3 a is made a flex container;
the title text becomes an anonymous flex item and .plugin-icon is
placed before it visually via order: -1, keeping the icon clickable
as part of the details link and preserving the existing DOM order.

Testing

Verified visually across 320, 375, 540, 768, 820, 1024, 1200, 1440,
1574, and 1920px viewport widths on the "Add Plugins" (bundled/beta),
single-column, and multi-column (2/3-col) card grids. In all cases:

  • Icon and title stay aligned regardless of title length
  • Action buttons consistently sit below (narrow cards) or beside
    (wide cards) the icon+title block, with no cards falling into an
    inconsistent in-between state
  • No overlapping elements at any tested width

Trac ticket: https://core.trac.wordpress.org/ticket/64686

Use of AI Tools

AI assistance: Yes
Tool(s): Claude (Anthropic)
Model(s): Claude
Used for: Root-cause analysis of the layout bug, CSS implementation (flexbox + container query refactor), and drafting this PR/Trac description. All changes were tested and verified across multiple viewport widths (320–1920px) by me before submission.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

…een.

Replaces the position:absolute based layout of .plugin-card-top with a flexbox + container query based one. See #64686 for background.
Copilot AI review requested due to automatic review settings July 1, 2026 06:34
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

Hi there! 👋

Thank you for your contribution to WordPress! 💖

It looks like this is your first pull request to wordpress-develop. Here are a few things to be aware of that may help you out!

No one monitors this repository for new pull requests. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core. To attach a pull request to a Trac ticket, please include the ticket's full URL in your pull request description.

Pull requests are never merged on GitHub. The WordPress codebase continues to be managed through the SVN repository that this GitHub repository mirrors. Please feel free to open pull requests to work on any contribution you are making.

More information about how GitHub pull requests can be used to contribute to WordPress can be found in the Core Handbook.

Please include automated tests. Including tests in your pull request is one way to help your patch be considered faster. To learn about WordPress' test suites, visit the Automated Testing page in the handbook.

If you have not had a chance, please review the Contribute with Code page in the WordPress Core Handbook.

The Developer Hub also documents the various coding standards that are followed:

Thank you,
The WordPress Project

@github-actions

github-actions Bot commented Jul 1, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props 369work, westonruter, wildworks, joedolson.

At least one ghost was discovered. ghosts represent deleted GitHub user accounts.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR addresses button overlap in the Plugin Install “Add Plugins” screen by refactoring the .plugin-card-top layout from an absolute-positioning approach to a flexbox layout driven by container queries. This aligns the internal card layout with the card’s rendered width (rather than viewport width), preventing breakpoint mismatches that previously caused overlaps.

Changes:

  • Adds container-type: inline-size to .plugin-card to enable size-based container queries.
  • Replaces .plugin-card-top’s positioning-based layout with a wrapping flex layout (icon/title, actions, description).
  • Updates action button list styling to switch between inline and stacked layouts via @container (min-width: 600px).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@joedolson

Copy link
Copy Markdown
Contributor

This is certainly going in a better direction - I think using containers to handle the width is a good idea.

However, this style change introduces a significant visual difference that leaves a large amount of empty white space that I don't think is desirable. I think it's going to require some structural changes in order to be feasible.

As I see it, the region with the icon, title, and action buttons needs to be a grid/flex with an order of icon > heading/description > actions. It won't be trivial to achieve the current or similar layout while also ensuring that the h3 is the first item in the card and the icon is clickable, but that's what needs to happen. It might mean needing to remove the icon from the link and give it a scripted event to trigger the heading's link, but have the image itself have aria-hidden. The focus target would change shape, but the ability to trigger the link would be unchanged for keyboard users.

westonruter and others added 5 commits July 4, 2026 16:52
Derive the `Disallow` and `Allow` directives in `do_robots()` from `admin_url()` and `admin_url( 'admin-ajax.php' )` rather than from a hardcoded `/wp-admin/` path built off `site_url()`. Only the URL path portion is emitted, as before, so installs that relocate or filter their admin URL now produce a correct default `robots.txt`.

Also guard the `Content-Type` header with a `headers_sent()` check to avoid a warning when the headers have already been sent.

Developed in WordPress#11998.
Follow-up to r34985.

Props masteradhoc, yogeshbhutkar, hrohh, westonruter, mukeshpanchal27, 1ucay.
Fixes #63467.


git-svn-id: https://develop.svn.wordpress.org/trunk@62633 602fd350-edb4-49c9-b593-d223f7449a82
The `ini_get()` function is called unconditionally early in the bootstrap process, so there is no need for subsequent `function_exists( 'ini_get' )` checks.

Follow-up to [44986], [45104].

Props siliconforks, shreyasikhar26, ankitkumarshah, westonruter, SergeyBiryukov.
Fixes #65423.

git-svn-id: https://develop.svn.wordpress.org/trunk@62634 602fd350-edb4-49c9-b593-d223f7449a82
This brings the `WP_Error` class to full PHPStan rule level 10 compliance.

Also make use of null coalescing operator where appropriate, and simplify `has_errors()` method.

Developed in WordPress#12405.
Follow-up to r42761, r49115, r49116.

See #64898, #64897.


git-svn-id: https://develop.svn.wordpress.org/trunk@62635 602fd350-edb4-49c9-b593-d223f7449a82
…p()` and `::chown()`.

This applies the equivalent fix which had previously been done to `::chmod()`. Tests are added for all three methods.

Developed in subset of WordPress#11593.
Follow-up to r12997.

Fixes #65584.
See #65409, WordPress#11261.


git-svn-id: https://develop.svn.wordpress.org/trunk@62636 602fd350-edb4-49c9-b593-d223f7449a82
Change the optional constructor argument of `WP_Filesystem_FTPext`, `WP_Filesystem_ftpsockets`, and `WP_Filesystem_SSH2` from an empty string default to an empty `array`, matching how the argument is actually consumed, and improve the associated DocBlocks.

These classes were also brought to adherence with PHPStan rule level 10:

* Add `FileListing` and `Options` array shapes, and initialize each transport's `$options` to a complete default array before any early return.
* Correct several inaccurate `@return` descriptions, including the `group()` methods that had been describing the owner.
* Allow `WP_Filesystem_SSH2::connect()` to be retried after a failed connection attempt.
* Stop `WP_Filesystem_FTPext::parselisting()` from leaking its intermediate date-parsing keys into the returned listing.
* Add `ext-ftp` and `ext-ssh2` to the suggested extensions in `composer.json`.

Developed in WordPress#11593.
Follow-up to r62635, r62636.

Props soean, westonruter, mukesh27.
See #65584, #64898.
Fixes #65409.


git-svn-id: https://develop.svn.wordpress.org/trunk@62637 602fd350-edb4-49c9-b593-d223f7449a82
@joedolson joedolson mentioned this pull request Jul 24, 2026

@joedolson joedolson left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly, I like this. One issue with focus order; I'm opening a PR against this PR to suggest an alternate, which I'll link in a comment.

There's also an alignment issue on secondary action buttons with icons in mobile viewports that needs looking at. When a plugin has a pending update or is being updated, the icon is out of alignment.

display: grid;
grid-template-columns: 128px minmax(0, 1fr);
grid-template-rows: auto 1fr auto;
grid-template-areas:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This grid layout causes the focus order to break. The order in which links get focus needs to match their visual order - with this layout, the order is Plugin Title > Action Button > Details Button > Author Link, but the order should be Plugin Title > Author Link > Action Button > Details Button.

A possible alternative is to move the author link into the same container as the plugin name.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this has been addressed in cf40017. The DOM is now structured as icon (aria-hidden) → info group (title, description, author) → action links, so the DOM order matches the visual order.

@joedolson

Copy link
Copy Markdown
Contributor

See #12672 with an additional commit to modify the DOM order.

369work added 3 commits July 25, 2026 00:44
Restructure .plugin-card-top so DOM order matches visual order: icon (aria-hidden) -> info group (title, author link, description) -> actions group. Addresses joedolson's focus-order review comment on #64686.

Also fix a pre-existing icon misalignment on the static Update Now button state, which was missing the vertical-align adjustment shared by the Updating.../Updated! states.

See #64686.
@369work

369work commented Jul 24, 2026

Copy link
Copy Markdown
Author

Thanks for the review!

I've addressed both issues:

1. Focus order

Rather than just moving the author link (as suggested in #12672), I restructured the DOM more broadly: the icon now comes first, followed by a single info group (title, author, description), then the actions group. This achieves the same result — DOM order now matches visual order (icon → title → author link → action button → details link) — while also simplifying the grid from 4 areas down to 3. Verified with keyboard tab order.

2. Icon alignment on secondary action buttons in mobile viewports

Confirmed and fixed. This turned out to be a pre-existing issue, not introduced by this patch: .plugin-card .update-now:before (the static "Update Now" state) was missing the vertical-align: middle; top: -2px; adjustment that .updated-message:before and .updating-message:before already had. Since the "Updating..." and "Updated!" states carry the update-now class alongside their own state class, the shared rule masked the gap — but the plain "Update Now" state (before any update action is taken) never picked it up, so its icon sat slightly low relative to the label text.

Fixed by adding .update-now:before to the shared alignment rule and removing the now-redundant vertical-align: top from its own rule. Verified at 344px (Galaxy Z Fold 5) across all three states (Update Now / Updating... / Updated!) with English labels — icon and text now align consistently.

@369work

369work commented Sep 2, 2026

Copy link
Copy Markdown
Author

Just checking in on this one.

I pushed an update to the PR back in July addressing the review feedback, and it's been sitting since then. I know the milestone moved to 7.2, and I'm not in a hurry — I'd much rather this be worked out properly than rushed.

Is there anything we need to do at this point?
We will take care of it if necessary.

@369work
369work requested a review from joedolson September 25, 2026 05:24
# Conflicts:
#	src/wp-admin/css/list-tables.css

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the late reply. I think this PR is heading in the right direction, and I'd love to see it ship in 7.3.

The following are AI-assisted suggestions, but it looks like the following CSS can be removed with the latest implementation. I'd appreciate it if you could check whether these points are valid.

  • .plugin-card .plugin-icon { align-self: start; }: The icon has an explicit height, so stretch doesn't apply anyway.
  • .plugin-card .plugin-icon { margin: 0; }: There is no longer any margin to reset. The two .plugin-card .plugin-icon rule blocks could also be merged into one.
  • .plugin-card-info { min-width: 0; }: The grid track is already minmax(0, 1fr), so the automatic minimum size of the grid item doesn't apply.
  • .plugin-action-buttons { margin: 0; }: Duplicates the existing div.action-links, .plugin-action-buttons { margin: 0; } rule.
  • .plugin-action-buttons li { display: block; }: Flex items are blockified automatically. (margin: 0 is still needed to reset li { margin-bottom: 6px; } from common.css.)
  • .plugin-action-buttons li .button { margin-right: 0; }: The media query that added margin-right has been removed, so there is nothing to reset.
  • .plugin-card-bottom { clear: both; }: There are no longer any floats in .plugin-card-top.
  • The @media screen and (max-width: 1100px) and (min-width: 782px), (max-width: 480px) block: .plugin-card .desc p:first-of-type { margin-top: 0; } is already covered by .plugin-card .column-description > p { margin-top: 0; }.

Comment thread src/wp-admin/css/list-tables.css Resolved
Comment thread src/wp-admin/css/list-tables.css Resolved
Addresses review feedback:

- Remove CSS that is no longer needed with the grid layout
  (container-type, align-self, min-width, redundant margins and
  resets, clear, and the 1100px media query block), and merge the
  two .plugin-card .plugin-icon rules.
- Replace the JS click forwarding on the plugin icon with a
  pseudo-element on the title link that covers the icon, so clicking
  the icon is a real link activation (context menu, open in new tab).

See #64686.
@369work

369work commented Nov 7, 2026

Copy link
Copy Markdown
Author

@t-hamano , Thanks for the review.

I went through each point against the current code, and they all checked out. I've pushed the changes in 8b8eed6:

  • Removed container-type from .plugin-card.
  • Replaced the JS click forwarding with your CSS approach (a ::after on the title link covering the icon), and removed cursor: pointer from the icon. With this, the PR no longer touches plugin-install.js.
  • Removed align-self: start and margin: 0 from the icon, and merged the two .plugin-card .plugin-icon rules.
  • Removed min-width: 0 from .plugin-card-info.
  • Removed the duplicate margin: 0 from .plugin-action-buttons.
  • Removed display: block from .plugin-action-buttons li (kept margin: 0).
  • Removed the .plugin-action-buttons li .button { margin-right: 0; } rule.
  • Removed clear: both from .plugin-card-bottom.
  • Removed the @media screen and (max-width: 1100px) and (min-width: 782px), (max-width: 480px) block.

Tested in a local wordpress-develop environment with the Japanese locale:

  • No overlap between the title/description and the buttons, from desktop down to mobile widths.
  • Clicking the icon opens the details modal, and right-clicking it shows the link context menu (open in new tab, copy link address).
  • The focus outline on the title link only surrounds the title text, not the icon.
  • The tab order is still: title → author → Install Now → More Details.
  • Hovering over the icon also applies the title link's hover color (a subtle color change).

Thanks again!

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. From what I can see, it looks like we are almost there, but I've left a few minor suggestions at the end.

Comment thread src/wp-admin/css/list-tables.css Resolved
Comment thread src/wp-admin/css/list-tables.css Resolved
Comment thread src/wp-admin/css/list-tables.css Resolved
Comment thread src/wp-admin/css/list-tables.css Resolved
Comment thread src/wp-admin/css/list-tables.css Resolved
Addresses review feedback:

- Use multiples of 8px for the spacing inside the plugin card:
  column-gap 24px, row-gap 8px, 16px above the action buttons
  (controlled by gap and padding instead of margin), and a 16px
  gap between the buttons.
- Remove the unneeded `.plugin-card .desc` rule.
- Remove the ticket number comments from the CSS and PHP, keeping a
  short comment for the stretched link.

See #64686.
@369work

369work commented Nov 8, 2026

Copy link
Copy Markdown
Author

@t-hamano Thanks!
I've applied all of your suggestions in 55708ef:

  • Removed the ticket number comments from the CSS and PHP, keeping a short comment (without the ticket number) for the stretched link.
  • Changed column-gap to 24px. I agree it gives the card a bit more breathing room.
  • Removed the unneeded .plugin-card .desc rule.
  • Replaced the margin-top on the action links with row-gap: 8px and padding-top: 16px, so the spacing above and below the buttons is now 16px on both sides.
  • Changed the gap between the buttons to gap: 8px 16px.

All the spacing inside the plugin card is now a multiple of 8.
I'd actually noticed that the spacing values were a bit inconsistent (8px, 15px, 20px, and so on), but I wasn't sure whether it was okay to change them.

I checked it locally with the Japanese locale: the layout still holds up, and the spacing matches your "After" screenshot.

Thanks for all the fine-tuning!


スクリーンショット 2026-11-08 211708

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I can tell, all cases have been handled properly and it is ready for release. @joedolson and @peterwilsoncc, could you provide a second look?

display: grid;
grid-template-columns: 128px minmax(0, 1fr);
grid-template-rows: auto 1fr auto;
grid-template-areas:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this has been addressed in cf40017. The DOM is now structured as icon (aria-hidden) → info group (title, description, author) → action links, so the DOM order matches the visual order.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants