Skip to content

Integrate Slippers blog layout component

Why is this change being made?

Closes https://gitlab.com/gitlab-com/marketing/inbound-marketing/growth/-/issues/1085, specifically checks off:

Middleman integration of wrapper component

Integrates the work done in the blog layout component MR in Slippers UI.

Also closes https://gitlab.com/gitlab-com/marketing/inbound-marketing/growth/-/issues/1134#note_527410485 by isolating Slippers and about.gitlab.com styles from one another.

  1. Bump slippers-ui to version 0.7.0
  2. Changes sites/marketing/source/includes/cms/blog_post/slippers-blog-post.erb to use the wrapper layout from Slippers UI MR
  3. Changes sites/marketing/source/slippers/posts/2021-03-04-slippers-test.html.md.erb to use the markdown content from the Markdown Guide in the Handbook, which demonstrates how the styles work with all possible kramdown generated markup.
  4. Adds source/javascripts/slippers-blog.js, which uses web components APIs to isolate the Slippers and about.gitlab.com styles from one another.

Manual QA

Compare these pages:

  1. Figma design for as-is blocks
  2. Slippers Storybook implementation of as-is blog styles
  3. GitLab Handbook Markdown Guide
  4. Check out this branch, yarn install, and start the Middleman server. Then visit localhost:4567/blog/slippers/slippers-test/

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:

  1. Do nothing: As we started on the integration, I wanted to see if the styles would Just Work. They didn't, that's reasonable.
  2. disable_default_styles: @laurenbarker and I started with disable_default_styles set to 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.
  3. 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.
  4. 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.
  5. resolve conflicts manually: @jgarc did this for some early iterations of the button components by using initial in the slippers stylesheet. @laurenbarker and I tried this but the conflicts became overwhelming and were hard to manage.
  6. 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.

Author Checklist

  • 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
Edited by Tyler Williams

Merge request reports