Redesign site list and Add Site flow with richer sync metadata

[shaunandrews]

This PR redesigns the flow for adding and connecting a site in WordPress Studio.

Existing Design

The existing flow for adding a site is needlessly complicated, with 4 different branches—and some useless steps around blueprint details and importing a site.

Blueprints are jargon, and never very well explained, and include a mostly empty step around the blueprint details.

Pulling (more jargon) a site uses a boring list, forcing users to read titles and urls to discern which site they want. It also shows options mixed, making it hard to understand which options are viable. Importing goes to a needless new screen.

Once a site is created, you can choose to "connect" it to a site (confusing language, with pulling in the other flow) which uses a narrow modal and the same boring list.

Changes

I gated these changes behind enableBlueprintsGallery flag so without the flag, the trunk should look the same.

--

New Design

This PR redesigns the flow for adding a new site, reducing branches down to three: Build, Connect, or Import.

Choosing to build a new site shows the option for an empty site, along with the blueprints.

Connecting a site shows a much larger, visual grid of sites split into groups depending on viability with those that need hosting features or a plan shows with more helpful messaging.

How AI was used in this PR

Used Claude Code throughout as a pair for the larger refactors — the Add Site redesign, the pagination-safe reconcile logic, and the layout or centering plumbing. Reviewed all diffs manually; the branch was rebased on trunk and reconciled by hand.

Detailed Changes

Site list (Sync tab + sync metadata)

• Enrich connected-site data with icon, plan name, and creation date (stored on the local connected-site record, see appdata-v1.json).
• Switch the WordPress.com sites fetch to the v1.3 me/sites API with server-side filtering + pagination.
• Redesign the site list as a grouped card grid with server-side search, mshot thumbnails, site icons, and plan badges.
• Fix a pagination-reconcile bug that marked any connected site beyond page 1 as deleted. Missing connected sites are now verified with an individual site GET and only flagged deleted on a confirmed 404.

Add Site flow

• Replace the three-step stepper with a single entry screen offering Build / Connect / Import paths, a dedicated blueprint picker, and a Connect screen that reuses the Sync site list.
• Modal chrome is now an X button and a floating action row (no full-width header/footer bars) so the Screen height is constant across steps and content doesn't shift when navigating.
• Backup imports preflight the dropped file (preflightBackup IPC) before advancing — invalid archives are caught on the entry screen.
• Added a sign-out link to the add-site options, and widened CSP img-src to allow site icons from any HTTPS domain.

Testing Instructions

1. Launch a dev build. You should see a larger window and the system color scheme honored on first run.
2. Open the site list from the sidebar — sites should appear as cards with thumbnails, plan badges, and grouped by status. Try the search and pagination.
3. From a site's Sync tab, open the Connect modal — confirm the "Connect your site" title is centered above the search input and the Enable button on sites needing hosting features is readable in dark mode.
4. Open Add Site from the toolbar:
   • Verify site adding options render on the entry screen and the dot grid shows behind them.
   • Drop an invalid archive into the Import card — the preflight error should surface inline without advancing.
   • Advance through any sub-path and back — content centering should not shift between steps; the X button and action row stay pinned.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?
• Have you tested on macOS, Windows, and Linux where applicable?
• Have you added automated tests where applicable?

🤖 Generated with Claude Code

[katinthehatsite]

I was trying to use the option to Connect a site but these preview generation step never finished for me:

[katinthehatsite]

Another observation is that visually it is very hard to see which site belongs to WP.com and which site belongs to Pressable in this list:

I think it would be great to add some element that would allow to distinguish them quickly.

[katinthehatsite]

One other comment is that I found this Preview link slightly strange because I expecred that once I am done with the preview and made my modifications, I could somehow port them into Studio. Instead, I was somewhat in the dead end because it looked like something I could edit but was meant to be serving as preview.

Also, the description of the WordPress.com option was sort of confusing. Once I created a site, it looked like a regular Studio site:

[katinthehatsite]

Another observation is that visually it is very hard to see which site belongs to WP.com and which site belongs to Pressable in this list

This should be now addressed ✅

[katinthehatsite]

One other comment is that I found this Preview link slightly strange because I expecred that once I am done with the preview and made my modifications, I could somehow port them into Studio. Instead, I was somewhat in the dead end because it looked like something I could edit but was meant to be serving as preview.

