Why do I always use a git repo to organize my Sass?

Why do I always use a git repo to organize my Sass?

Yesterday I talked about the work a design system for Marcus’ new site and how I organize things at a 10 thousand foot level.

Today I want to talk more about the details of the project. Specifically how I am organizing the project for the front-end build out + living styleguide. We are now descending to the 5,000 foot level.

Here I am using ZURB Foundation and the ZURB Template as a starting basis for my project, but the underlying technologies are interchangeable.

On projects I always create a private git repo on GitHub. This is critical because I have a revision history, can get other people involved with the project at will, and quickly share it with other team members and stake holders. Not to mention I have an offsite backup just in case thing go terribly wrong.

When I first approach a project, I always look at the design and try to think about how can I break it down into smaller patterns.

I ask myself questions like

  • Is this a pattern that exists across the entire site? Examples: header and footer.
  • Is this a pattern specific to a view or page? Examples: Special page flourishes or spacing. Custom hero’s with specific content, sizes and shapes.
  • Is this a pattern that repeats on across several pages, but not across all of them? Examples: Promos, Related Content, etc.

Thinking about this holistically gives me a better idea of how to approach the project.

I do this before I write even a single line of code.

When starting with a brand new project, I might keep everything together in one file so that I can rethink the patterns and how I want to organize my components.

However, I don’t just have a mishmash of a disorganized mess. I make sure that things are more or less in some sort of logical order. When I work this way quickly, I will often leave a comment as a note to myself as to how to categorize the CSS below when I return to it.

At the end I want the same result. I nice logically arrange hierarchy of Scss files that gives a nice overview of the project.

Here is an example of the ~/src/scss folder in my git repo

In this case the app.scss is mission control for the CSS / Sass build. Here I have two directories pages and components. Pages are as you might imagine page specific. Components are not.

Here is how you might break down the questions from above:

  • Is this a pattern that exists across the entire site? Examples: header and footer.

Components, helpers (or sometimes sitewide)

  • Is this a pattern that is specific to a view or page? Examples: Special page flourishes or spacing. Custom hero’s with specific content, sizes and shapes.

Pages or Views

  • Is this a pattern that repeats on across several pages, but not across all of them? Examples: Promos, Related Content, etc.


Without even taking a look at the source code, you can already get an idea about the components that are used. The names should be descriptive and unique.

There is no need to over think the naming bit. #NAMINGISHARD is a popular slack channel for a reason.

Now this might seem to be overkill for a small project, but I assure you you will soon reach the point where things become the “overwhelm.”

This is when you are stuck with a tight deadline and a boat load of technical debt (aka not planning enough) and you push onward. Not great.

When you approach projects with some intentionality and forethought at the beginning, you make the process much more lightweight and maintainable. Even as you progress through day-to-day maintenance mode and make changes, this structure will provide a nice framework for future work.

Tomorrow, I will take more in depth by talking about the Sass file contents and how I have created them with clarity and efficiency in mind.

Why can‘t most front-end engineers pull off a pixel perfect design?

Today a link came across in Front-end Focus called the Front-End Developer Handbook 2017.

Here is the description from the email:

“Cody Lindley’s popular guide to the practice of front-end engineering, how to learn it, and what tools to use, has been updated for 2017.”

If you want to grab a free copy, you can do so here.

But before you do, let me give you a quick warning: this book is a huge list of curated links to free online tutorials.

There is nothing wrong with that, but in this case, it is supported by Front-end Masters (more or less a coding boot camp). They have an interest in taking you through the forest to see the trees, so that you will see the value in an intense curated experience AKA the boot camp.

I am sure they are aware at the massive time required to consume every tutorial linked in this book. Immense amounts of time.

There is certainly value in programs like Front-end Masters, but it is not a one size fits all approach. My experience doing several workshops for other boot camps is while students get an overwhelming overview approach (much like this free ebook) they end up not being able to translate visual designs into responsive websites. Not good.

This handbook highlights the largest distinction between the front-end engineer and the design systems engineer.

