Gesso is a Sass-based and Pattern Lab integrated starter theme that outputs accessible HTML5 markup. It uses a mobile-first responsive approach and leverages SMACSS to organize styles. This encourages a component-based approach to theming through the creation of discrete, reusable UI elements. Gesso is heavily integrated with Pattern Lab, allowing WordPress and Pattern Lab to share the same markup.
For more information, view the Gesso WordPress GitHub repo. To submit bug reports or feature requests, visit the Gesso WordPress issue queue. Also available for Drupal.
The following packages need to be installed on your system in order to use Gesso WordPress.
In addition, in order to compile Twig files, Pattern Lab requires that PHP be available on the command line.
Timber helps you create fully-customized WordPress themes faster with more sustainable code. With Timber, you write your HTML using the Twig Template Engine separate from your PHP files. This cleans-up your theme code so your PHP file can focus on supplying the data and logic, while your twig file can focus 100% on the display and HTML.
In order to use this theme you must download and activate the Timber Library plugin from Wordpress.org.
Additional information about installing and configuring the Timber Library can be found in the Timber Documentation
LibSass is required to compile the Sass into CSS. Gesso includes Gulp tasks to compile the CSS and generate the compiled Pattern Lab files and to watch both for changes. To use these tasks, first run the following NPM command in the theme folder.
npm install
To initiate the Gulp build tasks that compile the Sass and Pattern Lab files and watch for changes, run the following command in the theme directory:
gulp
To initiate the Gulp build tasks only (without watching for changes), run the following command in the theme directory:
gulp build
To access the Pattern Lab instance, append /pattern-lab/index.html to your
site URL and theme directory (e.g. http://localhost:8080/themes/gesso/pattern-lab/index.html)
or, if developing locally, just open that index.html file directly in the
browser from your file system.
Gesso uses a configuration file source/\_patterns/00-config/config.design-tokens.yml
to manage the theme’s design tokens and automatically generate the global sass
map for styling and patterns to represent the theme’s design tokens. The default
gulp command will monitor changes in the config and rebuild all necessary
assets. To rebuild the theme assets a single time run gulp build
In addition to using hex values for colors, you can also use Sass functions and provide a fallback hex value to be used in Pattern Lab. This is useful when pulling in an external design system, such as USWDS.
For example:
gesso:
palette:
brand:
blue:
base: '#0071bc'
light: !sass
sass: 'lighten(#0071bc, 20%)'
fallback: '#23a7ff'
The following Sass functions can be used to access the tokens defined in config.design-tokens.yml.
gesso-box-shadow($shadow) Output a shadow value from the box-shadow token list
example:
box-shadow: gesso-box-shadow(1);
gesso-breakpoint($breakpoint) Output a size value from the breakpoints token list
example:
@include breakpoint(gesso-breakpoint(lg)) {
display: flex;
}
gesso-brand($color, $variant) Output a color value from the palette brand token list
example:
color: gesso-brand(blue, light);
gesso-color($type, $subtype) Output a color value from the colors token list
example:
color: gesso-color(text, primary);
gesso-constrain($constrain) Output a size value from the constrains token list
example:
max-width: gesso-constrain(sm);
gesso-duration($duration) Output a timing value from the transitions duration token list
example:
transition-duration: gesso-duration(short);
gesso-easing($easing) Output an easing value from the transitions ease token list
example:
transition-timing-function: gesso-easing(ease-in-out);
gesso-font-family($family) Output a stack value from the font-family token list
example:
font-family: gesso-font-family(primary);
gesso-font-size($size) Output a size value from the font-size token list
example (combined with the rem() function to convert to rems):
font-size: rem(gesso-font-size(2));
gesso-font-weight($weight) Output a weight value from the font-weight token list
example:
font-weight: gesso-font-weight(semibold);
gesso-grayscale($color) Output a color value from the palette grayscale token list
example:
color: gesso-grayscale(gray-2);
gesso-line-height($height) Output a height value from the line-height token list
example:
line-height: gesso-line-height(tight);
gesso-spacing($spacing) Output a size value from the spacing token list
example (combined with the rem() function to convert to rems):
margin-bottom: rem(gesso-spacing(md));
gesso-z-index($index) Output an index value from the z-index token list
example:
z-index: gesso-z-index(modal);
Gesso includes a script to generate new component files. To use, run the following command in the theme folder.
npm run component
By default, the compiled Pattern Lab and Sass files (e.g., /pattern-lab/
and /css/*.css) as well as some configuration artifacts (e.g., design-tokens.artifact.yml,
_design-tokens.artifact.scss) are ignored by Git as these files are generated
when the Gulp tasks run. To change this, edit the included .gitignore file.
-
Breakpoint: Easy to write media queries.
-
Sass: CSS on steroids. Adds nested rules, variables, mixins, selector inheritance, and more.
-
Sass Globbing: Adds glob-based imports to Sass.
-
Autoprefixer: Adds necessary browser CSS property prefixes during Sass compilation.
Stylelint is used to lint Sass files. Warnings will break the build, so if you have a valid reason to break Stylelint rules you can have it ignore code in two ways:
-
Add
/* stylelint-disable-next-line */to the line just before where the Stylelint warning is triggered. -
To ignore several lines, add
/* stylelint-disable */before the code in question and add/* stylelint-enable */afterwards.
See the README.md file in the /js directory for details on included scripts (e.g., mobile menu, primary menu, etc.).
The Gesso theme for WordPress is maintained by Corey Lafferty, Lindsey DiNapoli, Karen Kitchens and Elvis Morales.
Please use the Github issue queue: https://github.com/forumone/gesso-wp/issues