Comp to Code from the Content Out

A no-nonsense approach
for building out contemporary web comps
without compromising on quality.

Phase 1. Analyze the comp.

This first phase will guide us through breaking down the comp to analyze the logical structure of the content and realize the grid system in place.

This will give us plans for both simple, semantic HTML and for how to lay out the page with CSS in the following phases.

A. Determine hierarchy, grouping, and source order.

We don't want to assume that having a design comp in hand is the same as understanding the content in it and its structure. So before creating an HTML document or writing any CSS, we should first analyze what is in front of us. First the we examine the overall hierarchy of elements, and then we look at the grouping and logical ordering of those elements.

Determine the hierarchy of elements

First, we can analyze the overall hierarchy of the headings on the page. In doing this we should be careful to analyze the structural hierarchy of the content as opposed to the visual hierarchy.

Use the following as a guide:

  1. Identify the elements in the comp that are actual headings—labels for the content that follows them. Mark or highlight these throughout the page. Note that every large or bolded bit of text is not necessarily a heading.
  2. Identify the primary heading for the site from among these. Very often this is your site's branding at the top of the page. Mark this as an <h1>.
  3. From among the headings that remain, identify which should be considered direct subheadings of this heading. Mark these as <h2> elements.
  4. Repeat this process for each <h2>, identifying each one's direct subheadings and marking them as <h3> elements.
  5. Continue this inward process until you've accounted for all the headings on the page. Each successive round should add a new level of subheading from <h4> on down to <h6>.

Note that some prominent content might not have an explicit heading over it in your comp. In such cases, note a label could be used for such a group, and note where it would be organized in the content's hierarchy.

Grouping elements

Next consider which sets of content should be grouped together. Work through your comp, perhaps by making a quick wireframe sketch on paper, and outline each group or unit of content.

Only mark the significant groups or those that are worth distinguishing in order to keep the overall analysis from being too detailed. Too many details may be difficult to parse in upcoming stages. This approach facilitates moving from the outer-most layout down into micro-layouts, so feel free to keep it simple for now.

Ordering groups

Finally, we determine the order in which to code our groups. In an ideal world this would be a matter of following the hierarchical structure and groupings we've determined in the order they're presented, from top left to bottom right.

Unfortunately, its not always this simple. It is quite common for designers to use the space available to them to present elements visually and not necessarily structurally.

So keep in mind that this structural ordering should focus on the structure of the content despite the elements' physical location in the traditional reading order of a visual layout. Mark the elements, or groups of elements in the order you actually would expect to encounter them as a reader. Many times this will not be an issue at all. But when in doubt, we must favor the logical order over the visual presentation.

Two key considerations arise at this point:

Anyone with a little experience building out pages has probably faced the temptation to code elements in presentational order, since, frankly, it is has been simpler to build out a layout in this fashion. But thanks to flexbox and the CSS Grid module we can finally really let our semantic analysis shine. We can now create our structure 100% for the sake of the content without any blurred lines for how this will be transformed and presented later. This also allows us to shuffle the presentational order of elements from mobile to desktop without extra markup or other fancy tricks.

However, this is can be a rather subjective part of this process. Where we're headed is to identify the following in our comp:

Consider the following process:

  1. First identify the masthead, footer, and main content areas. While all might not be present in every site they are typically the outermost and largest groups of elements, and each could implement its own grid system. These will be considered as our basic container units. In most cases these form the outermost grid containers, but in some situations they might be arranged as layout units. In such a rare situation, you might consider the <body> tag the outermost container unit.
  2. In each of these container units, identify the next-most-prominent groups or individual elements based on your hierarchical and structural analysis from above, particularly those that are presented in a grid-fashion (such as side-by-side) or those that are presented in a different order than they might need to be coded. These will be considered layout units.
  3. Look at each group identified in the previous step and consider whether any of them have a more complex order or arrangement within them. If so, repeat step 2 on such groups, considering each of them a compound unit.

The bottom line here is to identify the key groups of content and the order in which they should be coded. Identify and number these in your comp before moving on to consider their visual positioning.

B. Analyze layout units to determine the overall grid(s).

With the content thoroughly analyzed—structured, grouped, and labeled—we can move on to think about how the layout is set up. We need to move towards identifying any grid systems that we can later translate into CSS. We will look at each container unit first and later move inwards to identify micro-layouts present in any compound units.

Sometimes such a grid is explicit and obvious thanks to a existing markings in the comp; other times we need to extract one by analyzing the alignment of elements in the comp.

