Docs dark mode v1.0

[akeller]

Description

Add a "dark mode" option to the docs web site, and check/refine CSS styles and content for any issues and to align branding with product dark mode.

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[mesellings]

Did some work on this today, still to check:

• Admonitions
• Tabs
• API ref styles
• Some images as discussed (transparent SVGs)

But other than that, it's already looking good (homepage and page content)! Shouldn't take much to finish off and get into review for the team.

@akeller FYI, I think this will be done before the hackathon, so might scrap that idea.

[mesellings]

SVGs non-blocking:
Investigated page: http://localhost:3000/docs/next/components/modeler/bpmn/bpmn-coverage

• All images render sufficiently, though black outlined ones could be clearer.
• Don't want to add a blanket background colour to .SVGs
• Suggest follow-up work on this page to go through these images and improve for dark mode.

[mesellings]

@camunda/tech-writers The first iteration of dark mode is now ready for review in this PR:

https://preview.docs.camunda.cloud/pr-4510/index.html

Changes made as follows:

• General dark mode styling/colours follows the product dark mode where possible.
• Home page edited to suit dark mode.
• Enable/disable using the icon at the top right of the banner.

Things to look at and check if we need to make further mods, or if they are 'okay as is' for now.

• Admonition colours
• Tabs (I changed them to 'buttons in dark mode)
• Link colour (blue works better than orange in dark mode and matches product)
• API ref styles
• Images (might do some follow-up work on a few specific pages with transparent SVGs, but they are usable for now)

[conceptualshark]

This is super cool, thank you for all the time you've put into making this feasible!! 🙌

• The admonitions, like you mentioned, including things like <details>, look very bright for the theme. When stacked with other elements (code blocks or admonitions nested in <details>) I think this becomes more apparent.

• The badge buttons also look very bright:

• The Algolia search seems to use a different default dark mode, but I don't think this necessarily needs to be updated in a V1 push.

I'm not sure how important any of these are! Nothing looks dramatic, everything seems to be functioning on the pages I'm reviewing in the areas you've asked us to take a look at. I'm stoked for this to be possible!

[mesellings]

Approving my own work, but would benefit from other eyes 👀

[conceptualshark]

I think this is looking great! The areas familiar to me/that I know were less table like the APIs, etc, all seem to be functioning well for me.

My lingering question is on dark mode maintenance moving forward - I know we don't update the css or make new components too terribly often, but when we do, how can we be certain that dark mode is included in the review? I happen to be reviewing this and the Connectors PR simultaneously, and the new (and very cool!!) table there prompted me - if folks make similar PRs in the future, we should make sure dark mode doesn't get forgotten in the testing/reviewing process.

Otherwise, this is good to go from me! Thank you for all the work you've done pulling this off!

[akeller]

I forgot this was originally my PR until I went to review it. 🤣

I checked around on a few formatting and image-heavy pages (concepts, best practices, API reference docs) and didn't see anything I would call a bug or experience issue, so I have very limited feedback on those aspects.

‼️ I do have questions around branding, but mostly because I haven't looked closely at the brand colors and combinations. So the blue text on a black background, can we do that extensively? I'm not sure, but maybe you (@mesellings) already connected with the brand team or their assets to make an informed decision about this. I always want to stay on the good side of the brand police, so I would view this as a blocker.

The main page is super dark, so the contrast between the top nav and the footer is almost negligible on my monitor. It makes things challenging to see (Ask AI widget is black on black, as is the version drop down). This is probably ok for a first increment, but for a11y we'll likely need to refine this a bit.

Nit picks:

• The main page boxes "hop" when I toggle light & dark
• The BPMN coverage page is difficult to look at with green on white (but this has nothing to do with dark mode, it's like this in both modes)

[mesellings]

Thanks for the great review @akeller 🚀 Issues addressed as follows:

‼️ I do have questions around branding, but mostly because I haven't looked closely at the brand colors and combinations. So the blue text on a black background, can we do that extensively? I'm not sure, but maybe you (@mesellings) already connected with the brand team or their assets to make an informed decision about this. I always want to stay on the good side of the brand police, so I would view this as a blocker.

The blue text colour is the same pattern used in the product for dark mode, so I think this is the way to go, is more accessible-safe, and aligns with brand guidelines 👍

The main page is super dark, so the contrast between the top nav and the footer is almost negligible on my monitor. It makes things challenging to see (Ask AI widget is black on black, as is the version drop down). This is probably ok for a first increment, but for a11y we'll likely need to refine this a bit.

Agreed - I've re-aligned with the product dark mode, so we use the same colours (I'm sure this changed since I did it) so less dark, footer and navbar have a bottom-border (as per the product), and I've added a border for the Kapa widget so it stands out more. Great comments, improves the dark mode definitely!

• The main page boxes "hop" when I toggle light & dark

This is by design - in dark mode there is too much space here once the colour separation is removed, so I take out some padding otherwise the elements get orphaned.

• The BPMN coverage page is difficult to look at with green on white (but this has nothing to do with dark mode, it's like this in both modes)

Something to look at in general on that page, I think we can probably do something better with the page elements, regardless of dark mode?

Thanks for these suggestions etc, the changes make the dark mode much better I think - valuable feedback! 👍 🚀

[akeller]

Approved (but it's my PR originally, so I can't outright approve) ✅

[mesellings]

Approved

[pepopowitz]

Apologies for the late review, nothing blocking.

[pepopowitz]

@pepopowitz Let me know if this has any impaact on your docusaurus 3 migration?

@mesellings I don't think so, but even if it does, don't wait for me. I'm weeks out from merging that.

[mesellings]

Approved

[github-actions]

The preview environment relating to the commit 46cf1f9 has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4510/index.html