Composable PageHeader ☂️

[elycheea]

Page header v2

Brief description

Page header is one of the key component that Carbon for IBM Products delivers, however we have heard that it can be restrictive and does not meet the needs of all our adopters.

We want to make a page header v2 that is more composable and addresses any design and development issues.

Existing resources

• Website
• Storybook
• Figma kit

Links to other materials

• Page header Sketch import
• Data & AI Figma
• Atlassian page header
• C4Cloud page header
• Component gallery – Header (mostly web)](https://component.gallery/components/header/)

Design Maintainer(s)

• Owner/main maintainer(s)
• Second/backup maintainer(s)

Checklist of requirements/features

Common elements

• Identify commonality
  • Reference the Anatomy of a Pageheader
  • Breadcrumbs (slot)
  • Title (size, single line, multi line, truncation guidance?)
    • Editable ?
    • Include pictogram or slot for pictogram/icon.
  • Sub copy (variable size and length)
  • Common extras (possible slots):
    • Tabs
    • Tags
    • Action items (aligned to title)
      • Various requests: single button, button group, menu button, links
    • Action items (aligned to breadcrumbs)
      • Action bar?
    • Status indicators
  • Are all elements context dependent?

Functionality

• Collapsable
  • Is it scroll logic or via a button
  • Enhancement of page header on scroll  #3807 menu button collapse behaviors
• Breakpoints
• Simple and complex page header
• Scroll logic
  • Hook vs use or don't use it

Tasks

Before starting work on this epic, please review and complete the following.

• Initial review of design/existing code

Tasks

Preview Give feedback

1. Set up kickoff with a Security and CFP team to understand scope
2. General audit of Page headers across Software teams (include Cloud) #6154
   component: PageHeader role: design +2
   
3. Page header requirements #6278
   component: PageHeader role: design +2
   
4. [PageHeader v2] Design r1: Slots #6370
   component: PageHeader role: design +2
   
5. [PageHeader v2] Design r2: Type & Spacing #6371
   component: PageHeader role: design +2
   
6. [PageHeader v2] A11y, Responsiveness, and collapsing #6372
   component: PageHeader role: design +2
   
7. [PageHeader v2] Present current design and incorporate feedback from Design & Dev #6482
   component: PageHeader role: design +2
   
8. [PageHeader v2] Final header design iteration #6536
   component: PageHeader role: design +2
   
9. [Page header v2] Page header spec draft #6538
   component: PageHeader role: design +2
   
10. Stress tests
11. Discuss new component v. enhancement to existing
12. Discuss: Products or Carbon core
13. Investigate what data is hooked into Page header
14. Prototype page header requirements #6685
    component: PageHeader needs: prototype role: dev +3
    
15. [Page header v2] Finalize specs #6705
    component: PageHeader role: design +2
    

[elycheea]

Alan/Security —
Slightly blocked — certain functionality that’s required in the CP4S apps.

• Need more flexibility around the breadcrumb — either by composition or the functionality replicated within the component. This is the main sticking point. Necessary for the customers and a blocker to adoption. Want to adopt the PageHeader but not something that’s currently supported.
• Collapsed button for handling the combo button.
• Huge advantage in the page header because it enforces a certain amount of uniformity and consistency.
• Consistency can be defined within CP4S that we can run to 2 lines as a max and a location for actions
• Use composition for rendering the content
• Content we pass in should be un-opinionated and owned by the teams
• If we can get the scaffolding with a series of slots and some functionality afterwards (no one wants to re-implement the scroll logic)

From Laura/AppConnect —

• Also similar with how to handle menu buttons with collapsed behavior
  • Cameron: How to handle the tertiary buttons when it collapses
• Want to be able to include content switcher in the page header — probably not frequently seen but difficult to accomplish — kept it in the same position as the button (thought it’d be swappable the same way it is in Figma) — pretty niche so doesn’t need to be in the guidance, but should at least be supported.
• Wanted a tooltip in the description but wasn’t possible to do
• Mental model would be to have more zones similar to Figma where the designer and developer could have a bit more control (PageHeader as a less prescriptive component)
• Sometimes need a slimline basic page header (which should be editable)
  • Internal SimpleHeader component
  • Reduced page header story also has an example but possibly still more opinionated
• Default behavior truncates within a single line — this was not something we could accomplish so had to build the page header from scratch — human readable titles and descriptions
  • From Alan — machine-generated titles can be quite long with start of the titles are very boilerplate (Needs design consideration!)
• Heights of things should be consistent ... consistent spot for breadcrumbs, title, actions

Carbon recommends 2-3 words maximum but it’s not enforced.
Enforcing best practices versus recommending them.

“Zones” could make sense or help for Alan — pass the breadcrumbs in as a node, but there would probably run into issues with scrolling.

• Array to support the history feature or need to accommodate via composition but easier if that works

Dotcom has also dealt with line length and text length — set a max-width of 640 to help avoid long string of text, but Laura brings up the title needs to be present so understanding that balance.

[Laura-Marshall]

Note to add around the simple page header- we would need it to act a bit like a page header / toolbar combined (see below).
I could imagine that any canvas products may also want this.

Looking in the product gallery, data stage seems to have the reduced header + buttons, with a toolbar below. As we don't have as many actions, it would be good to house breadcrumbs, actions + status in the page header itself.

AI Ops also has an example that seems to include dropdowns too in the "page header"

[oliviaflory]

Design work that will need to be broken out into issues (feel free to add):

Breadcrumb

• Type size (why is it 12px instead of default 14)
• Support for history (Security / Alan)

Type styles

• Heading
  • Truncation
    • Not set to default truncation
    • When to truncate
    • Tooltip handling
  • Include pictogram
• Description
  • How to limit width

Slots

• Current page header has button group that can collapse on scroll
  • Include explorations with tertiary & ghost buttons
  • Menu
  • Explore content switcher (this will not always collapse)

Example:

Height

Consistency in height of header

• consistent spot for breadcrumbs, title, actions

[elycheea]

@oliviaflory I’m glad you put height into a separate issue too because this the “simple header” section ends up being the spot where we load up so much when screen sizes are small.

https://ibm-products.carbondesignsystem.com/?path=/story/ibm-products-components-page-header-pageheader--fully-loaded-and-some

1. Hit T if the toolbar isn’t showing
2. Switch to sm or md breakpoints to see back button — (I think this used to be an icon button but we switched it to something more custom since the new version breaks the current spacing.)

[Jonathan-Bruckbauer]

Not sure if this helps in any way, but I've built a page header component for Data&AI covering use cases from CPD. You can find it in the v10 Figma Library named 'Experience Library' which is in the team 'Figma for Data and AI (D&AI)':

https://www.figma.com/design/Ftw6XaLhKKv2QO07qRG3hS/Experience-Library?node-id=2356-84179&t=ZXewogAEuHGQG7d0-4

It contains the following properties:

[aknguyen7]

Adding to simple header: the ability to add text/link inplace of buttons in Actions zone

[RichKummer]

Enabling key actions while scrolling 12/11/24

(Some ways devs implement this is to have two instances of an element: one in the page and another in a separate container for scroll. The below may not apply depending on how product devs are meant to implement the scroll container).

We discussed an idea to give teams flexibility between the default view of the PageHeader and the scrolling view. Ideally, only key actions that the user would need as they scrolled the page would appear in the scroll version of the header. Product teams may need a way to determine which select actions should appear instead of all actions in the default header.

Wondering if we could allow adopters to label or identify an element in the header that signals that this element should appear in the scrolling header. Could be a prop, label, or something else to identify in the product code.

• We would need guidance on how to select which items and sizing (needs to fit in 40px height area.
• In the example below, the button is tagged for scrolling-priority (name TBD), but not the content switcher. In this case, the button would appear in the scrolling view of the PageHeader, but not the content switcher.
• This could give teams flexibility without being too prescriptive.