Agentic UI: Add a first-run orientation guide by bcotrim · Pull Request #4331 · Automattic/studio

bcotrim · 2026-07-24T12:58:32Z

Related issues

Related to STU-2016

How AI was used in this PR

Implemented with Claude Code; Reviewed and tested manually.

Proposed Changes

Adds a first-run orientation guide to the agentic UI — a focused three-page modal that introduces the sidebar, Studio Code, and the live preview. It opens once on first arrival in the workbench and can be reopened anytime from Help ▸ Getting Started.

The copy adapts to the user:

New vs migrating (page 1): a fresh install is welcomed to Studio; someone coming from classic Studio is reassured their sites and files carried over.
Studio Code available vs not (pages 2–3): when chat is on, the guide teaches building by asking and the realtime preview; when it isn't — signed out, offline, or turned off in Settings → AI — it points to the site overview and the plain preview instead.

Seen-state persists (desktop app.json, browser localStorage) and is versioned, so it never nags but can be re-shown after a redesign.

Step 1	Step 2	Step 3

Testing Instructions

Enable the Agentic UI beta feature and open a site's workbench.
Choose Help ▸ Getting Started — the guide opens.
Page through it: Back appears from page 2, the dots stay centered, the last button (Let's go) closes it. Confirm Esc and the ✕ Skip button also close it.
Signed in with Studio Code on, pages 2–3 read Build by asking / See your site update in realtime.
Turn agentic features off in Settings → AI (or sign out), reopen from Help — pages 2–3 now read Manage your site / See your site inline.
Verify in both light and dark mode.

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

…tion-guide # Conflicts: # apps/studio/src/storage/storage-types.ts

…ailability

wpmobilebot · 2026-08-03T09:29:02Z

📊 Performance Test Results

Comparing 2830a95 vs trunk

app-size

Metric	trunk	`2830a95`	Diff	Change
App Size (Mac)	1405.32 MB	1375.36 MB	29.96 MB	🟢 -2.1%

site-editor

Metric	trunk	`2830a95`	Diff	Change
load	1062 ms	1074 ms	+12 ms	⚪ 0.0%

site-startup

Metric	trunk	`2830a95`	Diff	Change
siteCreation	7533 ms	7002 ms	531 ms	🟢 -7.0%
siteStartup	2890 ms	2397 ms	493 ms	🟢 -17.1%

Results are median values from multiple test runs.

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

katinthehatsite · 2026-08-04T11:55:24Z

+		title: () => __( 'Welcome to WordPress Studio' ),
+		description: () =>
+			__(
+				'Every site you build lives in the sidebar on the left. Switch between them anytime. The sidebar is where you’ll find site settings and a quick way to start and stop your site.'


We would need to make sure we are clear here for RTL because it would be on the right. Maybe, we can add the translators comment to clarify this.

katinthehatsite · 2026-08-04T12:02:36Z

+		description: () =>
+			__(
+				'Every site you build lives in the sidebar on the left. Switch between them anytime. The sidebar is where you’ll find site settings and a quick way to start and stop your site.'
+			),


One thing is that might be confusing is that we also have general settings there which say Settings:

The users might easily think that this is what we are referring to

katinthehatsite

Overall, this is looking good 👍 I left some minor comments that can help avoid potential user's confusion

shaunandrews · 2026-08-04T13:32:43Z

While the tour is open, I'm unable to move the app window—there doesn't seem to be any draggable area.

shaunandrews · 2026-08-04T15:23:11Z

Also, the page dots seems to have a full radius, so when they're width changes they look awkward. We should specific a fixed radius in pixels.

katinthehatsite · 2026-08-05T07:50:29Z

 		illustration: 'sites',
 		title: () => __( 'Welcome to WordPress Studio' ),
 		description: () =>
+			/* translators: "on the left" describes the sidebar in left-to-right layouts; in right-to-left languages it sits on the right — adapt the direction accordingly. */


Nice, thanks for adding those 👍

bcotrim · 2026-08-05T16:10:47Z

@shaunandrews @katinthehatsite I've made some updates, can you take another look, please? 🙇

…4441) ## Related issues - Part of [STU-2016](https://linear.app/automattic/issue/STU-2016) - Stacked on #4331 (base branch is `stu-2016-add-orientation-guide`); retarget to `trunk` once that merges. > ⚠️ Visual change: needs human review in light + dark mode. ## How AI was used in this PR Built and iterated interactively with Claude Code. ## Proposed Changes <img width="499" height="484" alt="image" src="https://github.com/user-attachments/assets/49f20429-028d-485c-a540-679b08480c87" /> <img width="507" height="469" alt="image" src="https://github.com/user-attachments/assets/0bd12948-6060-493d-9a7a-d38a2ea84be5" /> Replaces the orientation guide's placeholder header art with animated illustrations that *show* the workbench rather than describe it. - **Page 1 (sites):** a real-looking sidebar row where a cursor drifts in, hovers the site-overview button, then clicks the status button to start the site — stopped → starting → running — with the tooltips it would really show. Loops. - **Page 2, signed in (chat):** a one-time playback of Studio Code — the composer types a prompt, sends it (dropping off-stage and flipping to its busy state) as the prompt becomes a user bubble, the reply streams in, and a tool call appears and keeps working. A subtle Replay control restarts it. Both are theme-adaptive and respect reduced motion. They're built as a small reusable system (a `Stage` + `Cursor` and an id-keyed scene registry) so more scenes can be added without bespoke plumbing. The "manage your site" (overview) and preview illustrations remain placeholders for follow-up. ## Testing Instructions 1. `npm run cli:build:ui` (the agentic UI isn't rebuilt by the normal dev watcher). 2. Enable the **Agentic UI** beta and open a site's workbench. 3. **Help ▸ Getting Started** — page 1 shows the sites animation. 4. Signed in with Studio Code on, page 2 shows the chat animation; the Replay control (top-left) restarts it. 5. Verify in **light and dark**, and with **reduced motion** enabled (scenes settle on a clean static frame). ## Pre-merge Checklist - [x] TypeScript / lint / build pass for the changed files. - [ ] Human visual review in light + dark mode. --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

nightnei

I tested both dark and light mode. Also tested suggestions from Shaun - everything looks greart 👍

Add a first-run orientation guide, replayable from Help

44a3e20

github-actions Bot assigned bcotrim Jul 24, 2026

bcotrim changed the title ~~Agentic UI: Add a first-run orientation guide, replayable from Help~~ Agentic UI: Add a first-run orientation guide Jul 24, 2026

bcotrim added 3 commits July 24, 2026 14:14

Scope onboarding hints to the guide and share the browser store

eb0e680

Merge remote-tracking branch 'origin/trunk' into stu-2016-add-orienta…

b574def

…tion-guide # Conflicts: # apps/studio/src/storage/storage-types.ts

Adapt the orientation guide to new/migrating users and Studio Code av…

938d288

…ailability

bcotrim marked this pull request as ready for review August 1, 2026 11:27

bcotrim requested review from nightnei, sejas and shaunandrews August 1, 2026 11:27

Merge branch 'trunk' into stu-2016-add-orientation-guide

13dc62f

bcotrim mentioned this pull request Aug 3, 2026

Agentic UI: Show "What's New" #4414

Open

1 task

bcotrim requested a review from katinthehatsite August 4, 2026 10:39

katinthehatsite reviewed Aug 4, 2026

View reviewed changes

Comment thread apps/ui/src/data/onboarding/orientation-guide.ts

katinthehatsite reviewed Aug 4, 2026

View reviewed changes

Comment thread apps/ui/src/data/onboarding/orientation-guide.ts

katinthehatsite reviewed Aug 4, 2026

View reviewed changes

Comment thread apps/ui/src/data/onboarding/orientation-guide.ts

katinthehatsite reviewed Aug 4, 2026

View reviewed changes

shaunandrews mentioned this pull request Aug 4, 2026

Agentic UI: Sites and Chat illustrations for the orientation guide #4441

Merged

2 tasks

Make the orientation guide RTL-aware and annotate directional copy

73a56fa

katinthehatsite reviewed Aug 5, 2026

View reviewed changes

bcotrim added 2 commits August 5, 2026 16:53

Make the tour modal a window-drag handle and fix pager dot radius

5c9cf83

Drag the tour window via the backdrop, not the transformed popup

d2d17a0

bcotrim requested a review from katinthehatsite August 5, 2026 16:10

nightnei approved these changes Aug 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

Agentic UI: Add a first-run orientation guide - #4331

Agentic UI: Add a first-run orientation guide#4331
bcotrim wants to merge 9 commits into
trunkfrom
stu-2016-add-orientation-guide

bcotrim commented Jul 24, 2026 •

edited

Loading

Uh oh!

wpmobilebot commented Aug 3, 2026 •

edited

Loading

Uh oh!

katinthehatsite Aug 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

katinthehatsite Aug 4, 2026

Uh oh!

katinthehatsite left a comment

Uh oh!

shaunandrews commented Aug 4, 2026

Uh oh!

shaunandrews commented Aug 4, 2026

Uh oh!

katinthehatsite Aug 5, 2026

Uh oh!

bcotrim commented Aug 5, 2026

Uh oh!

nightnei left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

bcotrim commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

How AI was used in this PR

Proposed Changes

Testing Instructions

Pre-merge Checklist

Uh oh!

wpmobilebot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Performance Test Results

app-size

site-editor

site-startup

Uh oh!

katinthehatsite Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

katinthehatsite Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

katinthehatsite left a comment

Choose a reason for hiding this comment

Uh oh!

shaunandrews commented Aug 4, 2026

Uh oh!

shaunandrews commented Aug 4, 2026

Uh oh!

katinthehatsite Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

bcotrim commented Aug 5, 2026

Uh oh!

nightnei left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bcotrim commented Jul 24, 2026 •

edited

Loading

wpmobilebot commented Aug 3, 2026 •

edited

Loading