Larva CSS

This package contains Larva's base CSS, CSS algorithms, utlities, and CSS for JS patterns from larva-js. Design-related utilities e.g. typography, spacing, and color, are generated according to configuration in larva-tokens.

Overview of Functionality

This package provides the source files for the larva.css stylesheet. They are built together and available as larva.css from the @penskemediacorp/larva package, but are available in chunks from this repository in order to support project-level additions to the library.

CSS rulesets are provided in a variety of ways. Many utilities, for example, are generated by iterating over design tokens provided in the SCSS map from larva-tokens, while other rules, such as flex-related utilities or generic styling resets, are added statically since their values are not controlled by tokens. Still others, specifically CSS algorithms, or rulesets that are more complicated than single declarations, are generated by SCSS mixins available in larva-scss (a-grid, a-crop), or are generated from a Node script (a-font - see below for details).

The CSS is ordered intentionally, following the ideology of low specificity and adherence to the cascade via layering similar to ITCSS.

Contribution to this repository is relatively infrequent, and will genereally be for the purposes of increasing the capability of the library.

Development Setup

1. Clone this repository and follow the root README setup instructions.
2. Make changes to this package, paying careful attention to where you are adding CSS, and ensuring it aligns with existing conventions.
3. From the root of this repo, run npm run prod:scss

Note: For more immediate feedback during development, it is possible to run npm run dev in this package, and npm run dev:scss from the root.

Using larva-css in Projects

The easiest way to access the contents of larva-css is by using the built larva.css that is available in the package @penskemediacorp/larva. However, it is possible to use larva-css on its own.

First, install the package:

npm install @penskemediacorp/larva-css --save

Then, using the below details, determine how to load larva-css in your project.

Loading larva-css into your project's build

larva-css files can be accessed as CSS directly by linking the stylesheets available in the build directory, but the current recommended approach is to load them into a local project build and output a single file.

Option 1: Without project-level utility generation (simple)

In your local build, inlcude these files into your main stylesheet:

// larva.scss => larva.css
@import '@penskemediacorp/larva-css/build/css/generic.common.inline';
@import '@penskemediacorp/larva-css/build/css/algorithms.common.inline';
@import '@penskemediacorp/larva-css/build/css/algorithms.common.async';
@import '@penskemediacorp/larva-css/build/css/utilities.common.inline';
@import '@penskemediacorp/larva-css/build/css/utilities.common.async';
@import '@penskemediacorp/larva-css/build/css/js.common.inline';

If you are splitting inline CSS, you can load inline CSS separately by including the following in a file that will be inlined:

// larva-inline.scss => larva-inline.css
@import '@penskemediacorp/larva-css/build/css/generic.inline';
@import '@penskemediacorp/larva-css/build/css/algorithms.inline';
@import '@penskemediacorp/larva-css/build/css/utilities.inline';
@import '@penskemediacorp/larva-css/build/css/js.inline';

Note that at present, there are no js or generic files for async CSS from larva-css.

Option 2: With project-level utilities (complex, not recommended)

This approach is not recommended because accrues technical debt, but it also indicates the areas where the design system is not supporting designs requirements (and vice versa). Generally speaking, this approach allows a project to build the larva.css stylesheet locally and provides areas to plug in additional functionality while maintaining the same, strict architecture.

Prerequisites to this approach:

1. Your project is using the larva binary for its build step.
2. Your project includes a CSS architecture and directory structure that matches that of pmc-spark/assets.

Include the source .scss files from this repository in your top-level common stylesheet in assets/entries/:

In all of the following, replace default with the brand name containing tokens.

// common.async.scss
@import '@penskemediacorp/larva-tokens/build/default.custom-properties';

@import '@penskemediacorp/larva-css/src/01-generic/*.scss';
@import '01-generic/*.common.*.scss';

@import '@penskemediacorp/larva-css/src/02-algorithms/**/*.scss';
@import '02-algorithms/*.common.*.scss';

