Update navbar design and improve search UI #1084

lhsazevedo · 2024-10-04T01:28:33Z

Tip

You can view this proposal live at: https://php-navbar.lhsazevedo.dev/

Intro

Over the years, the PHP webpage received various design proposals, some didn't gain traction due to their drastic nature or departure from PHP's established branding style. However, our community has shown that we can successfully implement design improvements when they're incremental – the PHP 8 release pages, homepage hero and thanks page are great examples of this approach.

Inspired by these successful updates and the the discussions they sparked, I'd like to propose some updates to the navbar design and introduce a new search dialog to enhance a bit the user experience on php.net. These changes are inspired by modern web design principles while respecting PHP's branding and build upon previous community discussions.

By focusing on small enhancements rather than a full redesign, we can improve the site's usability and aesthetics without disrupting its familiar layout and branding.

UI Scope

It's worth noting that while the current client-side search implementation could be considered outdated, replacing it would be beyond the scope of this design improvement. Such a change would require a separate, focused effort. This proposal aims to enhance the user interface while maintaining the existing search functionality, setting the stage for potential future improvements to the search implementation itself.

Enhancements

Modernized navbar design:
- A responsive navbar with improved mobile navigation.
- Ensures a consistent experience across devices, addressing the growing mobile user base while maintaining PHP's established visual identity.
New search dialog:
- A user-friendly search modal with keyboard navigation.
- Improves accessibility with proper ARIA attributes and keyboard navigation, making php.net more inclusive.
Retained search implementation:
- Integration of the existing FuzzySearch with the new UI.
- Maintains familiar search behavior while setting the stage for future improvements to the search implementation.
Code improvements
- CSS refactoring and removal of outdated libraries (Hogan.js, typeahead.js).
- Improves maintainability, making future enhancements easier to implement.
Enhanced reliability
- Introduction of Playwright E2E tests for the new search modal.
- Ensures the changes don't introduce regressions, maintaining the site's reliability.

Impact

These changes are designed to be minimally disruptive:

Existing users will find a familiar but enhanced experience
New users will benefit from improved navigation and search UI

Preview

Please note that the preview site uses an improved search index generated by a companion change I'm proposing to the PHP documentation generator (phd). While both PRs can be merged independently, I've captured the screenshots and recordings using the new index to showcase the full potential of these improvements.

You can find the companion PR for the phd changes here: php/phd#154

Preview Site

You can view this proposal live at: https://php-navbar.lhsazevedo.dev/

Desktop preview

desktop_preview-2024-10-03_22.08.18.mp4

Mobile preview

mobile_preview-2024-10-03_22.10.47.mp4

Comparison

View GIF comparisons (image heavy)

Desktop comparison

Navbar

Search modal dialog

Mobile comparison

Navbar

Navigation

Search

Final thoughts

I believe these improvements will benefit the PHP community while respecting the site's established design principles. I look forward to your feedback and collaboration in refining this proposal.

If you find this proposal valuable or have any concerns, I'd greatly appreciate your feedback. Please consider leaving a 👍 or 👎 to help measure the community opinion.

github-actions · 2024-10-04T01:29:43Z

🚀 Preview for commit fcc9565 can be found at https://web-php-pr-1084.preview.thephp.foundation

github-actions · 2024-10-04T01:30:16Z

🚀 Regression report for commit fcc9565 is at https://web-php-regression-report-pr-1084.preview.thephp.foundation

lhsazevedo · 2024-10-04T01:30:30Z

Suggested reviewers: @morrisonlevi @dragoonis @cmb69 @kamil-tekiela @ramsey @mvriel @pronskiy @Girgias @localheinz

Edit: Will check visual tests asap

kamil-tekiela · 2024-10-04T12:06:40Z

I like it. I like the changed color, I like that the text of the buttons is more readable, I like that the PHP logo is now white, and I like that the search results list is simpler. The mobile view looks really good. There are a couple of things I don't like though.

