Designgineering Chronicles: Months 9.5-11ish?

A slightly delayed Chronicle, but no less juicy! In preparation for the kick-off of Blueberry, we are figuring out how to actually share and publish modules as the design system (named Larva) becomes a product that stands on its own.

Scribbles turning into ordered lines

I have definitely messed up the month increments in this series – not sure where it went off and not sure I care! So, although it has been over two months (gasp!!) since the last Chronicle, I’m rounding this one out to month 11ish. Maybe someday I will go back and give them chapter names that are more useful.

Okay! There is a lot to catch up on! But first, a quick recap of where things left off in the last Chronicle.

A quick recap of Month 8.5-9.5

A big reveal of the true identity of project Cantaloupe – Deadline.com – and the major overall success of the project! That the project launched on time, came in a bit under budget, and was high quality, makes Deadline the true proving grounds for a systems approach to front-end at PMC (even though all the websites look different! it can be done!).

I also reviewed some general notes about creating a roadmap and identified the next project in the pipeline that will be code-named Blueberry. And I think that’s enough of a recap – there’s a lot to get to in this post!!

That wasn’t actually the end of the Deadline project

I think part of the reason this post was delayed more than I liked is that there ended up being another two sprints left in Deadline. The contracted engineers had finished, so it was only me and AS (the back-end tech lead) left on the project. I wanted to challenge myself to take on more back-end responsibilities which ended up being a good learning experience, but definitely time consuming.

One particular issue was around some very rank handling of captions on images inside the post editor in WordPress. And by rank I mean programmatically inserting a <span class="u-hidden">.</span> into the caption metabox to force the wp_caption shortcode to apply on all images in the_content so that we could then filter the caption to include an image credit….yikes. But a good learning experience! Sometimes things are just nasty, I don’t want to say especially in WordPress per se…but especially in WordPress.

There were a few other issues that were unpleasant, such as dealing with some unexpected advertisement configurations, for example, a massive dropdown video that needed to remain above the sticky version of the header menu which is totally contrary to what it was initially programmed to do. Everything is water under the bridge now, but it’s worth mentioning that I did feel a bit like the haggard Harry Potter mentioned in the last Chronicle by the time the project was actually over.

I think this is a good example of how the gradual, thoughtful investment that a design system requires can sometimes be at odds with business requirements. The nature of quick turnarounds and last minute stakeholder requests is a core part of how PMC operates as a business, and the system needs to support that. The tooling we built did a great job. There were a couple of relatively significant design changes that resulted beautiful, tiny pull requests, as well as a last minute module addition whose design elicited a major sigh from me, but ended up being no big deal thanks to our ready-to-roll CSS utilities and algorithms.

While the tooling held up well, I can’t quite say the same for myself; I was dragging myself over the finish line by the time the final sprint ended. But it did end! Whew.

A Name + Backlog + Roadmap = Almost Official Design System

Perhaps the “Make it official” part can only truly, truly be checked off once we have a published, shared module, but I think giving the system a name, backlog, and roadmap gets us pretty darn close.

“Lara’s magical design system” Presentation

No joke: this is actually the name of a meeting the head of product (who is SO cool) set up for me to present design system concepts to one of PMC’s executives (also a super cool!)! I put together a slide deck that focused on the business case behind a design system and how it will manifest at PMC, and the presentation went super well. I did not shy away from presenting the road map, either! The most ambitious element of which is “Full-time Design Ops team of 3-4 by May 2020”. You never know!

You are welcome to look at my slide deck here for inspiration. So much of this content and any success I’ve had is thanks to those who have put in the work to guide my way! Thank you, design systems community!

Also, before I give presentations like this or spec out design systems work, I make to sure talk it all over with my manager and one of our engineering directors. It’s proven so valuable to get input from colleagues – regardless of their design systems knowledge – to make sure the solutions we come up with are designed for PMC specifically and not rooted in my subjective understanding of what a design system should be.

The magical design system is called Larva

Alas, our design system will be named Larva. At least it is ripe for cute monster illustrations:

I tried to get some other ideas flowing from the product team with this message:

Hi PEP team! We need a name for the design system – in the running was “Larva” sort of as a joke (it was my nickname in high school because I was afraid of worms) but it has come time to name a repository and I think it’s too weird. Any other ideas?

