documentation update

Besides the formatting nitpicks, I’d mostly want to discuss the following:
* let’s **not** use `[data-icon="name"]` instead of `.icon.icon-name` — I think this has proven to be a bad experience so far;
* could we start documenting the classes we use right now? This is by far my biggest fear about this project: if we use arbitrary classes, let’s make sure they are properly documented and that the chosen names make sense for UX, designers and developers.

So glad to see this v2 happening! :-)