Admin UI: Page header design spec

[grbicsanja]

Universal page header component

Figma spec link

Essential header elements

• Title (Heading LG (15/20)
• Header background color is the same as Page background (Default: wpds/color/background/surface)
• Border: Always present, 1px, neutral

Optional header elements

• Logo/Decoration: 20×20px
• Badge: Indicating status
• Tagline: Page summary, brief intro to product, etc
• Breadcrumb
  • When breadcrumbs are shown, the page title should be hidden (but still present) to avoid visually duplicating page info.
• Navigation: Optional
• Actions:
  • Button size is compact
  • Number of actions in the header: MIN 0, MAX 3
  • Only 1 primary button, up to 2 secondary buttons
  • Tertiary actions stay behind the ellipsis menu
• Controls slot:
  • An optional slot for search, DataViews controls and other needed actions
  • When navigation is not present, controls can float left or right

Aditional guidelines

• On scroll: Stickiness is optional
• Actions: Primary button is always positioned to the right

Responsiveness

• Long titles are truncated
• Everything except the primary action moves inside the ellipsis menu. If there was no ellipsis menu initially, one is generated.
• At a certain breakpoint the logo disappears and the hamburger is revealed.
• If space allows, Hamburger, Title, and Actions remain on one line.
• On scroll, the tagline/description disappears.
• Breadcrumb is always constrained to a single line. Once it's unable to shrink to fit any more, it moves to the line below.
• Navigation: Horizontal scroll
• If space allows, controls stay in line with navigation
• When there's no space, controls stack underneath the navigation and can float right or left.

@WordPress/gutenberg-components
@WordPress/gutenberg-design

@keoshi @jameskoster @poligilad-auto @verofasulo @simison

[ciampo]

A couple of comments:

• Title and Breadcrumbs should be seen as different elements (with different semantic purpose), even if the breadcrumbs can include the page title. Ideally, we should get to a place where the title is still added to the page but visually hidden.

• In terms of responsiveness, what happens for breadcrumbs with 3+ items?

[grbicsanja]

• In terms of responsiveness, what happens for breadcrumbs with 3+ items?

@ciampo Good question, how about we just handle that with truncation?

[grbicsanja]

• Title and Breadcrumbs should be seen as different elements (with different semantic purpose), even if the breadcrumbs can include the page title. Ideally, we should get to a place where the title is still added to the page but visually hidden.

@ciampo Good point! Added to the spec:

[ciampo]

how about we just handle that with truncation?

Some thoughts:

• Truncation is the nicest way visually, but it's tricky to implement in an accessible way — hopefully we'd be able to do that correctly;
• From personal experience, I usually see ellipses being used in the middle of the list, ie, home / ... / current page, rather than at the start. I guess it gives end users (including assistive tech) more context (example)
• Implementing a responsive, "auto-collapse as many items as needed into ellipses" behaviour is going to be quite complex to get to work flawlessly.
• Should the badge (if present) ever break the line, or should it force breadcrumbs to shrink even further?
• Let's prepare for "worst case scenarios" where the viewport is very narrow (eg 320px), and have additional "last resort" measures for when first item / ... / last item doesn't fit. A few ideas:
  • cause the first item be absorbed into the ellipses (ie. ... / last item)
  • could truncate the last item (ie. ... / last i...)
• Should this "collapse items into ellipses" be applied also when breadcrumbs and actions are on the same line? If yes, to what degree? (ie. should it try the "last resort measures" above?)

[grbicsanja]

Thanks @ciampo !

• From personal experience, I usually see ellipses being used in the middle of the list, ie, home / ... / current page, rather than at the start. I guess it gives end users (including assistive tech) more context (example)

I'm good with taking that approach instead 👍

• Implementing a responsive, "auto-collapse as many items as needed into ellipses" behaviour is going to be quite complex to get to work flawlessly.
• Should the badge (if present) ever break the line, or should it force breadcrumbs to shrink even further?

Yes, on keeping the badge in the same line. In the use cases I've seen, the context is very tightly related to the title of the current page

• Let's prepare for "worst case scenarios" where the viewport is very narrow (eg 320px), and have additional "last resort" measures for when first item / ... / last item doesn't fit. A few ideas:

  • cause the first item be absorbed into the ellipses (ie. ... / last item)
  • could truncate the last item (ie. ... / last i...)

So something like this?

In this extreme case, I'd say it's ok to truncate the last item too.

• Should this "collapse items into ellipses" be applied also when breadcrumbs and actions are on the same line? If yes, to what degree? (ie. should it try the "last resort measures" above?)

Yes but not to the extreme. How about if more that one item needs to truncate it should move to the next line. Or if you have any suggestions that would be easer to implement.

[CGastrell]

At a certain breakpoint the logo disappears and the hamburger is revealed.

What would the hamburger menu trigger/hold in this case? I might take a shot at these specs, wondering if there's already a decision on the expected hamburger menu or merely hiding the logo until there is one.

Also on this matter, to be able to control the logo/hamburger behavior the logo needs its own rendering logic, I'm trying to add the prop on #76469 but there might be some implications (as seen on the discussion there) as to what's the best approach for it.

[simison]

Logo/Decoration: 20×20px

@jameskoster you suggested here that icon could be 24px to match Icon component's default size. Is that the final decision, or does it need more discussion?

[CGastrell]

Something to keep in mind from what I see on the spec, more rendering logic might need to be put into place.

Since we're talking about how to better prepare the API for the future:

• actions might need to be a simple array and then have their own API to determine which ones render as a button and which ones get collapsed into the ellipsis menu. Right now that can be done by the consumer (providing a dropdown as one of the actions), but if we mean to automate that based on viewport size, the actions API might need some thought
• related to the above, the "primary" action should be placed to the right, that also calls for actions to have their own API and construct the action based on its own logic and conditions
• the hamburger menu seems to rely on a slot, this might require a backwards compatibility depending on the build
• looking at the screenshots here, likely a flexbox (HStack, Stack) won't suffice, likely a grid might be a better candidate

So, all in all I'd say the entire hierarchy of components will need to rule their own rendering logic. Definitely we'll need the icon prop separate from title and/or breadcrumbs. Should next step be export Header on its own?