forumone / gesso-wp

Gesso WordPress theme
34 stars 17 forks source link
accessibility component-driven html5 mobile-first pattern-lab php sass smacss starter-theme twig wordpress wordpress-theme

Gesso for WordPress

A starter block theme for WordPress 5.9+.

Requirements

Getting Started

  1. npm ci
  2. [Optional] Rename the theme with npm run rename
  3. npm run dev
  4. Enable the theme

Building the theme

To build the theme for production (or to get your local up and running if you will not be working on the theme itself):

  1. npm ci
  2. npm run build

Configuration

theme.json

Gesso utilizes theme.json file for setting theme defaults and variables. Colors, font families, font sizes, individual block styles and custom values like layout constrain widths are included. For more about what can be configured with theme.json, see the Block Editor Handbook.

Sass

Sass can be compiled as part of the global styles.css file or to individual CSS files for use in a block style.

@use is used to import Sass variables, mixins, and/or functions into individual SCSS files. @import is discouraged by the Sass team and will eventually be phased out. This means that most files will start with @use '00-config' as ;. This allows you to use functions and mixins provided by Gesso throughout your SCSS files. Note that to avoid namespace collisions, only mixins, and functions should be used with.

All Sass files that are compiled to individual CSS files must have a unique filename, even if they are in different directories.

Global styles

Prefix the name of your Sass file with _, e.g. _card.scss. Add it to the appropriate aggregate file (i.e. _components.scss).

Individual block styles

DO NOT prefix the name of your Sass file with _, e.g. menu.scss. Import the config and global aggregate files. Add your CSS file to the wp_next_theme_block_assets function inside functions.php:

wp_enqueue_block_style('f1-block-library/standalone-link', [
  'handle' => 'wp-next-theme-standalone-link',
  'src' => get_theme_file_uri('build/css/standalone-link.css'),
  'path' => get_theme_file_path('build/css/standalone-link.css')
]);

Omit the path line if the WordPress should not be able to choose whether to inject the styles via a <style></style> tag instead of loading an external file. You may need to remove that line if you find that image paths break when the CSS is injected. See the WordPress dev note for more on loading block styles.

Block Styles

Block Styles can be registered or unregistered in the source/editor-styles.js. This script is loaded whenever the Block Editor is loaded. For more about Block Styles, see the Block Editor Handbook.

Linting

Linting is done with Prettier, ESLint, and Stylelint. Linting follows the WordPress standards, with some rules disabled where needed to resolve conflicts between tools (mostly Prettier and Stylelint) or between linting standards and the theme design tokens.

CSS Variables

Gesso uses CSS variables generated from theme.json. You can view the list of all available variables generated by theme.json using your browser's inspector tools. Select the <body> tag for the page and in the styles tab you can view a list of all available CSS variables.

var(---wp--preset--color--brand-primary) Output the primary brand color.

example:

background-color: var(---wp--preset--color--brand-primary);

CSS Variables in JavaScript

You can use the values of custom properties in JavaScript just like standard properties.

For example say you have added a custom variable for breakpoints. You cna use it in your scripts like:

const body = document.querySelector('body');
const desktopBreakpoint = getComputedStyle(body).getPropertyValue(
    '--wp--custom--breakpoint--desktop'
);

if (window.matchMedia(`min-width: ${desktopBreakpoint}`).matches) {
  // Some script that should only run on larger screens.
}

Viewport width-based media queries

Gesso uses custom mixins to specify viewport width based media queries:

Each mixin takes one or two width parameters, which can be a straight value (e.g., 800px, 40em) or a design token value called using the gesso-breakpoint function (e.g., gesso-breakpoint(tablet-lg)). The breakpoint-max and breakpoint-min-max mixins can also take an optional parameter to subtract one pixel from the max-width value, which can be useful when you want your query to go up to the value but not to include it, such as when using WordPress breakpoint variables.

You can also use the width-based breakpoint mixins defined in @wordpress/base-styles, alongside the breakpoint variables. We recommend using those instead of defining your own for consistency between theme styling and plugin styling.

$break-huge: 1440px;
$break-wide: 1280px;
$break-xlarge: 1080px;
$break-large: 960px; // admin sidebar auto folds
$break-medium: 782px; // adminbar goes big
$break-small: 600px;
$break-mobile: 480px;
$break-zoomed-in: 280px;

