Change 973168 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Add Rules component for dos and don'ts

https://gerrit.wikimedia.org/r/973168

@DTorsani-WMF I've pushed a patch to add a new Rules component that can be used in the docs to create dos and don'ts. It's available in all of the docs markdown files, so you don't need to import it or anything.

I updated the contrast demo on the Typography page to use the new component. Please note that this demo has a special, darker background color - by default, the media section of each column will have @background-color-subtle.

With the Rules component, you can:

• Add either an image or a coded example as the "media" for each item
• Add a single line of text that appears on the same line as the "Do:" or "Don't:" label
• Add an ordered or unordered list under the "Do:" or "Don't:" label
• Add custom labels to use instead of "Do:" or "Don't" (this will be needed on the Designing icons page)

Here's now it works:

Bullet points

In the markdown files, you can mix markup/Vue components and markdown. This is nice because you don't have to write out the HTML for an unordered list or an image. The important thing is that you leave an empty line between markup/Vue and markdown:

<cdx-demo-rules class="cdx-docs-contrast">
<template #do-media>

![A screenshot of an interface conveying an example of a dialog using clear messaging.](../assets/content-guidelines/writing-for-copy/clear-do.svg)

</template>
<template #do-text>

- Use the same terminology in the title and the CTA.
- Group related content together.
- Consider how the text looks, as well as what it says.

</template>
<template #dont-media>

![A screenshot of an interface conveying an example of a dialog adding additional, unnecessary questions.](../assets/content-guidelines/writing-for-copy/clear-dont.svg)

</template>
<template #dont-text>

- Add an additional information or question or use inconsistent terminology.

</template>
</cdx-demo-rules>

A single line of text

To get a single line of text on the same line as the "Do" or "Don't" label, we need a little HTML to prevent Vitepress from wrapping the line in a new <p> tag. For HTML, do not leave any empty lines. The example below is the contrast demo, which uses text for the "media" and then has a single line of text for the dos and don'ts. You can see that the text does use empty lines around it, so that VitePress will wrap it in a <p> tag, while the explanation text has no empty lines around it and will be treated like HTML.

<cdx-demo-rules class="cdx-docs-contrast">
<template #do-media>

Bento (弁当 bentō) is a single-portion take-out or home-packed meal common in Japanese cuisine.

</template>
<template #do-text>
Contrast against the background
</template>
<template #dont-media>

Bento (弁当 bentō) is a single-portion take-out or home-packed meal common in Japanese cuisine.

</template>
<template #dont-text>
Low contrast below 4.5:1, especially at smaller sizes, makes text harder to read.
</template>
</cdx-demo-rules>

Custom labels

You can customize the "Do" and "Don't" labels by passing in these props:

<cdx-demo-rules custom-do="Codex will mirror: " custom-dont="Codex will not mirror: ">
<!-- stuff --->
</cdx-demo-rules>

This will be useful for that Designing icons page (although that particular demo only has a single image; we will need to break it into 2 images to be able to use the new Rules component)

Let me know what you think about this! If you like it, I will rebase your content guidelines patch on top of my Rules patch and update a few examples there so you can see the results.

This seems great @AnneT, thank you for doing this. I would be grateful if you could rebase my patch on top of yours with a few updated examples so I can check it out and continue with the rest.

Change 973168 merged by jenkins-bot:

[design/codex@main] docs: Add Rules component for dos and dont's

https://gerrit.wikimedia.org/r/973168

Change 980902 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] Update Codex from v1.0.1 to v1.1.1

https://gerrit.wikimedia.org/r/980902

Test wiki created on Patch demo by ATomasevich (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/d419984345/w

Change 980902 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v1.0.1 to v1.1.1

https://gerrit.wikimedia.org/r/980902

Test wiki on Patch demo by ATomasevich (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/d419984345/w/