[ViewFromTheBox]

Description

Adds docs/design/site-editor-ux.md — the D0 site-editor design brief that gates Phase D (D1–D5). This is a research + design PR, not an implementation PR. The only artifact is the doc.

Closes: #367

Type of Change

• Documentation update

Related Issue

Issue: #367

Motivation and Context

The V1 expansion plan (§2.2) commits to building the site-editor shell ourselves rather than depending on @wordpress/edit-site, to preserve the #309 premise of owning admin chrome. That ownership is only valuable if we don't clone WordPress's IA by default. D0 is where we earn that decision — before D1–D5 start relitigating layout and mode-switching across five PRs.

Changes Made

Single-file PR — docs/design/site-editor-ux.md (1,045 lines). Contents:

• §1 Research: WP pain points — 16 documented Site Editor friction patterns with source links (Gutenberg issues, WP Tavern, Brian Coords, FSE Outreach, WP.com support). 13 structural, 3 polish.
• §2 Research: Competitive scan — Webflow / Framer / Craft CMS / Squarespace Fluid Engine across three axes (site-vs-content editing, nav editor, global styles) + cross-tool patterns and anti-patterns.
• §3 Information Architecture — shell region roles (navigator / canvas / inspector / top bar) + per-section IA for Templates, Template Parts, Patterns, Styles, Navigation.
• §4 Mode Model — URL-per-scope routing + explicit Save scope table (never bare "Save").
• §5 Key Flows — storyboards for: edit a template, customize global styles, build a nav menu, create a synced pattern, swap a template part.
• §6 UX Principles — 10 rules (P1–P10) D1–D5 must be reviewed against.
• §7–§10 — phase-D impact map, open-question resolutions (plan §8), glossary, sign-off.

Key positions the brief commits V1 to

• Spatial, not modal, scope communication. Each site-editor section gets its own URL; no mode toggle. Directly addresses WP F1/F2/F9.
• Site editor and post editor are siblings, not nested. No "Edit template" button in the post editor.
• Typed-reference menu items (Craft/Verbb pattern) — menu items point to Page/Post IDs, auto-sync labels. Addresses F4.
• Config-driven menu locations in V1 (resolves plan §8 open question).
• Nav section uses a tree editor, NOT the block-editor iframe — nav trees are structural data, not block trees.
• Style Book is the default canvas of the Styles section, not a buried icon. Variations picker ships in V1 (resolves plan §8).
• Unsynced patterns are pure block-tree copies in V1 (resolves plan §8). "Convert to unsynced copy" replaces "Detach."
• Every Save button names its scope ("Save template", "Save menu") — never bare "Save."

How Has This Been Tested?

Testing Environment:

• N/A — documentation-only change

Tests Performed:

