BrianAA

JasonBernert

alexisbarnes

artmsilva

atomictangerine

baconjulie

carlyn-c

caroldinh

chrisalcantara

christian-wp

clairehhelms

crombach

ebgranger

erikreyna

freedmand

hs4man21

kbondanza

klimenkoff9

linorabolini

mgifford

mjperales

unconstruct

val-l-hosler

wp-aberg


<BR />{" "}

## What we learned

Hey there! We just had our design workshop number 2 and it was great joy to share with you all of the new things we have been working on. Here is what you missed:

- Answering some frequently asked questions since we released.
- Learning about our new component api.
- Deep diving on our button component
- Our new css framework
- Slots (new figma pattern for components)

<BR />

---

## The workshop video

<YoutubeEmbed videoid="e_jzDfTdjow" />


Continuing our deep dive in our new design system.

To the right of the image, a woman sits at a desk looking down at her computer. Around her head are bubbles depicting a quote, a video, a website, and a message. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 2 - WPDS for Designers'. 'WP Design System' appears on the lower left.

WPDS v1 - Design Workshop 2


<BR />
Watch Brian Alfaro lead a design workshop for our v1 rollout of the new WPDS. (Recorded
March 16th, 2022).
<BR />

<YoutubeEmbed videoid="cODayPp8b_U" />
<BR />

**Chapters:**

<BR />

