refactor: Adjust styling of back top top button

[dsmmcken]

Motivation

1. The new back to top button is in the same location as is common for live chat/help widgets, and there is no easy way to fix that without swizzling the "unsafe" component. This PR exposes position as css variables, so it's easy to shift the button to the side or above any other bottom right content.
   

2. Subjective opinion: it is too visually prominent, I propose switching it from color-primary to color-secondary. The entry animation, plus the use of color-primary really draws your attention to it on entrance. It is a minor convenience feature, and should not act as a distraction from reading content.

Additionally:

• it was missing an ARIA label, no indication of what this button was for a screen reader
• It lacked full themability:
  • icon should be in css to allow customization, removed svg, can re-use an existing icon even.
  • color shouldn't introduce a hardcode value, should use existing variable
  • buttons use color-dark for hover state rather than opacity, should match styling
  • should use box-shadow infima variable rather than custom shadow
  • posistion should be user themeable.

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

Button as now rendered in default theme

I am unsure whether I did the change to base.json correctly. Couldn't figure out what the convention for naming them or if there was any logic to order, hope this was right. I just added it to the end.

Related PRs

#5419

[Josh-Cena]

Back to top button should actually be safe to swizzle, it's just because the whitelist hasn't been updated for long🤦‍♂️ cf #5263

[netlify]

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: 1ac9a36

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/613c8395c067430009572630

😎 Browse the preview: https://deploy-preview-5469--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	80
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5469--docusaurus-2.netlify.app/

[slorber]

I'll be on holiday soon, but @lex111 can probably review this PR

Some quick thought

• we should mark it safe to swizzle
• we should add a stable className (ThemeClassNames) file so that it's easy to target with custom CSS
• adding new CSS vars would become useless
• didn't we remove this aria-label on purpose @lex111 ?

[dsmmcken]

• we should add a stable className (ThemeClassNames) file so that it's easy to target with custom CSS

That would be great, I haven't seen that adopted yet, what are the naming conventions?

• didn't we remove this aria-label on purpose @lex111 ?

Title was removed, but it really should have an aria-label still for a11y, otherwise this button is a complete mystery as to what it does.

[lex111]

Thanks for PR, but at the moment in custom CSS it is not possible to override CSS vars without using !important rule. Actually, I would prefer to use stable CSS class name instead of having bunch of CSS vars if users want to change default button style. aria-label is a really useful thing for a11y. Not sure about changing of background button , I'll have to think about that.

[dsmmcken]

Oh interesting, I assumed because I can override --ifm variables, I could override --docusaurus variables. That seems like something I should be able to do. I see the inclusion order is different. Is there any ticket to improve this?

re: css vars vs stable class names. I would consider maintaining both. Having stuff pulled out as css variables make it easier for handling light/dark mode overrides, and it also kind of act as guide rails to users doing theming. It makes it clear, here are things you might need to customize, but if you need to do more than override the css directly.

Guidance for adding a stable class name? docusaurus-button-back-to-top?

[lex111]

Yes, we have dedicated issue to track this #3678

Most likely minority of users will customize back-to-top button, so I don't want to add even more CSS vars (we have so many not very used ones already). So stable CSS class name seems like good compromise. This can be confusing, so we probably need to document more about CSS customization later.

For now suggest adding new class name here, such as theme-back-to-top. https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts#L35

About background, think you're right, at the moment the button is too noticeable. So we can use gray shade, by analogy with button-secondary button.

[lex111]

@dsmmcken please let me know if you cannot finish this PR, then I will do it myself.

[dsmmcken]

@lex111 Was away for the long weekend, I can update it now that I am back.

[dsmmcken]

Ready for re-review :

• dropped the root styles
• added a stable class name
• changed hover to use media queries detecting hover support, to address mobile issue from fix: various fixes back-to-top button #5419. Previous fix would make hover state not apply on desktop after the first click, while still focused. https://css-tricks.com/solving-sticky-hover-states-with-media-hover-hover/
• added missing active state

[lex111]

Perhaps we need to add dark mode support also?

Current state:

[lex111]

@dsmmcken thanks!

[slorber]

FYI this description change has a typo and will be overridden anyway, as it's extracted from the code