You've been handed a design and tasked with writing the code that will bring that design to life. Where do you start?
You've been handed a design and tasked with writing the code that will bring that design to life.
Where do you start?
If you jump right in and begin writing code, you're likely to encounter more bumps along the way and end up rewriting the code, perhaps even multiple times.
A plan is crucial to keeping your code concise and your time focused.
Many websites today are built with components. Components are reusable pieces of code that can be composed to create web pages.
Components are a great way to approach building a website because they enable you to reuse work you've done before. Thus, development of the site speeds up over time. And maintenance tends to be easier, as every component has a single source of truth. So if there's a bug with that component, you generally only have to fix it in one place.
Building such a plan requires that you step back and look at the entire system — the largest context in which you're working, which is usually the whole site, but may be a single page.
So let's do it! We'll walk through the process of taking a design for a single page and breaking it down into components. What we'll be left with is a blueprint for how you will build that page.
And let's use a real world example — Contentful's home page. (In this case, we'll assume we're working with a single-page site and not worry about the broader design system.)
Here is the design we've been given:
And now let's make a plan.
The typical website can be organized into section components. A section spans the full width of the page and includes related content.
The distinction between sections is usually obvious. A well-designed page provides visual breaks that you should be able to pick up on naturally. Your eye will often tell you where a break should be.
Here's how I would break our design down into sections. Each section is outlined in red:
In some cases, there may be elements like background images that blur the lines between sections. If that happens, it should be a warning to you that writing the code will be a little trickier and more time-consuming.
This can be handled in a jam session, which we'll discuss in Step 5.
Next, give each section a name. This helps create a common language for you, the designer, other developers, content editors, and stakeholders can refer to each section.
Naming is hard. There's no perfect name for any section. But, one thing that has helped me tremendously in the past is to name sections by their structure, not the content.
Content can always (and probably will) change, while the foundational code and underlying functionality may stay the same. It's much easier to avoid name changes every time you want to change the content.
This also provides flexibility in using a section in multiple ways.
Here's an example with stats about Contentful's market position. We could call this section
MarketTabs, but that could quickly become irrelevant. I'd choose something more generic and functional, such as
You have sections and names for each section. Now, take a step back. Look for similarities in structure among sections, regardless of the name you chose.
And don't just consider direct copies, but be open to small differences.
For example, here are two sections that fit well together as
CardSection. The first has a heading and three components we'll call cards. Each card has a label, heading, subheading, body text, and background image. The second has a subheading and slightly difference cards, where the image is positioned differently and there appears to be a link at the bottom.
All of these adjustments can be made conditionally and relatively easy in the code. We might consider these two be two different card types in these sections, and those may map to different components, but that's all configurable. That's something we could surface to editors as an option in our CMS.
Sections can then be further broken up into what we call blocks at Stackbit. These are smaller, repeatable components.
It's easiest to start by looking for repetition within a section. Using the example above, we already identified that a
CardSection has card components inside, which I might describe as
The slightly more difficult task is to look for similarities across sections. This can be more difficult, designers might make small adjustments to components that could otherwise be shared.
The classic example of a component often shared among sections is a button. Here's an example with a button in multiple sections.
Once you have a general component plan in place, it's an opportunity to make adjustments through jam sessions. A jam session is a meeting with the designer meant to clear up ambiguity and find opportunities to adjust the design to speed up development.
Jam sessions are most effective when you bring a list of questions to the designer and work through them, one at a time. (See below for common topics.)
The goals of the session are to:
Though there are many scenarios that arise
If the designer insists that a change you feel is crucial must remain as is, consider first consulting with another (senior) developer to see how they would build it. It's possible they'd have some advice on how to build it quicker. For example, perhaps they know of a reliable library that has already solved the problem for you.
That said, disputes most often come down to time and budget, both of which are optimized by simplicity. As a developer, it's your responsibility to work with the designer to find a balance between simplicity of the code and effectiveness of the design.
Once you have your plan, and are fully clear on what you are to build, it's time to dig in.
While writing code, it's important to keep the plan in mind. Continue to build with the system in mind. Be consistent where possible. Use repeatable components when it's reasonable to do so.
Every time you veer from the system and create an ad hoc solution, you make maintenance of the entire system more difficult.
This was a simple example with broad steps on how to get started. Applying to the real world means more nuance and complexity.
When you feel overwhelmed by the volume or intricacy of the design, come back to these steps. Be methodical. Start at a high level and drill down. Work with the designer to clarify ambiguity and help streamline what you'll have to build.
If you want to take at components in action and see the result of this process, head over to jamstack.new to create a free site, then dig into the code.
Or if you want to talk more about this process in general, let's do it! I'm @seancdavis29 on Twitter and I'm a huge component nerd.
You could build a house one brick at a time. Every room could be unique. That would take a long time and it'd cost a lot of money, as houses usually do. But what if you could build a house room-by-room?
One of the biggest benefits of a headless CMS is that they can serve multiple front ends.