documentation conventions

---

tags: [conventions]

Documentation Conventions

Stencil API reference

Stencil uses JSDoc for their API reference generation. Stencil generates a docs-json output target, which is parsed and displayed on the SDK site. The API reference includes property/attribute names, descriptions, types, values, and description notes (e.g. required, optional, deprecated). The SDK site updates the API reference after Calcite Component releases.

Style guide

Follow these conventions when adding or editing API reference:

• Use complete sentences with proper grammar, capitalization, and punctuation.
• No abbreviations, e.g. use "property" instead of "prop".
• Verbs must be in present tense.
• Use the full tag name when referencing other Calcite Components (prefix with calcite-), e.g. calcite-button instead of button.
• For plural context, use calcite-buttons instead of calcite-button elements.
• Use backticks (`) for the names of slots, events, properties, CSS variables, and component names (e.g. calcite-button instead of calcite-button and selectionMode instead of "selectionMode"). Also use backticks for the values of properties and event details (e.g. true). If the value is a string, use both backticks and double quotes (e.g. "single-persist").
• Only use single quotes (') as apostrophes.
• No links or URLs allowed in descriptions. If a link is necessary, a custom JSDoc tag should be added and parsed in the SDK site.
• Refrain from using "e.g." or "i.e." references. Leverage "such as" (or similar) where examples are referenced.
• Use "Accessible" instead of "Aria" or "a11y" language.
• Verify slots and properties/attributes don't use the text "optional" in their descriptions.

Deprecation notices

There are two ways to document deprecations, depending on the API reference. In both cases a deprecated chip will be displayed in the SDK site within the component's API reference section.

1. The @deprecated JSDoc tag is used for JavaScript properties, events, and methods in the <component-name>.tsx file. Notes can accompany the JSDoc tag, such as "use <property> instead".
2. The [Deprecated] text is added at the beginning of the JSDoc description for slots (@slots) in the <component-name>.tsx file and CSS variables in the <component-name>.scss file. The text is parsed and removed from the description in the SDK site.

Usage snippets

You can provide code snippets demonstrating a specific behavior or pattern for a component. Within the component's directory, create a new usage directory. Then, create a Markdown file with the filename as the title of the snippet. There should only be one snippet per Markdown file. Stencil will add the usage snippets to the component's README after building. These usage snippets will then be displayed in Storybook.

Storybook

Calcite Components uses Storybook to provide an interactive showcase of components with accompanying documentation and also to provide previews for screenshot testing. Storybook is deployed with prerelease versions, whereas the SDK site is only updated during releases. Storybook is a great resource for testing the newest changes and viewing the newest API reference.

Writing stories

For each main component (i.e. one that can be used by itself), there should be a <component-name>.stories.ts file in its component folder.

Each component should use the Component Story Format (CSF) with at least two stories. If your component has properties that effect visual styles, you can use the storybook knobs addon to allow people to manipulate properties and see live updates in the documentation. A minimal stories file might look something like this (explained below):

import { boolean } from "@storybook/addon-knobs";
import { modesDarkDefault } from "../../../.storybook/utils";
import { storyFilters } from "../../../.storybook/helpers";
import { html } from "../../../support/formatting";
import notes from "./readme.md";

export default {
  title: "Components/My Component",
  parameters: { notes },
  ...storyFilters(),
};

export const simple = (): string =>
  html`<my-component demo-prop="${boolean("demo-prop", true)}"></my-component>`;

export const darkModeRTL_TestOnly = (): string =>
  html`<my-component
    demo-prop
    dir="rtl"
    class="calcite-mode-dark"
  ></my-component>`;

darkModeRTL_TestOnly.parameters = { modes: modesDarkDefault };

Make sure to import the README generated by Stencil so that it can be viewed in Storybook. Parent components should also import the READMEs for their children:

import accordionReadme from "./readme.md";
import accordionItemReadme from "../accordion-item/readme.md";

export default {
  title: "Components/Accordion",
  parameters: {
    notes: {
      accordion: accordionReadme,
      accordionItem: accordionItemReadme
    },
    ...
};

General guidelines

• Story names should be camelCased
• All stories need to import the storyFilters util and include it in the default export so stories can be properly filtered
• Update the main custom theme story instead of adding a specific story showing how to use a custom CSS prop
• Should only have HTML for the component or use case itself (e.g., no need to wrap in calcite-label)
• Update the simple story with a corresponding knob instead of adding a story specific to a new prop
• Don't add or update a story if it is covered by an existing one

Interactive showcase stories

• Should have knobs configured to allow users to toggle different options available to the component
• The simplest, base configuration should be named simple for consistency
• This story should have as many knobs possible for developers to interact with
• Should have one story per unique, supported use case
• Stories that can be covered by adding a new prop/knob should instead update an existing playground story (with the exception of _TestOnly stories, explained below)

Screenshot test-only stories

• Should have the minimal HTML needed to reproduce the test scenario
• Should not have knobs since screenshot tests cannot interact with them
• Stories that are only meant for testing should use the _TestOnly suffix, which ensures it is only used for the screenshot test build. For example, if a snapshot with specific properties is needed for testing, it wouldn't need to be included in the playground where knobs can be used to display the state in the simple story.
• Stories that are not meant for testing should use the _NoTest suffix, which ensures it is only used for the internal playground build. For example, stories that requires interaction not supported by the screenshot test environment, such as changing knobs.
• The simple story and any other significant configuration should have a matching darkModeRTL_TestOnly story
  • In order to reduce snapshot count, dark mode and RTL visual tests have been combined

Using utilities

There are a variety of Storybook helpers and utilities that should be used for common patterns. You can use existing stories as a reference for when/how the utilities and helpers should be used.