Implement site redesign with dark mode

[parlough]

Rewrites the site styles from scratch, to improve accessibility and add support for dark mode, while also dropping the dependencies on bootstrap and jquery. Various smaller PRs have already landed over the past few months to facilitate this change. It was intentional to avoid large changes to the site layout and structure as part of this work.

Staged: https://flutter-docs-prod--pr11172-feat-site-redesign-utslfe4y.web.app/

New features:

• A toggleable dark (or device/auto) mode
• Collapsible left sidenav
• Dismissible top banner
• Simpler top navbar, with focus on search
• Much more space for content on narrow and mobile layouts
• More consistent and accessible HTML and styles
• Add external link icons to external sidenav entries
• Implement more dynamic design functionality with CSS instead of JS

Issues resolved: Resolves https://github.com/flutter/website/issues/3632 Resolves https://github.com/flutter/website/issues/8030 Resolves https://github.com/flutter/website/issues/7769 Resolves https://github.com/flutter/website/issues/1667 Fixes https://github.com/flutter/website/issues/1728 Fixes https://github.com/flutter/website/issues/1940 Fixes https://github.com/flutter/website/issues/2313 Fixes https://github.com/flutter/website/issues/8505 Fixes https://github.com/flutter/website/issues/9000 Fixes https://github.com/flutter/website/issues/9329 Fixes https://github.com/flutter/website/issues/10532 Fixes https://github.com/flutter/website/issues/10536 Fixes https://github.com/flutter/website/issues/10543

Contributes to https://github.com/flutter/website/issues/9495 Contributes to https://github.com/flutter/website/issues/10534 Contributes to https://github.com/flutter/website/issues/10535

Left for follow-up:

• Active section highlighting for TOC
• Narrow version of TOC
• Search results without leaving page
• Updating or adding new images to work better in dark mode

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 876dd53d8facde1af0a11ef48be2183d9f89a6d6):

https://flutter-docs-prod--pr11172-feat-site-redesign-bygmk5c1.web.app

[domesticmouse]

Nitpick: Remove white on right side of "What's on this page" bar.

[sfshaza2]

Interesting! You can now close the banner. I like it.

• On the upgrade page. Please change the "master channel" text to "main channel". Funny how it's so hostile to me now and I never used to notice.
• Could you also incorporate Eric's sidenav changes, so we can look at all of it at once?
• Wow, the dark/light mode is so seamless and so beautiful!
• On this page ( https://flutter-docs-prod--pr11172-feat-site-redesign-pgdgowic.web.app/release/archive ), the tab defaulted to macOS - yay! Then I selected the other tabs and the "Windows" text never de-highlighted.

@parlough, this is, overall, looking and feeling fabulous. But I'll keep playing with it.

[parlough]

Thanks for the feedback and issues! Keep them coming :)