I am not of a fan of the search opening up to cover the page. Why is it that when I click on an input box a new input box pops up? The placeholder text also doesn't match suggesting that the popup does something different than the box I actually clicked on.
If the popup stays, I would not disable the page scroll. I never liked this as it creates a jarring visual experience. At least on Chrome the page shifts to the right and the scroll bar is now in the middle box which means that if I want to scroll I need to hover my mouse over the thin box.
If the popup stays, there should be no load animation. It's an unnecessary gimmick that only delays loading of the box.
Even though the text is more readable, I still think it's not contrast enough from the background color. Especially the "Search" placeholder is visually blending in with the surroundings. Make it stand out more, either by changing the text color or giving the search box lighter border. I wouldn't mind if all text in the navbar was pure white or whitesmoke.
IMHO there is no need to make the navbar taller. The previous height was ok. On most monitors the vertical space is more expensive than horizontal, so every padding you add makes the actual content push down to a place with less priority. You made it shorter in mobile view so why make it taller in desktop view.
Not sure if related but the code formatting on /releases/8.3/en.php is borked.
The navbar is now almost the same color as the main div of /releases/8.3/en.php. Everything is purple now. I don't hate the color, but it's just too much. Something needs to change.
The logograms in mobile view have too low contrast with the background. You made them #D2D9FF but even if they were #FFFFFF they would be still too dark. I would suggest making it #F5F5F5 with opacity 1, the same as all text in the navbar.

cmb69 · 2024-10-04T12:30:09Z

Thank you! Overall, this looks like a nice improvement, but I don't like that the search now won't work if JavasScript is not available.

simonrjones · 2024-10-05T14:04:27Z

The popup search results looks very smart. A few thoughts:

Accessibility:

Contrast of primary navigation items fails WCAG accessibility (so does the current site it seems), text colour #DBE2FF or lighter would fix this
Contrast of search text fails WCAG accessibility, text colour #CBCCF1 or lighter would fix this
ALT text of PHP logo is "PHP Logo" - there's no need for the text "logo" here for accessibility reasons. Ideally it would be "PHP home" to indicate it links to the homepage.

Other:

I'd strongly recommend using progressive enhancement so the search works without JS. JS can fail for many reasons and the search should be accessible to all. The search box is a button, if this switched back to input then the form would work without JS (since would submit to the search results page)
When you do just press return it loads this full website search results page instead of the manual lookup page. It's probably more useful, but the styling is very basic on the full website search results page (I appreciate this is the same on the current site). Compare:
- https://www.php.net/manual-lookup.php?pattern=function&scope=quickref
- https://php-navbar.lhsazevedo.dev/search.php?lang=en&q=function

Girgias

The search bar not working any more with JS is a massive issue.

include/footer.inc

Adjust navbar and search modal element colors to meet WCAG AA contrast ratio. Additionally, match the search button label and input placeholder text to avoid confusion, and hides some SVG images from the accessibility tree.

CSS BEM is used in the PHP 8 Release pages and Special Thanks pages.

lhsazevedo · 2024-10-06T05:29:25Z

Thanks for the quick review and feedback! I've addressed many of your points and would like to discuss a few of them:

Progressive enhancement

@cmb69 @Girgias @simonrjones
The search was updated to work without JavaScript, using a form by default with the modal as a progressive enhancement.

Searching on mobile sized screens will still require JS. Given that it's common for mobile users to have JavaScript enabled, I think this is a reasonable trade-off. Some major language require JavaScript for searching (even on desktop): Kotlin, Rust, Swift, MDN, Dart. All Algolia-powered docs as well, and MkDocs.

Accessibility and contrast

@kamil-tekiela @simonrjones

All elements in the navbar and search modal have been updated to comply with WCAG AA contrast ratios. This includes the primary navigation items, search text, and icons in mobile view.

Layout

Page covered, no scroll

