#ShareYourDocs: One-off Patterns

I do not have the time or energy to write a full blog post, so instead I will share some interesting documentation about writing one-off patterns in our in-progress design system under a hash-tag I just came up with called #ShareYourDocs.

Screen shot of a direcory tree showing a folder for one-offs/author and it's contents

I do not have the time or energy to write a full blog post (especially not a Designgineering Chronicles installment which is already past due…maybe this weekend, but also maybe not), so instead I will share some interesting documentation about writing one-off patterns in the design system for Cantaloupe (which is the project’s code name, read more in the last Designgineering Chronicles) under a hash-tag I just came up with called #ShareYourDocs.

This documentation lives in theme-name/assets/src/patterns/09-one-offs/README.md. Note that this is taken completely out of context and will likely bring up a reaction of “huh?”, but I think it’s a good example of our workflow so far, and provides a glimpse into the architectural choices we’ve made.

Without further ado…

One-off Patterns

One-offs patterns are module patterns that are not parsed into directly into PHP. Their implementation in the pattern library and the production theme are separate. The one-offs in the pattern library are artifacts of the development process, and are not necessarily up to date with the production version. Their markup files should have a .html extension so that they are not parsed into PHP.

Writing One-off SCSS

When writing styles for a one-off, get as far as you can with utility and algorithm classes, then add additional styles that do not fit into utilities/algorithms in the One-off pattern’s SCSS file.

Class names for One-off patterns should have no namespace to indicate they are outside of the design system. For example, a one-off pattern for an author, might have the following styles in 09-one-offs/author/author.scss:

// Set up for the hover functionality
.author {
	opacity: 0;
	transition: opacity $transition-duration-300 ease-in;
	position: absolute;

.author__story-list li {
	list-style-type: square;
	color: map-get( $semantic-color-list, brand-red );

When adding these selectors to the markup, separate the one-off selector from system classes with a // for improved readability. For example:

<section class="author // pmc-u-padding-a-1 pmc-u-background-white u-hidden@desktop-max u-box-shadow-light u-max-width-300">

Using the Twig Parser for Prototyping

While the markup for One-offs should ulitimately have a .html extension, it might be useful to output the markup to PHP during development. This can be done with the following steps:

  1. Scaffold the one-off pattern: npm run scaffold -- author
  2. Write the markup, add utility classes, and build out the pattern in the pattern library.
  3. Once it is in a good place and you are ready to work in PHP, run the parser: npm run parser. This will generate a PHP file in template-parts/patterns/oneoffs.
  4. Move the file to template-parts/patterns/one-offs and delete the oneoffs directory. The parser should not add files to the appropriately named one-offs directory; those should be hand-written PHP.
  5. Work on the PHP template in template-parts/patterns/one-offs.
  6. Change the pattern markup file extension to .html to ensure it is no longer parsed into a PHP template.

It is important that the Twig parser does not directly output a one-off pattern to template-parts/patterns/one-offs so that it is clearly indicated that this markup is not linked to the pattern library. Be sure to delete the comment about "a generated file" from the initial PHP template.

Okay…that’s all from me. Back to work!