On this page ( https://flutter-docs-prod--pr11172-feat-site-redesign-pgdgowic.web.app/release/archive ), the tab defaulted to macOS - yay! Then I selected the other tabs and the "Windows" text never de-highlighted.

Could you provide a screenshot or video of this? I'm not sure I understand as I haven't been able to reproduce it. If it's easier, free to message me it too. Thanks!

[sfshaza2]

I can't reproduce it today, either. So, nvm.

[ericwindmill]

I don't want to bog down this work, so please let me know if you'd like me to hold off on comments until its ready for review.

I have some suggestions, and they all come down to personal preference. You should feel completely comfortable ignoring these if you disagree.

(Screenshots for reference)

Contrast: I feel there could be more contrast. (I like the colors otherwise.)

• The contrast between the background and the content background feels low.
• The breadcrumb box feels like it could be higher contrast from the text.
• The code block contrast from the content background could catch the eye more. I feel stronger about this on than the previous two.

Spacing:

• The width of the main content could expand more. On my MacBook, I would expect the content to take up all the available space.
• In general as it pertains to everything on the site: there could be more spacing (margin, padding, paragraph spacing, etc). There are so many elements and widgets on our site -- navs, note boxes, code blocks, videos, text sizes, header sizes -- and it feels busy and overwhelming to me. This is 100% preference. I just like minimalism and space in design. I also realize that this comment provides no concrete suggestions. Sorry 😃 . Also, this isn't an issue that your PR introduces, its something that I've felt about our site since the beginning. But this could be a chance to update it if you feel its a good idea.

In general, I love the updates. It looks so much more modern and less corporate-y. Also, thank you for doing this work in which everyone has opinions, despite not having expertise.

[johnpryan]

I have some questions about the new toolbar, but this is looking great overall!

The Flutter logo at the top doesn't look quite right to me, maybe it's too big or doesn't match what I normally see, but it might look better if we make the font smaller.

Also, making "Docs" a link feels weird, since there are two links right next to each other, it's not discoverable or clear which one I should click on to get to the main docs page. I see a few different options:

1. Make them a single link that take you to flutter.dev
2. Make them a single link that take you to docs.flutter.dev
3. Remove the second link
4. Keep the two links (no change)

I'm also wondering if we should consider keeping the toolbar as-is for now (including dropdown menus and such), since it's meant to visually look the same as flutter.dev. But I like having the new search bar in the center too, so maybe it's OK as is.

[parlough]

@ericwindmill Thanks for the feedback! I went ahead and increased the spacing in a few areas, both within and between content, as well as increasing the maximum width of the main content/article. I also increased contrast in each of the areas you mentioned as well as for a few interaction states. I'll explore some more spacing improvements, but let me know if anything else comes to mind. Thanks again :D

---

@johnpryan Thanks for the feedback and thoughts! Some thoughts and questions:

I'm also wondering if we should consider keeping the toolbar as-is for now (including dropdown menus and such), since it's meant to visually look the same as flutter.dev. But I like having the new search bar in the center too, so maybe it's OK as is.

I thought about this, but I feel there's little reason for developers currently reading the docs to return to the main site, which most of the menu items lead to. I've at least never used the menu from the docs site before. Plus, the dropdown menus give the feeling their entries will lead to the same site, but in the end they're quite different. That's why I added "Docs" after the Flutter logo, to make it clear that this is a completely separate experience.

Also, making "Docs" a link feels weird, since there are two links right next to each other, it's not discoverable or clear which one I should click on to get to the main docs page. I see a few different options:

Hmm you're right, but it's tricky as I imagine developers might want to return to both home pages. Which do you think users would more likely want to navigate to?

Another option to consider would be "Flutter Docs" going to the docs homepage and adding a little home icon next to the theme switcher to return to flutter.dev.

[domesticmouse]

Can we please follow the light/dark preferences of the target system? Here's a post detailing the required CSS.

[mit-mit]

A few overall comments:

1. The links to the Spanish and Chinese versions seem to be missing in the footer?
2. The brand link in the footer seems to be missing?
3. I agree that the logo+wordmark looks off. I think the text use is to big, and maybe the kerning is off?
4. I looks a bit odd with the menu open/close button before the logo. I'd prefer to have the logo first in the header.
5. I worry a bit that removing the top-nav leads to that content being less discoverable?
6. I don't see the cookier banner anymore; was that removed?
7. The search box looks like it's not aligned to anything; maybe the right hand side should align with the right hand side of the main content panel? Alternatively it could be smaller and aligned over next to the mode selection button?

[ericwindmill]

I'm also wondering if we should consider keeping the toolbar as-is for now (including dropdown menus and such), since it's meant to visually look the same as flutter.dev. But I like having the new search bar in the center too, so maybe it's OK as is.

I thought about this, but I feel there's little reason for developers currently reading the docs to return to the main site, which most of the menu items lead to. I've at least never used the menu from the docs site before. Plus, the dropdown menus give the feeling their entries will lead to the same site, but in the end they're quite different. That's why I added "Docs" after the Flutter logo, to make it clear that this is a completely separate experience.

FWIW I agree with Parker here. I don't think anyone is ever using the drop down buttons to go from docs to the marketing site. I think the top nav adds a bit of confusion and makes the user experience worse. Only marginally worse, but still worse.

Edit to add: I very much like that it says "Flutter Docs", and I think that kind of gives us permission to make the site look different than the marketing site. Perhaps that text could be one link, and there could be another button next to the dark mode button that takes the reader back to the marketing site. I have no idea what text would be on that button, though. There are probably numerous good solutions to the problem, this is just one idea

[mit-mit]

I don't think anyone is ever using the drop down buttons to go from docs to the marketing site.

I'm not 100% convinced about that. I agree for the core marketing stuff (once you get to docs you are already "sold"), but there is other content there like events, showcase, and community that seem relevant?

[ericwindmill]

I don't think anyone is ever using the drop down buttons to go from docs to the marketing site.

I'm not 100% convinced about that. I agree for the core marketing stuff (once you get to docs you are already "sold"), but there is other content there like events, showcase, and community that seem relevant?

Fore sure, I spoke hyperbolically. Looking at analytics, there are a few pages on the marketing site that account for a vast majority of traffic (the home page and Showcase, for example). Maybe there can be a single dropdown that links the most valuable pages? There are several pages (learn, the pages under 'Multi Platform') that are at best not interesting and at worst misleading to folks who are trying to find something in the docs.

[parlough]

Thanks everyone for all the feedback! It's extremely helpful as I've gone a bit blind to the changes now :P

Can we please follow the light/dark preferences of the target system?

I was originally planning to come back to this, as my feeling is we'd prefer to still default to the light experience. Would an option (under the same button) to use the system configuration be sufficient?

The links to the Spanish and Chinese versions seem to be missing in the footer?

I'll look into ways to resurface these. I'm not sure the esflutter community is maintaining a version of the docs anymore though.

The brand link in the footer seems to be missing?

Thanks for calling that out! I added it back :)

