At Neo, we work in small cross-functional team to explore and iterate on ideas quickly. We also have longer-term engagements and build and scale web applications and their user-facing interfaces.  It is in the scaling - the long-term trajectory - the anti bit-rot - the anti entropic view of software. We've had the opportunity to work on a project that will become open-source. And not just open source as a token gesture, but the project has aspired to open-source. Part of its vision is to engage the scientific, academic, and open software communities to extend functionality that lives at the core of the user experience, but lives at the edge of the software ecosystem. We are very interested in ensuring the developer experience is  Technically, the software is loosely-coupled. Inversion of control is the design pattern that comes to mind. Exposing access to the guts of Tahi, the academic publishing platform, enables institutions to create the small, custom, glue-like functions, behaviors, and integrations. Integrations are inevitably required when implementing a publishing system. Review, Editing, Communication, Analytics, Analysis, or Billing. Requirements The Style Guide is as close to the real code as possible Easy to update Shows multiple states of UI behavior Shows the results of dynamic markup (.sass, .erb, .handlebars, .js) Shows the markup needed to produce a section of UI Easy for Designers and Developers to use Works across languages and environments

Ways to do it

Do it up front: Define elements. Vet them. Choose from them to build Pages. Do it after-the-fact: Inventory elements. Vet them. Consistent-ify them. Choose from them to build pages. :: INSERT WORKFLOW DIAGRAMS HERE ::

Experiments KSS Strengths - it exists. It iterates over a set of annotated comments in a CSS file. Special .erb Ruby blocks of code can then reference those annotations in order to exercise a particular piece of CSS. Benefits: Some amount of automation. Drawbacks: doesn't capture any behavior. Doesn't test Components. Requires a lot of duplication of markup. Auto Screenshot & Tahi UX & Custom Stuff

Declare your Style Guide using HTML Write a Harvest file that basically works like your Ruby specs. It visits pages and triggers specific states. The Harvest file saves named versions of .png and .html pages. 

Hydration File: Reads the Declaration file and populates a new version of the Style Guide based on the markup and images harvested.

What is the intention of a Styleguide? To ensure consistency in style. To provide a set of intermediary tools to build from.

At least 2 Ways to Keep an Updated Styleguide Design into the Styleguide first, then implement UI from the Styleguide into the App. Ensure the Styleguide is updated on an ongoing basis, for example, on every commit to the codebase - this is an after the fact solution

How does a Styleguide fit into our Practice? How should it?

Design to Build

There is a difference between designing to design, and designing to build. Designing to build acknowledges the realities - the limitations and constraints of project resources and building medium.