Feature Request - Add CSS classes for styling

[jdahdah]

Right now I'm finding it very difficult to style the portal. Styled Components are great and I love to use them for all of my own projects, but at the same this is a portal that is meant to be customized, often according to corporate design rules. The generated class names make it impossible to target specific elements of a page.

Example:

I need to add a simple left-hand border to the right-hand TOC menu. That's impossible right now because in the entire hierarchy there is no class to target it. I can't use aside.sc-bRubDb because obviously this can change. I could try to add a nested child selector (starting from body) to target it, but this can easily break if anything in the main structure happens to change in an update. It's also not possible to override the TOC component via the _overrides directory because it's not a UserComponent, and even if it were, the portal components are not open source (at least I can't find the original source anywhere apart from a few PR examples), and I would be stuck to reading the compiled and minified React.createElement code in node_modules/@redocly/developer-portal/dist/engines/src and painstakingly reinterpreting that as JSX to make sure it retains the identical behavior, just to add a few styles to it. I already had to do this this with the NavBar component because I had to add dropdown menus. It took a while to understand that your PRs are code examples because it's far from obvious and I haven't seen them mentioned anywhere in your documentation, and they of course don't match the original components 1:1.

It would be really helpful if you could add CSS classes to all of your components as hooks for styling. I would save myself hours of work if I could just add a global style such as .toc { border-left: 1px solid grey; } instead of going through the process above.

[RomanHotsiy]

Hi, @jdahdah this is a know issue we feel your pain 🙈. We are actively working on it.

I'll post a detailed write up about our roadmap on it later this week.

[jdahdah]

@RomanHotsiy Thank you for acknowledging this issue. I'm looking forward to learning about your roadmap.

[RomanHotsiy]

Hi @jdahdah,

Finally found some time to provide more details here.

First of all, we don't want to add HTML classes as it will limit our ability to change/update product without breaking changes. With CSS classes almost every layout change becomes a breaking change and we still have a lot of different features on our roadmap which will require those changes.

We 100% agree the current them is very complicated to use. There are 2 main issues:

1. no way to know what some specific variable controls
2. no way to know which variable controls some specific aspect

We think we can solve 2) while keep our ability to evolve the product.

Our idea is to convert our theme to css-variables based one. In such case you can right-click on any element on the page, inspect it and immediately understand how to adjust it. You can even adjust variable value directly in dev tools to see the impact.

We hope this will improve styling dramatically. Also, we'll provide a bunch of example themes.

This project is in progress right now but we plan to release it publicly only in Q3.

[jdahdah]

@RomanHotsiy Thank you for your thoughts on this. Implementing CSS variables is certainly a good first step for a better developer experience. I don't see how they would solve the issues I outlined above, however? You are moving the existing SC theme variables into the browser, but this does not add any new ways to style parts of the interface that can't be reached at the moment, like adding that border to the ToC. The point is to have a few general css classes so that we can have more reliable control over parts of the portal design that weren't considered by the portal developers. It's clear that this can introduce breaking changes (and you can add that disclaimer to your docs), but having something like .toc { border-left: 1px solid grey; } is still an order of magnitude more reliable than writing CSS selectors that traverse the entire DOM down from <body> just so we can grab the right <div> to add a border to.

[RomanHotsiy]

Oh, I forgot to mention that we're building theming solution which will allow you to "eject" any component. You can then either add class to it or modify its styles directly.

The work is in progress. We don't have any specific details to share yet.

[jdahdah]

@RomanHotsiy Ah, that sounds more like it, thank you for clarifying.

[mDuo13]

For what it's worth, I also would rather have meaningful HTML classes so that I can re-style elements, even if it means that our customization are "brittle" when it comes to breaking updates. There are a lot of customizations that would be trivial to implement if elements had proper HTML classes instead of inline styles. For example, it's difficult to impossible to implement a client-side light/dark theme toggle with things the way they are, but HTML classes would make it very straightforward. Similarly, there are plenty of other powerful customizations one could do with CSS that are difficult to apply when things have only procedurally-generated class names.

[dredlong]

Hi @RomanHotsiy are you able to provide any updates on this issue? Currently also trying to fit a Redocly portal into brand style and coming up against the same challenges that @jdahdah flagged. Even setting the font for the TOC panel is proving difficult.