Docs site styling improvements

[mesellings]

Description

This PR contains styling improvements to fix the following user problem.

As a user of the docs site, I am experiencing friction due to the following issues:

• Headings and white space: Pages are too busy (cognitive overload, reduced readability), with little visual separation between headings, sections, and content such as tables, lists, and images.
• Some elements have unusual padding (badges are slightly indented for some reason) which looks unfinished.
• The font is different to the Camunda font (IBM Plex Sans) and looks outdated.
• I find tabs in a page hard to distinguish (@conceptualshark).
• There is too much bold across the site - it looks dated and causes cognitive issues.
• Images have a drop shadow and big border, this looks dated.

The fixes include:

• New heading styles for readability.
• improved content spacing for readability and to reduce cognitive overload/wall of text issues.
• Modern border/padding style for images.
• Site uses Camunda IBM Plex Sans font.
• Tabs have a slight background to help visually.
• Badge padding improved.
• Menu font changed so not all bold, and menu categories collapse.

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]

@camunda/tech-writers I have created this POC PR for the docs site styling - just some quick changes that should hopefully greatly improve the site and UX. We can discuss this in our next team meeting, but feel free to look through the preview site and make any suggestions etc.

Note: Don't get hung up on the CSS implementation - this was just a quick and dirty fix to get feedback on the styling - if we are happy with the changes, I'll implement the CSS properly.

[akeller]

Most of this feedback is personal opinions and just not having the bandwidth to fight Docusaurus and existing styles back when it was just me and @christinaausley 🥲. Thank you for caring and moving this forward! 🙌

• There is a lot of blue, which doesn't match the blue links on the website. I find the current blue-on-white hard to read. To me, the blue comes across as too bright.
  • We also have quite a few links on some pages, which make the content very blue. We discussed this internally at one point, but I don't remember who was involved. We ultimately concluded that .com and .io could deviate in styling choices because their audiences and/or purposes differed.
• Previously, I fielded A LOT of feedback on image styling, including the shadow. Ultimately, I don't care. I want a clear image that is up-to-date. You may want to pull in more reviewers via ask-c8-documentation.
• Underlining the title on pages in C7 docs vs. H2 in C8 docs. Doesn't matter to me, but we previously intentionally matched the styles in the C7 docs.

To your point, if it improves the accessibility and provides a more modern look and feel, let's do it.

That said, I support you on these changes. 👍

[mesellings]

Most of this feedback is personal opinions and just not having the bandwidth to fight Docusaurus and existing styles back when it was just me and @christinaausley 🥲. Thank you for caring and moving this forward! 🙌

• There is a lot of blue, which doesn't match the blue links on the website. I find the current blue-on-white hard to read. To me, the blue comes across as too bright.

  • We also have quite a few links on some pages, which make the content very blue. We discussed this internally at one point, but I don't remember who was involved. We ultimately concluded that .com and .io could deviate in styling choices because their audiences and/or purposes differed.

• Previously, I fielded A LOT of feedback on image styling, including the shadow. Ultimately, I don't care. I want a clear image that is up-to-date. You may want to pull in more reviewers via ask-c8-documentation.

• Underlining the title on pages in C7 docs vs. H2 in C8 docs. Doesn't matter to me, but we previously intentionally matched the styles in the C7 docs.

To your point, if it improves the accessibility and provides a more modern look and feel, let's do it.

That said, I support you on these changes. 👍

Great feedback thank you - I agree on the blue, that is actually the blue from the product itself (trying to make it more seamless from product > docs, i.e. link patterns are the same) but I agree the blue is a bit bright with so many page links, so for now I'll revert back to the orange which is more subtle, and we can investigate the link colours in another iteration 👍

[christinaausley]

This looks great! 🥳

[mesellings]

Removing from 8.6 release, but can release during the week of the release 👍

[mesellings]

@pepopowitz Please re-review, I have fixed all those issues/edge cases I think - especially badge behaviour/padding etc on pages such as the release notes, and also styles within the API ref docs 🤞

Note: there is no urgency here 👍

[mesellings]

@pepopowitz I can still see differences in styling between locally run & the preview environment, so I'm going to do some more work on the APi ref styles 🙄

[pepopowitz]

One new thing I noticed, which I'm not sure of the cause --

The API endpoint path at the top of the API pages has some sort of alignment problem:

versus what it looks like in production currently:

[pepopowitz]

Oops, I forgot to add my previous few comments as part of this review....but there are still a few wonky bits.

[mesellings]

Thanks @pepopowitz, great feedback as always - I am sure that these last snags are now fixed.

NB: Just FYI the only one that is slightly annoying is the API ref endpoint padding one which I have to refresh on the preview site to see the 'correct' new version - try it in an incognito browser or refresh the page and it works correctly first time, so think this might just be a caching issue. Anyway, these are how the fixes appear in the preview site.

Underlines in API specs are correct

(including removal of H2 line for GET endpoints that do not have any request body content)

Badges vertically aligned to middle

Hopefully one last review please!

p.s. On another note, I have tested in Firefox and all looks good, although in Firefox I noticed an existing issue with the API ref statuses which uses the tabs classes (not fixed with these changes). We could look at this at a future date, just putting it here for now:

[mesellings]

Also to note, some of the guides (e.g. https://docs.camunda.io/docs/guides/orchestrate-human-tasks/) have hard-coded
tags in to add padding below the badges - a next step after the changes would be to quickly remove those, so the padding is applied globally via the CSS as it should be, rather than with custom elements/padding in the page.

[pepopowitz]

Thanks for the updates!

There is one minor thing that I noticed -- bottom borders on some tab-buttons on the API explorers (see screenshot below).

I leave it up to you whether you want to fix them in this PR or in a follow-up, I don't personally feel strongly.

[github-actions]

🧹 Preview environment for this PR has been torn down.

[mesellings]

Thanks @pepopowitz I'll create a follow-up PR to pick this up and any other issues that might crop up once it's merged into production 👍

[mesellings]

Notified in ask-c8-documentation channel:

[mesellings]

Thanks for the updates!

There is one minor thing that I noticed -- bottom borders on some tab-buttons on the API explorers (see screenshot below).

I leave it up to you whether you want to fix them in this PR or in a follow-up, I don't personally feel strongly.

Fixed in #4456