Update component documentation template (#2787)

Co-authored-by: James Nash <[email protected]>

content-style-guide.md

@@ -0,0 +1,94 @@
+# Salt content style guide
+
+Content written for Salt should follow this style guide. This includes component documentation, pattern guides and other website pages.
+
+Use American English and follow general guidance for producing clear content—concise, active voice, second person, present tense.
+
+## Guidance
+
+Entries are listed in alphabetical order.
+
+### Arrow keys
+
+The correct terms for the four arrow buttons on a keyboard are:
+
+- <kbd>Up arrow</kbd>
+- <kbd>Down arrow</kbd>
+- <kbd>Left arrow</kbd>
+- <kbd>Right arrow</kbd>
+
+### Best practices
+
+Use as a section header where necessary to draw the reader's attention to recommended tips and guidance. Never skip levels when using section headers. See the section section below for more information.
+
+"Best practices" is preferred to "guidance" as it provides greater clarity on what a reader can expect from the section, and provides greater differentiation from other parts of the section.
+
+### Components
+
+Write the term components in sentence case.
+
+When referring to the component as a whole, use Pascal case wrapped in back ticks. Use the name of the component as it appears in code, i.e. `PillNext` rather than `Pill`.
+
+It's likely you will need to use this version if:
+
+- You are introducing the component in a document for the first time.
+- You are recommending the component in a document where the component is not a primary subject.
+- You are describing a release or new version of the component.
+- You are describing how to import the component for use in a project.
+
+When referring to an instance of a component, use sentence case. **If in doubt, use sentence case**.
+
+Here is an example of a correctly-formatted sentence: "I see `Button` has just been released. My project has so many buttons."
+
+### Foundations
+
+Used when referring to the Salt foundations. Avoid the term if not referring to the Salt foundations (or foundations in another design system) to reduce confusion.
+
+Write both the term foundation and the name of the foundation in sentence case, e.g. "Read more in the size foundation."
+
+### Key combinations
+
+Wrap individual keys in \<kbd> tags.
+
+Remember that when using the `KeyboardControl` component to produce a table, the component adds these tags to keys in the function column. Don't worry about adding tags elsewhere in the table, as it would make the table very large and hard to read.
+
+Place modifier keys, such as Shift, before other keys in a combination.
+
+Use + to separate keys within a combination. Add a space to either side of +.
+
+Use / to separate alternative keys or key combinations. Add a space to either side of /.
+
+### Patterns
+
+Used when referring to the Salt patterns. Avoid the term if not referring to the Salt patterns (or patterns in another design system) to reduce confusion.
+
+Write both the term pattern and the name of the pattern in sentence case, e.g. "Refer to the button bar pattern."
+
+### Prop
+
+Use prop, do not use property. Wrap the prop in back ticks. Write out the statement in full to make the formatting clear.
+
+- Correct: "Set `wrap={true}`"
+- Incorrect: "Set the `wrap` prop to `true`"
+
+Outline the simplest possible complete statement. When a user can use a prop with no values, such as `aria-hidden`, recommend the reader use it as-is, rather than passing a Boolean or a string value. When a user can pass a Boolean or string value, prefer Boolean where possible.
+
+### Salt
+
+The name of the design system is Salt. You can describe Salt as a design system, i.e. "We used the Salt design system in our project."
+
+Do not use Salt Design System, Salt DS, or SALT.
+
+### Sections
+
+Section levels should always follow a clear order—as an example, an H3 should follow an H2 or another H3. Refer to the [W3C guidance](https://www.w3.org/WAI/tutorials/page-structure/headings/) for more information.
+
+### Space
+
+Use <kbd>Space</kbd> to refer to the keyboard button. Use \<kbd> tags where appropriate. Don't use <kbd>Spacebar</kbd>.
+
+### Tab
+
+Use <kbd>Tab</kbd> to refer to the keyboard button. Use \<kbd> tags where appropriate. Avoid the term tabbing where possible.
+
+Use tab order. Don't use tabbing order.

templates/component-pages/README.md

@@ -1,8 +1,114 @@
 # How to use the component page MDX template
 
-To add a new component page to the Salt website:
+Follow these steps to add a new component page to the Salt website.
 
-1. Copy the [`component-name/`](./component-name/) folder into the [`site/docs/components/` directory](../../site/docs/components/) and rename it to your component's name in kebab case. For example `form-field/`.
-   - 💡 **Tip:** If you are using GitHub's website to edit component docs, you can press the <kbd>.</kbd> key to launch a version of VS Code in your browser and copy the directory via that.
-1. Fill in the `index.mdx` file's frontmatter (refer to the comments within that file for guidance)
-1. Fill in the `usage.mdx`, `examples.mdx` and `accessibility.mdx` files (refer to the comments within that file for guidance)
+## 1. Getting started
+
+Copy the [`component-name/`](./component-name/) folder into the [`site/docs/components/` directory](../../site/docs/components/) and rename it to your component's name in kebab case. For example `form-field/`.
+
+- 💡 **Tip:** If you are using GitHub's website to edit component docs, you can press the <kbd>.</kbd> key to launch a version of VS Code in your browser and copy the directory via that.
+
+Read the [Salt content style guide](../../content-style-guide.md) to ensure your writing maintains consistency with other documentation.
+
+## 2. Index.mdx
+
+Fill in the `index.mdx` file's frontmatter.
+
+### Description
+
+Wrap the description in "" quote marks. Introduce the components(s) with one to three sentences describing what the component is, why someone would use it, and what problem it solves. Try to introduce all the components that the document covers using Pascal case and back ticks, i.e. `ToggleButton` and `ToggleButtonGroup`.
+
+### sourceCodeUrl
+
+Provide the URL to the relevant directory that contains the main source code for this component.
+
+### Package name
+
+Provide the name of the NPM package that contains this component, e.g. "@salt-ds/core."
+
+### alsoKnownAs
+
+List synonymous names that someone might use when searching for this component. Use sentence case. List them in alphabetical order.
+
+### relatedComponents
+
+List other, similar components with the relationship "similarTo." List other components that this component uses with the relationship "contains." As with alsoKnownAs, use sentence case and order them alphabetically.
+
+### stickerSheet
+
+Link to a Figma stickersheet where applicable.
+
+## 3. Usage.mdx
+
+### Using the component
+
+Change the header title to "Using the components" where applicable.
+
+If needed, provide general usage and guidance that the reader should know. This could cover how they might use it, what sort of questions they might have, what sort of usage you want to discourage. Link to other resources where relevant.
+
+Keep the guidance here short, no more than five sentences. Leave the section blank (but keep the header for navigation consistency) if general usage tips are already covered by the introduction and when to use sections.
+
+### When to use/when not to use
+
+These are H4 headers that sit underneath the "using the component" header and text (if present).
+
+Use this section to outline situations where a user may want to use a given component. Be as thorough as possible, and try to cover all scenarios. Try to ensure each "when to use" has an accompanying "when not to use" and vice versa.
+
+Use bullet points, unless there is one point in **both** sections. Use a new bullet point for each new point for clarity.
+
+Don't worry about writing "use" and "don't use" at the start of each sentence, as it's implied by the section header. Try to start the sentence with "when" or "to", such as "when the nav item contains more than four items."
+
+For the "when not to use" section, provide an alternative solution for each point where possible. Format as "Instead, use X" or "Instead, use X to Y" where X is a component or alternative solution and Y is a task or outcome. Use back ticks and Pascal case for component names, and link to the relevant documentation.
+
+### Import
+
+Introduce with the text "To import `[ComponentName]` from the [core/lab/other] Salt package, use:"
+
+- When there are two components: "To import `[Component1]` and `[Component2]` from the [core/lab/other] Salt package, use:"
+- When there are three or more components: "To import `[Component1]` and related components from the [core/lab/other] Salt package, use:"
+
+Format import commands with "\```js".
+
+### Props
+
+Props tables are automatically generated using the `PropsTable` component.
+
+```js
+<PropsTable packageName="core" componentName="ComponentName" />
+```
+
+If there are two or more components, use an H4 header with the name of the component above each props table. Use back ticks and Pascal case for the header. Use the name of the component as it appears in code.
+
+### Content
+
+Provide content-related guidance if applicable. This could include label text for a button component, or list item length for a dropdown. Remove the section if it's blank.
+
+### References
+
+Include any third-party links that may be relevant here, such as W3C guidance. Use bullet points, unless there is only one.
+
+## 4. Examples.mdx
+
+Follow the structure as outlined in the template for examples. Each example needs a corresponding live preview.
+
+Write header titles in sentence case as always.
+
+Example text should describe what is being demonstrated, what it shows about how the component functions, and why it's significant. Why is it different to other examples? Aim for fewer than six sentences, and avoid bullet points.
+
+Where relevant, include a "best practices" H4 section for the given example. While the main example section covers what the component does, this section covers how the component should be used. What sort of usage would you like the encourage or discourage?
+
+Use bullet points for each tip. Don't use any bullet points if there is only one tip.
+
+## 5. Accessibility.mdx
+
+Under the best practices header, write general accessibility tips that the user should know. Refer to third-party sources and guidance where applicable.
+
+Add keyboard interactions underneath the relevant template header. Use the component structure as outlined in the template to produce a table of key combinations. See [the style guide](../../content-style-guide.md) for detailed information on how to refer to given keys.
+
+Use bullet points unless there is only one point in every row. If the combination refers to a single key, use the name of the key in the explanation. If it's a combination or there are multiple possible keys, refer to the combination with "this action."
+
+Place modifier keys, such as Shift, before other keys in a combination.
+
+Use + to separate keys within a combination. Add a space to either side of +.
+
+Use / to separate alternative keys or key combinations. Add a space to either side of /.

templates/component-pages/component-name/accessibility.mdx

@@ -9,8 +9,11 @@ data:
   $ref: ./#/data
 ---
 
+### Best practices
+
 Accessibility best practices and things to be aware of for this component.
-Copy the contents of the "Accessibility" section in the content template here.
+
+### Keyboard interactions
 
 Where needed, a table of keyboard controls can be created as shown below (just
 delete it, if not needed)

templates/component-pages/component-name/examples.mdx

@@ -13,10 +13,9 @@ data:
 
 <LivePreview componentName="component-name" exampleName="ComponentExample" displayName="Component Example Title">
 
-### Component Example Title
+### Component example title
 
-Brief description of this example. The text should be copied from the
-corresponding example in the content template's "Examples" section.
+Brief description of this example.
 
 The `displayName` prop's value is used to display the example's name in the list
 view and should therefore match the heading within this section.
@@ -25,6 +24,10 @@ If you omit it, the `exampleName` will be displayed in the list for this example
 (with spaces inserted, so "ComponentExample" would display as
 "Component Example").
 
+#### Best practices
+
+See the readme for more details about this section. Delete if not applicable.
+
 </LivePreview>
 
 {/* Add more <LivePreview>...</LivePreview> blocks here as needed */}

templates/component-pages/component-name/index.mdx

@@ -1,9 +1,8 @@
 ---
 title: Component Name
 data:
-  description: Brief (~1 paragraph) description of the component. Copy the text from "Introduction" section in the content template here
+  description: ""
 
-  # Fill in the info from the content template's "Metadata" table below.
   # To omit optional items, comment them out with #
   sourceCodeUrl: "https://github.com/..."
   package:

templates/component-pages/component-name/usage.mdx

@@ -9,16 +9,19 @@ data:
   $ref: ./#/data
 ---
 
-### Using the Component Name component
+### Using the component
 
-Usage information for this component. Copy the content from the content
-template's "How to use" section here.
+Usage information for this component.
+
+#### When to use
+
+#### When not to use
 
 ### Import
 
 {/* Update the text and code snippet below as needed: */}
 
-To import Component Name from the core Salt package, use:
+To import `ComponentName` from the core Salt package, use:
 
 ```js
 import { ComponentName } from "@salt-ds/core";
@@ -33,10 +36,10 @@ import { ComponentName } from "@salt-ds/core";
 
 ### Content
 
-Add text from "Content" section here when available, or else remove this
+Provide content guidance where available, or else remove this
 section.
 
 ### References
 
-Add text from "References" section here when available, or else remove this
+Provide references where available, or else remove this
 section.