-
Notifications
You must be signed in to change notification settings - Fork 14
Glossary
After reading through this Glossary, you will likely want to take a look at the UI Development Workflow here.
A pattern is markup supporting configuration for both data and HTML attribute values via an data object, called the pattern prototype. Each pattern has its own directory inside project/assets/src/patterns, and its own built template part inside project/template-parts/patterns
A pattern's Twig file is the originating source of its markup. Any instance of the markup in another language is the result of the parser, or a script that transforms the Twig.
The parser is the script that transforms the Twig markup so that the patterns can be used in a format appropriate to the consuming application. For example, there is a Twig to PHP parser that results in PHP versions of the patterns, ready for use in WordPress applications.
A pattern's Node prototype is a Node.js file stored alongside its Twig file. It exports an object containing default values for the pattern's configuration e.g. project/assets/src/patterns/modules/header/header.prototype.js.
The JSON prototype is the object exported from the Node prototype, written to a separate file as JSON so that it can provide default values to a consuming project.
A prototype variant is method to extend a pattern's prototype in order to adjust CSS classes so the pattern can be used in a different context e.g. project/assets/src/patterns/modules/header/header.prototype.vip.js
The controller is a file in a consuming project that corresponds directly with a module, and provides data to the module. In this file, the prototype JSON is used to construct a default object with CSS classes. This object properties with dummy data for text, URLs, or image sources, are overwritten with real data. In WordPress themes, these controllers exist in the template-parts/ directory and are named according to the module they control.
Although Larva does not use the same terminology, it is helpful to be familiar with the concepts in atomic design for understanding the pattern types.
Patterns can either originate in the Larva mono-repo, or they can be built at the project-level.
A component is the smallest piece of interface, or "atoms" in atomic design. Components are generally oriented around a single HTML tag, along with a few options. Examples: c-span, c-link, c-button (which can either be a button tag or an anchor tag), and c-icon for pull icons from the SVG sprite.
(Mostly from Larva)
Objects are akin to "molecules" in atomic design. Objects include 1 or more components or objects. Objects are re-usable and should be named according to their semantic HTML, not according to where they are used on the UI. Examples: o-nav is a nav around an unordered list, o-figure, o-tease is supports an image next to a heading and dek, o-email-capture-form is a simple email form with input.
(Mostly from Larva)
Modules are the highest level of interface, and do not have a namespace. Their names should correspond with product and design terminology, and they are not intended to be re-usable, though in some cases, one module is used in multiple places. This should be rare. Modules are build with containing markup, objects, and components. Examples: header, header-sticky, trending-stories-roadblock, author, editors-pick.
(Mostly project-level)
A one-off pattern is a pattern that, for whatever reason, could not be built with the system architecture. These should be extremely rare and avoided at all costs. One-offs tend to occur when we rely on markup output by WordPress, or when we need to manipulate the rendering with PHP. latest-news-stories-river in Art News is an an example, where we needed to programmatically add modules according to an iterator. We should look for a way to avoid this in the future.
(Exclusively project-level)
CSS in Larva is rooted in the concept of functional CSS, or utility-driven CSS where, instead of naming a piece of UI and writing styles for it, CSS is written by composing single-declaration classes in the class attribute. It is almost like writing inline styles. In order to make this approach useful, a code-base must have a means of re-using the composed classes. In Larva, this happens via the JSON prototypes, or classes written directly into markup that are re-used across the site.
The CSS architecture used in Larva is ITCSS, modified to be oriented around functional CSS vs. semantically named classes, and includes the addition of CSS algorithms.
A CSS algorithm is the concept of "A function should do one thing and do it well", applied to CSS. CSS algorithms can really be anything – they can be a group of classes, they can be selector patterns, or they can be large chunks of styling that needs to stay together, such as the algorithm for styling the editor content in WordPress (a-content). The most important part of a CSS algorithm is that exists for - and is named according to – a specific purpose related to styling functionality. To get a better understanding of the what and why of CSS algorithms, check out Lara's talk on the topic, here.
Some algorithms have higher than one class specificity, but other algorithms benefit from their position above utilities in the cascade, and are sometimes overridden by utlities. When using and writing algorithms, be sure to remember that the rules or naming conventions governing one algorithm may not apply to others. The important, non-negotiable part is that an algorithm does one thing.
Utilities are single-declaration classes whose names express their declaration. Utilities are "dumb" in that there should be nothing fancy or special about what they do. Many utilities are generated using a Sass mixin that generates utility classes from a list of tokens or variables. Utilities make up the majority of the stylesheet, and of the classes you will use when styling any given pattern.
The JS namespace denotes CSS that is directly related to JavaScript functionality. These can be directly related to a JavaScript module (indicated by a capitalized / sentence case name e.g. js-Header or js-Flickity) or they can be more utility/algorithm like js-fade or js-sticky-header-slide-down.
These styles are used to update the styles of existing js-* classes according to the state of an interactive element, though if one-off CSS is necessary, they can be used to style the name of a module e.g. the selector .is-mega-open .mega-menu. Usually these are classes like is-expanded or is-hidden.
Tokens are