Architecture

---

What is this doc?

This doc describes architecture that is used in this Pattern library.

For conventions and implementation details, see conventions.md.

For approach and philosophy introduction, see index.md.

At the beginning, this doc will contain information/notes about the migration path from current state of things. This part will be removed once the migration is over.

Doc adopted: 2/24/2017

Migration expected completion date: 5/26/2017

---

Changing/adding to this doc

If you have a suggestion or addition to this doc, here is a good place to start:

1. Summarize your proposed change and what problem it is solving.
2. Make a PR on Github. Include examples and a proposed migration path, if appropriate.
3. Once PR is merged, create Pivotal Tracker stories implementing your change. Include detailed Acceptance Criteria.

Biggest goals of this migration:

1. Make it easier for full stack developers to use the Pattern Library.

This means:

• Implement a reliable architecture, that is consistent and works as expected.
• Improve navigation and make it easier/intuitive to find things as the library grows.

2. Make it easier for designers to use the Pattern Library.

This means:

• Adopt presentation structure of Pattern Library that facilitates the design process.
• Provide confidence and predictability of "plug-and-play" functionality of the library.

Combining the two items above will increase the productivity of designer-engineer collaboration.

---

Item types

The styleguide has these categories of items:

• BASE STYLES
• ELEMENT
• COMPONENT
• MODULE
• LAYOUT
• TEMPLATE
• EXAMPLE

BASE STYLES

• Denote simple visual standards across the app.
• Are not tied to a specific HTML tag.
• Don't have an html reference.
  These can be mixins, variables, placeholders, but not classes or html tags.
• Have no or very few overrides.
  i.e. times when a custom style is defined for an item usually controlled within Base Styles.

WHY?

For engineers:
Base Styles help to keep code organized and easily changeable. If variable/mixin/placeholder is used, it is very easy to change things. Change in one place -> effect applied to the entire library.

For ticket owners:
Base Styles reduce time necessary to prepare the Acceptance Criteria. No need to specify the colors and details of a shadow, just pick one and write its name.

For designers:
Base Styles certainly introduce limitations. However, in the long run they will make design development faster. It takes less time to reuse existing designs, than to create every time from scratch.

EXAMPLES

Typography, Colors, Gradients and Shadows

ADDING TO THIS CATEGORY

Adding a new Base Style is a design direction: they are design standards.
A good rule of thumb: if designers don't care about something being a Base Style in our app, it probably should not be.

Once something is a Base Style, engineers are responsible for enforcing it in the code.

An example of what that means:
Say, Shadows are Base Styles. Engineer starts a ticket which has a new module with a shadow. The Acceptance Criteria will specify the name of the shadow from Base Styles and engineer should reuse the mixin/placeholder/variable, rather than create new rules, even if they result in the same output.

BASE STYLE OVERRIDE

Sometimes a designer will create a module with a unique shadow (or color, or any other Base Style). When this happens, it will be specified in the ticket. It is important that a specific shadow is used, but it's a one off and should not count as a standard. In this case custom rules for shadow will be used in this module.

MIGRATION TASKS, AKA HOW DO WE GET THERE?

• Implement existing Base Styles in our code (use mixins/placeholders/variables across CSS codebase).
• Designers+Engineers work to identify, add and implement the remaining Base Styles.

ELEMENT

• Semantically tied to a specific html element.
• Can be reused as part of Component, Module or Template.
• If reused with a class, cannot be overridden.
  For example, module cannot directly override rules of an Element class that it happens to be reusing. In this case, module will not reuse an Element class and will define its own rules.
• Doesn't have outer margins/padding.
• Uses complete reset.
  This gives us control for browser interpretation and removes the chance that our code is affected by external libraries.
• Always has a base class and may have chainable modifiers, for example .button.action.mini, or .link.action. However, modifiers can not be nested.
• No coupling between implementation and styling. Use of the specified html tag is not required.
  For example, a style for Link will also work for a div, with appropriate class.
• Specified html tags are styled with defaults for each tag. So, usage of a link without class will give it default PG Link style.
  For example, when no style is specified for an Element inside a module, it will fall back to the default PG style.

WHY?

For engineers:
Elements add a layer of abstraction allowing to extract styles from Components, Modules and Templates. This results in more modularity and an added framework of reusing parts of code and saves times in development.

For designers:
Same as for Base Styles, this adds already designed styles to the designer's arsenal. It is faster to choose between existing designs than to design new every time. The cons are also the same, this introduces limitations for variaty, but in the long term, will save time and effort.

EXAMPLES

Links, Buttons, Lists and Tables

ADDING TO THIS CATEGORY

An item qualifies to be an Element when:

• It is a sematic HTML tag or HTML element
• A small number of stylistic variations of this element comprise the majority of its usage cases in the app.

It is usually the intention that Element is to be used with the html element it is associated with. Having said that, there is no requirement and it will work with any html element.

