GitLab UI components demos: Reduce style inconsistencies between Storybook and design.gitlab.com
What problems are we trying to solve here?
.md
styles leaking into GitLab UI components demos
1. design.gitlab.com
has a set of typography CSS rules being applied on several common HTML elements in the .md
scope: https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/5f1e9246192f9f04dcd50cefa55985d63c0f88ce/assets/stylesheets/framework/_typography.scss#L35-81
This has been causing issues with components demos as they are being displayed into the same scope, resulting in some components inheriting unexpected CSS rules, an example is the GlBanner
component: !1620 (comment 245401786)
This has led us to explicitly setting more and more CSS rules in components stylesheets, solely to override .md
styles. We have tried to circumvent this specific issue by wrapping components in a custom element where GitLab UI styles would be injected in the Shadow DOM. While this solution was promising as it stopped all CSS leak issues, some components like tooltips and popovers aren't Shadow DOM-ready and aren't able to render when they don't have access to the global document
. More generally, this approach brought us back to problem #2
.
2. Styling elements in the global scope
To prevent GitLab UI's styles from conflicting with design.gitlab.com
's styles, we have scoped its styles to the .app-styles
class: https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/5f1e9246192f9f04dcd50cefa55985d63c0f88ce/assets/stylesheets/app.scss#L33-36
This lets us apply components styles locally, without affecting the rest of the website.
This is a sensible approach but we've reached its limits as some components are appending elements to the body
in the global scope. Since those elements are escaping the .app-styles
scope, they can't be styled properly, unless we can come up with specific workarounds. For example, we've been able to preserve styles for the GlModal
component by adding the .app-styles
class to its wrapper element: https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/5f1e9246192f9f04dcd50cefa55985d63c0f88ce/layouts/default.vue#L103-114
There are other cases, like the GlToast
component, where there is no obvious workaround that we can apply, resulting in a broken looking element in the demo:
Overall, we should try to make it as easy as possible to include components demos in design.gitlab.com
. Having to come up with workarounds makes for a poor developer experience.
How can we address these issues?
.md
styles from leaking too deep in the DOM
1. Prevent To prevent .md
styles from affecting too many of their children, let's make sure that the CSS rules only apply to direct children in .md
. This will prevent the CSS from leaking into component demos, reducing the need for explicitly setting CSS rules in GitLab UI to override Pajamas' styles.
This approach has a downside: Markdown elements can be nested. For example: > ### A title in a blockquote
. By applying styles on direct children only, those nested elements will not be styled properly. Since Pajamas doesn't seem to contain any nested Markdown element at the moment, this fix should be acceptable considering its benefits outweigh its disadvantages.
MR: !1753 (merged)
2. Apply GitLab UI styles globally
TBD
MR: !1740 (closed)