After introducing the five atomic rules for starting your scalable front-end architecture, in my previous Brave New World article I addressed the first three of those rules:

  • Defining the HTML layout structure and start working from that base skeleton
  • Controlling your CSS base
  • Using patterns

Something was missing, though. And I couldn’t quite put my finger on it. I’m kidding; I know exactly what was missing. Those first three equipped you with the tools to get your bachelor’s degree in scalable front-end architecture, but now it’s time to step up and get your master’s:

  • Defining your own rules and processes for scalability in OutSystems
  • Creating a platform to centralize all information

Let’s get right back to our universe and see how these two remaining rules are going to help you master a beautifully crafted front-end universe.

Becoming the Master of your Universe

Once you’ve acquired the technical tools that enable you to populate your universe, you need to take your “one giant step for architecture-kind.” So, it’s time to think really hard and lay down the rules and respective processes that will help define:

  • How many planets exist per star system
  • How many galaxies there are and how they’re all swirled up
  • What conditions can sustain (human) life
  • Whether a planet will have {chocolate, beer} or not

Besides, since no one can create a whole universe single-handedly, you need to document everything into your single source of (universal) truth that anyone else can learn from and follow.

Once these processes are in place and well documented, you are ready to start scaling your projects. The issue here is: how many people work on a single project at once? And how many come and go? This turnaround of personnel working on projects dramatically increases the risk of misalignment and the loss of vision. As they usually say, hindsight is 20-20, but there are some things you can do to prevent this.

Because you do not want to end up with a really strange bizarro parallel universe, where everything that should look good ends up quite the opposite, you must ensure that everyone who’s contributing to the project is on the same page.

Therefore, the next step here is to:

4. Define Your Own Rules and Processes for Scalability

(Yes, this is step 4. It is not a typo. Steps 1-3 were in my last article.)

What I mentioned about this rule in my first article can be fully applied to OutSystems and recommended as a best practice for your customers.

We’re quite modular; we do not associate rules and processes that can easily become a bottleneck in the future. So, we like to plan first to avoid future problems. I know, groundbreaking; you probably had never thought about it, right?

What I mean is that we’ve been doing this for a long time now, and we compiled what we learned throughout the years and put it into our Digital Transformation Foundation Playbook. It’s all covered there, in fine detail, but let’s have a look at how you can benefit from what we know.

The first things you need to consider are your team’s strategic goals and objectives. Starting from there, you can define the tactics and dynamics that will be used internally and with other teams. Break those silos, people! Once these are set, a wild need for processes and rules appears.

Process Is Your Friend

Process is amazing. When well defined, that is. If you document your processes well, they are extremely effective for defining practice and behavioral patterns. Do not try to create an “ecosystem” of unfollowable processes just because they’re cool or trendy. Focusing on team discipline and establishing the proper ways that teams should interact with each other will enable agility while reducing the need for maintenance and the propensity for risk.

They should be set to scale easily—not just the code, but the way the team operates.

The exact processes required are different from company to company. However, a few of them are common, transversal, and needed in every proper front-end team out there. Otherwise, you’re not really working as a team.

Here are a few essentials:

  1. Validate assets
    1. Ensure sketch uses standard template format
    2. Validate feasibility
  2. Sizing and work along with UI team
    1. Always exercise a possible merge with other patterns, understanding outcomes and maintenance effort
    2. Estimate effort for task
    3. Provide UI team with effective feedback about bottlenecks
  3. Add tasks to backlog

This is an internal front-end team process, but that team is not an island. Collaboration with other teams is both expected and welcome. In the cases of those who are not aware they are part of this process, you’ll need a method of unified communication so everyone knows the expected outcome of all exchanges.

Good Checklists Prevent Accidents

Well, imagine that you don’t have checklists. I’m sure that your universe will end up with really strange planets and galaxies, which will make people question some of those strange planets forever, right, Pluto?

Checklists are great for so many reasons. You can track when someone completes a task. You can quickly skim them to see if something is missing. Checking off all the tasks imbues feelings of accomplishment and confidence. Here are examples you might create for your team:

  • Pattern Creation Checklist
  • Scalability Checklist
  • Platform Review Checklist
  • Mobile Responsiveness Checklist
  • Testing Checklist
  • Newcomer Onboarding and Ramp-up Checklist

Here’s an example of a scalability checklist. I make mine as descriptive as possible so they’re easy to follow and learn.  And, others have the opportunity to challenge the rules and jumpstart the discussions on whether they still make sense. In addition, descriptive checklists can be revisited without extra explanation, and they promote teamwork.

  • ☐ Do not use CSS in blocks and pages
    • You will add an extra resource for each block
  • ☐ Avoid the use of !important in CSS
    • Just use in special cases like disabled state, or when you want to ensure the override
    • While using an !important, you should always add a comment with a reason. For example: /* as defensive code, to ensure disabled state */
  • ☐ Don’t add inline style in elements
    • No scalability and may affect responsiveness in mobile devices
    • May also affect preview in the OutSystems IDE
    • To override an inline style rule, you will need to add !important to your CSS
  • ☐ Check if the resources are being used
    • Remove the ones that are not being used

Checklists, you know? Use them and abuse them. They will speed up development, reduce overall costs by minimizing error margins and having everyone speak the same language. And that brings us to our next recommendation.

Communicate With Purpose

I love this one. Great communication speeds up the way your team operates and how it coordinates its work with other teams. Say, for example, that your front-end team is working with a UX/UI team—as it should. There are handovers and constant communication that normalizes those exchanges, which will, in turn, provide consistency. That’s how you define the foundations of great UI.