ELEMENT OVERRIDE

Many html elements in the library will fall back to default Element styles. Overriding this behavior in Modules and Components is normal and necessary.

When Element is used with a class, for example, .button, it may not be overriden by Module, Component, or Template.

MIGRATION TASKS, AKA HOW DO WE GET THERE?

• This category currently doesn't exist at all, so first step would be to identify reusable Elements
• Add reusable Elements to Pattern Library and extract them from their usage in Modules, Components and Templates.

COMPONENT

• May or may not include Elements
• May not include other Components or Modules (with a small exception).
  The exception being small Component items such as Tooltips and Icons, that perform an aside function and can be really mixed up just about anywhere, even in a string of text.
• For elements inside of Components, markup uses html tags or html5 elements where it is semantic to do so.
  One exception to this is typography-type elements. These need to be class selectors for SEO reasons.
• Can be reused as part of Module or Template.
• When reused, cannot be overridden.
• Doesn't have outer margins/padding.
• Expands to fill its parent container.
• May contain multiple nested levels.
• May not be big in size.

WHY?

Being able to plug-and-play Components and Modules is a crucial advantage for a full stack engineer, resulting in speed improvement when developing. For a front-end engineer, Components provide building blocks to be reused in bigger items such as Modules and Templates. As a designer, benefits are much the same as Base Styles: existing building blocks are faster to use than design from scratch. It also gives the website a consistent style/look.

EXAMPLES

Checkbox, Searchbox, Tooltip, Caption Bubble, but also Spacers and Icons

ADDING TO THIS CATEGORY

There is somewhat hazy distinction between Module and Component.

• If an item includes Components (other than Icons and Tooltips), it is probably not a Component.
• If an item is big/has many nesting levels or complexity, it is probably not a Component.
• If an item fits the description of an Element, than it is not a Component.
• If an item is reused multiple times in different Modules or Templates, and fits the description, than it is probably a Component.
• If an item could be further broken down to component parts, then it is probably a module.

One of the hardest things about adding items to the library is naming. Components are abundant and there are many more which can or should be extracted.

When adding new Component:

• Consider creating a variation of existing one, if it shares many similarities with one of the existing Components.
• Ask design if this new item instead could be one of the existing Components. This will save a lot of headache when growing the codebase later.
• Component always has a unique class name. It starts with com-, to keep it consistent with Modules starting with mod-. This will give us clear indication of whether something is a Component, and will aid in code reviews and markup readability.
• Inner classes inside Components do not have to use the com- naming prefix. They should be short semantic names, that are easy to read.
• Nest all of the rules related to parts of the Component under top level Component selector.
  
• Component does not need to be nested under mod-* selector or be inside a Module.

COMPONENT OVERRIDE

Component rules may not be overriden, except for the situations in the above example.

MIGRATION TASKS, AKA HOW DO WE GET THERE?

We currently have Components pattern, but sometimes they are coupled with Modules/Layouts.

• Remove coupling of existing Components/Modules and Components/Layouts.
• Some of the Components are really modules and need to be refactored.
• Some Components have too many variations, and need to be consolidated.
• Others don't need to exist at all and need to be replaced with more common ones.
• Remove mod-* selector with care, because somewhere it might actually have protected against regression. We can do that with more confidence once we remove foundation styles from newer parts of the app.
• Rename top component classes to prefix com- before component name.

MODULE

• May or may not include Elements, Components or other Modules.
• When reused, cannot be overridden.
• Another module may not directly select a Module/Component/Element inside of it.
  For when it is necessary to give the inner Module/Component/Element positioning, use a wrapper element.
• Doesn't have outer margins/padding.
• Expands to fill its parent container.
• Does not use selectors for HTML tags or HTML elements. Inner parts of Module are styled using classes.
• Is medium-to-big in size and/or complexity.
• Can be reused as part of another Module or Template.
• Modules inner classes naming will take clue from the module name and will add a module-specific prefix. So, all of the inner classes of a module named mod-robust-card, will start with robust-. This will enable modules to be fully plug-and-play, where class name clashes will not be an issue inside a module nesting other module

WHY?

Modules are like Components, but bigger and they have slightly different rules for what's inside of them. Benefits are the same as Components.

EXAMPLES

Panels, Cards, Fields, Footer, Nav and Breadcrumbs

ADDING TO THIS CATEGORY

Similar to Components. Consider these things:

• Naming conventions (top class, inner classes).
• Is this a new Module or a variant of existing one?

MODULE OVERRIDE

Modules may not be overriden by any of its parents. They are completely the same as anywhere they are used. If an altered version is needed, a variation can be created (with guidance and approval of designer)

MIGRATION TASKS, AKA HOW DO WE GET THERE?

We currently have Modules pattern, but sometimes they are coupled with Layouts.

• Remove coupling of existing Modules/Layouts.
• Some Modules have too many variations, and need to be consolidated.
• Others don't need to exist at all and need to be replaced with more common ones.
• Some Modules contain Component-type parts that need to be extracted into Components.