Regardless, start by looking at each primary container unit you labeled earlier one at a time, investigating the layout units inside to identify a grid.

Identifying an explicit grid system

Explicit grid systems may be in play in a design comp if you can clearly see rows and columns marked in the comp, or if a straight-forward analysis of the alignment between elements shows a system is in use. On one hand, software aids such as planning guides or layover boxes might be in use. On the other hand, a clear vertical and horizontal rhythm might be immediately obvious.

Regardless, identify the vertical column grid lines and the horizontal row grid lines based on explicit markings or clear alignment of elements. Disregard any grid lines that are not used as an alignment point by at least one element.

Identifying a less-than-explicit grid system

A grid might not always be explicitly used or immediately obvious. Sometimes a designer has an overall grid system in mind, but has been a bit liberal in exacting the system. Other times, no grid was used at all, and there is some work to do to extract one.

Use these steps to extract a system from a less-than-obvious situation:

  1. Draw vertical and horizontal lines along the edges of the layout units directly inside of a container unit that extend to the outer edges of the container unit.
  2. Simplify these markings, looking for normative lines between similarly-aligned elements.
    • With elements that have similar edges, favor the outermost edges in common between them; we can use margin and padding in CSS later to enforce the inner offsets from those outermost lines if necessary.
    • Sometimes this might mean going back to the concept with your designer and tweaking the alignment between elements in order to simplify the grid and strengthen the unity of the layout. If you are not the designer yourself, you might feel like you're stepping on toes to do this, but this is worthwhile as it is likely to lead to a stronger, more unified layout.

Be careful not to overthink this or get too detailed. We'll investigate smaller grids or micro-layouts in the last analysis phase. Stick to the layout units directly inside of each primary container unit.

Extracting the applicable grid

With this initial analysis in place we can now extract the applicable grid to use later in our CSS. If any layout unit contains a series of elements that are coded in the same order they appear and no elements are presented side-by-side—they're all stacked on top of each other—then you have no need for flexbox or the grid.

Otherwise, before we assume the grid system is the best solution, consider the following:

In either case flexbox might be simplest unless you prefer the centralized setup of the grid system. If you have anything more complex the grid will be a nice solution.

Once you've determined that the grid is the best solution, use this process to sketch the grid separately for reference later:

  1. Draw a sketch of the horizontal and vertical grid lines involved.
  2. Add to your sketch the distance between each grid line. These distances will later become the grid tracks for the system in CSS using grid-template-columns and, when necessary, grid-template-rows. Keep in mind that you have several options:
    1. Measure the explicit pixel dimension of the grid track. This is most useful if you want a fixed or adaptive layout as opposed to a flexible or fluid layout.
    2. Realize the dimension of the grid track as a percentage of the overall size of the container. This is helpful for creating fluid layouts. In such a case, you can simply measure the pixel dimensions of the track and divide it by the pixel dimension of the container. Multiply the result by 100 and round as you see fit to achieve a percentage value you can use in CSS.
    3. Realize the dimension of the grid track as a flexible ratio to be represented with the new fr unit. In this situation you can either imagine the ratio of the size of one item compared to another along the same axis. Or, you can imagine the ratio a given track occupies out of the whole space, such as 1/3 or 3/4. If an explicit grid system is in play this might be more obvious. If it is not easy to deduce you can first determine the percentage each unit occupies, and then simplify these into fractions. While this seems to be the most work the result is a much simpler and very flexible ratio system moving forward.
    4. Sometimes you might simply want the elements themselves to dictate the size of the tracks. In these cases you can also note auto as the dimension for the track. This is most commonly used for grid row tracks since height is typically fluid in web design.
  3. Note how layout units fill the grid tracks to create grid areas. Mark theses areas and give them names you can use later to set them up with grid-template-areas and assign content to them with the grid-area. Keep in mind:
    • Some layout units might simply fit in a single cell.
    • Other units might span multiple cells creating merged area.

The end result here should be a sense of the overall grid that is applicable to use as the page is reconstructed with CSS. We now also have a stronger sense of the overall visual structure of the layout.

C. Microlayouts

Many contemporary web layouts involve some more detailed areas that should be built as micro-layouts. You should have already identified such areas as compound units. These will implement a nested grid system in the context of that particular compound unit.

You can use the same process you did for outer container units to analyze the nested grid in these compound units. Similar sketches and labels will help you quickly set these up.

Bear in mind that some elements that appear beside others can be accomplished with a simple float:left or float:right setting and might not warrant being treated as a whole grid layout. Likewise, elements that simply stack side-by-side might be best set up using flexbox.