@kamil-tekiela The popup is inspired by Algolia that used in popular documentation sites (e.g. Composer, PHPStan, Laravel, Vue, React etc). It felt it a bit awkward the first time I saw it, but got used to it eventually.

The ideal UI for me would be something like Psalm docs (Material for MkDocs), but it is a bit more complicated to implement. Given the current search UI situation (5 different scrolling elements nested in a thin menu) maybe we could proceed with the Algolia-like modal as a first step and further improve it in the future. Would you consent to this approach?

Fade animation

@kamil-tekiela I believe this is a bit subjective and a matter of taste, but I can remove it if it's a common opinion. For now I halved the animation duration to 1/10th of a second, is this still a deal breaker? You can test it here (may need to disable cache).

Navbar height

@kamil-tekiela Forgot to mention but I followed @morrisonlevi's suggestion to avoid the sticky header, so now it doesn't take up any space after scrolling down. Note that the navbar is 64px tall on both desktop and mobile, which seems a common height for navbars, even sticky ones.

Other fixes

Matched the placeholder text between the search button and the modal.
Darkened the release page background a bit for better contrast with the navbar.
Hid navbar logo from the accessibility tree, as the anchor aria-label is already "PHP home".
Plus some minor adjustments, see commits.

Unrelated or out of scope

Release page formatting

@kamil-tekiela I think this is now fixed php/phd#156

Search page styling

@simonrjones Given that this is the current behavior and it relates to the page content, I think it would be out of scope for this PR. What do you think of discussing this in a separate issue?

Additionally, increase contrast of navbar items and make some minor adjustments and fixes.

lhsazevedo · 2024-10-12T01:49:45Z

Just pushed some commits addressing both points.

@Girgias @simonrjones
Both search and menu buttons (mobile) are now progressively enhanced as well, using the same approach as gov.uk. I've included end-to-end tests for them too.

@kamil-tekiela
Contrast increased a bit for all menu items.

Changes are deployed to https://php-navbar.lhsazevedo.dev .

There is one pending fix to ensure that it will gracefully update to the new local index cache format. I'm planning to push it (and fix CI) by next week

Fun fact:

These changes were finished and pushed during this month's PHPRio Pub Meetup event 🍻

Girgias

Some minor nits, but LGTM.

I will let other people more in charge with the Website take over.

include/footer.inc

Girgias · 2024-10-13T19:45:16Z

js/common.js

