Designgineering Chronicles: Swan Song [PiH]

The last installment of the Designgineering Chronicles. The work itself is far from over, but I am very over writing these posts.

This Chronicle, rather than WiH, Written in Haste, us PiH, Published in Haste. This is distinct from WiH in that I have not been writing this in haste at all. This post has been months in the making. I worked on it for around 20 minutes every other day, every other week, for like four months. Definitely not written in haste, but Published in Haste because I have to be done with this and just publish it goddammit otherwise I’ll never get on to the next thing. Which is what? Good question. Anyway…

How do you eat an elephant? One bite at a time.

I learned that phrase from my friend Liz that is somewhat of a mantra for me these days.

I am happy to announce that this Chronicle will (hopefully / probably) be the last. The Swan Song. Wikipedia makes the swan song sound very bleak:

The swan song is a metaphorical phrase for a final gesture, effort, or performance given just before death or retirement.

But I’ll go with it. I am not planning to die or retire, but this series is. As I grow as a developer, my blog post writing interests are diverging from the theme of this series, and a 2020 goal is to do better about keeping job-work at job-work and I would really, really like to lessen the amount of brain space I devote to design systems to make way for some other things.

So, in the usual Chronicle fashion, let’s recap the last installment before diving in.

Where we left off, about eight (?!) months ago

I wrote the last Chronicle at the end of June 2019, and celebrated that our design system at PMC had become almost official. It got a name, Larva – a very unusual name for a design system, and one that differs by only one letter from the name of its creator (me, Lara). That is not a coincidence. Larva was my nickname in high school (and I drove my family’s minivan which my friends called the Larvan). This information came to light during a meeting about the design system – I tried to suggest other names, but my co-workers liked this one. I am very happy to move on to the next thing. Larva it is!

After a somewhat marathon finish of the Deadline project (which was the design system “big bang” project) I had a bit of time for research and development to proactively work on system things before the next project started. I created a backlog in JIRA under the banner “Design Ops” to track this work. That felt official. What felt more official was giving a presentation for one of the executives at PMC to explain the concepts of design systems in general, and Larva in particular. Word was out to the higher ups! This went very well and was very exciting.

I also created a roadmap for Larva that extended through one year. Given that was quite a while ago, I’ll conclude this post with an update according to the roadmap, with some adjustments.

I introduced the next redesign project, code-named Blueberry (just like Deadline was Cantaloupe, see?). Since that site has now launched, and I didn’t end up writing any Chronicles during the project, I can refer to it without a fruit-based code-name:, which also contains a sub-site for Art In America since PMC consolidated them into a single site upon acquiring the brands. This made for a good test of Larva’s capabilities – will it support two different visual styles within a single code-base? Spoiler: yes.

Also in the last Chronicle, I made a big list of pre-ArtNews to-dos, many of which are completed now, however, they ended up happening during the project instead of before it for a variety of reasons, partially changing timelines and partially my learning the lesson that “basically done” does not equate to usable software.

I think that about sums it up. Now, onto more recent updates and concluding commentary.

Where we are now

What happened in nine months? A lot. I’m probably not including all of it here, and that’s fine. But most importantly:

Larva is really, really official.

What is the line that makes a design system “official”? I believe that depends on the design system and the company, but for PMC, I think official means that Larva is in the project requirements for brand redesigns. Shared UI code is also a big indication for us (that is, all of the responsibility and risk that goes along with shared UI code).

Also, two really, really official part: we had a team summit last week, and the CEO did a shout out to Larva! And Larva is mentioned by name is one of our job descriptions for a new Software Engineer.

Perhaps more official than all of those items, is that it is time for me to take a step back from contributions to Larva. I have authored about 98% of the code, and if this is going to last, more people on the engineering team need to contribute.

But…is it a design system?

I mean, yes, absolutely, but…

There is not very much design in our design system; Larva’s performance on this design systems checklist that has made rounds on Twitter, for example, is laughable. We have a little bit of design as far as placing limitations on the amount of colors and font families supported, but Larva is largely the software side of a design system…the design side is still to come.

Larva makes our code-bases consistent and more maintainable, and that was my goal. It is “Front-end Core Tech” at PMC (whereas before, Core Tech was only back-end) – a suite of UI programming patterns and standards that are shared across our portfolio of sites. Maybe “low-level” design system?

I feel that we need more words for design systems. “Design system” means too many things. Or maybe a taxonomy for design systems. That would be an interesting research project.

Feature complete is on the horizon.

While there are still loose ends to tie up here and there, Larva is nearing the end of its alpha phase and will soon be feature complete, a stage towards the end of alpha where everything planned at the onset of the project has been built, but there are still some bugs to work out and tests to be written. After alpha, development moves more slowly. There are less frequent refactors and breaking changes. I am looking forward to that.

Here’s what almost-feature-complete looks like in Larva:

Core packages