@include breakpoint($width) { // styles } Output a min-width based media query.

examples:

@include breakpoint(800px) {
  display: flex;
}

@include breakpoint($break-medium) {
  display: none;
}

@include break-small {
  display: grid;
}

@include breakpoint-max($width, $subtract_1_from_max) { // styles } Output a max-width based media query. The optional $subtract_1_from_max parameter will subtract 1px from the width value if set to true (default: false).

examples:

@include breakpoint-max(900px) {
  display: block;
}

@include breakpoint-max($break-small, true) {
  display: none;
}

@include breakpoint-min-max($min-width, $max-width, $subtract_1_from_max) { // styles } Output a media query with both a min-width and max-width. The optional $subtract_1_from_max parameter will subtract 1px from the max-width value if set to true (default: false).

examples:

@include breakpoint-min-max(400px, 700px) {
  display: flex;
}

@include breakpoint-min-max($break-small, $break-medium, true) {
  display: block;
}

Side padding

In previous versions of Gesso, constrain classes were used to apply max-width and inline padding at the same time. As of 6.1, WordPress can now generate most of these styles automatically, and Gesso opts into this via theme.json. settings.useRootAwarePadding is set to true, and the spacing value is set at styles.spacing.padding. If you're not getting the padding you expect, check the layout settings on your blocks. More details can be found in the documentation.

Container queries

Gesso uses custom mixins to specify container queries:

Each mixin takes one or two width parameters, which can be a straight value (e.g., 800px, 40em) or a design token value called using the gesso-breakpoint function (e.g., gesso-breakpoint(tablet-lg)). The container-max and container-min-max mixins can also take an optional parameter to subtract one pixel from the max-width value, which can be useful when you want your query to go up to the value but not to include it, such as when using Gesso breakpoint token values.

In order for container queries to work, you need to set a containment context on a parent element.

container-type: inline-size;
container: container-name / inline-size;

@include container-query($width) { // styles }

Output a min-width based media query.

@include container-query(800px) {
  display: flex;
}

@include container-query($break-xlarge) {
  display: none;
}

@include container-query-max($width, $subtract_1_from_max) { // styles }

Output a max-width based container query. The optional $subtract_1_from_max parameter will subtract 1px from the width value if set to true (default: false).

@include container-query-max(900px) {
  display: block;
}

@include container-query-max($break-small, true) {
  display: none;
}

@include container-query-min-max($min-width, $max-width, $subtract_1_from_max) { // styles }

Output a container query with both a min-width and max-width. The optional $subtract_1_from_max parameter will subtract 1px from the max-width value if set to true (default: false).

@include container-query-min-max(400px, 700px) {
  display: flex;
}

@include container-query-min-max(
  $break-small,
  $break-xlarge,
  true
) {
  display: block;
}

Wordpress Template Hierarchy, Template Parts & Full Site Editor

The gesso theme has been structured to not leverage the Wordpress Full Site Editor at this time. It does, however, leverage template parts, allowing the block editor management of templates and their structural parts. A suite of baseline template parts have been created for each of the base PHP templates within the theme and can be found in the parts/ folder.

If you wish to leverage the Full Site Editor functionality, you can make the following modifications to the gesso theme structure. Please note that at this time, there are concerns around certain aspects of deployment procedures with database specific references (such as navigation blocks). Unless there is a strong case to leverage FSE, it is advised to opt for just leveraging the template parts at this time.

To leverage the Full Site Editor:

  1. Create a directory in the root of the gesso theme named templates
  2. Copy all html files from within the parts directory (with the exception of header.html and footer.html) and move them into your new templates directory. You will need to reference the header.html and footer.html parts within your html files now in the templates folder. You can do this in the UI.
  3. Create a new file called index.html and place it within the templates directory.
  4. All PHP files corresponding to one within the templates or parts directories, located in theme root, can be deleted.
  5. Remove add_theme_support('menus'); and add_theme_support( 'block-template-parts' ); within functions.php

Block Patterns

Gesso now also supports the template structure to automatically pull in rendered Block Patterns. When creating a Block Patter, you can store the markup and block definitions as individual files within the 'pattern' directory.

By default WordPress core block patterns are disabled. To re-enable, remove the following from functions.php:

remove_theme_support( 'core-block-patterns' );

Custom Gutenberg Blocks

When starting your new Wordpress project, you may have a need to register custom blocks for your site's theme. Prior to starting new, first take a look at the available blocks located within the f1-block-library. If the blocks there do not suffice, the Forum One github repository also contains a starter block plugin that you can install and use to house all custom blocks.