+            ) {
+                $("#goto .results ul").append(`
+                    <li>
+                        <a href='/manual/en/${node.id}.php'>


This probably should use the current language instead of directing to the English version.

Suggested change

<a href='/manual/en/${node.id}.php'>

<a href='/manual/LANG/${node.id}.php'>

Yup, it probably should. Actually, this code is part of the "global search" feature that triggers with g then a. I wasn’t aware of it until I had to adjust the code to prevent breaking due to changes in the search index structure.

TBH, I believe that we could just remove it and use g a as another shortcut to the new search dialog, but may be out of scope for this PR.

For now I've pushed a commit for the anchor href you pointed and the cache key a few lines before it.

js/search.js

Co-authored-by: Gina Peter Banyard <[email protected]>

Simplified function signatures by avoiding redundant language parameter passing, now using the one available in the outer scope. Also avoids shadowing the language variable.

Additionally, use brand blue as the selected color for search results

ddevsr · 2024-10-23T03:42:22Z

I think keep header position fixed, but after scrolling resize to small is good

Girgias · 2024-10-23T12:14:59Z

@saundefined can you have another look at this?

saundefined

I like it, thank you!

We can wait a little longer (say, until the end of the week),
and if there are no objections, merge it

lhsazevedo · 2024-10-23T17:30:01Z

Sounds good, no rush.

It would be great to have this ready for the 8.4 release though.

lhsazevedo · 2024-10-23T18:15:32Z

Fixes #502

theodorejb · 2024-10-27T22:08:48Z

Can the mobile nav sidebar be made to close when tapping outside of it? I instinctively tried to do this when testing on my phone, and it feels annoying that I instead have to tap a small X in the corner.

saundefined · 2024-10-31T08:48:21Z

@lhsazevedo can you take a look?
lhsazevedo#1

Can the mobile nav sidebar be made to close when tapping outside of it?

Should solve it

lhsazevedo · 2024-10-31T18:02:09Z

Thanks @saundefined, merged.

I noticed some common code between the offcanvas menu and the search modal.

web-php/js/search.js

Lines 315 to 321 in eb7a39d

    
               // Close when the user clicks outside of it 
        
               backdropElement.addEventListener("click", (event) => { 
        
                   if (event.target === backdropElement) { 
        
                       hide(); 
        
                   } 
        
               }); 
        
           };

In the future, we could consider refactoring this into a helper to keep things DRY. But hey, it's always good to go WET first!

Hero classes changed after php#1107. Should fix visual tests.

lhsazevedo added 5 commits October 3, 2024 20:05

Update navbar design

03491d5

Add new search modal dialog

89c598e

Add search modal e2e tests

8650771

Remove Hogan.js and typeahead.js

d0da0c8

Update playwright snapshots

831f80c

lhsazevedo requested review from saundefined and sy-records as code owners October 4, 2024 01:28

Fix e2e and visual tests

b17b606

lhsazevedo mentioned this pull request Oct 4, 2024

Improve search index generation for PHP.net php/phd#154

Merged

lhsazevedo added 2 commits October 4, 2024 18:36

Avoid page shift when opening the search modal

0048ef1

Match search label and input placeholder text

b83f783

Girgias requested changes Oct 5, 2024

View reviewed changes

include/footer.inc Outdated Show resolved Hide resolved

include/footer.inc Outdated Show resolved Hide resolved

include/footer.inc Outdated Show resolved Hide resolved

include/footer.inc Outdated Show resolved Hide resolved

lhsazevedo added 10 commits October 5, 2024 23:32

Increase contrast for accessibility

23003ff

Adjust navbar and search modal element colors to meet WCAG AA contrast ratio. Additionally, match the search button label and input placeholder text to avoid confusion, and hides some SVG images from the accessibility tree.

Halve the transition duration of the search modal

cd0754b

Reduce search scrollbar width

07da74b

Darken release background to better fit the navbar

ec7e9b9

Fallback search when Javascript is disabled

7146752

Remove logo alt text

535b25d

Fix modal input type and aria-label

b8bb98c

Use <kbd> tag

75a3e38

Use correct CSS methodology

9fe9ed1

CSS BEM is used in the PHP 8 Release pages and Special Thanks pages.

Avoid search flash on mobile

4c062ec

Fix e2e and visual tests

21b220e

lhsazevedo added 2 commits October 11, 2024 22:31

Progressively enhance mobile menu and search

afaaa2e

Additionally, increase contrast of navbar items and make some minor adjustments and fixes.

Add e2e tests for JS disabled search and menu

2f3da84

lhsazevedo force-pushed the navbar-2024 branch from 393d3c4 to 2f3da84 Compare October 12, 2024 01:31

Girgias approved these changes Oct 13, 2024

View reviewed changes

lhsazevedo and others added 8 commits October 21, 2024 18:27

Invalidate old search cache format

ae5a14c

Use a single kbd tag for each arrow key

97a865b

Co-authored-by: Gina Peter Banyard <[email protected]>

Fix leftover vars

6a4dcd1

Use current language in legacy global search

2d89914

Add missing docblocks and improve existing ones

e35fe6e

Use language parameter from outer scope

1fa0853

Simplified function signatures by avoiding redundant language parameter passing, now using the one available in the outer scope. Also avoids shadowing the language variable.

Format search.js

d2d68a0

Tone down result hover background color

39bc218

Additionally, use brand blue as the selected color for search results

lhsazevedo force-pushed the navbar-2024 branch from 4522fe1 to 39bc218 Compare October 22, 2024 23:51

lhsazevedo added 2 commits October 22, 2024 23:49

Update visual tests snapshots

0d5a896

Add search modal visual test

f97426e

Fix visual tests snapshots

eb7a39d

lhsazevedo force-pushed the navbar-2024 branch from 77ba1cf to eb7a39d Compare October 23, 2024 04:52

saundefined approved these changes Oct 23, 2024

View reviewed changes

lhsazevedo mentioned this pull request Oct 23, 2024

Convert homepage hero section styles to use BEM methodology #1102

Closed

saundefined added the hacktoberfest-accepted label Oct 31, 2024

Close offcanvas menu by outside click

614a1ad

Sync class name with master

d54e103

Hero classes changed after php#1107. Should fix visual tests.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update navbar design and improve search UI #1084

Update navbar design and improve search UI #1084

lhsazevedo commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

lhsazevedo commented Oct 4, 2024 •

edited

Loading

kamil-tekiela commented Oct 4, 2024 •

edited

Loading

cmb69 commented Oct 4, 2024

simonrjones commented Oct 5, 2024

Girgias left a comment

lhsazevedo commented Oct 6, 2024 •

edited

Loading

lhsazevedo commented Oct 12, 2024 •

edited

Loading

Girgias left a comment

Girgias Oct 13, 2024

lhsazevedo Oct 21, 2024

ddevsr commented Oct 23, 2024

Girgias commented Oct 23, 2024

saundefined left a comment

lhsazevedo commented Oct 23, 2024 •

edited

Loading

lhsazevedo commented Oct 23, 2024

theodorejb commented Oct 27, 2024

saundefined commented Oct 31, 2024

lhsazevedo commented Oct 31, 2024

	<a href='/manual/en/${node.id}.php'>
	<a href='/manual/LANG/${node.id}.php'>

Update navbar design and improve search UI #1084

Are you sure you want to change the base?

Update navbar design and improve search UI #1084

Conversation

lhsazevedo commented Oct 4, 2024 • edited Loading

Intro

UI Scope

Enhancements

Impact

Preview

Preview Site

Desktop preview

Mobile preview

Comparison

Desktop comparison

Navbar

Search modal dialog

Mobile comparison

Navbar

Navigation

Search

Final thoughts

github-actions bot commented Oct 4, 2024 • edited Loading

github-actions bot commented Oct 4, 2024 • edited Loading

lhsazevedo commented Oct 4, 2024 • edited Loading

kamil-tekiela commented Oct 4, 2024 • edited Loading

cmb69 commented Oct 4, 2024

simonrjones commented Oct 5, 2024

Girgias left a comment

Choose a reason for hiding this comment

lhsazevedo commented Oct 6, 2024 • edited Loading

Progressive enhancement

Accessibility and contrast

Layout

Page covered, no scroll

Fade animation

Navbar height

Other fixes

Unrelated or out of scope

Release page formatting

Search page styling

lhsazevedo commented Oct 12, 2024 • edited Loading

Girgias left a comment

Choose a reason for hiding this comment

Girgias Oct 13, 2024

Choose a reason for hiding this comment

lhsazevedo Oct 21, 2024

Choose a reason for hiding this comment

ddevsr commented Oct 23, 2024

Girgias commented Oct 23, 2024

saundefined left a comment

Choose a reason for hiding this comment

lhsazevedo commented Oct 23, 2024 • edited Loading

lhsazevedo commented Oct 23, 2024

theodorejb commented Oct 27, 2024

saundefined commented Oct 31, 2024

lhsazevedo commented Oct 31, 2024

lhsazevedo commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

lhsazevedo commented Oct 4, 2024 •

edited

Loading

kamil-tekiela commented Oct 4, 2024 •

edited

Loading

lhsazevedo commented Oct 6, 2024 •

edited

Loading

lhsazevedo commented Oct 12, 2024 •

edited

Loading

lhsazevedo commented Oct 23, 2024 •

edited

Loading