Component Pattern Libraries: reedtalks

<h1 class="presentation-title">Component Pattern Libraries</h1>
        <p class="presentation-subtitle">for an Accessible WordPress Experience</p>

<p class="presentation-meta"><b>Reed Piernock</b><br>Principal Web Developer</p>

<p class="presentation-meta"><i>WordPress Accessibility Meetup</i><br>20 November 2023</p>

---

## Pattern libraries and style guides

Notes:

go over:
- why a style guide is beneficial
- high-level overview Web Content Accessibility Guidelines
- installing and setting up KSS-node
- using Twig files and CSS comments
- integrating with WP themes and blocks

will not go over:
- how to structure files: OOCSS, Smaccs, bem, atomic structures
- specifics of WCAG success criteria
- manage node projects
- CSS, Sass, Less, Tailwind, etc
- specifics of creating themes and blocks

---
**Style guide:**

the document that lists all the components

**Pattern library:**

the code that creates the components

Notes:

allow for consistency and maintainability
Old WP themes: What is used where!? Repeated code? Too many components! Can get bloated, conflicting styles, etc. Further troubles with “static” gutenberg blocks

style guide: “source of truth”
- one place where everything is listed
- can tell which components are used in other components

pattern library: a more sustainable way of coding that truth
- change made to one component only made in one place for all instances

Other types of UI component tools: Pattern Lab, Storybook, Fractal.
Use KSS for ease of templating with Twig/HTML, Sass comments

---
## Benefits

🧑‍💻 Web Team

🧑‍🎨 Content Creators

Notes:

OK but what does this have to do with accessibility?

beneficial when web team (dev, manager, design, etc) with different content creators from internal org or external clients

Web Team
- create components used in themes and blocks
- interpret Web Content Accessibility Guidelines (WCAG) into code
- iterate on components for design/functionality changes
- fix bugs on components

Content Creators
- produce content for site
- site architecture, content strategy, copywriters, graphic designers, video and/or podcast, etc
- focus on what they do best: create content

---
## Four Principles of Accessibility

- Perceivable
- Operable
- Understandable
- Robust

