Thanks for sharing, Jon!
Jotting down some of the thoughts and questions I have after reading this—
I think right now the components in our styleguide are very small, for example just a button or an input field. We'll start facing the same issues as Lonely Planet as we move to more complex components. The approach they are taking is similar to Web Components (yay web components!) and I guess we'll be doing the same with OOUI.
Would it make sense to have empty CSS/SCSS files that are just for the documentation strings of OOUI elements? These could be generated from JSDoc comments in the OOUI widget itself. No matter the process, it would be nice if the documentation for the OOUI widgets could be generated directly from their JS source and put in the styleguide that we currently have.
But the styleguide will only show the components in Agora styling whereas those components are CSS agnostic. Would the components need to have separate documentation too? One with an option to see them with different skins?
—prtksxna