But…the rest of the team seems to like the name Larva. It is kind of funny and endearing and weird and memorable and the right length. Also, the notion of a “tiny baby thing that can’t really do much on its own” – a.k.a. embryonic design system – is accurate. This may change in the future as our language for interface elements matures, but at the moment, Larva is not a design system of robust components and won’t be for a while. It’s a system of markup patterns, CSS utilities, CSS algorithms, and coding standards that will enable developers to build robust components. We just can’t commit to specific components or names yet. A big part of that, I think, has to do with how little design is involved with product at PMC and the fact that we basically have zero conversation about UX…one step at a time, please.

Also, I think subconsciously, perhaps, the name Larva is inspired by Help Scout’s design system, Seed, which I have referenced heavily. And, perhaps, the metaphor of Larva will help with naming future repositories. Pupa? Cocoon? Spawn? Butterfly? Now I am looking up pictures of cocoons and it’s a little disgusting. I also heard before that a larva completely digests itself while in a cocoon and spends over 1/3 of its life doing that…

Larva has a backlog 🎉

This is a big milestone! And given how important project management is at PMC, I think this is the one major thing I have done to ensure it is, indeed, official and taken seriously. Even if our design systems team only consists of me, it goes a long way to treat the work like any other work happening at PMC. Plus, the act of writing JIRA tickets in the first place and thinking about a “definition of done” really helps keep me on task.

A screenshot of a JIRA backlog with stories filed under the Larva 1.0 epic
Larva is officially part of the project management workflow at PMC!

I actually have been doing this pretty much since I started at PMC, but previously the epic I used to track systems work was called “Front-end Ops”. That resulted in the pmc-build-utils repository that contains a webpack configuration and other tooling.

Kind of an aside, but I think this ability to self-manage is something really, really valuable I learned from freelancing for several years before getting a full-time job. I’ve definitely questioned whether I missed out development knowledge by working independently for so long, but … 1) that is not the case and 2) I gained a lot of other skills that are not as straightforward to obtain when working at a company.

Larva has a roadmap 🎉

It only extends until about one year from now and is pretty high-level, but it’s hard to foresee what will come up at PMC much further in the future than that. Here is Larva’s roadmap:

  • Design System Big Bang: Deadline (Jan. – May 2019)
  • Sharing Modules: Blueberry / Larva 1.0 (May – Nov. 2019)
  • Tooling, Testing & Documentation: Lara + Contractor (Oct. – Dec. 2019)
  • PMC Engineer Education: PEP Summit and refactoring exercises during holiday code freeze (Dec. 2019)
  • Roll out to other brands: Either build out a high value shared module, or iterate on Larva via another redesign (Jan. – May 2020)
  • Design Ops Team headcount: 1-2 hires (!) (May 2020)

That last bullet point is quite ambitious, but not out of the question! It really is a dream of mine to have a team – I would love to hire two people with a similar skill-set as mine, but one person more focused on design and one more focused on back-end and tooling. I’ll need to revisit Nathan Curtis’ writing on the topic once we get closer to that milestone!

Pre-Blueberry To-dos

The next systems big-bang project will be Blueberry (code name), as I have mentioned. I have been blessed with about a month between the end of Deadline and the start of Blueberry to work on Larva outside of a specific project’s requirements which is so, so crucial at this point. The major goal with Blueberry will be sharing modules between it and Deadline. This means there will be many changes to the Deadline code-base as we build out Blueberry…and we have to figure out how to share a module in the first place.

Note that the term “module” equals a shared UI element built with Larva tools – things like a video player, an author image and excerpt, a “trending stories” slider-roadblock thing, or a featured article full page header. These are the product names for a given bit of interface. I suppose they might be “organisms” in atomic design.

Here are some big questions that I have made decent progress answering, more on that soon:

  • How are modules versioned?
  • Where to the primitive patterns live vs. the modules that use the primitive patterns?
  • The CSS for modules is mostly in utilities. How can we be sure the consuming theme has all of those utilities?
  • What about share-able code that isn’t a module? e.g. a specific CSS algorithm or the breakpoint mixin or JavaScript functionality
  • Where do the parsed templates live? Are primitive pattern templates (o-* and c-*) parsed into the same place as modules?
  • Are these parsed, PHP template-parts in the parent theme or the child theme?
  • Do we even need a JSON file and a project-level pattern library if patterns come from a centralized repo? Why not override the JSON data in the PHP, instead of having an intermediary JSON if something comes pre-configured?