Also watch for microlayouts that repeat throughout a comp such as thumbnail items, each containing several elements laid out using a grid. You will be able to set up this microlayout easily using classes or nested selectors, so only one sketch of the overall microlayout is necessary.

Case Studies

Read the case study introductions »

Corner Bakery

This site has a straight-forward hierarchy that is clearly indicated through the way the elements are designed.

When considering the logical order in which to code this content, most pages are also pretty straightforward, with the content logically running from top-left to bottom right consistently between mobile and desktop.

But the homepage presents an interesting variation for which our method will prove particularly beneficial. The mobile layout presents the masthead followed directly by the location and hours, then the banner, the menu section, orders section, and about section. This would be a logical order to code the page, considering a mobile-first approach: user research suggested that users wanted most of all to check the store's hours and location, and were least interested in a short statement about the store. Therefore, we have numbered the elements according to this priority.

When we transfer these numbers to the same elements in the desktop comp we can see a situation arises that would be challenging to create quickly with traditional CSS. The grid module should make this a snap, but will get to that later in our process.

Turning finally to consider the overall grid at play, we note the following observations on each page:

Act On It

As we consider the markup to use for this application, we can start by thinking about the heading structure. Like many other applications we don't have many headings here to work with for structure. We can at least identify the text of the application branding as the primary heading and plan to mark it with an <h1> element. In the main task list we have the option to organize tasks by their deadline categories, in which case a subheading will be used to label each group. It will make the most sense to mark these as <h2> elements. Other than these headings we will need to rely more on the overall grouping to determine the core structure.

We do have a few lists in the application:

Most of the elements that remain will be treated as either paragraphs or buttons.

Shifting to think about the overall organization in order to determine the structure in which to mark this content, we can quickly distinguish the primary elements of the application thanks to the distinct box-like presentation of these areas. Rather than just a masthead, body, and footer, we have four elements that will be best to present in the following order:

  1. The application branding we can mark with a <header> element. This comes first in the source order as it is very simple and provides the context for all the content that follows.
  2. The category/project navigation we can mark with a <nav> element. This comes next so that the user can navigate to the desired category or project. Since this application will be a single-page application we don't expect many refreshes or new page hits. Yet this could still be a long list for a person using accessibility tools to move through. Therefore we'll provide a shortcut hyperlink to the task list at the top of this group.
  3. The task list itself is the <main> element, containing the content that is the focus of the application.
  4. The application options should be marked as an <aside> and placed last in the source order. They are important for the application to function as planned, but they're not as important to place earlier. Thanks to the CSS Grid Module we can place this at the end of the source order and easily position it where we want it with CSS.

With these groups and overall structure of the application in mind we can move on to consider the grids at play. First, the overall application can implement a grid in order to smoothly make the transition from the mobile to the desktop comps. My analysis suggests two columns and three rows for the mobile version, and two columns and two rows for the desktop version.

Next we look at each of the four main areas and consider whether flexbox or grid is needed. The branding and navigation groups are simple enough to accomplish with basic content styling. Yet the other two areas need further consideration.

The task list itself is laid out in a simple tiling grid. Here we could use either the grid or flexbox. Due to the overall simplicity and desired flexibility from mobile to desktop, flexbox will be simplest, and no further analysis is needed. However, looking closer at each individual task a grid could be useful. On one hand the elements are laid out rather simply with the status checkbox placed neatly beside the due date and the task content. On the other hand, we chose to mark each task by placing the content first, due date second, and checkbox third in the source order. So while traditional techniques or flexbox could be used, we can instead make great use of the source order independence the grid affords and analyze a grid structure here. We find a two-column and two-row setup:

In order to enforce the layout concept while also allowing flexibility later we'll fix the first column and row tracks each at 30px but leave the other tracks at the flexible 1fr setting.

The application options bar is another area with more complexity to consider. Thankfully, the source order matches the presentation order from left to right on the desktop display. Yet on the mobile display things are more complicated with some content hidden by default, and, when expanded, laid out in several rows. My analysis below shows this group's grid and the resulting template with the source order labeled on each grid area. The result is a four-column and three-row grid. We can leave all tracks set to auto to allow the elements inside them to control their size.

This layout flattens into one row with five columns in the desktop view, placing each component in its own cell and hiding the expand/contract button.

Last of all we can analyze the modal window and its contents. Here we have an outer grid that allows us to center the modal window in the overall application frame. In both situations we'll have a three-column and three-row grid. The center cell alone will contain the modal content while the outer ring of cells will be empty.