[**0:00**](https://www.youtube.com/watch?v=cODayPp8b_U&t=0s) - Agenda & intro

<BR />

[**3:16**](https://www.youtube.com/watch?v=cODayPp8b_U&t=196s) - Our new tokens

<BR />

[**5:49**](https://www.youtube.com/watch?v=cODayPp8b_U&t=349s) - Color tokens

<BR />

[**7:26**](https://www.youtube.com/watch?v=cODayPp8b_U&t=446s) - Numeric tokens

<BR />

[**12:47**](https://www.youtube.com/watch?v=cODayPp8b_U&t=767s) - Context (light and dark)

<BR />

[**17:24**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1044s) - Color intention (theming)

<BR />

[**21:26**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1286s) - Figma plugin (Token
tools)

<BR />

[**25:09**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1509s) - Component API

<BR />

[**27:47**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1667s) - Zeplin code/style guide

<BR />

[**30:30**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1830s) - Zeplin extension

<BR />

[**31:59**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1919s) - Navigation our doc site


Watch Brian Alfaro lead a design workshop for our rollout of the new WPDS.

To the right of the image, a woman sits at a desk looking down at her computer. Around her head are bubbles depicting a quote, a video, a website, and a message. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 1 - WPDS for Designers'. 'WP Design System' appears on the lower left.

WPDS v1 - Design Workshop


## What's happening

Watch Arturo Silva lead our second developer workshop for our v1 rollout of the new
WPDS. Same topics as the first one, but with a different approach. (Recorded April
7th, 2022).

<br />

## Topics discussed

- Box component
- Theme package's OOTB Stitches functions
  - `css`
  - `styled`
  - `theme`
  - `utils`
- The differences between SASS/SCSS and CSS-in-JS
- How to use the `css` function in Svelte, Vue.js, and more
- and much more!

<br />

<YoutubeEmbed videoid="pDQK-UJ2LJQ" />


Watch Arturo Silva lead our second developer workshop for our v1 rollout of the new WPDS. Same topics as the first one, but with a different approach.

To the right of the image, a man stands holding a text box with both hands. In front of him a large website floats in front of him. He appears to be inserting the text box into the upper left of the website. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 2 - WPDS for Developers'. 'WP Design System' appears on the lower left.

WPDS v1 - Developer Workshop 2


<BR />
Watch Arturo Silva lead a developer workshop for our v1 rollout of the new WPDS.
(Recorded March 17th, 2022).
<BR />

<YoutubeEmbed videoid="CN-vbXz0asI" />


Watch Arturo Silva lead a developer workshop for our v1 rollout of the new WPDS.

To the right of the image, a man stands holding a text box with both hands. In front of him a large website floats in front of him. He appears to be inserting the text box into the upper left of the website. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 1 - WPDS for Developers'. 'WP Design System' appears on the lower left.

WPDS v1 - Developer Workshop


---

## Getting started

### Requesting access

If you are a Washington Post employee, please submit a SAR to gain access to your
Figma Product & Design workspace. If you are not a post employee and are
looking to use WPDS Ui Kit, please reference these Figma files.
[WPDS Ui Kit & WPDS Asset Manager](https://www.figma.com/@WPDS).

#### Prerequisite

Before jumping into Figma and using our design system, you must first understand the concepts around our system. The Figma library is built and designed to parallel what is happening in the code.
Please read over the following before proceeding with this guide.

1. [Color](/foundations/color)
2. Tokens - `color`, `radius`, `shadow`, `size`, `typoggraphy`, `z-index`
3. [Asset](/foundations/wam)

---

## Using components

### Enabling our Figma libraries

When using our Figma library, it is essential not to detach as this will
give you the optimal experience when handing off designs to a developer.

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", maxWidth: "100%", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Our_Figma_Library__hutMYjdCRe-Anb5ckKUvpw"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

### Component variants

All of our components match the coded API (properties of the variants)
as close as possible.

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", maxWidth: "100%", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Component_Api__rc7AiXYQTX2fe4lMLEOnHg"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

#### Slots

Some of our components use a concept called slots. Slots are for you to
replace with your component or nest another component. To replace,
select the slot in the layer and replace it with the desired component.
You can build out a design that does not need to be detached by replacing slots.

<Container caption="This example shows available slots to replace with other local or design system components">
  <InlineImage
    width={252}
    height={285}
    maxWidth="100%"
    src="/img/guides/figma/slots.png"
  />
</Container>

#### Icons

If an icon layer of a component is locked, this indicates that you should not change the icon. Otherwise, you may modify the icon glyph using any icon available in our Asset Manager.

#### Use Figma variant controls

Only use the Figma variant controls when modifying the Figma component to apply the desired variant. These controls closely match
to the coded component and inform the developer on what property value to assign.
Avoid manually overriding the properties by selecting the layers.

<Container>
  <InlineImage
    width={318}
    height={156}
    maxWidth="100%"
    src="/img/guides/figma/component_properties.gif"
  />
</Container>

---

## Using our tokens

### Applying tokens

In Figma, we have two tokens managed by the native Figma UI.
The shadow and color tokens can be accessed by
selecting the style icon. All other tokens are handled either through our token
tools or manually.

#### Applying color

Select the style icon and apply the fill or stroke color to apply a color token in Figma.
When selecting a color style, all tokens are displayed; a helpful way
of picking the right colors is to use our [theme](/foundations/color#Themes) alias to assign color with intention.

<Container>
  <InlineImage
    width={239}
    height={322}
    maxWidth="100%"
    src="/img/guides/figma/using_theme.gif"
  />
</Container>

#### Applying shadows

To apply shadows to an element, select the effects in the design panel and apply one of the shadow tokens.

<Container>
  <InlineImage
    width={228}
    height={322}
    maxWidth="100%"
    src="/img/guides/figma/applying_shadows.gif"
  />
</Container>

### Applying other tokens

We developed a plugin to manage and assign tokens in Figma that are currently
not supported or flexible enough to be used in design without detaching the style.
Our plugin resolves this by connecting our tokens while still being flexible in Figma.

#### Installing Token Tools

To install the plugin, visit the [plugin landing page](https://www.figma.com/community/plugin/1044987008646864166/Token-Tool)
and install. You will now have access to the plugin in your Figma file. If you do not see the plugin, please reload the file.

#### Token tools

Token Tools is a plugin that we will iterate and expand on as our needs grow with the system.
The interface design mimics Figma UI to avoid learning new interaction patterns.

<Container>
  <InlineSVG
    width={300}
    height={600}
    path="/img/guides/figma/plugin.svg"
    description="TESTING"
  />
</Container>

#### Theme

The theme tool in token tools applies the matching color for that theme switching it from its
current context to the following context.

<Container>
  <InlineImage
    width={1148}
    height={406}
    maxWidth="100%"
    src="/img/guides/figma/plugin_theme.gif"
  />
</Container>

#### Border radius

Using the border radius tool will apply the border radius token to any frame or shape that
has a uniform border radius.

<Container>
  <InlineImage
    width={1158}
    height={540}
    maxWidth="100%"
    src="/img/guides/figma/border_radius.gif"
  />
</Container>

#### Font size & Line height

The font size and line height tool will apply the token to the selected text element.

<Container>
  <InlineImage
    width={1158}
    height={540}
    maxWidth="100%"
    src="/img/guides/figma/font_size_line_height.gif"
  />
</Container>

#### Font weight & Font Family

Currently, token tools do not manage font family or font weight. However, in the WPDS Zeplin extension, the extension will note the tokens. For more information, please refer to our tokens documentation to apply the correct value in
Figma.

<BR size="xl" />

#### [Read next our Zeplin guide >](/resources/guides/zeplin-guide)

<BR size="xl" />


Figma is our tool of choice when designing and using our design system. Other design software is currently not supported, but maybe in the future.

Figma Guide


---

## Getting started

### Requesting access

If you are a Washington Post employee, please submit a SAR to access our Zeplin Product & Design workspace. If you are not a post-employee and want to use Zeplin in your suite, please reference our Figma file to upload and create your style guide.

### Creating a Zeplin project

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Creating_a_Zeplin_project__3QIHj0krQKKwmVOizwQ50Q"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

### Connecting WPDS Styleguide

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", maxWidth: "100%", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Zeplin_Workflow__Sl-5tsJ3R26TMT8HyT_4QQ"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

### Connected Components

By linking the style guide you unlock our connected compoents. Selecting a component connected to code in Zeplin will reveal a code snippet and the props chosen for the component variant. This happens when you use our Figma Ui Kit components!

<Container caption="In this example the properties reveal taht 32 was selected for the prop `size`">
  <InlineImage
    src="/img/guides/zeplin/connected.png"
    width={520}
    height={671}
    maxWidth="100%"
  />
</Container>

#### Properties

We do our best to ensure that our Figma API that translates to Zeplin properties matches as close to 1:1 of the actual coded component. However, you might find some properties like states that are not in the coded component; this is due to the nature of Figma. In those instances, you can ignore it unless otherwise documented.

---

## Extension

### Getting WPDS Extension

Zeplin supports a good amount of tokens; there are some limitations in how some tokens are managed or not managed at all. Right not the current tokens managed by Zeplin is only color. We chose not to manage typestyles; instead, we highlight individual tokens font size, font, line height using our extension. We also manage tokens like border radius and shadows using our extension.

#### Installing the extension

Select the project in Zeplin you would like to add the extension to and then select extension > explore extensions > add WPDS Tokens.

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", padding: "$100 $100" }}
    src="https://scribehow.com/embed/WPDS_Zeplin_Extension__5t1hkwhtTzWyXS749Yk-2g"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

#### Typography tokens

To reveal the typography tokens, select a text layer to have the extension show the properties of that text.

<Container>
  <InlineImage
    alt="Animated image of showing how to add the WPDS extension"
    width={323}
    height={195}
    maxWidth="100%"
    src="/img/guides/zeplin/text_tokens.png"
  />
</Container>

#### Border radius and shadows

To reveal the border radius or shadow, select a layer with a border radius or shadow, and the extension will show the corresponding tokens.

<Container>
  <InlineImage
    alt="Animated image of showing how to add the WPDS extension"
    width={318}
    height={156}
    maxWidth="100%"
    src="/img/guides/zeplin/shadow_border.png"
  />
</Container>

#### Token syntax

Note that all tokens will display in stitches token string format by adding a $. Stitches is our default styling framework for our system, but if you need to refer to the token, drop the $.

<BR size="xl" />


Zeplin is our tool of choice when it comes to hand-off. It offers a layer of connection to code and design not yet realized by other tools.

Zeplin Guide


## Getting Started

### What is a Carousel?

In simple terms, a carousel is a type of container that displays a sequence of items, which can be interacted with by clicking or swiping—much like a deck of cards or an old-fashioned slide projector – ie a “carousel”. Carousels are an extremely common UI pattern and it’s likely you’ve come across various instances of them across the web. Many websites make use of carousels— from news publishers and streaming platforms to e-commerce sites, recipe blogs and cloud-based tools.

<Container caption="Some examples of carousels from across the web">
  <InlineImage
    width={878}
    height={583}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_1.png"
  />
</Container>
<br />

### When Should I Use a Carousel?

Carousels are often a great choice for presenting individual cards or a collection of content in a format that is familiar to many users. Because they are interactive, carousels encourage discovery by permitting users to toggle the visibility of items in the sequence. The ability to navigate between previous and next items builds anticipation and gives users a sense of control.

In addition, using a carousel in your design can be an economical use of visual ‘real-estate’, as carousels typically don’t occupy much vertical space, but may display a continuous row of items, such as a series of articles. In contrast, a grid or photo gallery might occupy multiple rows or the whole page. This makes carousels convenient for use in scenarios in which free space is limited, such as on mobile screens.

### When Should I Avoid Using a Carousel?

In the browser, carousels can present challenges for users who rely on screen-readers or other assistive technology. Because carousels are inherently meant to hide or show individual items based on user-feedback, there’s a chance some content will be obscured from view, either visually or programmatically. This might result in important or essential information becoming hard to read or otherwise inaccessible to some screen-readers and users with visual impairments.

The WPDS Carousel is designed with modern accessibility best-practices in mind. The component supports reduced-motion and keyboard-enabled navigation and has been built to interoperate with screen reading technology. However, performance and functionality in these areas might be impacted when using rich media in your carousel (such as embedded audio or video). Ultimately it’s important to work closely with your engineering team to ensure that implementation of the carousel meets functional UX requirements and accessibility standards for your use-case.

Now that we’ve had a chance to understand Carousels as a UI pattern, let’s learn how to use the WPDS Carousel component in your Figma designs.

### But First – Component Docs!

Before delving further into this guide, we highly recommend taking the time to read our component documentation for WPDS Carousel, if you haven’t already done so. As a starting point, the Carousel component doc provides plenty of useful information regarding the component’s key technical features and functionality, including considerations for web-accessibility.

---

## Configuring the Carousel

### Figma’s Component Properties

WPDS Carousel takes advantage of **component properties**, a native feature in Figma. With component properties or ‘props’, we can build components that are flexible enough to configure according to your needs, while preserving reusability. A further benefit of this approach is that we can establish a direct relationship between the **design** component that lives in Figma and the **coded** component that lives in the browser, because they share the same properties. (Learn more about “connected components” in our [Zeplin resource guide](/resources/guides/zeplin-guide)).

### Adding an Instance of the Carousel to your Figma Design

Like all of the components in our UI Kit Library, the Carousel component can be placed into your Figma file by dragging an instance of it from the **“Assets”** panel into your document.

<Container>
  <InlineImage
    width={900}
    height={600}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_2.gif"
  />
</Container>
<br />

### Renaming the Carousel

In the design panel, you will see the `⬦Carousel` component instance, along with its configurable properties — including `🄵 title`.

By default, the text displayed at the top of the component is _“Carousel title”_. To alter this text, simply **click the input** field next to `🄵 title` to edit its value and press enter when done.

If you’d prefer not to display a title for your Carousel, you may **toggle the switch** next to `🄵 show title?`. (Toggling this setting hides the text layer in your `⬦Carousel` instance.)

<Container>
  <InlineImage
    width={350}
    height={292}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_3.gif"
  />
</Container>
<br />

### Positioning the controls

`⬦Carousel` ships with several options for placement of controls (e.g. prev / next buttons) and pagination — including the option to hide controls entirely.

To change where controls are placed, **click the dropdown menu** next to `🄵 controls` and select the option that’s most suitable to your design.

The available options are meant to serve a variety of use-cases and visual preferences while maintaining functionality and predictability for our website visitors. (For more guidance on custom controls, see section 4: Advanced Customization)

<Container>
  <InlineImage
    width={350}
    height={350}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_4.gif"
  />
</Container>
<br />

### Resizing the Carousel

To adjust the **width**, simply **drag the right or left edge** of the `⬦Carousel` frame. You may choose to make your instance of the component narrower or wider, depending on the space available in your design. Increasing the width will reveal additional content items nested within the component. (For more guidance on this, see section 3: Working with Content).

<Container>
  <InlineImage
    width={930}
    height={478}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_5.gif"
  />
</Container>
<br />

### Dynamic height with Auto layout

Using Figma’s Auto Layout feature, we can set the vertical dimension of `⬦Carousel` to “hug” its contents. This means the **height** of the carousel is determined by the content nested within it, and will adapt its height accordingly.

<Container>
  <InlineImage
    width={278}
    height={317}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_6.png"
  />
</Container>
<br />

---

## Working with Carousel Content

### Selecting a content type

As previously discussed – Carousels can contain many kinds of content. The WPDS Carousel component ships with a number of content types to pick from when populating your instance (more on “content organisms” below).

To choose from the available options, **click the dropdown** menu next to `🄵 content type` and make a selection. Your selection will be applied to all nested **“Slot”** elements within your `⬦Carousel` instance.

<Container>
  <InlineImage
    width={300}
    height={743}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_7.gif"
  />
</Container>
<br />

### Content Organisms

The options found under `🄵 content type` represent specific content patterns commonly found across washingtonpost.com. These “organisms” are in fact, unique sub-components that are maintained in their own dedicated Figma library (ie **Pattern Kit**), which lives outside of the core WPDS UI kit.

<Container>
  <InlineImage
    width={840}
    height={551}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_8.gif"
  />
</Container>
<br />

### Editing Content via Component Properties

Each content type features its own, unique component properties. Once you’ve selected a content type, its properties can be modified directly in the Design panel. Any edits you make will be applied to your instance of `⬦Carousel`.

<Container caption="The “Story card” (content organism) features several component properties.">
  <InlineImage
    width={298}
    height={620}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_9.gif"
  />
</Container>
<br />

---

## Advanced Customization

### Understanding Component Nesting in Figma

One of the most powerful aspects of designing with components in Figma is the ability to override _nested components_. (Read more about this technique in our guide, “[How to Use Slots](/resources/tutorials/how-to-use-slots)”).

Combined with Figma’s “swap instance” feature,`⬦Carousel` offers several methods to customize the appearance of key UI elements such as content and controls. Out of the box, the component ships with placeholder elements (eg, “slots”) that can be replaced with your own, unique designs— all without ever detaching the component from our component library.

To begin customizing your instance of `⬦Carousel`, **click the dropdown menu** next to `🄵 controls` and select **“Custom”**.

<Container>
  <InlineImage
    width={310}
    height={337}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_10.png"
  />
</Container>
<br />

### Creating Your Own Button Controls

In order to swap the placeholder element with your own custom button — you’ll first have to create a custom button! Your button will then be used as a replacement for the placeholder (shown below).

<Container caption="Placeholder for the “next” button shown in pink">
  <InlineImage
    width={688}
    height={480}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_11.png"
  />
</Container>
<br />

Once you’ve designed the buttons you intend to use in your `⬦Carousel` instance, create a component of each button — one for _“previous”_ one for _“next”_. Frame your selection and give it a name (such as “Custom Buttons”, shown below). Make note of where this frame lives in your Figma file in case you want to make adjustments later.

<Container>
  <InlineImage
    width={358}
    height={280}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_12.png"
  />
</Container>
<br />

Now, in the instance panel, click the dropdown menu next to `🄵 prev button` or `🄵 next button`. In the search field, type the name of the frame where your custom buttons are located.

Choose the “previous” or “next” button that corresponds to the button you are swapping. Your selection will be applied to the `⬦Carousel`. Repeat the process for the other button and your buttons are now customized.

<Container>
  <InlineImage
    width={242}
    height={546}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_13.gif"
  />
</Container>
<br />

<Container caption="Carousel with custom “next” button applied.">
  <InlineImage
    width={688}
    height={480}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_14.png"
  />
</Container>
<br />

### Using Your Own Content

As we saw earlier, Carousel ships with several common patterns to choose from for `🄵 content type`. However, what if none of these options are well-suited for your design or use-case?

Employing the same approach described above, we can replace the default “content” slots in the Carousel, with our own custom content by swapping instances.

<Container>
  <InlineImage
    width={688}
    height={396}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_15.png"
  />
</Container>
<br />

Just as before, you’ll design your own content card in Figma, create a component from it, and place it into a frame. Name the frame something easy to remember such as “Custom Content” (shown below).

<Container caption="Custom content cards like this one can be swapped into the Carousel.">
  <InlineImage
    width={388}
    height={468}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_16.png"
  />
</Container>
<br />

Now let’s look at the instance panel once again and click the dropdown next to `🄵 content type`.

This time, rather than selecting from the default options under “Preferred” – we’ll choose “Local components”, find “Custom Content” and select the content card we designed earlier. Your instance of `⬦Carousel` is now populated with your own custom content!

<Container caption="Choosing your custom content card from the instance panel">
  <InlineImage
    width={240}
    height={546}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_17.gif"
  />
</Container>
<br />

<Container caption="Carousel with custom buttons and and custom content applied">
  <InlineImage
    width={688}
    height={402}
    maxWidth="100%"
    src="/img/resources/tutorials/carousel/figure_18.gif"
  />
</Container>
<br />


WPDS Carousel is robust enough to support a variety of use-cases. In this guide, we’ll show you how to implement the component in your designs and get the most out of its many features. You’ll also learn how to configure the Carousel to enable custom elements such as your own button controls or custom content.

How to use the WPDS Carousel component in your Figma design


<br />

## Installation

Add tailwind to your project by following their specific [framework guides](https://tailwindcss.com/docs/installation/framework-guides).

Install the theme package from npm

```js
npm install -D @washingtonpost/wpds-tailwind-theme;
```

<br />

Add the theme to your tailwind.config.js. It's strongly recommended to override the default theme to prevent the accidental use of Tailwind's color variables and scale values. Tailwind's [preflight](https://tailwindcss.com/docs/preflight) base styles should be disabled.

```jsx demoHeight="200"
const WPDSTheme = require("@washingtonpost/wpds-tailwind-theme");

module.exports = {
  content: [
   ...
  ],
  corePlugins: {
    preflight: false,
  },
  theme: WPDSTheme,
};
```

<br />

Ensure that the WPDS fonts and css variables are available on the page if they are not already installed.

```jsx
// _app.js or other main script file
// also available from @washingtonpost/wpds-ui-kit
import { getCssText, globalStyles } from "@washingtonpost/wpds-theme";

const style = document.createElement("style");
// cssText contains the wpds css variables
style.innerHTML = getCssText();
document.head.appendChild(style);

// global styles adds wpds fonts
globalStyles();
```

---

## Token Naming

The following tokens are used from the WPDS.

- color
- size
- fonts
- fontSize
- fontWeights
- lineHeight
- radii
- shadow
- z-index

The wpds token names and scales for each value replace the Tailwind name and scale.

For example when setting lineHeight `<p class="leading-normal">` becomes `<p class="leading-150">`

---

## Example

<Box css={{ display: "flex", justifyContent: "center" }}>
  <div>
    <h1 className="font-headline text-200 text-primary mt-0 mb-025">
      {`Headline`}
    </h1>
    <h2 className="font-subhead font-light text-150 mt-0 mb-025">
      {`Subheadline`}
    </h2>
    <p className="font-body text-100 mt-0 mb-025">Body text</p>
    <div className="font-meta text-075 text-accessible mb-100">Meta text</div>
  </div>
</Box>
```jsx
<h1 className="font-headline text-200 text-primary mt-0 mb-025">Headline</h1>
<h2 className="font-subhead font-light text-150 leading-200 mt-0 mb-025">
  Subheadline
</h2>
<p className="font-body text-100 mt-0 mb-025">Body text</p>
<div className="font-meta text-075 text-accessible mb-100">Meta text</div>
```


Tailwind WPDS Theme


---

## Introduction

Web performance and SEO are crucial aspects of a website's success. Both contribute significantly to the overall user experience, user engagement, and the website's visibility in search engines.
Web performance refers to the speed and efficiency with which a website loads and operates. A website with good performance ensures a smooth and enjoyable user experience. The importance of web performance lies in the following aspects:

- **User Experience**: Fast-loading websites provide a better user experience, which is essential for keeping users engaged and encouraging them to explore content.
- **Conversion Rates**: A website that loads quickly and functions efficiently can lead to higher conversion rates, as users are more likely to complete desired actions (e.g., making a purchase, signing up for a newsletter).
- **Mobile Users**: With the increasing use of mobile devices, it's crucial to ensure that a website performs well on various devices and network conditions. A well-performing site caters to a broader audience and ensures a positive experience for mobile users.
- **Search Ranking**: Google and other search engines consider web performance as a ranking factor. Faster websites are more likely to rank higher in search results, leading to increased visibility and organic traffic.

SEO is the process of optimizing a website to improve its visibility in search engine result pages (SERPs). The importance of SEO can be summarized in the following points:

- **Organic Traffic**: Effective SEO helps increase the website's visibility in search engines, leading to more organic traffic. Organic traffic is valuable because it is targeted and often has higher conversion rates than paid traffic.
- **Credibility and Trust**: Websites that rank higher in search results are often perceived as more credible and trustworthy by users. Good SEO practices can help improve a website's reputation and authority.
- **Cost-Effective Marketing**: SEO is a cost-effective marketing strategy compared to paid advertising. Once your website ranks high in search results, you can enjoy a continuous stream of organic traffic without incurring additional costs.
- **Competitive Advantage**: By optimizing a website for search engines, it gains a competitive edge over competitors with less effective SEO strategies.

Web performance and SEO are vital for providing a positive user experience, increasing website visibility, driving organic traffic, and ultimately, improving a website's overall success. By focusing on these aspects, you can create a strong foundation for a website's growth and long-term success.

---

## Web Performance

### Loading performance

- Optimize images by compressing them, using responsive images for different screen sizes, and implementing lazy loading to defer the loading of off-screen images until they are needed.
- Minify and compress CSS, JavaScript, and HTML files to reduce their size and improve load times.
- Use Content Delivery Networks (CDNs) to distribute static assets across a network of servers, reducing latency and improving load times for users around the world.

### Rendering performance

- Optimize the critical rendering path by minimizing the number of critical resources and prioritizing the loading of above-the-fold content. This helps ensure that users see content faster.
- Use efficient CSS selectors to minimize browser work during the rendering process, and avoid layout thrashing by batching DOM updates and minimizing forced reflows.
- Optimize JavaScript execution by deferring or asynchronously loading non-critical scripts, profiling and optimizing JavaScript performance, and using requestAnimationFrame for animations.

### Responsiveness

- Design websites for various screen sizes and devices to ensure a consistent and enjoyable user experience across different contexts.
- Implement responsive design techniques, such as fluid grids, flexible images, CSS Flexbox, and Grid Layout, to create adaptable layouts that adjust to different screen sizes and orientations.
- While JavaScript can be used for certain aspects of responsive design, it's generally recommended to prioritize CSS for controlling the layout and visual presentation of the page at different viewport sizes. CSS-based solutions typically perform better, require less code, and can be managed within stylesheets, keeping the separation of concerns between style and functionality.
- JavaScript should ideally be used for interactivity and enhancing the user experience, not for managing core layout changes wherever possible. In some complex scenarios, JavaScript might be required to achieve advanced responsive behaviors that CSS alone can't handle. In these cases, care should be taken to ensure performance and accessibility are not negatively impacted.

---

## SEO (Search Engine Optimization)

### On-page SEO

- Use descriptive and concise title tags to accurately represent the content of each page, helping search engines understand its purpose and relevance.
- Optimize meta tags for both users and search engines:
  - Write informative and unique `meta description` tags to give users a preview of the page content, improving click-through rates from search results.
  - Utilize `meta lang` tags to specify the language of the site's content for better search engine understanding and accessibility.
  - Implement `Open Graph` meta tags to enhance how the pages appear in social media shares, providing richer snippets that attract more engagement.
  - Use `meta robots` tags to guide search engines on what to do with the site's pages. For instance, you can instruct them not to index a page, or not to follow any links on a page.
  - Remember, each meta tag serves a distinct purpose, so ensure they are used appropriately and are relevant to the page's content.
- Use header tags (H1, H2, H3) effectively to structure content and provide hierarchy, making it easier for search engines to understand the content's importance.
- Optimize URL structures by making them readable, descriptive, and concise, helping both users and search engines understand the page's content.

### Content optimization

- Write high-quality, unique, and engaging content to satisfy user intent and increase the likelihood of ranking higher in search results.
- Use proper keyword targeting by including relevant keywords naturally within the content and avoiding keyword stuffing, which can harm rankings.
- Optimize images by using descriptive alt text, relevant file names, and compressing images to reduce file sizes, improving page load times.

### Technical SEO

- Improve site speed by optimizing page load times, as faster-loading pages are more likely to rank higher in search results.
- Implement structured data (schema markup) using JSON-LD to provide additional context for search engines, potentially improving search result appearance and click-through rates. Here are some resources to delve deeper:
  - Understand how to structure data in JSON-LD format. You might use schemas such as `NewsArticle`, `LiveBlogPosting`, and more depending on the content (here is an [example](https://validator.schema.org/#url=https%3A%2F%2Fwww.washingtonpost.com%2Flifestyle%2F2023%2F03%2F15%2Fdog-adoption-potcake-turks-caicos%2F)). Check the JSON-LD website and the Google's guide for further learning.
  - Always validate the schema markups for correctness. Use tools like the Google's Structured Data Testing Tool or Schema Validator to ensure the JSON-LD is error-free and up to standard.
  - Remember, a well-structured schema markup can enhance visibility in search engine results, improve click-through rates, and provide a better understanding of the page content to search engines.
- Ensure crawlability and indexability by properly configuring robots.txt and creating XML sitemaps, helping search engines discover and index the site's content.
- Use canonical tags to avoid duplicate content issues and signal to search engines which version of a page should be considered the original.
- Implement HTTPS and secure the site to protect user data and improve trust with both users and search engines.

### Off-page SEO

- Build high-quality and relevant backlinks from authoritative websites, as they serve as signals of the site's credibility and trustworthiness.
- Utilize social media for content promotion, expanding the content's reach and potentially attracting more backlinks and organic traffic.
- Consider guest posting and content outreach to build relationships with other websites and influencers, increasing the site's visibility and authority.

---

## Monitoring and Reporting

- **Use web performance monitoring tools**: Utilize tools such as Lighthouse and WebPageTest to analyze the site's performance. These tools provide insights into various aspects of performance, including loading speed, rendering, and responsiveness. They also offer recommendations for improvements, making it easier to identify areas that need optimization.
  - **Lighthouse**: An open-source tool by Google that audits websites for performance, accessibility, progressive web apps, SEO, and more. Lighthouse can be run in Chrome DevTools, from the command line, or as a Node module.
  - **WebPageTest**: A free web performance tool that allows you to run tests from multiple locations and browsers, providing detailed information on load times, rendering, and other performance metrics.
  - **Catchpoint (RUM)**: Real User Monitoring tools like Catchpoint help track real user interactions with the site, giving you an accurate picture of actual user experiences across various devices and network conditions. While synthetic tests are useful for simulating specific scenarios or devices, RUM data offers real-world insights that can inform optimization efforts.
  - **Track Core Web Vitals (CWV) trends**: Collaborate with the analytics team to request a report highlighting CWV improvements over a specific time range, or verify the trend directly in the Google Analytics CWV Dashboard, which allows for filtering by page type, date range, mobile versus desktop, and more. Verify trends in the Catchpoint RUM Web Vitals dashboard for the same time range. Although synthetic tests, like Lighthouse or Chrome extensions, can provide useful instant feedback, they are not sufficient to confirm impact at scale. Therefore, make sure to use a combination of these resources to gather comprehensive insights about the site's performance over time.
- **Set up SEO tracking and reporting**: Implement tools like Google Search Console and Google Analytics to track and report on the site's SEO performance. These tools offer insights into organic traffic, search queries, click-through rates, and other valuable SEO-related data.
  - **Google Search Console**: A free service offered by Google that helps you monitor, maintain, and troubleshoot the site's presence in Google Search results. It provides information on indexing status, search queries, and any issues that might be affecting the site's visibility.
  - **Google Analytics**: A comprehensive web analytics service that provides insights into website traffic, user behavior, and other performance metrics. With Google Analytics, you can track organic traffic, user engagement, and the effectiveness of the SEO efforts. Integrating Google Analytics with Google Search Console can provide more in-depth data on the site's SEO performance.

---

## Resources

### Web Performance

1. Google Web Fundamentals: Performance - https://developers.google.com/web/fundamentals/performance
2. Mozilla Developer Network: Performance - https://developer.mozilla.org/en-US/docs/Web/Performance
3. Web.dev: Fast load times - https://web.dev/fast/
4. PageSpeed Insights - https://developers.google.com/speed/pagespeed/insights/
5. High-Performance Browser Networking - https://hpbn.co/

### SEO

1. Google Search Central: SEO Starter Guide - https://developers.google.com/search/docs/beginner/seo-starter-guide
2. Moz: Beginner's Guide to SEO - https://moz.com/beginners-guide-to-seo
3. Yoast SEO: The beginner's guide to SEO - https://yoast.com/complete-beginner-guide-to-seo/
4. Backlinko: SEO This Year - https://backlinko.com/seo-this-year
5. Ahrefs: SEO Basics - https://ahrefs.com/blog/seo-basics/

### General Resources

1. Web.dev: Measure and Optimize - https://web.dev/measure/
2. Google Lighthouse - https://developers.google.com/web/tools/lighthouse
3. Google Search Console - https://search.google.com/search-console/about
4. Google Analytics - https://analytics.google.com/
5. W3C Web Performance Working Group - https://www.w3.org/webperf/


Proven strategies and guidelines for optimizing web performance and search engine optimization (SEO)

Web Performance and SEO Best Practices and Guidelines


---

## Intro

There may be some instances where your team needs to use an icon with an asset that does not currently exist in WAM.

While we aim to help as much as we can, other commitments could mean that we are unable to add an icon to WAM within your timeframe.
It is also possible that you need an icon for a domain specific use case and it does not make sense to add this asset to the system.
For both of these instances, a custom icon might be what you need.

### Prerequisites

This guide assumes that you are working with ReactJS and are using the WPDS Icon Component.

---

## Design

1. **Double-check**: Please make sure that the icon you are looking to use doesn't currently exist in WPDS. You can check Figma or go to the [Icon Assets Page](https://build.washingtonpost.com/foundations/icons) in our docs site to look through what assets we currently make available.

2. **Follow contribution guidelines**: When creating your icon, please follow the contribution guidelines outlined in the [Making an Icon](https://build.washingtonpost.com/foundations/wam#Contributing) section of our docs

3. **Export as SVG**: Please ensure that your new icon is a SVG. In WPDS, all icons are 16x16 pixels.

---

## Code

1. **Add svg to repo and make it a React Component**: Add the svg file to your repo and make it a React Component. There are a couple of different ways you can do this.

   - If you are going to be using a lot of SVGs in your repo, then you might consider using something like [@svgr/webpack](https://react-svgr.com/docs/webpack/) and setting up your webpack configs to convert your SVGs to React Components for you automatically.

   - You can use an online conversion tool such as [SVGR Playground](https://react-svgr.com/playground/) to convert your SVG into a React Component. You can then simply copy and paste that new component into your code.

   - You can cast your SVG into a React Component from your import statement. This might be an okay solution if you are going to be using this icon less than a handful of times. Otherwise, you might want to consider using one of the first two options.

2. **Pass SVG into the Icon component**: Once you have your SVGs available to you as React Components, you can now pass them into the WPDS Icon component like you would a WPDS icon. They will behave the same.

   ```jsx
   import * as React from "react";

   import { Icon } from "@washingtonpost/wpds-ui-kit";
   import { Bell } from "@washingtonpost/wpds-assets";

   // Casting our Crop SVG as a ReactComponent
   import { ReactComponent as Crop } from "./crop.svg";

   export default function App() {
     return (
       <>
         <Icon label="icon" size="200">
           <Bell /> //Our WPDS icon
         </Icon>
         <Icon label="icon" size="200">
           <Crop /> //Our custom icon
         </Icon>
       </>
     );
   }
   ```


How to use our Icon component with your own SVGs to create a custom Icon.

Welcome

What's new

Getting started

Foundations

Components

Resources

Dive Deeper