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