@import '@penskemediacorp/larva-css/src/03-utilities/*.scss';
@import '03-utilities/*.common.*.scss';

@import '@penskemediacorp/larva-css/src/04-js/*.scss';
@import '04-js/*.common.*.scss';

In a corresponding stylesheet for inline CSS, include only the .inline.scss extensions.

// common.inline.scss
@import '@penskemediacorp/larva-tokens/build/default.custom-properties';

@import '@penskemediacorp/larva-css/src/01-generic/*.inline.scss';
@import '01-generic/*.common.inline.scss';

@import '@penskemediacorp/larva-css/src/02-algorithms/**/*.inline.scss';
@import '02-algorithms/*.common.inline.scss';

@import '@penskemediacorp/larva-css/src/03-utilities/*.inline.scss';
@import '03-utilities/*.common.inline.scss';

@import '@penskemediacorp/larva-css/src/04-js/*.inline.scss';
@import '04-js/*.common.inline.scss';

Next, create a file for project-level tokens in in assets/src/scss/00-tools/tokens.scss that contains the following:

@import '@penskemediacorp/larva-tokens/build/default.map.scss';

$local-tokens: (
	'font-size-12': pmc-rem(12),
	'opacity-075': 0.75,
);

$TOKENS-MAP: map-merge( $default-map, $local-tokens );

And in assets/src/scss/setup.scss, import the tokens:

@import '00-tools/tokens.scss';

Be sure to @import 'setup' at the top of all of your local utility files. Font size is already generated from the larva-css repo, but opacity is not.

If a property is not generated from larva-css, you can iterate over the local tokens map with the following Sass:

// Example: u-opacity.common.inline.scss
@import 'setup';

@each $token, $value in $TOKENS-MAP {
	$token-str: quote( $token );

	@if str-index( $token-str, 'opacity' ) {
		.u-#{$token} {
			opacity: $value;
		}

		// If you would like to generate a hover selector,
		// that could happen here, but media queries need
		// to be in an additional loops to maintain the cascade

	}
}

//
// Media Queries
//


@include pmc-breakpoint( desktop ) {

	@each $token, $value in $TOKENS-MAP {
		$token-str: quote( $token );

		@if str-index( $token-str, 'opacity' ) {
			.u-#{$token}\@desktop {
				opacity: $value;
			}
		}
	}

}

@include pmc-breakpoint( desktop-xl ) {

	@each $token, $value in $TOKENS-MAP {
		$token-str: quote( $token );

		@if str-index( $token-str, 'opacity' ) {
			.u-#{$token}\@desktop-xl {
				opacity: $value;
			}
		}
	}

}

Refer to the larva-css source files in larva-css/src and in the local Larva server, navigate to /css to see available classes.

Things to Know

The .lrv namespace

CSS originating from larva-css .scss files contain a .lrv- namespace. Local project CSS should only contain an a-, u-, or js- namespace.

Utility Naming

Utilities that are generated from larva-tokens, are named as follows:

.lrv-u-{$token-name}

For spacing-XX tokens, they are named:

.lrv-u-margin-{l|r|t|b|lr|tb|a}-{$size}

Where, if the token was spacing-1, the utility would be lrv-u-margin-l-1.

Algorithms

Algorithms are presentationally named CSS patterns that provide functionality difficult or impossible to accomplish with utilities, or where abstractions are useful. Examples are aspect ratio cropping, CSS grid with flex box fallbacks, and SVG icons with ::before and ::after.

Many of the variations for algorithms are generated with mixins from larva-scss, but this is slated to be deprecated in favor of Node scripts in this repository.

.lrv-a-font Generation

The .lrv-a-font algorithm handles the styling for typography styles that are included in a style guide. Each property value and selector is generated according to data from larva-tokens. The SCSS itself is generated from a Node script in this package that is incoporated into the larva-css build.

JS-related CSS

The SCSS files inside 04-js should be imported directly into a local project build, other than js-MobileHeightToggle which is added to the js.common.inline chunk here.