[docs] Best Practices and Guidelines ("This / Not This") examples improvements

[markcaron]

Break up our "This / Not This" best practices and guidelines images and examples into separate images and columns (or cards), similar to what we do on our Brand site.

This will make it easier to scan as well as improve non-visual accessibility.

"This" and "Not this" should be HTML text paired with an icon.

Current situation

What we're looking for

Pages that will need to be updated:

Unchecked tasks with a PR number are in progress

• Accordion (docs(accordion): update best practices #2029)
• Alert
• Audio player (docs(audio player): update best practices #2101)
• Avatar (docs(avatar): update best practices #2098)
• Badge (docs(badge): update best practices #2099)
• Blockquote
• Button
• Call to action
• Card
• Code block
• Dialog
• Footer
• Navigation - secondary
• Popover (update docs during element development)
• Progress steps (update docs during element development)
• Spinner (docs(spinner): update best practices #2094)
• Statistic
• Subnavigation (docs(subnav): update best practices #2072)
• Table (docs(table): update rh-table best practices #2061)
• Tabs (docs(tabs): update best practices #2040)
• Tile (docs(tile): update best practices #2033)
• Timestamp (docs(timestamp): update best practices #2031)
• Tooltip (docs(tooltip): update best practices #2030)

[marionnegp]

The Color page's Best Practices section uses this format.

This is a sample of what the Dos and Don'ts currently look like in code:

<div class="best-practices-grid">
    <div>
        <img slot="header" src="/assets/color/best-practices-custom-themes-correct.svg" alt="Blue submit button, blue default call to action, black tooltip, and blue switch">
        <h4 class="correct">Do</h4>
        <p>Use the color variants already available for elements and patterns.</p>
    </div>
    <div>
        <img slot="header" src="/assets/color/best-practices-custom-themes-wrong.svg" alt="Magenta button, brand red default call to action, green tooltip, and dark orange switch">
        <h4 class="wrong">Don't</h4>
        <p>Do not create your own colors, design tokens, or change the colors of existing elements and patterns.</p>
    </div>
</div>

It would be good to add this format as a shortcode.

[marionnegp]

Also, is there a preference for using "This"/"Not this" vs "Do"/"Don't"?

[markcaron]

Also, is there a preference for using "This"/"Not this" vs "Do"/"Don't"?

@marionnegp not really. I'm ok with using Do/Don't instead. Might be more of a common practice anyway.

[zeroedin]

I did some initial work on this in #1465

https://deploy-preview-1465--red-hat-design-system.netlify.app/foundations/color/usage/#custom-themes

The variation looks a bit different then the examples above as I used a <figure> For the image. It seemed appropriate given the linked description of the images as the <figcaption>

Here is what the HTML looks like:

<uxdot-best-practice>
  <uxdot-example slot="do" no-border="" variant="full" alignment="left" color-palette="lightest">
    <figure>
      <img slot="header" src="/assets/color/best-practices-custom-themes-correct.svg" alt="Blue submit button, blue default call to action, black tooltip, and blue switch">
      <figcaption>Use the color variants already available for elements and patterns.</figcaption>
    </figure>
  </uxdot-example>
  <uxdot-example slot="dont" no-border="" variant="full" alignment="left" color-palette="lightest">
    <figure>
      <img slot="header" src="/assets/color/best-practices-custom-themes-wrong.svg" alt="Magenta button, brand red default call to action, green tooltip, and dark orange switch">
      <figcaption>Do not create your own colors, design tokens, or change the colors of existing elements and patterns.</figcaption>
    </figure>
  </uxdot-example>
</uxdot-best-practice>

This component can be tweaked however we deem necessary as I was just evaluating using a slotted <figure> in a uxdot-example for this use case.

Right now <uxdot-best-practice> has 2 slots do and dont and currently only only displays in a 2 up grid as that is the only use case I've ran across so far.

[marionnegp]

@zeroedin, using <figcaption> makes sense to me, though we might want to adjust the placement of the caption or "Do/Don't" heading.

There might be times we want to add more than one "do" or "don't" image (like if we split the two images in this audio player example) or have a best practice example be full-width.

[zeroedin]

<uxdot-best-practice do> and <uxdot-best-practice dont> which use a figcaption in the shadowroot. It is available in #1465. This PR does not update any content.

I believe this issue partially an ask to update all Best Practice sections across the site to use this new style as well so will leave it open.

[coreyvickery]

@marionnegp

• Use new icons
• 8px of space in between icon and text