Nothing enhances written content quite like a well-crafted demo, or collection of demos. They don’t have to be complex either — in fact, it’s better if they’re not complex. The most important thing is that good quality demos can help people really get what you’re trying to explain, especially if reading isn’t the most effective way for them to learn.
It’s easier than you think
You might be thinking that “I don’t have time to implement a whole demo system”, or “I’m a developer so can’t make demos look good”. The good news is both of those are easily solved.
CodePen is a fantastic resource for producing demos. In its simplest form, it’s a “pen” that has 3 panels: HTML, CSS and JavaScript. All of those get smooshed together on the fly. CodePen is also completely free (although we recommend getting a Pro subscription).
FYI
A “pen” is what you call a CodePen file. It’s a collection of HTML, CSS and JavaScript. You can read more about them here. Now you know what we mean whenever we say “pen” throughout the rest of the article.
Our favourite part of using CodePen for demos is how customisable the embeds are. You can show the result on its own or just the CSS and result for example. You can theme them to integrate better with your site, too. You can even go one step further and show a completely frameless demo. That’s how we do it on this site, when all we want to show is the result.
The best feature of CodePen though, is you can use other pens as CSS or JavaScript files in your demo. This is how we have produced a base styles system in the past, like the demos for Learn CSS for Google’s web.dev.
First, you create the base styles pen. We also added example components for people to be able to copy and paste.
Then, for each demo, we took the URL of this base pen, appended .css to it, then imported that in each demo like so.
The Learn CSS course has hundreds of demos, so if we ever needed to make adjustments, we’d only have to update one pen. Handy! CodePen has a great guide for that.
In terms of making your demos look great, a very quick and easy way for beginners to at least make demos look consistent and reasonably polished is reach for a framework like Tailwind CSS or Open Props. Open Props is probably your best bet for writing CSS and if you don’t want the hassle of a build process. Tailwind is probably better if you haven’t got much CSS experience and you need something to look decent out of the box.
The next step up from that approach is to spend some time designing and building a styles system that acts as a base for your demos. We do that for all demos on this site and as mentioned earlier, have done that for clients too. What this approach enables is all repetitive legwork is done, so all you need to do is import that and spend the whole time focussing on creating a perfect demo for your article instead.
This demo is from our article, Relative rounded corners and pulls colours and type styles from a specific pen. We use that pen as the base for other demos and will use it for future demos too. If we redesign our site in the future, we can update one pen and everything will update automatically.
Another approach — which is especially useful if you don’t have internal capabilities and you don’t want to be limited to basic looking frameworks — is to commission designers to produce demos for you. This option is probably limited to companies, but you’ll probably find the process of commissioning designers or design teams to produce stunning demos is more efficient and importantly, cheaper than struggling internally. Especially as really good demos can expand both the quality of your articles and shareability of them too.
Where we’d love to see better demos
The main place we’d love to see better demos is MDN. MDN is the canonical resource for web platform documentation and often, MDN resources rank really high in Google searches.
The written content on MDN is excellent because they hire the best in the business to write it. The problem, though, is the demos are often really basic, inconsistent and underwhelming. This is especially the case in contexts like animation, where it’s imperative to not just show the CSS properties, but also inspire people to use CSS for excellent animation too.
Another crucial point is that everyone learns differently. Some people can read documentation and get it straight away. A lot of people though, are visual learners and seeing something in action helps them get it. Sure, MDN do create visual examples, but maybe showing some real-world, polished examples would help people understand how certain technology can help them improve the real-world work they’re working on.
We think high quality demos would enhance the quality of the already excellent documentation and help people really understand the fast-paced HTML, CSS and JavaScript landscapes. Even having a base styles system for demos on MDN would completely transform them for the better!
Speaking of which, we’d love to see web.dev roll out their consistent styles system from Learn CSS across all demos on the site. Their content is fantastic — especially their free courses. Unfortunately, the demos in those can look a bit slap-dash in places and again, using the existing base styles would enhance those demos immediately. We’d love to see that happen in the future.
People who are doing a good job of demos
It tends to be individuals rather than companies that do a great job of demos which should, we hope, inspire some companies to fill that void by producing or commissioning demos that blow their competition out of the water. Here are some of our favourite people.
Cassie Evans
Cassie is one of the best educators out there, helping people learn web animation. Their articles are always great because they break down tricky-looking animation concepts into easy to digest content.
Cassie has also gone for the pro level by deeply integrating her animations into her articles.
Good example: https://www.cassie.codes/posts/swipey-image-grids/
Josh W Comeau
Josh’s articles are always top-drawer, but what is truly exceptional is their attention to detail with demos. Again, like Cassie, Josh breaks down difficult concepts into digestible pieces. They also deeply integrate demos with their own bespoke system too.
Good example: https://www.joshwcomeau.com/css/interactive-guide-to-flexbox/
Ahmad Shadeed
Demos don’t have to be code-based either. Ahmad demonstrates that really well in his writing, by producing really smart diagrams. They also use real-world contexts for demos in articles, which is really useful. Especially for beginners.
Good example: https://ishadeed.com/article/defensive-css/
Amelia Wattenberger
Amelia blows everyone out of the water with her highly specific demos. She makes the whole article a demo! This is especially useful in her legendary “The CSS Cascade” article, as they take arguably the hardest thing to learn in CSS and make it really approachable and understandable.
Check out The CSS Cascade.
Wrapping up
Hopefully, this has inspired you to up your demo game if you haven’t already. Most importantly, we hope that we have shown you that although the best examples are highly customised, you can produce good demos for free and rather easily.
If you want to take your demos to the next level, we’d also more than happily help you out too, just like we have for clients in the past! Just give us a shout.
Hey there, we are Set Studio.
We’re a small but nimble, distributed design and development studio
The web is truly global, so our rare combination of highly technical and highly creative designers produce stunning websites that work for everyone.