Finally we consider the inner layout of the task editor modal window. Thankfully we've done some of the work for this component already, as it contains a very similar layout to the task cards in the main task list. Here there's just a little more space for the date and content editing fields, but we can actually reuse the same grid as we planned for standard task cards. Below the task editing fields there is a set of options to select the task type, save the task, and delete the task. This is the preferred source order for the elements so a simple three-column grid should allow us to alter their order. We'll place the delete button in the first cell, the types in the second cell, and the save button in the third cell.

Inside the second cell, the type options can be most simply accomplished using flexbox so no need for further analysis.


Content-out analysis for this site could begin on any page. We'll start with the student's "home" page, the "All My Work" page. Here we see the standard elements of a website including the branding, navigation, main content area, and a footer. All four of these elements are common among all the different pages of the site with some minor variations so work we do here will carry over to the others. Thinking first of the headings our content contains, we can easily spot the primary heading the branding, in the upper-left corner. A short tagline paragraph follows it.

Next, hierarchically, we notice the text, "All my work." Its prominence and bolder style suggest it is another heading in the page, very like the secondary heading. If we compare this to other pages, we see a similarly-styled line near the top of most of the other pages. It is likely that this should be the secondary heading on the other pages as well.

Back on the "All My Work" page other candidates for headings could include the bolded items in the sidebar navigation. However, these form a list of different categories of collections. So despite their bold styling I might instead take note of these as an outer list of collection categories and then the blue items underneath each could be a nested list of specific collections. Seeing no other headings in the page, let's solidify our decision to mark the sidebar items using a list and move on to look for other lists in the page.

Next we take note of the tiles of sample work items in the comp. These work well as a list of student work, each item having a name, date, and image of the work in question. Scanning around the rest of the page the remaining elements can be marked as paragraphs but with classes that might help us adjust their styling, such as the line directly under our secondary heading that is styled larger as lead-in copy.

If we look at the "Sophomore Review" sample collection page we notice many common elements as we identified on the first page. The same branding, navigation and footer are in place; the same secondary heading style and lead-in paragraph is also in place although the text content is different. We can also see similar thumbnail tiles. We have different kind of list here that the enumerated elements indicate—a list of categories in the portfolio. Each category has its name, description, status, and nest list of thumbnail tiles. We can also consider the names as our third-level headings on this page. The thumbnail tiles also two buttons or indicators that show the work items' review status and comments.

An identical heading and list structure is at use in the faculty view for the sample collection and in the collection manager. Yet the collection manager omits actual student work, showing instead options to edit and rearrange the categories and the collection as a whole.

The faculty view of a student's collection allows for one further step, where the professor can see a single work for a more detailed review. This page uses the same branding, navigation and footer and implements a similar secondary heading but there are not third-level headings. There are several paragraphs showing the date and description of the work. There is also a set of images of this work; students can provide up to five images showing different aspects of the work. We can mark this as a list and realize that the first image in the list is the feature image and presented larger than the others in both the mobile and the desktop arrangements.

This analysis completes all the faculty and student views of the application. The public view of the sample collection shows a very similar structure as in the faculty and student views of the same content. Yet here there is no sidebar navigation since this portfolio is to be viewed in isolation from other work. While it might appear that we no longer have a primary heading, we should note that there is still a very subliminal masthead that says, "Work by Student name." This truly fits as the new "branding" or primary heading for this page, so while it looks more like a paragraph, we'll choose to mark it as the new primary heading and simply style it accordingly. Therefore, the collection name is still the secondary heading and the category names are third-level headings. We have the same nested thumbnail lists that we marked in the other views of the sample collection.

Finally the public view of a single work also uses the same revised content structure as the public view of the main collection page. Yet here the secondary heading is the name of the work being viewed and we have a similarly-styled list of images as we had in the faculty view of the single work.

Now we can step back and think about the organization. All student and faculty views include four major components: branding, main content, navigation, and footer. I'd suggest that we mark them in that order. Here we choose to place the navigation after all the content as we expect users navigating this site using assistive technology will prefer not to wade through that navigation every time the land on a new page, but rather, get to the content sooner. Across these pages, the variation occurs primarily in the main section, and this is where we'll also find most of our grid analysis. We'll cover the organization of each of these chunks as we survey the grids we need. Note that the public views use three of these main components, but omit the navigation.

After sketching and analyzing the layouts and microlayouts through our site, we have can identify the following grids: