#tldr How building upon a strong foundation, best practices and ready-made-integrations enables delivering new features and content in record time, drastically improving your time-to-market. To showcase this, we’ll add two completely new structured content types to our website: Showcases and Appearances. We’ll also follow a workflow shaped by the use of a Design System, connect Contentful as our content source, and extend our Gatsby theme to render such content along the way!
Points to reflect in the post:
- What role would be involved in each step, in reality -> great isolation helps to build solutions asynchronously / compartmentalized
- Summarize “investment”: LOC, Minutes, etc
- Low-Code != junior, but huge lever when setup correctly
What we’re building (Definitions)
- Appearance
- Showcase
What we’re building with
- kickstartDS
- Storybook
- Contentful
- Gatsby
Process
- Create component in Design System (link Create component guide)
- Create content models in Contentful
- Create / adapt transformer in Gatsby theme
- Refine components further
- Create new templates in Gatsby theme and integrate into website
1. Create component in Design System
First step of adding something to your Design System should always be having a solid idea of what your new component is supposed to do, which options it should have, what information should be conveyed, and finally what interactions should be possible.
We like to call this a component API, and we typically encode it in JSON Schema in kickstartDS.
Have a look at an example in our docs, where we add a new component… with all the involved steps in described in detail. We also have a more general section in there about the possible processes that can be involved in creating a new component.
In this example we stick relatively close to our already existing Glossary component, at least initially. Have a look at that one in our Storybook, or explore its JSON Schema on Github.
This step can be done pretty early on in the process of creating a new feature, without any other direct involvement (for example from your backend / CMS team). That in turn enables super early feedback on ideas, without making compromises that will stand in your way when finally tasked with bringing those early ideas into a more stable state.
And using something like Playroom enables the more code-savvy designers to actually build prototypes with your real components, which can be super liberating when it fits your team makeup! (we support Playroom for your custom Design System out-of-the-box with kickstartDS).
See the whole process in the following YouTube video capture from the live stream:
2. Create content models in Contentful
Creating the matching content model, in your headless CMS system of choice, should be pretty straight-forward. Our JSON Schema definitions (generally) match really well for that purpose. We follow our component API closely when creating the record types and fields in Contentful. This enables easy integration into our theme later, where component and data finally meet up and get combined into real pages and content.
We also create some example records for those content models right away, so we’re able to test the integration and our new components.
This is something that can also be done by someone more (or only) familiar with the editorial side of creating content, and doesn’t require any dev work per se.
Follow me along to see this applied to our Appearance and Showcase types on the following stream capture on YouTube:
3. Create / adapt transformer in Gatsby theme
With our components in place in Storybook, and the respective content models defined in Contentful, we’re ready to start integrating everything. We already have a Gatsby theme in place, so we’ll only need to “explain” our new content structure to that. This mainly involves creating resolvers that translate the ingested content (coming from Contentful in our example here) into our existing kickstartDS Node interface for pages. This is where a solid foundation (in our component API) and existing integrations really shine!
You won’t have to fiddle with GraphQL types or fragments to get this running… this is all managed for you by our theme. Everything gets generated based on your JSON Schema in a tailor-made fashion, so you have full control. Mapping your ingested data to the new components, and rendering them correctly on your page, will be fully automated!
TODO add example block of generated fragment
You’ll need a developer with good knowledge of Gatsby (in our case) to complete the first-time setup of this. But this is a one-time thing, and he should be done with it pretty quickly!
See how we connect the needed resolvers, test the transformed data in GraphiQL, and finally connect up two new page types and templates in the video capture of the stream, on YouTube:
4. Refine components further
As often the case, after having a first visual impression of your new content type, you’ll notice things. There’ll be some improvements that suddenly seem obvious to you.
This serves as a nice example for having an early feedback loop. When being able to integrate early, and getting something visible out the door, you get to validate and generate feedback without a big investment up front. This helps in getting stakeholders involved, at a point in the process where their feedback actually matters most… and can still be implemented without much added friction.
While also adding some new properties into our component APIs, we mainly change the template around a bit to make both new content types feel a bit more distinct. They were pretty similar in their rendering to our Glossary before. But as different content is displayed here, the component should adapt to that, too!
TODO add before after of components
Again, we benefit by having our component API abstraction while doing this, because how the data is rendered is completely owned by the component in your Design System. As long as that structure doesn’t change, you’ll get to integrate those changes into your website without making any changes to your Contentful content models or your resolvers / Gatsby theme integration!
This is huge news, at least for most teams out there, because it means changes to the way components look can be done in a completely isolated fashion. Even automatically consuming those changes downstream (e.g. in your Gatsby / Next.js), without involvement of your whole core team, gets trivial!
See how we apply this our Appearance and Showcase components in the accompanying capture of the stream on YouTube:
5. Create new templates in Gatsby theme and integrate into website
Insert description, timelapse and YouTube embed
Conclusion
Detail how this is exemplary for the ways best-practices and good defaults enable such development velocity. This is not restricted to this specific example, but is enabled by having good architecture in kickstartDS.
