A demo for every thing

2 Jun 2015 · by David DeSandro

I'm going gangbusters with demos. For every option, method, and idea within a Metafizzy library, expect a demo — both in the docs and on CodePen.

UI design deals with visuals and behaviors — things that are difficult to describe in words. A demo is the best way to communicate these concepts.

Creating a demo for every concept is tedious. But each one serves as a focused showcase for an individual behavior. Take for example this demo, which is for Flickity's contain feature.

See the Pen Flickity - contain by David DeSandro (@desandro) on CodePen.

The demo itself is unimpressive, but it clearly shows how the feature works.


Demos enable "hands on" learning. They are playpens that already have some building blocks stacked up. Users can try adding their own blocks, or knocking them all over. By giving the tools to the users, they can investigate and understand it for themselves.

My favorite benefit is how demo coverage aids issues. Since implementing the demos in Masonry and Isotope a year ago, I've found that fewer issues are submitted on GitHub. Masonry has 8,000 GitHub stars, hundreds of daily npm downloads, but less than 20 open issues.

When an issue does get submitted, it's more likely to have a reduced test case with it. Users have to do less work to create reduced test cases — just fork the CodePen. I feel more justified asking for reduced test cases. Can't bother forking a CodePen? Then it's not a real issue.

Demos are the critical thinking tool for front-end developers. They are how developers learn ideas, and how developers verify ideas. By covering your documentation with demos, you better enable your users to understand your product and better enable yourself to defend your own time.