The former focuses on frameworks and technology (kind of like the back-end world of business logic thrown into the front-end of today) but fundamentally does not understand how to translate visual designs. They might be familiar with a framework like Bootstrap but when push comes to shove, they are just pushing other people’s buttons on the page. They can do it, but they have little to know understanding of how to change things. Matching a design precisely is likely out of the question.

Compare this with the role of the design systems engineer. An individual trained to translate the visual nature of today’s websites and apps into a fantastic experience. They are an advocate for the user, advocates for the design team, but they are also advocates for the engineering team that will have build on the systems they create.

Marc Otto, the famous creator of Bootstrap, even suggests himself that we should be building our own Bootstraps. This is in 2013. That is like 50 years ago in web time.

This is what I aim to do in my new course, Responsive Design Translation. I will teach you my process on how to build your own design systems. It is the perfect training for the aspiring design systems engineer on your team. Basically, as Marc Otto says, to build your own Bootstrap.

Now I want to explore the handbook more. Here you will find only one table of contents listing for HTML + CSS. This shows you the level of importance the author placed on the subject.

I took a quick look at this chapter and it provides a single link to a free box model tutorial. Super disappointing.

I have talked before how many tutorials covering the box model fail by telling you every single option, not telling you why you would use said opinion, and pretty much zero real world examples of how to use this.

Just skimming the table of contents of this box model tutorial, I can see that this tutorial also misses the sweet spot.

Its no wonder if you don’t have a solid design systems engineer or team on your project you can be thrown to the wolves.

This handbook does not give you a good understanding of what it is like to actually build modern sites, nor give you the tools to be visually accurate in your approach.

In addition, it provides too much information in the wrong areas. It has no less than six CSS architecture’s that they target at the aspiring front-end engineer. This information alone, without a strong understanding of how a site has to be structured or built can lead to many problems down the road.

We are talking huge technical debt before a single line of code has been written. Avoid this like the plague.

Scouring the internet for a bunch of loosely connected articles is not the most efficient path from point A to point B. Nor is grabbing a free ebook that will send you on a similar wild goose chase through the inter webs.

If you are looking to train your next DSE that is something I can help with. I can also assist if you are struggling to scale as you expand to more and more platforms or web properties and don’t have time to keep up.

What‘s the big deal with the Box Model anyway?

Today I was doing research for and upcoming course I am working on. I was looking at the CSS Box Model and how other people were going about explaining it.

It is already explained well. And that is the problem.

In fact, I came across no less than 10 great explanation of all the technical details of the Box Model. You change this and then it looks like this. Very specific information. Super deep.

The big question that is unanswered though is, how do you create common patterns with the Box Model? I am always amazed that this gets skipped.

I have a theory.

For technical topics there are two different approaches. It doesn’t matter if you are looking at books, video courses, or a live workshop.

1) The theory style. For a technical topic this takes the entire thing, all the moving parts and just expands upon the official documentation. At the end you just have knowledge but maybe no way to apply it.

2) The tutorial style. This takes you step-by-step from a starting point to an ending point. At the end you have created something. However, you might not know why you have created it.

Although there are a myriad of books, courses, and workshops that fall into category 1, there are few of category 2. That is because category #2 is very difficult to create.

In both cases, often these books are not always written by active practitioners. That means that any advice or explanation you get might not have any actual relevance to real world problems.

My goal in my new course is to strike a nice balance between the tutorial approach and introduce just enough theory so you answer the why question. But that is not enough. I also plan to show you how to work with professional level designs and what my exact process and approach is to bring them to life.

What emergency pothole repair means to your app

What emergency pothole repair means to your app

Traffic in the Bay Area can be bad, but it seems I have had triple bad luck in the past few weeks. Don’t worry, I assure I will bring this back to Design Systems Engineering.

First, I was thwarted on my way to Santa Cruz by a crazy failed robbery attempt. The robber when confronted, dropped the cash and ran out into the woods. Then later that night stole some clothes and a minivan and tore up the mountain only to be thwarted again. He ran off into the woods again and the manhunt ensued. Supposedly he stole an unmarked police vehicle which ended up in San Jose, right in the middle of one of the largest interagency manhunts I have ever seen in the Santa Cruz mountains.

