Documentation Guidelines

If you need to refer to a specific version, use "Vivid x.x.x" (eg. Vivid 4.9.3)

**Do:** Vivid, Vivid x.x.x<br />**Don't:** VIVID, vivid, VIVID@3, vivid-3, Vivid 3

**Do:** Searchable Select, Combobox, Date Time Picker<br />**Don't:** Searchable select, combobox, date-time-picker

Use an [online tool](https://capitalizemytitle.com/style/APA/) to convert text to APA title case.

**Do:** Getting Started With Vivid<br />**Don't:** Getting started with Vivid

Don't write poetry. Don't use jargon and fancy words.

Write how you've done it in simple language, explain where to use it, and add guidance for using it again.

Be as straightforward as possible. Don't write essays; no one will read them.

People using the design system will only use the components when they fully understand the specifics.

**Do:** color<br />**Don't:** colour

**Do:** CSS, GitHub, npm<br />**Don't:** css, github, NPM

[Active vs Passive voice](https://www.grammarly.com/blog/sentences/active-vs-passive-voice/)

**Do:** Use the label attribute to provide a visible label for the Checkbox.<br />
**Don't:** The label attribute is used to provide a visible label for the Checkbox.

<vwc-button label="Live Example" appearance="filled" connotation="cta"></vwc-button>

A live code example can be added to a page using the following markdown:

```html preview
<my-component></my-component>
```

You can set the preview window’s height by providing the height in px’s:

```html preview 285px

You can also choose from these layout options: full | blocks | columns | inline (default) | center

```html preview blocks

• Make examples as close to real life as possible
  Eg. When demonstrating the label attribute;
  Don’t: use “Label text” as the example content
  Do: use a value like “Surname” as this closer to actual content
• Maintain the order of code in the example
  and for clarity, keep a clear line between each.
  1. HTML
  2. CSS
  3. Javascript
• Put the most relevant parts at the top of the code
  Eg. When demonstrating the appearance attribute on Button, make appearance the first attribute on the component.
• Use classnames to add extra styles
  Do: .split-button { .... }, .container { ... }
  Don’t vwc-split-button { .... }, div { ... }

Each component page is split into sub pages (represented in the tab-like navigation at the top of the page). When a new component is added using the generator, the following documentation sub-page files are produced:

• Variations: VARIATIONS.md
  • Examples of the component in all possible visual states
• Guidelines: GUIDELINES.md
  • Displays general do’s and dont’s on component usage
• Code: README.md
  • How to install the component
  • Examples for the properties that don’t effect the visual states
  • Examples for slots, events etc.
• Use Cases: USE-CASES.md - shows examples different ways the component can be used
• Accessibility: ACCESSIBILITY.md - show advice ono how to use the component in an accessible way

Each of these generated sub page files contain example content (markdown) to help our component docs stay consistent. Delete parts you don’t need, but maintain the order / format of the ramaining parts.

See the component generator files for examples of the recommended content & structure of each sub page.

Some component pages will not need every one of the sub-pages, this can be configured in the components.json file in the docs app.

When a new component is added using the generator, this object is added to the components.json.

[
  [...],
  {
    // Name of the component / concept
    "title": "My Component",

    // slug for the component page url (eg. /components/my-component). Since slug is unique, it also serves for an kay / id of the concept in the docs.
    "slug": "my-component",

    // optional, not generated - parent of the current page in the hierarchy. Please refer to `eleventyNavigation` plugin.
    "parent": "[...]",

    // optional, not generated - children of the current page in the hierarchy. Please refer to `eleventyNavigation` plugin."
    "children: ["...", "..."]
  },
  [...]
]