Consolidate foundations package

[mchadwickweb]

As per this discussion:

https://github.com/coopdigital/coop-frontend/discussions/444

This PR adds a new package and build scripts for a combined foundations packages. There have been little to no changes in the code within the package. The goal here was to combine them, provide a clear import for consumers and to fix cascade and specificity issues.

Combining packages into one

This packages aims to replace the following

@coopdigital/foundations-vars
@coopdigital/foundations-global
@coopdigital/foundations-typography
@coopdigital/foundations-grid
@coopdigital/foundations-colors
@coopdigital/foundations-layout

and combine them into a single package called

@coopdigital/foundations

Each package still retains its domain grouping within a sub-directory of the overall package. At the same time there have been some minor changes to the ordering, and splitting utilities and colours down further to allow better partial adoption if needed.

Changes to importing the code

Recommended: Importing everything

@import "@coopdigital/foundations/dist/vars/vars.css";
@import "@coopdigital/foundations/dist/foundations.css";

This is the easiest way to get everything you need.

Importing partials

If you only require partials of the foundations you can use the imports below. Make sure you keep the structure to ensure the cascade works.

/* Variables */
/* Colours */
@import "@coopdigital/foundations/dist/vars/colors.css";
@import "@coopdigital/foundations/dist/vars/colors-cls.css";
@import "@coopdigital/foundations/dist/vars/colors-membership.css";
/* Typography */
@import "@coopdigital/foundations/dist/vars/typography.css";
/* Spacing */
@import "@coopdigital/foundations/dist/vars/spacing.css";
/* UI */
@import "@coopdigital/foundations/dist/vars/ui.css";

/* Base */
@import "@coopdigital/foundations/dist/base/base.css";
/* Typography */
@import "@coopdigital/foundations/dist/typography/typography.css";
/* Layout */
@import "@coopdigital/foundations/dist/layout/grid.pcss";
/* UI */
@import "@coopdigital/foundations/dist/ui/a11y.css";
@import "@coopdigital/foundations/dist/ui/logo.css";

/* Utilities */
@import "@coopdigital/foundations/dist/colors/colors-utilities.css";
@import "@coopdigital/foundations/dist/colors/cls/colors-utilities-cls.css";
@import "@coopdigital/foundations/dist/colors/membership/colors-utilities-membership.css";
@import "@coopdigital/foundations/dist/typography/typography-utilities.css";
@import "@coopdigital/foundations/dist/spacing/spacing-utilities.css";
@import "@coopdigital/foundations/dist/layout/layout-utilities.css";

The one place I changed code was to the utilities. They now have !important rules added to them so that they are immutable and can't be overridden easy by a more specific selector. A problem with the previous packages.

Build scripts

I've added the foundation package specific build scripts into its package.json.

• Clear down dist
• Run linting
• Build foundations using PostCSS
• Build vars using PostCSS
• Run all the above in sequence

"build:clean": "npx rimraf 'dist'",
"build:lint": "stylelint 'src/**/*.{css,pcss}' --fix",
"build:css": "postcss 'src/**/*.pcss' --base 'src' --dir 'dist/' --ext css",
"build:vars": "postcss 'src/vars/*.pcss' --base 'src' --dir 'dist/' --ext css",
"build": "npm-run-all --serial build:clean build:lint build:css build:vars"

There are two PostCSS builds here as we have to pass a different config file for PostCSS to the vars build. That way we can tell PostCSS to preserve the custom properties and custom media properties. The other build will strip them away to remove duplication.

I have then added a Lerna powered build command at root which triggers the package's build command seen above.

npm run build:foundations

[matt-tyas]

This is my favourite PR. I'll test it on Monday but it would be cool if as many people as possible had a look.

[omidantilong]

Ace, just want to double check its still going to be possible to install the packages individually if needed. Eg there may be times when just the fonts and colours are needed without the huge grid import. I'm guessing this won't be an issue as they're still independent on npm? :)

[mchadwickweb]

@omidantilong so the thinking for that scenario would be you still install the one package. Even if you just need fonts. But as part of the build it will do two things:

1. Build a single kitchen sink file called foundations.css
2. Build each partial as their own .css file as well

So in the scenario you're talking about I see it being something like

npm install @coopdigital/foundations

then in your stylesheet

@import "@coopdigital/foundations/dist/vars/colors.css";
@import "@coopdigital/foundations/dist/typography/typography.css";

This would allow that gradual / partial adoption to avoid loads of unnecessary CSS in a project. You're right that the packages will still exist in npm, but they would be flagged as deprecated and point to the migration steps to this package.

I hope this answered your question!

[philwolstenholme]

+1 for making all the utilities !important 👍 I was trying to use a utility the other day to apply some spacing but it was being overridden by some application-level code that had a higher specificity.