I mentioned the phrase “library of UI programming patterns” a bit earlier, and here, exactly, is what I mean by that:

  • CSS library: This contains some core CSS utilities and algorithms, and generic styles.
  • Sass library: Mixins for generating project-level utilities and algorithms based on Sass maps, and core variables for sizing, z-index, and other property values.
  • JS library: This package contains JS patterns for things like a hide/show toggle pattern and a video player. They are used as js-* class selectors and require specific markup structure, usually provided in a specific Twig pattern.
  • Twig patterns: Markup patterns used as building blocks for UI. These do not provide ready-to-go UI by themselves, but can be assembled into UI (modules, below). They are divided into components and objects, and can be thought of as the “primitive patterns”. Each contains a corresponding data object, the “prototype”, that can be configured with data and CSS classes.
  • Modules: These are fully built UI modules (that is, they use HTML, CSS, and JS) that can be extended and customized per theme by overriding the default CSS classes provided by the data object. They are combinations of includes of Twig patterns and structural markup, and their data objects/prototypes are written to JSON files so the same pattern data can be used in PHP.
  • Tokens: Strictly named property values that can be configured per brand, so far font-family and color are the main ones. The output of this package is custom properties, Sass maps, and an HTML style guide generated with Theo. Utility classes are generated that correspond to the naming of the tokens, and assign the a value from custom property. This is a start at getting some actual design in the design system, but given the silo-ed nature of design at PMC and the resources we have, there is currently no way to ensure the designs actually follow these guides, but we can hope they do, and developers can make choices that align with tokens where possible.
  • SVG icon library: A library of SVG icons available as a sprite, and a command for building project-level sprites.
  • Screenshot testing: There is a package containing configuration for Backstop JS that allows for minimal project-level configuration. It allows for screenshot tests of individual modules as well as full URL screenshots. Screenshot testing is finicky, but it has caught bugs. This workflow still needs some work, and it is not automated.
  • Twig to PHP Parser: This package contains an algorithm that takes the contents of Twig templates and outputs WordPress-flavored PHP via some carefully chosen regular expressions. PMC’s sites are hosted on WordPress VIP which does not permit run-time compilation of templates, and therefore does not permit Twig. This package supports a limited amount of Twig syntax which has been a blessing in disguise – it’s kept us from doing any fancy, regrettable things in the templates, and hopefully kept them simple enough to transform into other languages (JSX…).
  • Larva scripts: Using Gutenberg’s scripts package as inspiration, the Larva package provides a binary, larva, that allows us to store configurations and scripts for our asset building, linting, and custom Larva needs in a single package.
  • Larva server: An Express server run locally from a consuming project that provides a sandbox for building patterns, a browse-able listing of all patterns (both shared and project-level patterns), and documentation for patterns that have it.

These tools are intended to serve as a starting point for projects, and as a means of sprinkling in new UI to old sites. They pair with a strict project-level architecture that allows themes to provide functionality not provided by the shared packages. I can confidently say Larva can be used to build anything the design team sends our way without resorting to turd-driven development, as I like to call it in my talk. My ultimate vision was to be able to build new modules in the context of a specific brand, then move the module to the shared code-base, so that it can be available to other brands. We are just about there!

Despite my inner critic’s commentary, Larva has proved itself on two full site redesigns, so far, and a third is underway. The third is being done by an external agency and it hasn’t gone as smoothly as Deadline and ArtNews. Myself and two other PMC engineers have been moved onto the project to finish it up. A next step will be to look carefully at this project.

Big Picture Notes

Big picture conclusions for this iteration of Larva (perhaps the next iteration will be Pupa or Chrysalis).

Larva solves problems

Before starting on the system about 18 months ago, I identified issues within the existing development workflow that a design system should solve. This list is a combination of those items, and a few other benefits we have achieved – the why of the design system:

  • Provides clear separation between front-end & back-end in development cycle
  • Speeds up UI development a great deal
    • Removes dependency on WP local development
    • Minimal (or no) asset compilation required for small style changes
  • Requires the pattern library and theme be maintained together
    • Outdated pattern libraries were an issue in several themes
  • Provides a platform for sharing UI code across brands
  • Controls CSS quality, prevents turd-driven development
  • Consistent front-end architecture for all brands
    • This means we can share solutions to problems between themes without battling dependencies and differing naming conventions
  • Removes the burden of naming – re-usable names for UI code
  • Accommodates different brand styles
  • Create the beginnings of a UI language for engineering/design/product

Trade-offs and new problems

Is it a fact of life that when problems are solved, new ones are created? Or perhaps that old problems return in a different form? If not a fact of life, is it a fact of software design?

Existential thinking aside, my instinct is that it is a good sign to be moving onto new sets of problems. And the problems that return in different forms, I think, return in forms that are more manageable and closer to the root problem (which is probably capitalism).

For example, I say in the above list that “Minimal (or no) build required for small style changes” is an advantage of using Larva. While we no longer need to compile Sass, we now have a different build step. It’s much faster and simpler, but now we have a new package of code we must maintain and document, and developers must learn to use. This is a trade-off.

