This repository is a set of common PostCSS utilities. It includes variables, icons, and mixins to help follow our products design system. They are consumed by our plugins' PostCSS files.
We have a design system for our plugins. Defining a set of variables and style groupings helps maintain consistency and ease of maintenance throughout all the plugins.
For example, if the primary text color was to change due to a design update, doing a search and replace through all the PostCSS files could be time-consuming and error-prone. Instead, changing it in one place changes the color for all styles consuming the variable.
The repository structure starts at the root level file _all.pcss importing all the repository styles. Variables, icons, and mixins are defined within their respective folders.
Variables are any reusable property values named specifically for their use case. They are found in the /variables folder. Though some variables may hold the same value (e.g. --tec-border-radius-default: 4px; and --tec-spacer-0: 4px), their use cases are very different and should not be used interchangeably.
SVGs are different from the other variables partial files. They are found in /variables/_svgs.pcss and are compiled using the PostCSS Inline SVG plugin.
Icons are SVG icons included in the design system and are found in the /icons folder. They are consumed by the SVG variables partial file /variables/_svg.pcss.
Mixins are groupings of reusable styles and are found in the /mixins folder. These reusable style groupings are often defined by the design system. Mixins are compiled using the PostCSS Mixins plugin.
Making changes to this repository should be done with care. As these utilities are the most upstream in our products PostCSS files, modifications to these files can have a cascading effect downstream.
When making any changes, whether they are additions, alterations, or deletions, consistency is key. Follow naming conventions and groupings so that viewing and editing the files are simple.
Additions are generally safe, as long as the variable names do not conflict with existing variables. Confirm that the variables or mixins you are adding are reusable and a consistent part of the design system before adding.
Alterations should be done carefully, as they will affect all downstream styles using the variable or mixin being altered. Multiple plugins use these styles and should be cross-checked before making the change.
Deletions should also be done carefully, for the same reasons as Alterations above. Removing a variable or mixin that is still being used will create broken styles and/or build failures.
You will need to include this package as a submodule to your plugin/project. To install this in in a custom path, in this case src/resources/postcss/utilities, add the following to your .gitmodules file:
[submodule "src/resources/postcss/utilities"]
path = src/resources/postcss/utilities
url = git@github.com:the-events-calendar/tribe-common-styles.git
To simply install the package in your project use:
git submodule update --recursive --init