Design exploration: Clarify Agentic UI site settings

[shaunandrews]

Related issues

• Related to STU-2348
• Explores an alternative UX to Set the right expectation for the "latest" WordPress version setting #4702 without changing or superseding that PR

How AI was used in this PR

Codex was used as an implementation and design-prototyping partner. The interaction model, hierarchy, wording, spacing, responsive behavior, dark-mode treatment, and disabled states were iterated through direct human review in the running Agentic UI. Codex also updated focused tests and prepared the review evidence; the design decisions came from that review loop.

Executive summary

The existing latest WordPress version value mixes two concepts: the version currently installed and whether WordPress should update itself. This draft separates those decisions in the Agentic UI so users can choose Automatic updates or Select a version, while still seeing the installed version.

The exploration also uses the settings redesign to restore currently missing Agentic UI controls for PHP runtime and file access, improve grouping and scanability, and keep the save action reachable as the settings surface grows.

This is a draft design exploration. It is intentionally separate from #4702 so that PR can continue to represent Gergely's narrower wording approach.

Proposed Changes

• Separate WordPress update behavior from pinned version selection with two radio choices. The compact version picker remains visible and selecting a version pins the site.
• Explain automatic updates in place and show the currently installed WordPress version without implying that it must already be the newest release.
• Group settings into Site details, PHP environment, Administrator, and Domain sections in one narrow, scannable column at every width.
• Expose PHP runtime and file access settings in the Agentic UI. Sandbox mode forces site-directory access and explains why through a WPDS notice and disabled-state tooltip.
• Use compact WordPress and PHP version pickers instead of stretching short values across the settings column.
• Move Save settings into the existing sticky footer, alongside the preview control, with spacing for the collapsed-sidebar control and a taller fade/blur over scrolling content.
• Improve native select and radio colors in dark mode and preserve the direction of untranslated fallback descriptions in RTL locales.

Review guide

1. WordPress update model

Please focus first on whether Automatic updates and Select a version correctly express the two user intents. Automatic mode reports the installed version; pinned mode exposes the same compact picker at all times. This deliberately avoids hiding controls or encoding update mode in a version named latest.

2. Settings hierarchy and density

The form stays in a centered 560px column rather than expanding into multiple columns at wide widths. Section headings and separators establish hierarchy; related controls remain visible without accordions or secondary screens.

3. Runtime and file-access dependency

PHP runtime and file access now have parity with the underlying site settings. Selecting Sandbox forces Site directory access. The file-access choices remain visible but disabled, accompanied by a neutral WPDS notice and the tooltip “Requires the Native PHP runtime”.

4. Persistent actions and responsive behavior

Save settings is portaled into the existing footer toolbar. Review the footer with the preview open and closed, and with the sidebar expanded and collapsed. It should remain reachable without covering the final form content.

5. Data path

Runtime and file-access values travel through the shared SiteDetails shape and the local connector's existing site set argument builder. Sandbox normalization happens before the update is sent. There is no persistence migration.

Okay to skim

• Theme-token color corrections for native select options and unselected radios.
• Mechanical test selector updates from the old WordPress version dropdown to the new radios and compact Version select.
• Spacing-only CSS once the overall hierarchy has been reviewed.

Known tradeoffs and follow-ups

• This intentionally does not change WordPress download/cache behavior. It gives that work a clearer UI contract to integrate with later.
• Site-specific Skills/Instructions parity is outside this exploration; existing Linear/GitHub work already tracks it.
• The new strings are not translated yet. RTL verification uses Hebrew and confirms layout/control order plus mixed-direction fallback copy, but some labels therefore remain in English.
• The WPDS Notice is currently marked “use with caution” upstream when mixed with @wordpress/components; this draft uses it to evaluate the intended design-system direction.
• The change spans UI and the local connector, so this should remain a Proof of Concept until the interaction model and scope are agreed.

Safety checklist

• No config or data migration
• No WordPress core or cache changes
• Sandbox mode cannot submit unrestricted file access
• Existing pinned/automatic update values remain compatible with the connector contract
• Save action remains associated with the correct form through its HTML form attribute
• Verified in light, dark, narrow, wide, preview-open, preview-closed, sidebar-expanded, sidebar-collapsed, and RTL states
• Product/design approval for the interaction model
• Final translation review

Screenshots

Wide layout with preview open

Light	Dark

The settings column keeps a stable readable width while the site preview uses the remaining space.

Narrow layout and sticky footer

Light	Dark

The footer keeps Save settings visible at the bottom. With the sidebar collapsed, its toggle and the save action no longer overlap:

WordPress update choices

Automatic updates	Pinned version

Sandbox and file access

Light	Dark

Disabled choices use a not-allowed cursor and explain the dependency on hover or keyboard focus:

RTL and mixed-direction content

The Hebrew pass verifies mirrored layout, physical control order, compact select alignment, footer placement, and punctuation direction in untranslated English fallback copy.

Testing Instructions

Automated checks run:

npm run typecheck
npm test -- apps/ui/src/components/site-settings-view/index.test.tsx apps/ui/src/components/site-overview-view/index.test.tsx
npm run cli:build:ui

Results:

• Workspace typecheck passed.
• 44 focused tests passed.
• Agentic UI and CLI build passed.
• Browser console had no errors during manual verification.

Manual verification:

1. Build and run studio ui, then open an existing site's Settings tab.
2. Confirm Automatic updates is selected for an auto-updating site and the installed version appears in its explanation.
3. Select Select a version, change the compact picker, and confirm Save settings becomes enabled.
4. Switch PHP runtime between Native and Sandbox. In Sandbox, confirm file access is forced to Site directory, both choices remain visible but disabled, the neutral notice appears, and hovering/focusing the group shows the tooltip.
5. Confirm the footer remains visible while scrolling and does not collide with the collapsed-sidebar or preview controls.
6. Repeat in light and dark appearances, at narrow and wide widths, and in an RTL locale such as Hebrew.

Pre-merge Checklist

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