An example of a old problem that we solved: rotting pattern libraries because developers will not maintain duplicate HTML/CSS in a pattern library and the WordPress theme. In Deadline, we solved that problem with the Twig to PHP parser, so that the HTML originated from Twig and was parsed into PHP. But then the problem of an outdated pattern library because of redundancy re-appeared in the form of maintaining the strings of CSS classes that were both JSON and in the PHP templates.

In ArtNews, we solved that redundancy problem by creating the data objects in Node.js and outputting that object to a JSON file to serve as a middle layer that provides defaults to PHP. The CSS classes are now maintained in one place, but this problem has re-appeared once more. Now, we have to maintain two sets of the “object preparation code” – one in PHP, one in JavaScript. While the UI code itself is no longer redundant, the problem of redundancy persists, but has returned in a different form. I believe this is a better form, because there will be consequences if these objects are not kept in sync. And we need proper testing to ensure the objects stay in sync to avoid the problems. I guess the takeaway here is that there is never less work to do, rather, new problems and needs arise as you move through the process. And I guess experience is helpful because I will know that this happens the next time I create a design system (unless I’m a one and done on design systems…very possible).

Anyway, that ended up being a little ranty. But I guess it all supports a point I feel strongly about: front-end development is software development. I mean, obviously…what else would it be!? Initially writing this section spiraled into rant that has been transferred to another blog post draft, and may or may not see the light of day.

Looking ahead

What’s coming up for Larva? Great question. I’ll make a list:

  • Static builds of the pattern libraries so they can be deployed for documentation
  • Automated screenshot testing / refactoring the testing approach to be one large page with all modules vs. screenshots for each individual module
  • Continuous integration in the Github repository, at least to automate running the Node tests
  • PHP classes that correspond to patterns, and unit tests that can easily be run in our pipeline
  • JSX generation from the Twig templates
  • Educating product managers to annotate designs with design system language
  • Updates to the Larva server UI to show pattern variants

And some bigger items, or possible refactors, that will be at least a few months out:

  • Adding more properties/values to design tokens, namely font-sizing and spacing, and possibly moving the design tokens to project-level
  • Adding a slot or block capability to the templating language (which is Twig but not really Twig)

Far future:

  • Meta-programming / code generation for the Node prototypes and consuming project controllers (PHP for WordPress)

Things that make me anxious

In 2018, I attended Nathan Curtis’ workshop, Design Systems at Scale, at Clarity Conf. I learned a lot of useful things, and one thing that really stuck with me, and now concerns me somewhat, was his emphasis on how critical it is for a design system to have a dedicated team in order to survive. Here is an article of Nathan’s about design systems teams. I would say Larva is at least two or three years away from anything like that. This makes me nervous. In fact, all of the ways Larva has, and continues to, deviate from descriptions of other design systems makes me nervous, but as I learn more, I’m realizing there’s nothing to be nervous about because:

  1. All design systems are different because design systems are for people, and people and groups of people in companies are all different,
  2. Design systems are a long game – maybe Larva will end up conforming to this model of design systems I have in my mind (which, worth mentioning, is a largely rooted in blog posts by consultants), but it also might not. Time will tell.
  3. Relative to the history of software development, design systems are very new. Working on design systems is a highly specialized undertaking, and often – at least in the beginnings – a highly individual undertaking. Doing my best.

While PMC does qualify as “enterprise” in that it is a very large company comprised of other companies, the product and engineering team is relatively small and tight-knit. The nature of our work is more akin to an agency serving a suite of brands than a single product focus. PMC’s needs are different than what comes to mind when one might think of companies with design systems (Salesforce, Atlassian, Shopify, Pega).

Vox’s design system comes close to our needs since they also support several brands like PMC, but Vox maintains their own content management system and have significantly more design and user experience resources. At PMC, we don’t have designers on the product team – the designers mainly work with stakeholders or as print designers for the brands – and any design and development for the CMS-side of things is handled by WordPress. So, while similar, not the same.

The primary goal of our design system is consistency in how we build UI for the front-end of the brand websites, which are WordPress themes, and the ability to share the UI between brands. It will extend beyond the code-bases into a system of design decisions, but we aren’t there yet. So, maybe the team model I learned about from Nathan Curtis doesn’t quite fit for PMC at the moment. Maybe we will be okay without a dedicated team, or maybe that’s something that will come in time.

What I do know: the engineering team at PMC has successfully shared responsibility for software in the form of our back-end core tech – the plan is for improvements to Larva to follow the same model, with myself as the guiding force. Time will tell if this is sustainable or not, but I am optimistic. There is no one-size fits all, for anything really, but especially for design systems.

In Conclusion

I’ve learned a lot over the last almost two years of working on Larva, and I know there is so much more to learn. But I must say…I AM SO F#CKING OVER WRITING THESE POSTS.

And yet…someday I hope to spin all of this into a talk. But I’m putting that idea on the back-burner.

But for real, thanks for reading! I think it’s the coolest thing ever that people actually read my blog posts, and maybe this can provide some reprieve from the tumultuous things happening in the world right now.

If you’ve kept up with this series, or are just coming across it for the first time, I’d love to hear what you think and what you’re working on. Are you building a design system? How’s it going?