I talked to some locals, apparently bank robbery is a common thing there.

We ended up driving all the way up the coast and spent most of the day driving for what should have been 40 minutes.

Then, last week on the way out of Merced we came across another un-passable mountain pass. We pulled off the road for hours. We even tried inching forward at about 1/4 a mile per hours, going nowhere fast. We ended up turning around, going right back where we came from to San Jose and spent from 4pm to midnight which should have been an easy 2 hour drive.

Today I am stuck in the East Bay as a catastrophic pothole has caused the entire south bay area to slow down to a standstill. See photo below.

Looking at this, you can see how this could really put a dent in the normal traffic. But let’s take a look from another angle before the repair.

From this angle it doesn’t actually look that bad.

It is easy to take things for granted when you are whizzing by at 10+ the posted speed limit along with all the other commuters. Sure there are potholes, bumps, crazy drivers and other hazards. But you don’t really think about that when driving. It isn’t until the pothole is huge, rebar poking through, and commuters complaining it is a sinkhole the size of the entire lane (and exaggeration, but a sometimes necessary one to get CalTrans on the scene).

With a web app or large site you have worked very hard to establish a certain level of trust. Just as you trust the road won’t fall out from under you when you drive on the freeway.

So there you are whizzing your customers to and fro with efficiency and ease. And then it hits, an “emergency pothole” situation. The problem is on a freeway, people will call the CHP (California Highway Patrol) which will send CalTrans out in droves to handle the repair.

On the web there is often nothing to show that you have disrupted your customers journey. There is no CHP or CalTrans out on the scene trying to fix the situation. But you have the same result, gridlock and a bunch of upset drivers that can’t get to their desired destinations.

Be sure to make your customers happy. One good way to do that is with Design Systems Engineering on your side.

Should I use a graphic design app like Sketch or create a coded prototype?

Should I use a graphic design app like Sketch or create a coded prototype?

Today I read an interesting article by Viljami Salminen titled On Design Tools and Processes. In the article Viljami gives you a flash tour trough the history of graphic design.

His point was that, many of the tools we are using today still use this paradigm of the printed page. Even in tools like Sketch, we are still confronted with what size to set our artboards (the printed page) to.

It is no wonder that when we come to translate such designs; it is hard to get away from this idea of pages.

Even in our world of many devices with a variety of shapes and input methods we still think about the printed page as being 1-to-1 with say a mobile screen. In his article he explains that even if we have a mobile screen, we have an infinite amount of real estate. You just have to swipe to see it.

As we move away (hopefully) from this idea of the printed page–even while we are in this transition–it is critical to think in terms of tools and processes. Ones that foster communication across the dividing lines of specialized teams. Once only the realm of the designer, or perhaps on the realm of the developer, he suggests that using the tools of Design Systems Engineering (style guides, pattern libraries, modular code based design systems AKA front-end code, etc.) should now get many more people involved.

Here is a direct quote from his article:

source: https://viljamis.com/2017/design-tools-processe

The goal of this is to foster conversation and collaboration amongst teams. Tools such as a coded / living styleguide and front-end code (live examples of templates and patterns in the wild) go a long way towards having a common language across teams. You put more effort into the naming of components because you know these names will be used across your organization.

In the article Viljami continues to suggest how we might overcome some of the limitations of our current page driven design tools.

Here is another direct quote from the article: source: https://viljamis.com/2017/design-tools-processes

I have written before about the benefits of solving UX issues in the browser. I also wrote yesterday about the cyclical nature of design systems and gave some strategies on how to navigate from design to development and then back the other way.

The important question here is at which point is it more productive (in terms of team communication) to produce design artifacts in a tool like Sketch verses creating a coded prototype.

I would say the answer depends. It also is possible to use both. The ideal situation is when you use the right tool for the job, and then let one experiment inform the other.

