Guide 03 · Developer docs

The theme repo and the asset pipeline

Everything a developer changes on a Core dna site lives in its theme repository. This guide covers the repository and its build, printing records in templates, stylesheets and client-side code, and the parts of a site around the main content.

L1–L2
Unit 03 · Stylesheets and SCSS

Several stylesheets from one build

Stylesheets and SCSS Page 19 of 35 Updated

A build can compile several stylesheets: a main one, a checkout one, a vendor one loaded late, one per landing-page family. Two real splits with their sizes and the templates that load them, and the rule for what belongs in each file.

Who this is for. The developer whose main stylesheet keeps growing, or who is adding a section of the site that looks nothing like the rest. Afterwards you can decide whether new styles go into an existing stylesheet or a new entry, and wire a new entry into the build and the templates.

A split by purpose

A production gulp repository compiles four entries, listed in its config/gulp.js, measured gzipped from the committed files:

OutputHoldsLoaded byGzipped
styles.cssTokens, base styles and every site-wide componentThe base template and the checkout's base template27 KB
fonts.cssFont utilities and an icon font trimmed to the icons the site usesBoth base templates1 KB
checkout.cssThe checkout's own componentsThe checkout's base template only7 KB
vendor.cssThird-party widgets: slider, lightbox, phone inputA script, after the page has rendered5 KB

Each entry is listed with its output name:

JavaScript config/gulp.js (extract) 
const entryFiles = [
  { src: 'styles.scss', output: 'styles.css' },
  { src: 'fonts.scss', output: 'fonts.css' },
  { src: 'checkout.scss', output: 'checkout.css' },
  { src: 'vendor.scss', output: 'vendor.css' }
];

In a webpack repository a stylesheet is an SCSS file in an entry's import list, and mini-css-extract-plugin writes it out under the entry's name.

A split by page family

A production Twig repository pairs every JavaScript entry with an SCSS entry, one per landing-page family and one per brand, so each family of pages loads one stylesheet of its own: the home page 30 KB gzipped, a lean standalone sign-up page under 1 KB. The cost of that shape is on Design tokens as custom properties: five brand stylesheets that are nearly identical.

What belongs in each

  • The main stylesheet holds everything a typical page needs to render its first screen correctly. It blocks rendering, so it should be the only stylesheet that does on most pages.
  • A flow with its own base template, such as a checkout or a standalone campaign page, gets its own stylesheet, loaded only by that base template.
  • Styles that can arrive late, for widgets below the fold or opened on interaction, go into a stylesheet loaded after first paint: Critical and deferred CSS.
  • Not one per component. Every stylesheet in the <head> is another request that blocks rendering; a component's styles belong in the stylesheet of the pages that use it.

A stylesheet shared by two entries is compiled twice, once into each output, unless the build is told to share it. Watch for the same component appearing in two outputs when you split.

Go deeper
GuideSCSS structure and naming GuideBundle boundaries GuideBundle size GuideCritical and deferred CSS

Was this page helpful?

Your answer goes to the docs team.