CSS Guide

Using CSS

Overall you'll most likely be writing far fewer lines of CSS thanks to the Tailwind tooling of the theme. However, CSS files are here to act as a supplement to Tailwind styles in places like typography classes, component specific tweaks, button styles, etc. See below for the b-b-b-breakdown.

CSS Folder Structure

The sass folder is initially structured into 4 directories:

• Base
• Common
• Components
• Pages

Each directory houses CSS files that have access to token definitions, tailwind utilities, and variable definitions.

Base

This directory contains resets, tailwind imports, and utility classes. As well, this directory is the landing zone for generated variable definition files. The _generated-variables.css file here will provide CSS variables for each token. Changes to this file will be overwritten but the npm run format.tokens command.

Common

This directory contains theme primitives such as buttons and typography.

Components

This directory is similar to the Pages directory in that it's meant for edge case overrides, fine grain tweaks, or tailwind definition grouping for individual components. Adding a file with the component-name and using bem syntax you can include those rules.

Pages

This directory contains page level styles that aren't handled for by component tailwind classes. If you need to override a given page hero or another page section, add a file with the corresponding page-title to this directory and include those rules.

Dev Guide & Setup

All files in this directory have access to Tailwind's tooling and definitions via the @apply syntax. As well you can include token definitions via the generated variables in the Global directory. Some theme level definitions will be required as the project is getting setup.

Typography

In the css/common/typography.css file you can define classes for each type of html template tag. Some basic definitions have been provided mostly via @applying generated tailwind rules i.e.

body {
  @apply font-sans;
}

.h1,
.h2 {
  @apply font-serif;
}

These definitions will want to get enhanced and built out according to the project but will jump start the work.

Button Styles

Similar to typography in the css/common/buttons.css file you can define global styles for buttons on the site. Again, some basic definitions have been provided mostly via @applying generated tailwind rules. However, buttons in particular will need to be built out according to the project designs.

No SCSS No Problem!

We're using the PostCSS engine to power up basic CSS. The syntax is slightly different from SCSS to CSS.

Variables

Defining variables

SCSS:

$blue: #0000FF;

CSS:

:root {
   --blue: #0000FF;
}

Using variables

SCSS:

color: $blue;

CSS:

color: var(--blue);

Media Queries

SCSS: defined and applied with a mixin

@mixin mq($screen) {
  @if ($screen == "md") {
    @media (min-width: 769px) {
      @content;
    }
  }
}

...

@include mq(md) {
  color: $blue;
}

CSS: defined and applied with custom css media queries

@custom-media --bp-md (min-width: 769px);

@media (--bp-md) {
  color: var(--blue);
}

Nesting styles

SCSS:

.field-name {
  .field-child {
    color: $magenta;
  }
  &.field-modifier {
    color: $blue;
  }
}

CSS:

.field-name {
  .field-child {
    color: var(--magenta);
  }
  &.field-modifier {
    color: var(--blue);
  }
}

For more detail on nesting in particular see the postcss-nested plugin docs.

What about Mixins?

Use a class instead. If styles need to be repeated, try adding a new utility, or using a reusable twig template.

What about Extends?

There are no extends. However, @apply is here in a pinch.

Editor Integrations

• VSCode