Documentation Styleguide

Documentation

Documentation should guide a consumer through the steps needed to implement a component in their application. The ideal path should navigate through documentation that increases in complexity, so that the simplest path is reached as early as possible.

Snippets

A consumer should be able to copy and paste a snippet into their own application with little to no modification.

RECOMMEND

1. Short, focused snippets
2. Use native HTML elements
3. Use HelixUI-defined elements
4. Use HelixUI-defined class names
5. Function placeholders, with instruction to define in consumer's application

AVOID

1. Avoid long, complex snippets
2. Avoid using assets defined in a 3rd party library.
   • e.g., Bootstrap class names
3. Function placeholders without further instruction

Components vs Elements

Component

A component is a collection of elements that contribute to a larger set of behaviors.

RECOMMEND

1. Static examples of the component in various states
2. Interactive demos (optional)
3. Cross-link between related components to aid discovery.
   • e.g., from Grid to Layout (and vice versa)
4. Cross-link to elements used in a component
   • e.g., from Tabs to <hx-tabset>

AVOID

1. Do not cross-link to unrelated elements
   • e.g., from Icons to <hx-tabset>
2. Do not cross-link to unrelated components
   • e.g., from Icons to Grid

Element

An element is an isolated unit that is often used in combination with other elements to provide more complex behavior.

RECOMMEND

1. Document element metadata (parents, children, events, etc.)
2. Document element attributes
3. Document element properties
   • Every attribute should have an associated property.
4. Cross-link between related elements
   • e.g., from <hx-tabset> to <hx-tablist>
5. Cross-link to components the element helps compose.
   • e.g., from <hx-tabset> to Tabs

AVOID

1. No interactive examples
2. No empty elements
   • Do not define or document elements lacking behavior.
3. Do not reflect every property as an attribute.
   • Not every property can be configured via attributes.
4. Do not cross-link between unrelated elements
   • e.g., from <hx-tabset> to <hx-tooltip>
5. Do not cross-link to unrelated components
   • e.g., from <hx-tabset> to Box

Demos

(tentative to PR#281)

• <div class="example"> (bind VueJS logic to this element along with a [v-cloak] attribute)
  • <header> (optional, configuration for the demo)
    • <form class="beta-hxForm">
      • <div> or <p>
        • <label for="...">
        • <input id="..."> or <select id="..."> or <textarea id="...">
      • <fieldset>
        • <legend>
        • <label>
          • <input type="checkbox"> or <input type="radio">
  • <div> (live demo)
  • <footer> (code snippet)
    • <pre>
      • <code>

Try on Codepen