Yikes! There is a lot to figure out in the next two weeks…I think the plan is to kick off Blueberry then, but things can change quickly.

Spikes

With that list in mind, here have been the three main focuses during the downtime between projects. These are “spike” tickets in JIRA which is an Agile concept I learned about not too long ago. A “spike” is a ticket that basically provides you the space to figure something out and fill out knowledge about a particular topic. It doesn’t necessarily produce workable code, but it might produce a follow up ticket.

Here are the spikes I’ve been working on between Deadline and Blueberry:

  1. Visual regression testing on Deadline – there likely be a lot of changes to that code-base as things are moved to a shared repo. We must have testing! Testing is always overdue to begin with, so the time for it was yesterday.
  2. Publishing modules / sharing patterns – this includes many of the questions above, but specifically, with WordPress, where the heck will these shared patterns live and where will they be published?
  3. Whitelist/Blacklist properties & values in CSS algorithms – This is a cool one! We need a way to make sure any CSS algorithms created at a project level 1) aren’t modified to serve something beyond their original, intended purpose, and 2) aren’t used for things that utilities or other system tools should be used for. For example, Deadline has an algorithm for a very specific grid layout on the article template. Let’s say in a future ticket, that grid changes to accommodate some new module. It might be tempting for the developer implementing that change to add a margin declaration to the algorithm instead of using our margin utility. If that happens, we are in the domain of Turd Driven Development (a concept from my recent talk! link to that part of the video here), as the algorithm is doing more things than it should be doing. Its a slippery slope from there, and we would basically be back to the same problems Larva should solve.

So far, spikes 1 and 2 are complete. Actually, the visual regression testing has been implemented on Deadline! And we figured out a nice way to deal with unpredictable ad slots!

The question now is…do I write about that in this post or leave it to a follow up, which means it may never be written? Life’s big questions…and the answer is a follow up. I PROMISE. There will be a “Technical Part 2” for this Chronicle as well cause I have lots more to write about!

Technical Part 2, coming soon probably

Here is a brief outline of “Technical Part 2”. Usually I would keep this in a private note, but why not add it to the bottom of this post? It’s interesting.

  • Our visual regression testing tool (Backstop with an onReady script)
    • Challenges and that this is not a “silver bullet”
  • Refactoring some webpack configuration
  • Getting better at writing Node scripts and feeling powerful
    • Making the pattern JSON export an object so you can have better demo content
  • Opening patterns for extension via the JSON object (which I believe will come to be known as Larva’s API)
  • KSS-node is really slow in Deadline and I’m not sure how useful documentation in that form is. I’m looking into other static site generators, and, as the system matures, we may not need the theme-level pattern library in the first place.
  • Merging default pattern JSON schemas with wp_parse_args to solve the class string redundancy problems
  • Deciding on a single-version mono-repo and deploying core patterns in the parent theme
  • Successfully trimmed down the size of critical CSS quite a bit thanks to the single purpose utilities and using file extensions for code splitting
  • The concept of responsibility in CSS and that utilities are kind of an anti-pattern when compared to the original, intended purpose of CSS – this is a conversation I had with Jeremy Keith at CSS Day, and I’ve been thinking about it a lot. I will write down those thoughts eventually, maybe in Part 2 or elsewhere!

What’s Coming Up for Larva

Well…we have a big huge new website called Blueberry to build! This is when it gets real. Shared code. It’s scary and exciting. I’m very excited about the potential project team – I think it is going to be almost the same as before with AS as the tech lead, myself, Yahil as our front-end contractor, and another 1-2 folks for back-end. Unlike Deadline/Cantaloupe, Blueberry will involve a bunch of data migration from another WordPress instance and that’s a project in itself.

We will also have – I hope! – an additional PMC engineer at least at the beginning of the project to work with me on building out the workflow and tooling around publishing and using the shared patterns. A big reason why the Deadline project went so well – apart from number one reason which was that the team was great – is that we invested time up front in building tools that would help us move more quickly into the project. I hope to do the same with Blueberry!

Okay, that’s all for now! Written in haste…indeed. Publish, Lara, publish!!