[🔗 Introduction to Understanding WCAG](https://www.w3.org/WAI/WCAG21/Understanding/intro/)

Notes:

What does it mean to follow Web Content Accessibility Guidelines? From their docs:

- Perceivable - users must be able to perceive the information being presented (it can’t be invisible to all of their senses)
- Operable - users must be able to operate the interface (the interface cannot require interaction that a user cannot perform)
- Understandable - users must be able to understand the information as well as the operation of the user interface (the content or operation cannot be beyond their understanding)
- Robust - users must be able to access the content as technologies advance (as technologies and user agents evolve, the content should remain accessible)

---

The first rule of ARIA is “don’t use ARIA”

> If you _can_ use a native HTML element or attribute with the semantics and behavior you require **already built in**, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, **then do so**.

Notes:

ARIA = Accessible Rich Internet Applications

HTML is already accessible by itself! ARIA can assist in some ways, e.g. adding labels to page regions.

witnessed many times when used incorrectly, e.g. `div role="button"`

---
## Setting up a pattern library

---

### Sample directory structure

```
🗂️ sample-wp-theme
  ↳ 🗂️ builder
  ↳ 🗂️ styleguide
  ↳ 🗂️ src
  ↳ 🗂️ dist
  ↳ 🗂️ config
```

Notes:

library can be external project or internal to theme, can be named anything according to your team’s coding conventions

- builder: the scripts and templates that build the style guide
- styleguide: the generated output
- src: the source Sass and Twig files
- dist: the compiled stylesheet assets
- config: not required, but helpful for kss config and any other config files that may be needed for the project

BUILDER and DIST dirs: optional, depending on how themes are structured.
- builder could go under src - kss config can define location of builder
- may not have dist! WP theme requires style.css with theme info. Other stylesheets must be at the root of the theme to work properly, can compile directly to theme root
For this talk/demo: assume builder, dist, config dirs

---
### Install packages and add scripts

**on the command line**

```js
npm install --save-dev sass kss
```

**in `package.json`**

```json
{
  "scripts": {
    "build:css": "sass --no-source-map ./src:./dist/css",
    "build:kss": "kss --config ./config/kss.json"
  }
}
```

Notes:

super truncated version of package.json: include scripts to build the css, html, styleguide from the markdown, twig, sass, and sass comments. Minimum: sass and kss-node.

---
### Copy the base builder template

**installed location**

`🗂️ ./node_modules/kss/builder/twig`

**project location**

`🗂️ ./builder/twig`

Notes:

handlebars, nunkucks, and twig are included builders -- using twig because compatibility with CMS like WP and Drupal. Part of the reason we built the pattern library was for its maintainability with WP custom themes and custom blocks

---
### Create the pattern library directories

`📄 _index.scss` file in each source directory

```
🗂️ sample-wp-theme
  ↳ 🗂️ src
    ↳ 🗂️ base
    ↳ 🗂️ color
    ↳ 🗂️ text
    ↳ 🗂️ link
    ↳ 🗂️ card
    ↳ 🗂️ layout
```

Notes:

Sass to organize and compile the css, but _any_ style of CSS works, e.g. vanilla CSS, preprocessors like Less, frameworks like Tailwind. As long as ability for comments, only need kss to find the styleguide comments, and pattern library to find the twig files. will use to create namespaces

---
### Set up the builder configuration

`📄 ./config/kss.json`

```json
{
  "title": "Sample KSS",
  "source": "../src/",
  "destination": "../styleguide/",
  "builder": "../builder/twig/",
  "css": "../dist/css/styles.css",
  "namespace": [
    "color:src/color",
    "text:src/text",
    "link:src/link",
    "card:src/card",
    "form:src/form",
    "layout:src/layout"
  ]
}
```

Notes:

1. source, destination, builder: relative to the config file<br>
2. css relative to the generated pages in styleguide<br>
3. because we’ll reference Twig from pattern library, custom blocks, custom themes, let’s give our patterns a namespace

---

## Adding patterns and components

---
### Color

Notes:

Our first style guide entry!

Screenshot of the brand colors page in the style guide, with a heading named Colors. The colors include Eerie Black (a dark black), Maize Crayola (a medium yellow), Gainsboro (a light gray), Alabaster (an ivory white), and Jet (a dark gray). Color are laid out in a grid-like layout, and each grid item includes a representation of the color, its description, its color code, and its property name.

When the styleguide is generated, the comments from the CSS are used to create the pages. Loops through colors to output on page with information from the "colors" part of the CSS

---

#### Color stylesheet

```scss
// Brand colors
//
// Colors:
// --color-primary: hsla(60, 1%, 14%, 1) - Eerie Black
// --color-secondary: hsla(44, 88%, 66%, 1) - Maize Crayola
// --color-tertiary: hsla(150, 14%, 84%, 1) - Gainsboro
// --color-background: hsla(81, 28%, 90%, 1) - Alabaster
// --color-foreground: hsla(120, 2%, 20%, 1) - Jet
//
// Weight: 1
//
// Styleguide: Color

:root {
  --color-primary: hsla(60, 1%, 14%, 1);
  --color-secondary: hsla(44, 88%, 66%, 1);
  --color-tertiary: hsla(150, 14%, 84%, 1);
  --color-background: hsla(81, 28%, 90%, 1);
  --color-foreground: hsla(120, 2%, 20%, 1);
}
```

Notes:

CSS comments preceded with two forward slashes. Empty line between comment sections also slashes.

1. First: name of the pattern - brand colors
1. Second: specify colors, then list the colors - name, color code, description
1. Third: weight of the page
1. Next: section of the styleguide, used for creating hierarchy and page URLs
1. After comments: regular Sass or CSS declarations

---
### Text Heading

Notes:

Screenshot of the text page in the style guide, with a heading named Text and a subheading named Heading. An example section illlustrates how a heading would display on website. Below the example section is the Twig code used to create the pattern for the heading component. This code is listed in another slide.

Some sections with parent and children. Text, include stuff like headings and paragraphs. Text parent, heading child. Comments tell kss what goes where.

---

#### Text stylesheet

```scss
// Text
//
// Weight: 2
//
// Styleguide: Text

// Heading
//
// Heading content defines the header of a section.
//
// Markup: heading.twig
//
// Styleguide: Text.Heading
```

Notes:

1. First: name of the section
1. Then: default sort of styleguide is alpha, add weight to create custom list sort -- text comes after "colors" in the site menu
1. Last: kss section of the styleguide, used for creating hierarchy and page URLs

use Text as parent and add sections for other patterns below it, e.g. heading listed under Text

New under heading!
location of Twig file that creates the Heading pattern

---

#### Heading markup

```html
{% set heading_level = heading_level | default(2) %}

<h{{ heading_level }} class="text-heading">
  {{heading_text}}
</h{{ {heading_level }}>
```

Notes:

Create the Twig files, with the patterns for Heading. Most basic, attributes accept values from the files that include them. Nothing fancy to the output HTML, only class name. `heading_level` attribute define 1, 2, 3, etc. `heading_text` attribute sets text content of the heading.

---

#### Heading json

```json
{
  "heading_text": "Neodialectic conceptual theory"
}
```

Notes:

1. use json to pass sample key/value attributes into the Twig file
1. the filename must match the Twig filename, kss knows where to find the attribute values from the json

---
### Link

Notes:

Screenshot of the link page in the style guide, with a heading named Link. An example section illlustrates how links would display on website, including default, hover, and focus states. Below the example section is the Twig code used to create the pattern for the link component. This code is listed in another slide.

Displayed are name of pattern, description, etc as before, with addition of the modifiers for link states (default, hover, focus). without doing extra work to repeat those examples with passing in attributes over again many times

---

#### Link stylesheet

```scss
// Link
//
// **Links** are connections between two resources...
//
// :hover - the state when a mouse is hovered over the link
// :focus - the state when the link has keyboard focus
//
// Markup: link.twig
//
// Weight: 3
//
// Styleguide: Link

a {
  [...]
}
```

Notes:

Have all the same information as the other patterns, but here addition of “modifiers” or variants of the pattern, e.g. classes or pseudo-classes applied to an element

---

#### Link markup

```html
<a class="text-link {{ modifier_class }}" href="{{ link_url }}">
  {{ link_text }}
</a>
```

Notes:

addition of `modifier_class` in the pattern for the link

---

#### Link json

```json
{
  "link_text": "Neodialectic conceptual theory",
  "link_url": "https://example.com/"
}
```

Notes:

1. use json to pass sample key/value attributes into the Twig file
1. the filename must match the Twig filename, kss knows where to find the attribute values from the json

---
### Card

Notes:

We’re starting to put it all together!

Screenshot of the card page in the style guide, with a heading named Card. An example section illlustrates how a card would display on website, including heading, paragraph, and link patterns. Below the example section is the Twig code used to create the pattern for the card component. This code is listed in another slide.

patterns can include other patterns, and that’s where all the neat stuff starts happening

---

#### Card stylesheet

```scss
// Card
//
// A card includes content and a call to action.
//
// Markup: card.twig
//
// Weight: 4
//
// Styleguide: Card

.card {
  display: grid;
  grid-template-rows: auto 1fr auto;
  width: var(--card-width, max(25ch, 50%));
  padding: var(--card-padding, 1em);
  border: 1px solid var(--card-border-color, var(--color-secondary));
  border-radius: var(--card-border-radius, 1em);

:first-child { margin-block: 0; }
}
```

Notes:

Add CSS/Sass/Less, etc as we’ve been doing, the difference is only difference here is coding the Card twig patterns with other patterns.

---

#### Card markup

```html
<div class="card">
  {% include "@text/heading.twig" with {
    heading_level: 3,
    heading_text: card_heading
  } %}

{% include "@text/paragraph.twig" with {
    paragraph_text: card_description
  } %}

{% include "@link/link.twig" with {
    modifier_class: "cta-link",
    link_text: card_link_text,
    link_url: card_link_url
  } %}
</div>
```

Notes:

1. new Card-specific variables
1. include the heading, paragraph, link Twig
1. tell those Twigs to use the Card values
1. new! modifier_class passed to the link pattern

---

#### Card json

```json
{
  "card_heading": "Posttextual conceptualism",
  "card_description": "Lacan uses the term ‘posttextual conceptualism’ ...",
  "card_link_text": "Neodialectic conceptual theory",
  "card_link_url": "https://example.com/"
}
```

Notes:

1. use json to pass sample key/value attributes into the Twig file
1. the filename must match the Twig filename, kss knows where to find the attribute values from the json

---
### Layout

Notes:

We’re putting even more together!

Screenshot of an example layout page. It includes a global header, navigation, search form, main content, and global footer. The title in the header is Dialectic Narrative. There are three navigation links, and three cards in a grid layout.

it gets easier and easier to create more complex patterns once the smaller ones are all agreed upon and built. Grid made of cards, navbar that uses nav list that uses links, etc

---
## Fitting it in with WordPress

- custom themes
- custom blocks (Gutenberg)

Notes:

custom themes: larger component chunks like layouts, e.g. header, footer, navigation

custom blocks: smaller component pieces, e.g. callouts, icons, buttons put together

Benefits again:
- when the web team needs to work with various content creators
- Front-load a lot of work in the beginning to make building new patterns more easily.
- More maintainable moving forward, no need to make changes in multiple places
- related: e.g. fix the a11y issues with a basic card pattern, all components using that pattern get the fix
- because of above: fewer risk of bugs, style are consistent, etc
- able to spot accessibility issues in the themes and blocks so content creators can focus on content

---
### Adding theme templates

> With Timber, you write your HTML with the Twig Template Engine. This cleans up your theme code. Your PHP file can focus on providing the data or logic and your Twig files can focus 100% on the HTML and display.

[🔗 Timber: Getting Started](https://timber.github.io/docs/v2/getting-started/introduction/)

Notes:

- theme php files: functionality
- theme twig files: templating

---
#### Timber Context

```php
$context = Timber::get_context([
    'site_title' => site.name,
    'site_link' => site.url,
    [...]
]);

Timber::render('index.twig', $context);
```

[🔗 Timber: Context Guide](https://timber.github.io/docs/v2/guides/context/)

Notes:

get WP information and add to Timber context: the context is a list of all the variables WP exposes, that can be passed through to the templates in the theme

---

Some neat variables to add to Timber context:
- `post.thumbnail.src`
- `post.thumbnail.alt`
- `post.title`
- `post.author.name`
- `post.post_date`

---
#### Base template example

```twig
<!DOCTYPE html>
<html>
  <head>
    <title>Dialectic Narrative</title>
    [...]
  </head>
  <body>
    {% include "@layout/header.twig" with {...} %}
    {% include "@layout/nav.twig" with {...} %}

{% block main_content %}
      {{ post.content }}
    {% endblock main_content %}

{% include "@layout/footer.twig" with {...} %}
  </body>
</html>
```

Notes:

basic HTML page structure, e.g. head, body. inside body:
- include header layout pattern
- include nav layout pattern
- include footer layout pattern

`with` for passing attributes to the pattern it’s calling - don’t need to pass through attributes that are set in Timber context, e.g. `site_title`

for main content: create `block` that can be set up when the template is extended

---
#### Single post template example

```twig
{% extends "@template/base.twig %}

{% block main_content %}
  <article aria-labelledby="title-{{ post.id }}">
    {% include "@layout/feature.twig with {...} %}

{% include "@text/heading.twig" with {...} %}

{% include "@text/byline.twig" with {...} %}

{{ post.content }}
  </article>
{% endblock main_content %}
```

Notes:

there is already a good template set for the base HTML page, and instead of copying/rewriting can extend the template. `main_content` _was_ only `post.content` but can change here to also include feature image and heading

aria on article: the post id can be set when the heading is included, to create an HTML id attribute that can be referenced on the article tag

---
#### Page post template example

```twig
{% extends "@template/base.twig %}

{% block main_content %}
  {% for post in posts %}
    <article aria-labelledby="title-{{ post.id }}">
      {% include "@text/heading.twig" with {...} %}

{{ post.content }}
    </article>
  {% endfor %}
{% endblock main_content %}
```

Notes:

maybe a page doesn’t need to show feature image or article byline - re-set the `main_content` to only use what’s needed when extending the base template

because each WP template extends from one base template, and each template also includes patterns for components, easier to find and fix bugs or a11y issues

---
### Adding custom blocks

> Experience the flexibility that blocks allow, whether you’re building your first site or write code for a living. [...] Blocks allow you to build your own custom posts and pages without any coding knowledge.

[🔗 WordPress Gutenberg](https://wordpress.org/gutenberg/)

Notes:

- core blocks such as paragraph, heading, list, image, etc
- custom blocks let web team create the code necessary, content creators don’t need to know or learn HTML in order to update websites

---
#### Card custom block

Notes:

- dev a block for content creators to insert on page, without knowing HTML
- control a11y in ways some core blocks don’t allow or offer
- provide content creators with pattern and don’t get overwhelmed confronted with blank page
- only need to fill in the content fields, e.g. heading, description, call to action

---
#### Card block calling the Card pattern

```php
Timber::fetch( '@card/card.twig', [
  'modifier_class'   => $class_name,
  'card_heading'     => $heading,
  'card_description' => $description,
  'card_link_text'   => $link,
  'card_link_url'    => $url
] );
```

Notes:

Super simple example! I’m not a block developer! I only create the “skin” for the blocks!

in the block’s functionality, save attributes for content creator input - those are included when the block’s pattern is called

---
## Build all the things!

**GitHub repository**

[https://github.com/reedcodes/sample-kss-twig](https://github.com/reedcodes/sample-kss-twig)

**Demo website**

[https://samplekss.reedcodes.com/styleguide/](https://samplekss.reedcodes.com/styleguide/)

Notes:

- share links to demo website that’s just a style guide
- me: WIP on creating a custom theme that includes pattern library