BrianAA

JasonBernert

alexisbarnes

alstnc

artmsilva

atomictangerine

baconjulie

carlyn-c

caroldinh

chrisalcantara

christian-wp

clairehhelms

crombach

ebgranger

erikreyna

freedmand

hs4man21

kbondanza

klimenkoff9

linorabolini

mgifford

mjperales

smshaz

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


---

## The Framework

Our framework is grounded in the principle of thoughtful disruption—balancing the need to inform users versus their primary goal for coming to the Washington Post: Reading and engaging with our content.

- Consider these assumptions when using the user education framework:
- Users only internalize a small part of user education.
- Users are scanning, not reading.
- Users are also likely to dismiss a message before reading.
- Clarity begins on the feature level. User education is additive, but can't do all the work.
- The best messaging experiences are valuable, only when needed, and not overlapping. Be mindful of the greater messaging ecosystem. Are there several messages at this moment? Will if feel spammy?

### Using the framework

1.  **Identify the Use Case**

    - Assess the detail required
    - Assess the level engagement level
    - Determine what type of communication

2.  **Design and Implement**
    - Select the appropriate component: Use our matrix of components to help determine the correct pattern of user education for your specific use case.
    - Ensure consistency in design and messaging with other experiences.
    - Test the implementation to ensure clarity and effectiveness.

<Box
  css={{
    display: "grid",
    marginTop:"$250",
    border: "1px solid $outline",
    gridTemplateColumns: "10% 45% 45%",
    gridTemplateRows: "34px 1fr 1fr",
    gridTemplateAreas: `
      "empty lEng hEng"
      "hDet hDlE hDhE"
      "lDet lDlE lDhE"
    `,
  }}
