Why is this change being made?
Closes gitlab-com/marketing/inbound-marketing/growth#1085 (closed), specifically checks off:
Middleman integration of wrapper component
Integrates the work done in the blog layout component MR in Slippers UI.
Also closes gitlab-com/marketing/inbound-marketing/growth#1134 (comment 527410485) by isolating Slippers and about.gitlab.com styles from one another.
sites/marketing/source/includes/cms/blog_post/slippers-blog-post.erbto use the wrapper layout from Slippers UI MR
sites/marketing/source/slippers/posts/2021-03-04-slippers-test.html.md.erbto use the markdown content from the Markdown Guide in the Handbook, which demonstrates how the styles work with all possible kramdown generated markup.
Compare these pages:
- Figma design for as-is blocks
- Slippers Storybook implementation of as-is blog styles
- GitLab Handbook Markdown Guide
- Check out this branch,
yarn install, and start the Middleman server. Then visit
All four of these styles should look fairly similar when comparing the specified "as is" blocks from the design. There are still a few discrepancies, but overall I think this is in a good state for a first iteration.
Solving CSS Conflicts with Web Components
This is my proposal for how we resolve CSS conflicts between Slippers and about.gitlab.com. I tried a few different options between yesterday and today and this felt like the most robust solution. Here's what I tried:
- Do nothing: As we started on the integration, I wanted to see if the styles would Just Work. They didn't, that's reasonable.
disable_default_styles: @laurenbarker and I started with
true, but quickly realized that wouldn't work since we needed the styles for the header and footer, and it would be nice to pull in existing about.gitlab.com styles for other elements we didn't have covered.
- increase specificity for Slippers: @jgarc had a great find with the Tailwind configuration options for important and selector strategies. This resolved some of the problems, because it fixed places where our existing styles were beating Tailwind utilities, but it didn't do enough to reset or normalize styles we hadn't specified in Slippers. The about.gitlab.com styles were bleeding through and causing problems.
- pull in preflight with slippers-ui: I wanted to see what would happen if we enabled preflight and brought it in. Preflight didn't get the selector strategy/importants, and it also broke existing styles for about.gitlab.com.
resolve conflicts manually: @jgarc did this for some early iterations of the button components by using
initialin the slippers stylesheet. @laurenbarker and I tried this but the conflicts became overwhelming and were hard to manage.
- rebuild everything in Slippers first: we could theoretically start from scratch for everything and rebuild only using Slippers, but that would be cumbersome and add a ton of lead time to every Slippers rebuild we want to do. In an ideal world, we should be able to sprinkle Slippers throughout the existing project. I think this approach makes that available to us.
We can use a shadow DOM to encapsulate CSS entirely. Global styles don't leak in, local styles don't leak out. We can use templates and slots to write semantic HTML in erb or HAML templates as desired, and we can tie it all together with custom elements.
It's a little complex on our end, but the browser support is there, the performance is excellent, and the value we get makes the complexity worth it, in my opinion. We also have fallback options available for the rare cases where web components might fail for a user.
I think this should be a stop-gap measure until Slippers is in a place where we can rebuild pages entirely with it. We can use web components to manage our CSS problems until then, and when pages are ready to be rebuilt entirely, using
template tags means that we don't have to do a ton of converting between the web component and ERB/HAML (in fact, ERB/HAML compiles out to totally valid markup for this, so we don't really lose any of our ruby templating capabilities).
I'll go through the MR and make some specific callouts about what's going on here. I've got the MR in Draft because I still want to add docs about it in
doc/slippers.md if it gets approved.
Provided a concise title for the MR
Added a description to this MR explaining the reasons for the proposed change, per say-why-not-just-what
Assign this change to the correct DRI