Starter guide to style conventions in web development

If a web development team doesn’t have a shared record that documents naming and style conventions, coding inconsistencies will arise, users will grow frustrated, and the project will take a hit. Follow our tips to make work easier for developers, designers, testers and content managers.

Subscribe to our blog

Today’s digital experiences are a combined effort of large teams Product owners, strategists, business and functional analysists, copywriters, project managers, designers and developers, all the way to application managers, content contributors and testers. Each one contributes a significant piece to the final product.

While most web development projects follow a linear trajectory throughout their development (planning, workshops, wireframing, design, development, testing, support, etc.), rarely all of its contributors are actively involved in each phase. As a result of this disconnect between the phases of development and its different contributors, there’s a sort of Babylonian confusion: an idea is translated into a design, which is converted into code that becomes part of a web content management (WCM) system, where it may be presented to a content author in an entirely different form (and name) than originally conceived.

This unfortunate side effect happens all too often and can result in confusion, frustration or even total mayhem. Even small variances can quickly become major inconsistencies that drive team members apart, where they should ideally be involved, connected and have a sense of ownership of the final product. But how to enable all contributors to speak the same language? It’s my belief that design can play an important role in the solution for this problem.

Find out what benefits a coding style guide provides and the basic guidelines towards a shared language and a more maintainable codebase.

Use clear and unambiguous definitions

If we were to leave it up to a developer to come up with the names of our website’s components, we might end up with things like “the big blue button”, “some text” or “user actions in the top corner” which might not be an ideal scenario. Luckily, some user interface concepts have become common knowledge, such as header, footer, button, link, image, etc. UI or front-end frameworks such as Bootstrap or Material Design have introduced concepts like a grid system, menus, cards, dropdowns, accordions and many more, which are great contributions to a common language among web teams.

Focus on consistency

There’s an emerging trend in modern web development towards a component-based approach. A website is split into small parts with very specific functionality, which can be combined and arranged into bigger configurations according to the content author’s preference. When applied to design, this approach is referred to as a design system. The creator of such a system, acknowledging the atomic nature of UI components, strives to create a visual representation that reflects the interconnectivity of its elements. The adherence to a strict set of rules in design benefits the visual identity and coherence of the end result - everything looks like it belongs together. But this consistency has an equally important effect on the code: the less code that needs to be written, the less code needs to be maintained. This is where using naming conventions to give the proper name to a component becomes crucial.

Enforce naming conventions across all website project stages

If a component has been given a recognizable, specific name in the design phase, this name should be reflected in the code (via CSS class names or custom HTML elements) and ultimately in the author interface of the WCM. Should a problem occur in any of the website’s pages, it would be much easier to pin point which component(s) are responsible for the error, by anyone involved (developers, testers or content managers) using the browser’s inspect feature.

Take advantage of CSS custom properties

There are many more visual properties that could also benefit from a codified approach. The colors that are used in a digital application should be given readable names so that they are recognizable without the need to decipher their hexadecimal value. Modern design systems emphasize the importance of a primary and a secondary color, on which the entire palette of the application is based. As with components, developers should refer to these concepts in the naming conventions they establish to be used within the code (e.g. by using CSS custom properties instead of hexadecimal color values) and within the content authors’ interface.

Don’t forget text styles

The same applies to text styles: a designer needs to define and create clear, recognizable names for each of the text styles that will be used within the visual system. Other visual properties that could benefit from adhering to a predefined, naming convention list include margins, borders, and many more.

Make sure everyone agrees on what the standards are

Modern UI designers should, apart from being creative, be familiar with how their work will be implemented technically, be outspoken and articulate about the elements that make up their creation and why they are designed that way. The design should be the ultimate reference throughout the entire development process.

Keep your style guide alive

Ideally, whenever a new component is developed, it should be added to a comprehensive list naming conventions of all the visual elements that can be used within the application. Since development is in constant motion and certain elements of the design might be changed in later stages (much to my and other developers’ chagrin), this style guide should be dynamic: it should reflect the current state of the project’s code. It’s also a designer’s responsibility to verify the correct implementation of their work in this style guide, in order to catch any problems as soon as possible.

In conclusion, thinking about what it is that we’re creating ultimately helps get better work done and have a much more productive collaboration. Involving your entire team to define a strong, articulated set of initial agreements can resolve many problems further down the road and keep everybody on the same page. Although this might be a long process, coding style guides should be implemented as early as possible to avoid later confusion. I for one will always be an advocate for the use of strong naming concepts in all digital experience projects.

Does your team have a web development style guide or standardized naming conventions? Tell us your experiences.

Published on    Last updated on 26/09/2019

#Web Development

About the author

Mathijs Provoost is a Front-end Web Developer at Amplexor, based in Belgium. He’s responsible for writing and maintaining well designed, testable, efficient code for our clients’ public facing web-sites, web applications and lines of IT infrastructures. Mathijs also works closely with designers, developers, QA testers and support services teams to set the direction of our front-end technologies and lead their implementation.