If you want to check the code directly, be my guest. Also, maybe a demo?
At Edenspiekermann, we like to work with styleguides. We shape our design experiences in a matter of modules that we then expose individually in a document for future reference and documentation.
However, our technical setup is different from project to project, and while we have done some pretty decent styleguide with React and a solid Node.js structure… it’s sometimes slightly trickier when working on Rails or Middleman / Jekyll projects.
The problem with styleguides
The usual problem with living styleguides is that components get displayed in a context that is different from the one they normally live in. And by “context”, I am actually talking about media queries.
Consider this: you have a footer component that is usually full bleed, with some different styling below 1000 pixels. You display it in your styleguide in a 900 pixels wide column. It visually breaks. Why? Because media queries did not fire as your screen is still 1200+ pixels or whatever.
What’s the solution?
Element queries. Unfortunately, they do not exist natively just yet and while there are a lot of clever polyfills out there, they usually come with large costs (performance, JS dependency, etc.). So we keep building our components with tweaks based on screen sizes through media queries.
Now regarding this styleguide display problem, the solution is to render the element inside an iframe. An iframe being an inner document, media queries fire based on the width of the iframe rather than on the actual screen size. Which is what we want. Yay!
However, it means rendering each component individually in its own page and setting the URL of these pages as src attribute on iframes. Works, but that can be tedious to create a page for each component. Could even be unpractical in some cases. Surely there is a way?
Automating iframe generation
I was curious about this specific issue and came up with a solution. Let me present iframify. It is a tiny script that replaces a node with an iframe version of itself, and imports all its necessary styles to perform correctly.
To do so, it relies on the srcdoc attribute on iframe which happens to have a very decent support, or a local data encoded URL as a source when not supported.
It gathers all the styles needed by the node and all its children by parsing the stylesheets and trying styles against the elements to import everything inside the generated iframe.
See the Pen vGWpyr by Kitty Giraudel (@KittyGiraudel) on CodePen.
What’s next?
This is a nice and handy solution but it still lacks a few things. The first being font-face declarations. Right now, only styles used by the component are being imported, but fonts are not. That would be one (not too hard) thing to do.
Also, no JavaScript is being imported at all. We could design a solution to import specific JavaScript code, but right now it did not seem necessary. Living styleguide usually are about visual regression and documentation, and the current problem was really about breakpoints and media queries so JS is kind of out of the scope.
And of course, anything you can think of to improve the beast. Happy coding!