I looks a bit odd with the menu open/close button before the logo. I'd prefer to have the logo first in the header.

I'll explore some options here!

I don't see the cookier banner anymore; was that removed?

It should still be showing up. Perhaps you already dismissed it? Can you try again after clearing your localStorage and let me know if it's still missing?

I worry a bit that removing the top-nav leads to that content being less discoverable?

In relation to the topnav: I'll explore some options to continue surfacing the most important content!

[parlough]

@domesticmouse Mind trying out the new theme switcher and letting me know what you think?

[domesticmouse]

@domesticmouse Mind trying out the new theme switcher and letting me know what you think?

Still doesn't respond to macOS switching from light mode to dark mode. Tested against GitHub, which does follow the operating system light/dark mode setting

[mit-mit]

Yeah, this is shaping up super nicely!

I still think the logo needs to be the first thing in the top-nav. Yeah, that leaves an issue with what to do with the menu open/close button, but I'd punt on that to a later PR (i.e. remove that control for now). This just looks a lot nicer to me:

.

A concrete suggestion for an alternate open/close button design would be to make it similar to the Firebase Console one (which is a button at the very bottom of the nav).

[mit-mit]

Also, the spacing between the logo and wordmark is still a bit off:

[ericwindmill]

FWIW, automatic dark mode worked for me

[ericwindmill]

Maybe consider adjusting the color scheme (subtract 15 degrees from the hue) so it's more aligned with the Flutter logo:

I agree with this suggestion. (This is a nit, feel free to ignore.)

[redbrogdon]

/gcbrun

[parlough]

Thanks everyone for the great feedback and enthuaism here!

Many of the changes, accessibility improvements, and performance improvements in this PR have landed separately on the site already. A few extra new features are on their way as well.

As for the dark mode, I'll be revisiting it soon in a way to share more with dart.dev and better standardize with pub.dev. You can follow https://github.com/flutter/website/issues/3632 for more updates.

Thanks again :D