LAYOUT

• Are utility mixins or placeholders, depending on whether arguments are necessary.
• Control positioning, gutters and margins of blocks inside of it.
• Do not control anything else, including typography.
• Are empty space without content.
• Do not select any specific components, elements, modules or even classes inside of them, only general selectors like child, sibling, universal selector, etc.
• Do not have html reference (layouts are mixins and placeholders, but not classes).
• May be overridden in code if necessary.
• May be reused by Modules, Templates or even Components.
• Are internal developer tools, and are not included in public facing Pattern Library.
• Have clear documentation.

WHY?

Layouts are different than Modules or Components, or even Templates. Layouts are purely utility in function, and are reused in other parts of the library. Layouts will reduce the code repetition and increase modularity, allowing to reuse more of mundane repetitive CSS under the hood. It will also reduce ambiguity of Layout-vs-Page objects, making a clear line between the two.

EXAMPLES

layout-equal-columns, arrange-children-in-a-row, but also existing "Layouts" such as layout-banner and layout-hero.

ADDING TO THIS CATEGORY

Addition to this category will be more of a engineer decision than any other category. This is about reusable mixins and placeholders behind the hood, so design won't care about it.

An item here should be added if:

• It fits description and it does not control the whole page.
• Have repeated usage.
• No existing Layouts satisfy the requirement.
  Sometimes, an existing Layout may be adjusted slightly to accomodate for expanded use.

The naming of Layouts mixins or placeholders should start with layout-.

Every addition should also include detailed documentation and/or pattern library example.

LAYOUT OVERRIDE

Layout mixins and placeholder may be overriden in code, if necessary. Some of that usage variation may also be addressed by arguments (mixins).

MIGRATION TASKS, AKA HOW DO WE GET THERE?

Our current Layout needs are met with a combination of Layout classes and mixins/placeholders, but more heavy on classes.

• Convert all current Layout classes mixins/placeholders and document them properly.
• Identify, add and extract new Layout mixins/placeholders, based on reusable parts of current code.

TEMPLATE

• Are page objects that include all other building blocks inside of them.
• May not override or select specific Components, Elements or Modules that are inside of them. When there is need to position them, a wrapper element is used.
• May have variants, where necessary.
• Will heavily reuse Layouts mixins and placeholders.
• Control positioning-related rules, margin and padding of blocks inside of it, and also typography rules (typography rules must be class selectors for SEO reasons).
  Templates may control typography but only for items that are located directly underneath them (i.e. not part of a Module, Component or Element).
• May not control any rules other than positioning-related and typography. Thet are empty space without content.
  
• Each "type" of page in PG app will be its own Template. There will be no page in the app that is not some sort of Template.
• There will only be one Template per page in the app.
• There will be a small number of Templates (less than 10 for current neads).

WHY?

Templates are the final umbrella-type objects that don't have any heavy rules by themselves but their purpose is to combine and position blocks of content. Templates build upon the pattern that has worked well for us on pages such as Navigator and Comparison. Templates will work well with the other items in the Pattern Library, and complete the modular approach set by them.

EXAMPLES

Navigator, Comparison, Landing/Homepage, Affiliate and About.

ADDING TO THIS CATEGORY

Templates classnames will start with tem-, to keep incline with modules and components, and make them easily identifiable in the markup.

TEMPLATE OVERRIDE

There are no bigger items to override Templates. Templates should also not have custom-usage overrides. Use variants or different markup for this purpose.

MIGRATION TASKS, AKA HOW DO WE GET THERE?

We already have some of these Templates known as Layouts. For example, Navigator and Comparison.

• Decouple existing Templates from their contents and make them conform with the rules above.
• Identify and add new Templates, if any, to make each page in the app belong to a type of Template.

EXAMPLE (CATEGORY)

• Contain no CSS, only examples of markup.
• Have real text content and real images.
• Serves as a "feature test" to ensure that all works together with real content.
• Are real-world examples of pages in the app.
• Each Template will have an Example page. In addition, some other complex Modules/Components may also have Example pages.

WHY?

Big reason for examples is to enable to monitor/catch regressions (Percy). But also, Examples will simplify some of the engineering work as well, providing a full final picture of how the item looks with real content. Examples do not have to be Templates necessarily and can include Modules/Components if they are complex enough to warrant a feature test (a good example of that is the new nav).

For designers, it will provide the complete look of a new page, before it is implemented in the markup.

EXAMPLES

All of the Templates (above) New Nav

ADDING TO THIS CATEGORY

An Example should be added for each new Template. Also, for other items, if they are complex enough or have many states. For other items, will be on engineer's discretion if they think it is likely to break when it has real content inside of them.

MIGRATION TASKS, AKA HOW DO WE GET THERE?

We already have some examples.

• Expand Examples to include all Templates and some complex modules/components.