1. Verified all 16 friction-pattern source URLs resolve
2. Verified all 4 competitive-scan source URLs resolve
3. Cross-checked each D-phase issue (D1 · Site-editor shell: routing, navigator, canvas frame, tabs #368–D5 · Patterns library UI + inserter category (synced + unsynced) #372) against §7 impact map — each issue's topic is covered by a specific IA section and set of principles

Accessibility Tests Run

• N/A for this PR — documentation only. However, UX Principle P10 in the brief makes accessibility a first-class acceptance criterion for each D-phase PR (keyboard flows, focus management across iframe boundaries, SR labels).

Tests Added

• N/A — documentation only

Documentation

• New design doc added at docs/design/site-editor-ux.md

Documentation details:

This doc is the deliverable for issue #367. Follow-up: D1–D5 issues (#368–#372) will be updated to reference this brief in their descriptions so downstream implementers pick it up when they start those phases.

Pre-Submission Checklist

• Followed contributing guidelines
• Checked for other open PRs for same update
• N/A — docs only, no tests
• N/A — docs only, no lint
• N/A — docs only
• Code follows project style guide (markdown, wraps ~120 chars)
• Self-review completed
• N/A — docs only, no code
• No new warnings generated

Reviewer focus

Key review questions:

1. Do P1–P10 match the rules you'd apply when reviewing a D-phase PR?
2. Does §4.2 / §4.3 answer "what does Save do" on every screen unambiguously?
3. Is the Nav-section-is-a-tree-editor-not-an-iframe carve-out (§3.8) acceptable? It's the deliberate exception to the block-editor canvas pattern.
4. Are the three plan §8 resolutions (styles variations, menu locations, unsynced patterns) acceptable?

Approval gates D1 kickoff.

Summary by CodeRabbit

Documentation

• Added comprehensive site editor UX design specification outlining information architecture, interaction flows, mode model, design principles, and implementation roadmap.

[coderabbitai]

📝 Walkthrough

Walkthrough

A comprehensive design brief document for the site-editor is added, outlining WordPress site-editor friction points, competitive analysis across four non-WP tools, information architecture specifications, mode and save-scope models, key user flows, and foundational UX principles to guide D1–D5 implementation phases.

Changes

Cohort / File(s)	Summary
Site-Editor Design Brief docs/design/site-editor-ux.md	Adds 1,045-line design document covering WordPress site-editor pain point audit with sources, competitive findings from Webflow/Framer/Craft CMS/Squarespace, macro IA (navigator/canvas/inspector/topbar roles), mode model with explicit Save semantics, key flow storyboards, and five+ cross-cutting UX principles to guide subsequent implementation phases.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Poem

🐰 A brief has been drafted with care,
WordPress friction laid bare,
Modes and scopes now crystal clear,
Patterns emerge that all will revere,
D0's done—let D1 build near! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a D0 (design phase zero) site-editor UX research and macro design brief document.
Linked Issues check	✅ Passed	The PR fully satisfies all requirements from issue #367: audits WP friction (16 patterns with sources), scans 4 non-WP tools, defines IA/mode model/key flows/UX principles, and delivers docs/design/site-editor-ux.md.
Out of Scope Changes check	✅ Passed	All changes are in-scope: the 1,045-line design brief document directly addresses issue #367 objectives; no pixel-level UI, Figma components, post-editor changes, or frontend rendering work is included.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/367-d0-site-editor-design-brief

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/design/site-editor-ux.md (1)

453-453: Consider adding language identifiers to code blocks.

The 9 fenced code blocks in this document lack language specifiers, which affects syntax highlighting in some markdown renderers. For ASCII diagrams (shell regions, inspector patterns), use text. For flow storyboards, use text as well.

♻️ Suggested improvement

For example, line 453 (entry model):

-```
+```text
 Dashboard
 ├── Posts          ← post-editor (already shipped)

Line 474 (shell diagram):

-```
+```text
 ┌──────────────────────────────────────────────────────────────────────────┐

Lines 798+ (flow storyboards):

-```
+```text
 Admin nav: click "Site Editor" → "Templates"

Apply the same pattern to all 9 code blocks flagged by markdownlint.

As per coding guidelines (markdownlint MD040), fenced code blocks should specify a language for consistent rendering.

Also applies to: 474-474, 699-699, 798-798, 824-824, 847-847, 875-891, 903-903

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/design/site-editor-ux.md` at line 453, Add explicit language identifiers
to the nine fenced code blocks flagged by markdownlint (MD040): update the entry
model block containing "Dashboard ├── Posts" to start with ```text, the shell
diagram block beginning with "┌─────────────────" to start with ```text, and all
flow storyboard blocks (e.g., "Admin nav: click \"Site Editor\" → \"Templates\""
and other ASCII diagrams/inspector patterns) to start with ```text so each
fenced block specifies a language for consistent syntax highlighting.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/design/site-editor-ux.md`:
- Line 453: Add explicit language identifiers to the nine fenced code blocks
flagged by markdownlint (MD040): update the entry model block containing
"Dashboard ├── Posts" to start with ```text, the shell diagram block beginning
with "┌─────────────────" to start with ```text, and all flow storyboard blocks
(e.g., "Admin nav: click \"Site Editor\" → \"Templates\"" and other ASCII
diagrams/inspector patterns) to start with ```text so each fenced block
specifies a language for consistent syntax highlighting.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 68943eca-1bbc-457e-9dbc-02f5ce83e1c2

📥 Commits

Reviewing files that changed from the base of the PR and between d834339 and 50044b8.

📒 Files selected for processing (1)

• docs/design/site-editor-ux.md