Layers
Goldilocks-CSS is designed to allow customization of the theme through the use of layers. Layers are used to set the initial theme settings and can be extended to use custom settings. Goldilocks-CSS uses six layers to control the page decoration. The layer order is base, elements, extended, extras, layout and custom:
- Base: sets up global variables, theme, core HTML resets and helpers (colours, positioning, spacing, etc.;
- Elements: controls typography, buttons forms, tables, images and other common items;
- Extended: defines elements such as badges and avatars as well as common components such as accordians, breadcrumbs, cards and navigation;
- Extras: defines additional elements (progress bars, ribbons and tooltips) and components (modals, popovers, carousal and charts);
- Layout: defines page layout, grids, sections and other semantic tags (note that layout has a higher priority to stop any interference from item control);
- Custom: for the designer to override any settings or to add their own values.
Initial Variables with Default Settings
File initial-core-variables.css contains the CSS variables that drive all the elements and components.
:root {
/* version 1.0.0 - April 7, 2026 */
/* awareness variables - for info only */
/** typically (and sadly) @media does not support variables; so we need to hard code the mobile breakpoint **/
/** files affected: gridbox.css, level.css, page.css, pagination.css, blockquote.css, navbar.css, sidebar.css, image.css, media.css **/
--mobile-breakpoint: 576px; /* or 36rem at 16px base size */
/* Base measurement unit to be used for font, margins and padding */
/* changing the base html factor allows a user to change the font sizes to meet accessibility needs */
--base-html-factor: 100%;
--base-rem: 1rem;
/* Typography */
/** Note: text colors are set in file: initial-colors.css **/
/** Default is to use system fonts as much as possible **/
--family-sans-serif: "Tahoma", "Helvetica Neue", "Helvetica", "Arial", "Segoe UI", "Roboto";
--family-serif: "Georgia", "Times New Roman";
--family-monospace: monospace;
--render-mode: optimizeLegibility;
/** Define font weights here **/
--weight-light: 300;
--weight-normal: 400;
--weight-medium: 500;
--weight-semibold: 600;
--weight-bold: 700;
/** note: adjustable typography is set in the file: typography.css **/
--base-font-size: var(--base-rem);
/** Text line heights to match size **/
--line-height-125: 125%;
--line-height-150: 150%;
--line-height-175: 175%;
--line-height-200: 200%;
/** Sizing pattern - typically for text **/
/*** typical factors: (see https://typescale.com)
1.125 (Major Second) - A balanced choice for most UI designs.
1.2 (Minor Third) - Suitable for more information-dense UI designs.
1.25 (Major Third) - A very popular choice that provides enough distinction between heading levels.
1.333 (Perfect Fourth) - Offers a slightly larger, more dramatic scale.
***/
--size-factor: 1.125;
--size-7: calc( var(--base-font-size) / var(--size-factor) ); /* Example 1.125 scale factor: --size-7 = 0.9rem; */
--size-6: var(--base-font-size); /* Example 1.125 scale factor: --size-6 = 1 rem; */
--size-5: calc( var(--size-6) * var(--size-factor) ); /* Example 1.125 scale factor: --size-5 = 1.13rem; */
--size-4: calc( var(--size-5) * var(--size-factor) ); /* Example 1.125 scale factor: --size-4 = 1.27rem; */
--size-3: calc( var(--size-4) * var(--size-factor) ); /* Example 1.125 scale factor: --size-3 = 1.42rem; */
--size-2: calc( var(--size-3) * var(--size-factor) ); /* Example 1.125 scale factor: --size-2 = 1.6rem; */
--size-1: calc( var(--size-2) * var(--size-factor) ); /* Example 1.125 scale factor: --size-1 = 1.8rem; */
/* Grid Key Variables */
--gutter: calc(3 * var(--base-rem)); /** grid column gutter **/
--grid-min-px-width: 100px; /** minimum absolute column width in a grid layout **/
--grid-min-width: calc(5 * var(--base-font-size)); /** minimum relative column width in a grid layout **/
/* basic spacing values */
/* based on https://medium.com/user-experience-design-1/ui-cheat-sheet-spacing-friendships-e37a6fccc407*/
--space-element: var(--base-rem);
--space-block: calc(2 * var(--base-rem));
--space-collection: calc(4 * var(--base-rem));
--space-container: calc(5 * var(--base-rem));
/* Flexbox element spacing */
--gap-row: calc( 0.75 * var(--base-font-size) );
--gap-col: calc( 0.75 * var(--base-font-size) );
/* Elements Controls */
--pad-horz: var(--base-font-size);
--pad-vert: calc( 0.5 * var(--base-font-size) );
--pad-horz-small: calc( 0.5 * var(--base-font-size) );
--pad-vert-small: calc( 0.25 * var(--base-font-size) );
--padding: calc(0.75 * var(--base-font-size));
--padding-normal: var(--base-font-size);
--padding-medium: calc( 1.5 * var(--base-font-size) );
--padding-large: calc( 3 * var(--base-font-size) );
--mar-horz: calc( 0.5 * var(--base-font-size) );
--mar-vert: calc( 0.5 * var(--base-font-size) );
--margin: var(--base-font-size);
--margin-form: calc(1.5 * var(--base-font-size));
--margin-medium: calc(3 * var(--base-font-size));
--margin-large: calc(5 * var(--base-font-size));
/* Component Controls */
--radius: calc(0.5 * var(--base-font-size));
--radius-small: calc(0.5 * var(--radius));
--radius-comp: calc(1 * var(--radius));
--radius-elem: calc(1.5 * var(--radius));
--radius-rounded: 10000px;
/* Navbar settings */
--navbar-height: calc(4 * var(--base-font-size));
--navbar-offset: 0;
--navbar-z: 30; /* z-index to ensure that navbar gets priority */
/* Widgetbar settings */
--widgetbar-height: calc(2 * var(--base-font-size) + 1rem);
--widget-z: 30; /* z-index to ensure that navbar gets priority */
/* Breadcrumb setting */
/* other options are: arrow-separator = ">", bullet-separator = "\02022" or quote-separator = "\BB" */
--breadcrumb-separator: "/";
/* magazine normal width */
--magazine-width: 40ch;
/* carousel image height */
--carousel-image-height: calc(8 * var(--base-font-size));
--carousel-image-width: calc( 4 / 3 * 8 * var(--base-font-size)); /* aspect ratio of image */
/* uri encoded icon for select and dropdown - chevron down and initially set to primary color */
--indicator: url("data:image/svg+xml;charset=utf8,\
%3Csvg%20xmlns='http://www.w3.org/2000/svg'\
%20viewBox='0%200%2024%2024'%20\
fill='none'%20stroke='currentColor'%20stroke-width='3'%20stroke-linecap='round'%20stroke-linejoin='round'%3E\
%3Cpolyline%20points='6%209%2012%2015%2018%209'/%3E\
%3C/svg%3E");
--indicator-down: url('data:image/svg+xml;charset=utf8,\
');
--indicator-up: url('data:image/svg+xml;charset=utf8,\
');
--indicator-right: url('data:image/svg+xml;charset=utf8,\
');
}
Initial Colour Settings with Default Settings
File initial-colors.css contains the CSS variables that drive all colour choices for light / day theme.
/* initial-theme-colors.css */
/** main theme color definitions **/
:root {
/** main theme color definitions use https://www.colorhexa.com/ or https://paletton.com/ to build colors **/
/** main theme colour parameters - based on complement color selection **/
--main-color: 185; /** primary hue value used by charts **/
/** build main theme colours **/
--primary-raw: 185 58% 32%;
--secondary-raw: 37 14% 50%;
--complement-raw: 22 94% 56%;
--primary: hsl(var(--primary-raw) / 100%);
--secondary: hsl(var(--secondary-raw) / 100%);
--complement: hsl(var(--complement-raw) / 100%);
/* define text colours for main theme, adjusted for expected theme colour luminosity */
--primary-text: hsl(185,65%,19%);
--secondary-text: hsl(37,20%,28%);
--complement-text: hsl(22, 82%, 28%);
--primary-text-invert: hsl(185, 55%, 96%);
--primary-text-invert-dark: hsl(185, 55%, 96%);
--secondary-text-invert: hsl(37, 28%, 97%);
--secondary-text-invert-dark: hsl(37, 28%, 97%);
--complement-text-invert: hsl(22, 80%, 12%);
--complement-text-invert-dark: hsl(22, 80%, 97%);
/* optional light colors; use carefully as accessibility is hard to achieve */
--primary-light: hsl(185,55%,96%);
--secondary-light: hsl(37, 24%, 92%);
--complement-light: hsl(22,85%,93%);
--primary-dark: hsl(185,65%,19%);
--secondary-dark: hsl(37,20%,42%);
--complement-dark: hsl(22,88%,40%);
--link: hsl(240,52%,48%);
--link-visited: hsl(280, 52%, 48%);
--link-light: hsl(240, 50%, 93%);
--link-dark: hsl(240, 55%, 38%);
--link-text: hsl(240, 55%, 38%);
--link-text-invert: hsl(240, 52%, 97%);
--success: hsl(152, 47%, 48%);
--success-light: hsl(152, 50%, 92%);
--success-dark: hsl(152, 55%, 30%);
--success-text: hsl(152, 70%, 14%);
--success-text-invert: var(--black);
--warning: hsl(38, 92%, 54%);
--warning-light: hsl(38, 88%, 93%);
--warning-dark: hsl(38, 90%, 44%);
--warning-text: hsl(38, 65%, 22%);
--warning-text-invert: var(--black);
--danger: hsl(4, 70%, 50%);
--danger-light: hsl(4, 74%, 93%);
--danger-dark: hsl(4, 62%, 40%);
--danger-text: hsl(4, 65%, 32%);
--danger-text-invert: var(--white-10);
/* additional greys */
--black: color-mix(in hsl, black, var(--primary) 5% );
--black-850: color-mix(in hsl, black, var(--primary) 10% );
--black-800: color-mix(in hsl, black, var(--primary) 15% );
--grey-darker: color-mix(in hsl, hsl(0, 0%, 25%), var(--secondary) 5% );
--grey-dark: color-mix(in hsl, hsl(0, 0%, 40%), var(--secondary) 5% );
--grey: color-mix(in hsl, hsl(0, 0%, 60%), var(--secondary) 5% );
--grey-light: color-mix(in hsl, hsl(0, 0%, 85%), var(--secondary) 5% );
--grey-lighter: color-mix(in hsl, hsl(0, 0%,95%), var(--secondary) 5% );
--white-100: color-mix(in hsl, white, var(--secondary) 16% );
--white-50: color-mix(in hsl, white, var(--secondary) 12% );
--white-25: color-mix(in hsl, white, var(--secondary) 8% );
--white-10: color-mix(in hsl, white, var(--secondary) 2% );
/* set the body level colours for light mode*/
--bg-main: var(--white-10);
--bg-grid: var(--white-25);
--bg-container: var(--white-25);
--bg-component: var(--white-50);
--bg-element: var(--white-100);
--bg-main-invert: var(--black-850);
--bg-highlight: var(--warning-light);
--border-main: var(--grey-light);
--border-main-darker: var(--grey);
--text: var(--black-800);
--text-invert: var(--white-10);
--text-light: var(--grey-dark);
--text-darker: var(--black);
--text-elem: var(--black-800);
--text-comp: var(--black-800);
--text-invert-ter: var(--white-50);
--text-code: color-mix(in hsl, var(--complement), black 25%) ;
/** Common shadow treatment for containers, components and elements **/
/*** see https://www.joshwcomeau.com/css/designing-shadows/ ***/
--shadow-raw: var(--secondary-raw);
--shadow-container: 0 1px 2px hsl(var(--shadow-raw) / 0.12), 0 2px 6px 2px hsl(var(--shadow-raw) / 0.15);
--shadow-component: 0 1px 3px hsl(var(--shadow-raw) / 0.12), 0 4px 8px 3px hsl(var(--shadow-raw) / 0.18);
--shadow-element: 0 2px 3px hsl(var(--shadow-raw) / 0.12), 0 6px 10px 4px hsl(var(--shadow-raw) / 0.21);
}
Alternate Dark Colour Settings with Default Settings
File initial-dark-theme.css contains the CSS variables that over-ride the default colour choices to provide night / dark mode colour themes.
/* initial-theme-dark.css */
/** main dark theme color definitions
use https://www.colorhexa.com/ or https://paletton.com/ to build colors
**/
.main-theme-dark {
/** build main theme colours **/
--primary: color-mix(in hsl, hsl(var(--primary-raw) / 100%), white 10% );
--secondary: color-mix(in hsl, hsl(var(--secondary-raw) / 100%), white 10% );
--complement: color-mix(in hsl, hsl(var(--complement-raw) / 100%), white 10% );
/** define text colours for main theme, adjusted for expected theme colour luminosity **/
--primary-text: hsl(185,65%,22%);
--secondary-text: hsl(37,20%,32%);
--complement-text: hsl(22, 82%, 32%);
--primary-text-invert: hsl(185, 55%, 96%);
--primary-text-invert-dark: hsl(185, 55%, 96%);
--secondary-text-invert: hsl(37, 28%, 97%);
--secondary-text-invert-dark: hsl(37, 28%, 97%);
--complement-text-invert: hsl(22, 80%, 17%);
--complement-text-invert-dark: hsl(22, 80%, 97%);
--primary-dark: hsl(185,65%,22%);
--secondary-dark: hsl(37,20%,45%);
--complement-dark: hsl(22,88%,43%);
/** define colours for links, success, warning, danger **/
--link: hsl(240,52%,53%);
--link-visited: hsl(280, 52%, 53%);
--link-light: hsl(240, 50%, 95%);
--link-dark: hsl(240, 55%, 43%);
--link-text: hsl(240, 55%, 43%);
--link-text-invert: hsl(240, 52%, 20%);
--link-text-invert-dark: hsl(240, 52%, 97%);
--success: hsl(152, 47%, 53%);
--success-light: hsl(152, 50%, 95%);
--success-dark: hsl(152, 55%, 35%);
--success-text: hsl(152, 70%, 19%);
--success-text-invert: hsl( 152, 100%, 97%);
--success-text-invert-dark: hsl(152, 47%, 97%);
--warning: hsl(38, 92%, 58%);
--warning-light: hsl(38, 88%, 95%);
--warning-dark: hsl(38, 90%, 48%);
--warning-text: hsl(38, 65%, 27%);
--warning-text-invert: var(--black-800);
--warning-text-invert-dark: hsl(38, 92%, 97%);
--danger: hsl(4, 70%, 55%);
--danger-light: hsl(4, 74%, 97%);
--danger-dark: hsl(4, 62%, 45%);
--danger-text: hsl(4, 65%, 37%);
--danger-text-invert: var(--white-10);
--danger-text-invert-dark: hsl(4, 70%, 97%);
--grey-light: hsl(0, 0%, 75%);
--grey-lighter: hsl(0, 0%, 85%);
/** invert colours for elements and components **/
--border-main: var(--grey);
--border-main-darker: var(--grey-light);
--bg-main: var(--black);
--bg-main-invert: var(--white-10);
--bg-grid: var(--grey-darker);
--bg-container: var(--grey-darker);
--bg-component: var(--black-800);
--bg-element: var(--black-700);
--bg-highlight: var(--warning-text);
--bg-hover: var(--grey-dark);
/** invert or adjust colours for text **/
--text: var(--white-50);
--text-invert: var(--black);
--text-light: var(--grey);
--text-darker: var(--white-50);
--text-elem: var(--white-25);
--text-comp: var(--white-25);
--text-invert-ter: var(--black-800);
--text-code: var(--secondary-light);
/** Common shadow treatment for containers, components and elements **/
/*** see https://www.joshwcomeau.com/css/designing-shadows/ ***/
--shadow-raw: var(--secondary-raw);
--shadow-container: 0 1px 2px hsl(var(--shadow-raw) / 0.12), 0 2px 6px 2px hsl(var(--shadow-raw) / 0.15);
--shadow-component: 0 1px 3px hsl(var(--shadow-raw) / 0.12), 0 4px 8px 3px hsl(var(--shadow-raw) / 0.18);
--shadow-element: 0 2px 3px hsl(var(--shadow-raw) / 0.12), 0 6px 10px 4px hsl(var(--shadow-raw) / 0.21);
}