At ISL we have no shortage of desire to make our lives easier by leveraging technology. I can’t count the number of meetings I’ve been in where we’ve talked about automating X or using machine learning for Y, or using AI to power Z.
I also can’t tell you the number of times I’ve walked out of those meetings completely excited, but so overwhelmed with where to start. Do I make a neural net of my React TensorFlow Spark sensor? Yes that is a series of relatively unrelated things in a sentence, so welcome to my brain.
Enter the internal request for a Style Guide template…
Here was the ask:
- Make a reusable Style Guide – or an easily accessible, well designed online repository for brand marks, color palettes, fonts, photography, etc – template that can easily be reconfigured and deployed for any client and
- Enable our non-developers (designers, project managers) to configure and deploy the project with virtually no development effort.
I immediately descended into the rabbit hole, contemplating a barrage of solutions that might best suit the project requirements.
My initial thoughts:
Pros: We could write a theme that our team could then import and style.
Cons: Not exactly a couple day effort to get totally right. And while PHP and WordPress have a special place in my heart, they are not my immediate go-tos.
Pros: Basically the same pros as WordPress, though some might add that the admin experience is cleaner and more intuitive (I certainly would).
Cons: The custom JSON-ish format seems approachable enough, but the big burdens are vendor lock-in and cost (Squarespace ain’t cheap). What if we want to pivot away? Well, we’d be doing a bunch of re-writing.
- Netlify CMS:
Pros: Netlify is one of the cheapest hosting options and this CMS is completely open source – win win. It’s got a minimal and highly configurable admin experience – all in React 💛 We don’t need a ton of bells and whistles to add blocks and change colors.
Cons: It’s minor – Netlify CMS doesn’t yet support dependent fields in collections trivially. That is super nit picky. We liked Netlify CMS, it’s just not the easiest for a non-developer to deploy out of the box.
- Some custom Airtable, Google Sheet, etc. variant:
Pros: If we configured the hosted entry point well we could make it really easy to deploy. Something like Liftoff would be great here. Set a key for where to look and voila!
Cons: Things could get messy really quickly if we didn’t architect the sheet/Airtable well. Otherwise, it’s doable!
Wohhh there… You can probably feel the options mounting.
While normally we recognize that there is tremendous value in being really methodical in choosing how we do things, there were a few rallying concepts we knew would be true for this very small project:
- We wanted a reusable style guide with the following components:
– A base block
– Components that live in blocks (arbitrary text, font examples, color swatches, downloads)
– Contextual Nav
- With all likelihood we’d use React
With that in hand we made a decision: make the reusable components and we can add any necessary abstractions in the future (like a dynamic backend, one click deployments, etc.). We have the developer resources internally to iterate as needed in the future if we see value in doing so.
Gatsby felt like the perfect choice for what we were trying to do. Here’s why:
- It’s a static site, so it’s extremely cost effective to host.
- It’s extensible and easily configured into something more dynamic or CMS-y in the future (if needed).
- It’s React-driven so we get the normal tools and APIs we like working with.
As Gatsby has such a simple drop-in page system we created simple page templates that can be copy pasted into the pages directory and BOOM – new page created.
From there we created a components directory that shows our top level “Block” that houses any of the other components. This met the requirement that the visual display be consistent and highly reusable.
We chose to hide a ton of logic behind the <Layout> component, like the contextual nav, header, and footer because there was no requirement to have those be massively composable. Components like the header, footer, etc. aren’t shown in our “Components” directory. That’s because they are stashed away in a utils directory with a bunch of other non-user facing logic.
We used PropTypes to make our components loosely “typed” so there are reasonable defaults and useful errors should the correct props or children not be used when building the blocks. All of this in an effort to make the code hyper-easy to extend in the future! We can easily imagine a future where we connect these front end blocks to be generated off of an Airtable backend or even a more robust “true” CMS.
Are we happy with how it turned out?
Time will tell!
Like most internal experiments, there is a non-trivial chance this may end up on the cutting room floor – but because we chose to go the fastest route possible for a functional v1, there is little wasted in terms of personnel or financial costs.
PS: I may or may not have been super diligent about appropriately attributing the fonts and images we are using as placeholders in the project so it’s closed source for the moment 😳. If you’d like to see it open sourced please let us know and we will get back to you!