Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rethink the Document Bar and the Post Summary title #65238

Open
2 tasks done
afercia opened this issue Sep 11, 2024 · 0 comments
Open
2 tasks done

Rethink the Document Bar and the Post Summary title #65238

afercia opened this issue Sep 11, 2024 · 0 comments
Labels
[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Design Feedback Needs general design feedback. [Package] Editor /packages/editor [Type] Bug An existing feature does not function as intended

Comments

@afercia
Copy link
Contributor

afercia commented Sep 11, 2024

Description

See also #51460

I'd like to propose to completely rethink the editor Document Bar and the Post Summary title.

For better semantics, usability, and accessibility, two basic principles do apply in this scenario:

  • User interface controls names should clearly identified what the control action and purpose is.
  • Headings should clearly identify content sections.

Screenshot 2024-09-10 at 08 51 52

The Document Bar

The Document Bar implementation is less than ideal.

1
Starting from the basics, the rendered HTML is invalid HTML. In pseudo code, this is che HTML structure of the Document Bar:

<button ...>
    <div ...>
        <span ...>
            <svg ...>{ icon }</svg>
        </span>
        <h1 ...>This is my post title</h1>
    </div>
    <span class="editor-document-bar__shortcut">⌘K</span>
</button>
  • Button elements can't contain div elements. That's invalid HTML.
  • More importantly, Button elements can't contain headings, that's invalid HTML.

New generations of JavaScript developers may not know much about HTML, as frameworks like React educate them to just use components with abstracts names and not care much about the actual rendered HTML. Still, WordPress should strive to always render valid HTML.

2
The button label doesn't communicate what the button actually does. The label is:

  • Either the edited post name or title plus the characters ⌘K e.g.: This is my post title ⌘K.
  • Or No title ⌘K when there's no title.

However, clicking the button opens the Command palette.

As such, the label of the button doesn't communicate what the button does. This button is just not the right place to show the edited object name or title. The title and the button to open the Command palette should be separated.

It is worht reminding that the Document bar may also visually include a button to 'Go back', depending on the edited object. Example screenshot:

Screenshot 2024-09-11 at 14 13 29

  • The 'Back' button appears to be randomly placed there only for visual purposes. There's no great consideration about logical grouping as this button is more related to 'navigation' and it's instead placed in a spot dedicated to information about the edited object / document.
  • In this case, the visible text of the Document bar button is: Single Posts.
  • The actual accessible name is: Editing template: Single Posts.
  • Still, clicking the Document bar button opens the Command palette.

3
The Document bar button contains a H1 heading with the name or title od the edited object.

  • When editing a post, users may see the title in 3 different places. The document bar, the editor canvas, the heading in the post summary. The same information is repeated thrice. To me, that's too much and I'm not sure I understand why, as a used I need to see this info in three different places. Note: some edited objects don't have a title in the canvas so it would be just two times.
  • The Document bar title is a H1 so thare are actually two H1 headings on the same page. The main one is visually hidden and it is meant to identify the WordPress page e.g. Edit Post.
  • The title in the Post Summary is a H2 heading with the same text of the heading in the document bar. That's redundant and unnecessary information.
  • Additionally, headings in the settings panel should cllearly identify the panel sections. In the screenshot below, the headings 'Categories' and 'Tags' do identify the related sections. The heading 'My post title' doesn't, Thats the Summary section and it should be preceded by a heading that clearly says 'Summary'.

Screenshot 2024-09-11 at 13 40 49

Above: Screenshot to illustrate how the headings hierarchy and headings content are less than ideal.

Note: The HeadingsMap extension I used to take detect the headings isn't able to perceive the H1 in the editor canvas because it's in an iframe. Regardless, the post title in the editor canvas is one more H1 heading that repeats for the third time the post title.

Proposal

  • The information about the title / name of the object being edited doesn't need to be repeated. Ideally, it should be only shown once.
  • Optionally, it could also be editable to allow renaming.
  • The title / name of the object being edited should not be placed as first heading above the Post Summary in the settings panel. First, that's unnecessarily repeated information. Secondly, the post summary section needs to be clearly identified by a heading that just says 'Summary'.
  • The button that opsn the Command palette should be separated from the document bar and should be labeled in a meaningful way to clearly communicate what it does / is about e.g.: Commands.
  • Worth also mentioning that the placement of the Document bar in the middle of the editor top bar is problematic for small viewports. Currently, a number of buttons in the top bar get hidden on small screens because of the presence of hte Document bar. One more good reason to remove it.
  • The Document bar has limited horizontal space. Long titles / names get just truncated, which entirely defeats the purpose of showing the titles / names in that spot. The titles / names of the edited objects are a key pieace of information and should be fully visible.

Taking some inspiration from Google Docs:

google docs

  • Teh use a 'top bar' which is split in a left and right parts.
  • The left part displays controls and informations in two rows:
    • The title (which is also editable).
    • Additional controls realted to the title.
    • In teh row below: the main menu sections for editing and various tools.

The big advantage of this layout is that:

  • The title / name of the edited object is the very first thing in the editor (besides the logo / link to the home)
  • By placing the title in that spot, it could be simply be the main H1 heading of the page (the current 'Edit post') thus allowing to remove the duplicate H1.
  • By making it editable, it would also be a clear affordance for renaming.
  • The button to open the Commands palette should be moved elsewhere. I'd rather think the concept of 'Commands' is 'global' to the document. While the Command Palette lists commands of varying nature, it's certainly closer to a 'global tool' and as such a good option would be to move it into the 'Document tools' in the top bar.

Screenshot to illustrate. Disclaimer: I'm not a designer so please bear with me and this very rough screenshot:

Screenshot 2024-09-10 at 12 52 49

  • The visible text is the actual main H1 of the page. Reminder: headings don't need to be 'big'. They are meant to be used for semantics and content structure, not for presentation and font size.
  • There is enough horizontal space to show long titles and names of the edited objects.
  • The top bar height should be slightly increased to contain two rows.
  • Vertical alignment could be handled dlike Google Docs does.

Related:
#503
#65167

Step-by-step reproduction instructions

N/A

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

  • Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

  • Yes
@afercia afercia added [Type] Bug An existing feature does not function as intended [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Design Feedback Needs general design feedback. [Package] Editor /packages/editor labels Sep 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Design Feedback Needs general design feedback. [Package] Editor /packages/editor [Type] Bug An existing feature does not function as intended
Projects
None yet
Development

No branches or pull requests

1 participant