dokka
dokka copied to clipboard
Spike: decompose `styles.css`
styles.css
has 1.5k lines, which is a problem for two reasons:
- It's not convenient for us internally, so the developer experience could be improved if it's broken down into smaller components.
- We allow users to override
styles.css
with their own file, which leads to copy-paste, oudated styles and difficulty with maintaining backward compatibility.
As part of stabilizing Dokka's HTML format, we want to revisit the customization of Dokka's stylesheets, which also consists of two steps:
- Figure out what Dokka's users want to customize most often, what are the user stories here.
- Implement it technically (most likely as providing separate
.css
files for each customizable component)
This spike exists to help figure out the details/requirements of the second step, to understand what is possible, how long it would take to implement (in case new classes need to be added or the styles need to be refactored).
It should also help figure out how to approach the decomposition of styles.css
for internal use, i.e which separate .css
files we need and make sense internally. These files could be for our convenience only, so we could take these internal stylesheets and compile them into a single large styles.css
upon release.
Goals
- Come up with a proposal on how to decompose
styles.css
:- Which styles could be extracted into separate files for our internal use and convenience
- Which styles are possible to extract for user customization (theme-colors, different parts of pages, etc)
- Try to estimate the scope of changes (in terms of small/medium/large) and very approximate time estimate (in terms of a couple of days / a week / a month).
Non-Goals
The actual implementation of the decomposition is outside the scope of this issue, as it might take significant time to implement and test it. For now we just need to try to turn known unknowns into known knowns.