Tools like Sketch and Photoshop will be a better tool for building up elements of a strong visual brand. Making color choices, cropping and placement of images, and even typography are going to much easier to change in this environment.

Creating a coded prototype (or Scaffolding) is a great way to build out entire layouts with pre-built components. Frameworks like ZURB Foundation make this process much faster and consistent, but you could do the same with writing code from scratch. The other thing that the Scaffolding access at is interactivity.

There are methods and tools to export wireframes and mocks from graphic apps so you can create the simulation of interactivity, but often these fall short.

In HTML it is trivial to link to another page. When you make updates, you don’t have to redo the whole lot. (With many other tools like InVision, this can be a bit of a chore)

However, there is a point where you get diminishing results from a specific tool.

I am not in the belief (yet) that code is the end all be all answer to everything. There are things that will simply be faster with a better tool. Sometimes it is quicker to just pick up a Sharpie and a pad of paper.

The key takeaway is you should start to recognize where those gaps exist and ask yourself some questions:

**Is this the best way?

Is this the best tool for the job?

Am I communicating this idea as clearly as I can with the least amount of effort?**

This grey area of working between tools and disciplines is the realm of the Design Systems Engineer. Someone who not only can pick the right tool for the job, but also tell you why they chose that tool.

How do I know people are confused about the Box Model?

Yesterday I spoke about why the box model is fundamentally important in modern front-end code. I got some great responses and in general, most people seem to be confused about this.

This does not surprise me. Over the past few years I have done workshops around the bay area and I have noticed the same thing.

There are two types of people

1) The people that know the box model well and have no trouble creating about visual design on the front-end with CSS.

2) Those that do not understand or are confused or misinformed about the box model. Which is so sad.

And what is crazy about that is, most people I have talked to think they know CSS well. They say stuff like, “Oh yeah, I totally know CSS.” They have, no doubt, spent a ton of time learning all these different parameters, ways to change things around. But somewhere along the way, they never got a good introduction to the fundamentals.

In my workshops, even though sometimes it can make students cry (ok, no one has cried yet, but they often complain that it isn’t as fun as the new hotness), I have always made sure that everyone understands the box model well. I have ran into several students at events later on and they have told me how important that workshop was to their growth as a developer.

There are a few basic things you need to know:

**Understanding the basic structure of it. [the box model]

Being able to see patterns in the wild and mimic them using simple CSS settings.

This means understanding how the box model manifests in large frameworks like ZURB Foundation and Bootstrap or pretty much any other modern website or app.**

I thought, surely there has to be someone giving a great demo on YouTube. Yesterday I watched the top 10 most popular videos that talked about the box model.

I can sum up the content of all of these videos in just a few lines:

1) showing the computed box model in the inspector, but not showing how it works. 2) showing a live example of a box model, but in all cases just some weird colored box that resembles nothing useful. 3) going on a tangent about shadows and changing how the box is calculated (which can confuse and is an edge case). 4) giving you a bunch of information, but at the end you end up with pretty much nothing practical.

So, why tell you all of this? Well, I am hoping to set things straight.

And not just about the box model either. 🙂

My latest project is a course titled Responsive Design Translation and the 1st of 6 modules deals with, you could probably guess it, covers the box model in depth.

Here is a quick listing from my rough outline for the course (keep in mind this is subject to change):

MODULE 1: The Box Model Aha Moment

  • My Box Model Aha Moment – why this is so important
  • What are the moving parts?
  • Using the Chrome Inspector to better understand the Box Model
  • Reverse Engineering ZURB Foundation
  • How is padding used? hint for spacing inside of elements.
  • How is margin used? hint for spacing between elements.
  • All about borders
  • Build a simple button
  • Thinking about state
  • Colors and the box model: bg vs. color vs. border vs. shadow
  • Creating circles
  • Border radius
  • Rounded Button Group example – nth-child vs. nth-last-child
  • Hack: Creating Triangles
  • Spacing for typography
  • Bonus – Don’t set height – pretty much ever
  • Bonus – How to round off spacing errors
  • Border Radius
  • Example: Colored Sections
  • Example: Spacing