I removed this functionality for now and will move it to the Linear issue to make sure we think through this flow. We could potentially rename this as something like "Experiment" or "Try out" so that the user does not have an expectation that they will be able to activate it in Studio from Playground and that it is a circular process.

[katinthehatsite]

I was trying to use the option to Connect a site but these preview generation step never finished for me

I no longer saw this so I left this as is for now.

[katinthehatsite]

@Automattic/yolo I would appreciate the review. For now, I gated these changes behind enableBlueprintsGallery flag so without the flag, the trunk should look the same. To review these changes, make sure to enable the flag first. Please test different ways to create a site. I looked at it for some time already so I might be missing some things.

[wpmobilebot]

📊 Performance Test Results

Comparing 52bd1d4 vs trunk

app-size

Metric	trunk	52bd1d4	Diff	Change
App Size (Mac)	1454.57 MB	1454.78 MB	+0.21 MB	⚪ 0.0%

site-editor

Metric	trunk	52bd1d4	Diff	Change
load	1816 ms	1776 ms	40 ms	⚪ 0.0%

site-startup

Metric	trunk	52bd1d4	Diff	Change
siteCreation	8088 ms	8086 ms	2 ms	⚪ 0.0%
siteStartup	4938 ms	4949 ms	+11 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[sejas]

Shaun, Kat, Thanks for creating the PR. I like the new designs ✨.

A few things I found:

• We remove the whitelist of domains in apps/studio/index.html and apps/studio/src/index.ts
• The PR description says: Backup imports preflight the dropped file (preflightBackup IPC) before advancing — invalid archives are caught on the entry screen., but that seems not implemented. I suggest updating the description and maybe creating a Linear issue for that.
• The Studio window started at ~900x600 which cut the import from a backup button. Why not showing the three buttons in the same row?
• The scroll bar is not at the border and it conflicts with the close X.

• The Add site modal cannot be dragged by clicking in the background or the header. It shows an animation instead(Not sure if that is an issue on trunk).
• When clicking Build a new site, an error appears in the console.

• The Blueprint descriptions at the bottom are a bit blurred.

• The left sidebar hides if the window width is smaller than 1100, not sure if that's intentional.

left-sidebar.mp4

The PR is quite large, so I might have missed something.
Happy to have a second pass when E2E pass.

[katinthehatsite]

The PR description says: Backup imports preflight the dropped file (preflightBackup IPC) before advancing — invalid archives are caught on the entry screen., but that seems not implemented. I suggest updating the description and maybe creating a Linear issue for that.

There is already an issue for it in https://linear.app/a8c/issue/STU-1644/blueprints-gallery-library-consider-preflight-validation-for-import 😄 I removed the logic from this PR as it was getting too complex

[katinthehatsite]

The Studio window started at ~900x600 which cut the import from a backup button. Why not showing the three buttons in the same row?

I see it as well but I think this is the design question rather than the implementation question. I will move it to the new issue and we can discuss with Shaun there.

[katinthehatsite]

The scroll bar is not at the border and it conflicts with the close X.

I rebased trunk and I don't see this overlap anymore in this PR:

Are you still seeing it @sejas ?

[katinthehatsite]

The Add site modal cannot be dragged by clicking in the background or the header. It shows an animation instead(Not sure if that is an issue on trunk).

It can be dragged by the header:

Screen.Recording.2026-04-28.at.12.22.40.PM.mov

Which works the same as on trunk:

Screen.Recording.2026-04-28.at.12.23.23.PM.mov

I think we can leave it as is with this PR as it replicates the existing behaviour.

[katinthehatsite]

When clicking Build a new site, an error appears in the console.

I was testing this but not seeing this specific error. I am adding below the video of testing, am I taking different steps from you?

Screen.Recording.2026-04-28.at.12.26.16.PM.mov

[katinthehatsite]

The left sidebar hides if the window width is smaller than 1100, not sure if that's intentional.

I also retested this and can not see it on my end:

Screen.Recording.2026-04-28.at.1.10.49.PM.mov

Would you be able to check this with the most recent changes?

[katinthehatsite]

The Blueprint descriptions at the bottom are a bit blurred.

I dropped the gradient height for bluriness. I think it should be better now. Let me know if it still seems too blurry.

[katinthehatsite]

I am approving the changes, they are behind the feature flag so I think we are good to go.