Maisie

For Developers

by

Maisie

Table of contents

Why does this exist?

Maisie was prompted by two things that seemed to undermine the ability to build design-driven and performance-oriented websites on top of WordPress’ block editor:

  • the layout model was inflexible and resistant to being extended
  • the amount of boilerplate CSS was extraordinary, with deprecated block styles further increasing style sheets over time.

While the second point has been partly resolved with the option to load block-specific styles on demand (see the last list item in Presentation), the current built-in solution for broadly structuring content makes many layouts difficult to achieve, particularly when a design does not originate in the block editor. Adding project-specific CSS to extend core styles has continued to be problematic: core markup and styles can and do change at any time, and overriding core styles often requires separate solutions between the theme and editor to maintain visual parity.

Additionally, websites that bake in element-specific styles like margin, padding, or borders—something heavily encouraged by per-block UI settings—tend to be difficult to extend and maintain beyond launch day. Maisie‘s goal is to help keep websites easy to extend and maintain by providing a CSS base that embraces styling the context for elements, while allowing for targeted overrides when necessary.

Maisie is an experiment to help understand whether it is feasible to maintain a theme that has opted out of WordPress’ bundled styles.

Presentation

Maisie attempts to be more predictable and precise for content layout while the editor layout tools continue to be refined. This means the majority of block CSS is custom to the theme—uh-oh!

  • Styles have been written with an eye to being easily extendable and overwritable, when possible. Still, some unfortunate choices have been required to play well with WordPress.
  • Block-specific CSS is managed with the should_load_separate_core_block_assets() core filter. This filter ensures CSS is loaded only if a block is present in the current document.

blocks

CSS Grid is used to manage layout blocks like Columns and Group, and has been integrated with the block editor’s Layout toggle, “Inherit default layout”.

There are a few key points worth noting:

Columns

Stacking is intrinsic, where possible. This means the number of columns may be less than specified via the editor, if a minimum threshold for column width is not met. Some media queries are still currently used to refine how layout adapts.

Groups

A full-width group with a background colour will automatically have default padding applied. Padding can be overridden with either a block style preset or by applying a value in Dimensions > Padding.

Additionally, no top margin is applied to sibling groups with a background colour applied. Until vertical margin controls are made available for a Group block (coming in WordPress 6.0), a workaround for this is to use a Spacer block.

Navigation

Fully responsive without media queries, with wrapping intrinsic to content. The “burger” mode is managed via a px value in theme.json.

Presets and custom settings

All presets and custom settings can be managed via theme.json.

Spacing

Element spacing is based on Every Layout’s The Stack. Maisie implements space values as custom settings, at this time opting not to use the blockGap preset enabled by WordPress.

Three size presets are preconfigured:

  • Small
  • Medium
  • Large

Each preset is available in the WordPress-generated global stylesheet as a CSS custom property.

Layout

The default document layout for Pages and Posts is managed via settings.custom.layout:

  • contentSize sets a value in REMs for Page content width
  • narrowSize sets a value in REMs for Post content width
  • margin sets the value between the edge of the content and the browser

For both Pages and Posts, layout content is centred by default.

Text

Size presets are configured for:

  • Tiny
  • Small
  • Medium
  • Large
  • X-Large
  • Mega

Each preset also supports custom keys for:

  • line-height
  • line length (as max-width)

Responsive type is managed using the CSS clamp() function, with values generated by the Utopia Fluid Type Scale Calculator.

Navigation

The presentation of a few key elements related to navigation is managed via settings.custom.navigation:

  • burger.breakpoint: sets the value in pixels where the menu switches to burger/overlay mode
  • burger.color: sets the colour of the toggle button
  • burger.diameter: sets the width/height of the toggle button
  • overlay.backgroundColor: sets the overlay background colour
  • submenu.arrowColor: sets the colour of the arrow on a sub-menu*

* This is an opinionated design feature and not a functional requirement.

Accessibility

Maisie treats accessibility as a first-class citizen, being a key concern for development from the outset.

Gutenberg plugin

Maisie is intended for use with WordPress core releases, not Gutenberg. The intentional trade-off here is Gutenberg churn vs. new features.

Due to filtering wp_render_layout_support_flag() to generate element-specific styles for a CSS Grid approach to layout, it’s unlikely Maisie will work as intended if Gutenberg is active. This will possibly no longer be a constraint when CSS Grid layout is incorporated into Gutenberg.

Previous
Next