>
    <Box css={{
    gridArea:"empty",  
     background: "$gray600",  
    borderRight: "1px solid $outline",    
    borderBottom: "1px solid $outline"}}/>
    <Box
    css={{
        display: "flex",
        gridArea: "hDet",
        background: "$gray600",
        borderRight: "1px solid $outline",
        borderBottom:  "1px solid $outline",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>High Detail</span>
    </Box>

    <Box
    css={{
        display: "flex",
        gridArea: "lDet",
        background: "$gray600",
        borderRight: "1px solid $outline",
        borderBottom: "0px",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>Low Detail</span>
    </Box>

    <Box
    css={{
        gridArea: "lEng",
        background: "$gray600",
        display: "flex",
    borderRight: "1px solid $outline",
        borderBottom: "1px solid $outline",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>Passive Engagement</span>
    </Box>

    <Box
    css={{
        gridArea: "hEng",
        background: "$gray600",
        borderBottom: "1px solid $outline",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>High Engagement</span>
    </Box>
    <Box
        css={{
            gridArea: "hDlE",
            borderBottom: "1px solid $outline",
            borderRight:"1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b>High Detail & Passive Engagmenet</b>
        </div>
        Appropriate for information-dense content that doesn't demand
        immediate user action, but requires careful consideration
        (e.g., in-depth tooltips, instructional guides)
        </span>
    </Box>
    <Box
        css={{
            gridArea: "hDhE",
            borderBottom: "1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b> High Detail & Active Engagement</b>
        </div>
            Best suited for content that requires active user interaction,
            and involves complex information (e.g., detailed onboarding flows,
            multi-step product tours).
        </span>
    </Box>
     <Box
        css={{
            gridArea: "lDlE",
            borderRight:"1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b> Low Detail & Passive Engagmenet</b>
        </div>
        Fits content that is simple and primarily informational without
        requiring much interaction (e.g., notifications, passive alerts).
        </span>
    </Box>
    <Box
        css={{
            gridArea: "lDhE",
            borderBottom: "1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b>Low Detail & Active Engagmenet</b>
        </div>
        Ideal for interactive content that is easy to grasp,
        but still requires user participation (e.g., quick walkthroughs,
        feature discovery nudges).
        </span>
    </Box>

</Box>

<BR />

---

## Assess the Level of Detail

The level of detail is determined by several factors, primarily based on the complexity of the information, the user's experience level, and how critical the information is to avoid frustration. Consider the following:

1. **Complexity of Information**

   - High Detail: Necessary for complex information involving multiple steps or requiring thorough understanding (e.g., detailed instructions, complex workflows).
   - Low Detail: Suitable for straightforward or simple information, like quick reminders (e.g., single-step instructions, brief notifications).

2. **User Experience Level**

   - High Detail: Required for users new to the application or feature who need comprehensive guidance.
   - Low Detail: Appropriate for experienced users who only need brief reminders or notifications.

3. **Criticality of Information**

   - High Detail: Essential if missing the information could lead to significant issues, errors, or user frustration.
   - Low Detail: Adequate when the information is helpful but not critical to the user's success or safety.

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={796.7}
    height={460}
    maxWidth="100%"
    src="/img/resources/guides/user_education_detail.png"
  />
</Container>
<BR />

---

## Assess the Level of Engagement

When designing user education content, consider the level of engagement needed based on user interaction requirements, learning goals, and the urgency of the communication. Here's how to approach it:

1. **User Interaction Requirement**

   - Active Engagement: Required if the communication encourages users to perform actions, make decisions, or interact with features (e.g., product tours, walkthroughs).
   - Passive Engagement: Suitable for informational content that doesn't require user action beyond reading or acknowledging (e.g., tooltips, system messages).

2. **Learning and Adoption Goals**

   - Active Engagement: Necessary when the objective is for users to learn and adopt new features or changes through hands-on interaction.
   - Passive Engagement: Appropriate if the goal is to inform users without requiring immediate engagement with the content.

3. **Frequency and Urgency**
   - Active Engagement: Ideal for messages that are urgent or infrequent and need immediate attention (e.g., critical alerts, onboarding).
   - Passive Engagement: Suitable for regular communications that serve as ongoing support or reminders.

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={920}
    height={920}
    maxWidth="100%"
    src="/img/resources/guides/user_education_engagement.png"
  />
</Container>

---

## Determine the type of communication

It's crucial to identify the type of communication you need because it will guide decisions around language, messaging, UX, and more. We've categorized our user education into the following three buckets:

- **First Time User Experience**
- **Support**
- **Growth**

---

### First-Time User Experience (FTUX)

FTUX refers to a user's initial interaction with a product or feature. The experience should provide a smooth, engaging and informative introduction to the benefits and features. User education is often useful to show the value prop of our ever-evolving product offerings.

<BR />

**Common FTUX experiences include:**

- Onboarding
- Product Tours
- New Feature Announcements
- Feature Walkthroughs

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={840}
    height={398.28}
    maxWidth="100%"
    alt="A image with three items showing examples of First time user experience. From the left Product tours, Middle New feature annoucements, and last Feature walk-throughs"
    src="/img/resources/guides/user_education_ftux.png"
  />
</Container>

#### Considerations

**UX writing & content design**

- To create the most impactful experience, keep it as simple as possible, or consider if it's needed at all. If the goal is to teach a feature or interaction, make sure you're not leaning on the user education to fix unclear design.
- Many people close tutorials or similar without using them. The lengthier to tutorial, the more drop-off.
- If your user education has multiple steps, place them in order of importance to goals.
- Consider visuals or animation to improve comprehension and engagement.

---

### Support

Support provides users with contextual information and guidance, making it easier for them to understand and effectively use the product's features.

<BR />

**Common support experiences include:**

- Added context (information tooltips)
- System communication (e.g. server timeout and errors, form errors, successful interactions)
- Account messaging (e.g. status of payment, changes to policies, and terms)

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={840}
    height={268.31}
    maxWidth="100%"
    alt="A image with three items showing examples of First time user experience. From the left Product tours, Middle New feature annoucements, and last Feature walk-throughs"
    src="/img/resources/guides/user_education_support.png"
  />
</Container>

#### **Considerations**

**UX writing & content design**

- When providing system-level information (error, confirmation, info messages, etc.), be clear, concise and helpful.
- If it's an error, tell users what happened, why it happened, how to fix it and the next best option. See more details on writing error messages
- Use information tooltips to add non-critical context that helps users or builds trust. For example, “Why is this AI feature here?”
  **Semantic Color**
- Use our semantic colors for error, success, signal, and warning messages. These colors reinforce visual cues and help users quickly understand the context of the communication.

---

### Growth

Growth helps to expand a product'''s user base by encouraging user engagement, sharing, and retention through targeted messages and incentives.

**Common growth experiences include:**

- Upsell Visuals & Interactions
- Account/Subscription Upgrades
- Feature Adoption Campaigns

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={840}
    height={336.27}
    maxWidth="100%"
    alt="A image with two examples on the left account/subscription upgrades and on the right Driving a feature adoption"
    src="/img/resources/guides/user_education_growth.png"
  />
</Container>

#### Considerations

**UX writing & content design**

- User education can be useful to show our ever-evolving offering of features. Be thoughtful if the feature you're drawing attention is actually cool and new in the user's mind. Consider if the user education will feel helpful or spammy.
  -Make value proposition very clear.
- Understand this is an exchange. In exchange for my time, privacy or money, I will receive **\_\_\_**.
- Keep it short.
- Keep it simple. In general, only ask the user to make one choice at a time.
- Have the button/CTA be the appropriate level of commitment for the step. For example, “See subscription options” might come before “Continue to payment.” Example: See Google hotel booking case study
- The text underneath a button is called “trigger text”. It's often used to help someone make a decision, for example “Cancel anytime.”
  **Subscription Color**
- Use our designated subscription color whenever the communication specifically addresses subscription-related topics. This ensures visual consistency and reinforces the importance of subscription messaging.

---

## Selecting the Appropriate Component

We've aligned key components with their inherent interaction patterns within our framework for thoughtful disruption in user education. Each component offers different levels of support for handling complex details. Be sure to consult the component documentation for specific best practices.

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={920}
    height={920}
    maxWidth="100%"
    alt="A image with that place components on a matrix the y axis being level of detail from low to high and x axis being engagement from passive to active."
    src="/img/resources/guides/user_education_matrix.png"
  />
</Container>


This guide is an introduction to our user education framework. By the end of this document, you will have learned the following - Evaluate user education needs based on detail, engagement, and communication type. Apply best practices to select the right components and design effective user education experiences.

User Education Guide


## When to use

**If you're using emojis, they should ideally meet all the following criteria:**

- Used as an enhancement (but not in place of words)
- Used sparingly
- Used when the overall tone of the experience is light

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">
      Emojis chosen should also be light in tone (i.e. confetti is OK;
      tombstones for a Halloween email, not so much)
    </Box>
  </Box>
</Box>

- Used when there's no chance of the emojis appearing juxtaposed with grim, serious articles

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{

      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}

>

    <Box role="listItem">
      For example, Microsoft doesn't have flag emojis. Check to make sure your
      emojis convey what you're intending.
    </Box>

  </Box>
</Box>

<BR/ >

## How to use

**If you use emojis:**

- Use widely recognized emojis that translate well across devices.

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">
      For example, Microsoft doesn't have flag emojis. Check to make sure your
      emojis convey what you're intending.
    </Box>
  </Box>
</Box>

- Make sure the emoji has enough contrast for both light and dark modes.
- Place them at the beginning or end of sentences, not in the middle.
- Use within text (as opposed to an image or any other format).

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">This is required by Apple's guidelines.</Box>
  </Box>
</Box>

- Make sure related copy stands on its own — emojis should be able to be deleted without affecting the meaning.

<BR/ >

## When to avoid

**Avoid using emojis:**

- To represent our core product offerings.

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">
      If we need art to represent core product offerings, we should evaluate if
      the use case warrants creating custom art.
    </Box>
  </Box>
</Box>

- If there's any chance of the emojis appearing juxtaposed with grim, serious stories.


Use these guidelines to help make decisions about emojis in product and marketing contexts. (Newsroom follows its own style guide.)

Emoji 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>
```


Welcome

What's new

Getting started

Foundations

Components

Resources

Dive Deeper