Problems appear when you don’t communicate properly with others. Picking up on the example of those exchanges with a UX/UI team—and though I’m not saying designers are not systematic in their approach—they are used to being constrained mostly by their own creativity.

It’s quite common for designers working on mobile apps to stretch and scale certain elements (for instance, text) so they can properly fit in smaller screens. But you can’t just freewheel the thing; you need to consider base margin and padding sizes, font size and family, form elements, and so on. In collaboration, you define all these attributes that are going to attain proper visual consistency throughout your apps and also evaluate the exceptions to the rules.

And this is something that should be done constantly. Designers are a creative lot, so you can expect exceptions to happen; the front-end team’s role here is to keep it all real and as replicable as possible, so there’s a balance to strike. In sum, you’re applying the dynamics of a great development-slash-design couple.

5. Create a Platform to Centralize All Information

I finished my previous article by asking if applying those rules helped create some sort of paradise, but keeping track of all your Universe’s loose ends can be closer to hell than heaven.

It’s hard to stay aware of all the technical details, let alone tracking all aspects of the day-to-day practice—you know, those that ensure a healthy, scalable, front-end architecture. The best way to address all of this is to create a single source of truth to preach the overwhelming truth of best practices.

Without further ado...

Introducing the Live Style Guide (LSG).

At OutSystems, the LSG is our most sacred front-end document. This is a centralized resource that consolidates all the tenets I’ve been preaching in these articles. As we see it, it’s the framework that will help you define a methodology.

And yet, it is not essential. You can have a standalone app running properly without an LSG. But, I dare you to create a second and a third one, both following the same look and feel without one. I’m sure you’d be rueing the day you decided not to bother with an LSG.

With an LSG, you retain your sanity during the development process because that’s where you centralize the information about all elements used, and where you maintain them.

Creating Living, Breathing Style Guides

Typically, you start an LSG from a base template, a clean “starter app” with all elements you need: all the references for the LSG to work properly, the base theme applied to the project, and a showcase of all patterns and samples that you can pick from to accelerate development. In sum, the LSG goes way beyond boilerplate. It’s like a front-end menu full of visual and already cooked delicacies.

Now, alongside these practical and useful elements in the LSG should be the support documentation for the style guide. It should be the de facto go-to place for all the projects’ UI elements and rules: typography, UI components, and a clear description of the visual language with the respective consolidated front-end code elements.

To eke the most potential out of an LSG, really taking it to the next level, I even challenge you to use your LSG to log releases, document changes, and breaking changes. You can use it to justify your decisions. Not only to stakeholders, product owners, and coworkers alike, but also—and most importantly—to yourself.

When you get right down to it, an LSG should be more than just a blueprint or a map of your universe. It should be a “Living, Breathing Style Guide” that defines the visual aspects of your apps, but that also has a living architecture example of how the application modules should be related. All in all, this effectively makes it a living part of the applications’ underlying architecture.

If you’re wondering how you can achieve this, check out this image. (My avid readers might remember it from my previous article.)

To support a scenario like this you will need an LSG for enterprise architecture, with all the rules and common patterns from your company, and maybe an individual LSG for each channel or application. We see it as an important step in the definition of a full design system based on the company’s branding guidelines.

Rules to Living Style Guide By

Once again, a team that defines a transversal vision for all the projects can manage and maintain this system ever more efficiently. So, to get there, here are some organization rules for a front-end enterprise architecture:

  1. Clear ownership of the UI modules by front-end team
    1. Dev teams should not access the module theme and patterns
  2. Clear mandate that the dev teams use LSG as a reference to work:
    1. Front-end team should send an email to the dev team that reports new additions and changes to the LSG
    2. Promoting LSG as an anchor of information and guidelines for dev teams
    3. Last modification/review date by pattern
  3. Front-end team lives at the intersection of business, UX/UI, and development
  4. Open channel between the dev teams and front-end team
    1. Front-end team hands over new releases to the dev teams
    2. Dev teams should involve the front-end team in their UI development
    3. Front-end team should provide effective support to its internal customers
    4. Front-end team must communicate fully with the dev teams

These rules define clear ownership for your teams, mapped to their skills and expertise. As a result, your teams are focused on what they are really good at. And, since they depend on each other, you will promote better communication between them. Have I mentioned before that proper, constant communication is important?

What will come out of this is a wonderful display of Hyperspatial Engineering where the guy that knows about shorelines will be doing shorelines and not mountains. It’s wonderful to see it in action.

So, what an LSG gives you, at the end of the day, is the ability to be the master of your front-end universe. A place where you can define, name, reshape, make available and document everything. An infinity of possibilities all connected by almost invisible yet always present strings that tie everything together in a harmony that would otherwise be close to impossible to achieve.

Who’s The Biggest Winner In All Of This?

Looking back, you could say that developers will benefit the most. Others might say that the business people are the ones who reap the most benefits because they get stuff delivered faster and have a better overview of what’s going on. How about the UX and UI people? They can really focus on providing the most value and delighting the users, with beautiful UI and a glorious UX.

However, really: who’s the biggest winner, in the end?

Without any question: your users.

They are the biggest beneficiaries in all of this. After all, front-end is all about user interaction. Users are the ones who will have access to better features, that will benefit from the harmonious flow of your apps, or get quicker updates. They are the ones that will find delight in your beautifully crafted universe. They will leave in peace and harmony with no need for… star wars.