This guide explains the techniques involved in the ongoing development a Spectrum control as a spectrum-web-components.

According to webcomponents.org, web components are:

... a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML.

In order to add a new component to this library, you will need to develop a working knowledge of the following technologies:

• Web Components: Standards based method for adding new HTML tags to a browser
• Shadow DOM: The part of the Web Component spec that allows for encapsulation of component styles and child nodes
• lit-element: A simple base class for creating fast, lightweight web components
• CSS custom properties: CSS variables that can be used throughout a document
• Typescript: A typesafe variant of JavaScript

The most complicated part of implementing a Spectrum web component is getting the styles set up correctly. The shadow DOM is the heart of a web component. It isolates the component from the styles and DOM of the containing page. While this offers many benefits, it also means that we must structure our CSS very differently.

For more information on how to structure your CSS, see the Styling guide.

If you look at an sp-button in the Chrome developer tools, you will see a DOM structure that looks like this.

▼<sp-button tabindex="0" variant="accent">
    ▼ #shadow-root (open)
        ▼ <button id="button" tabindex="0">
            ▼ <div id="label>
                ▼ <slot>
                    ↳ #text
                </slot>
            </div>
        </button>
    "Click Me"
</sp-button>

If anything here looks unfamiliar, it is probably a good time to do some reading about web components.

All of the spectrum-web-components are written using the lit-element framework and Typescript. Your best bet is to look at similar components and match the style.

We have a working specification for the APIs for each of the Spectrum components. If you file an issue for the component that you want to implement, we can provide the necessary specifications for it.

The documentation for each component in the documentation site is adopted from the README.md in said package. The pages are written in Markdown. See one of the existing pages for an example.

To run the local documentation server, use the command:

yarn docs:start

The documentation automatically extracts the properties and attributes from the source code. You should document your component using the appropriate jsdoc tags. See Button.ts for an example.

Each component's packages/_componentname_/README.md. These files must meet our standards below:

• Heading structure must communicate the organization of the docs page. See W3C WAI's Tutorial on Headings.
• Main headings (level 2 and 3) should be consistent from component to component. See W3C WAI's Understanding SC 3.2: Predictable and the Documentation structure section below.
• All examples code must be accessible.
• The example code must show the component with enough context to demonstrate how to use it with other elements in an accessible way. See how the examples in packages/help-text/README.md show the component used with field elements.
• The "Accessibility" section contains tips on how to use the component accessibly. See the Accessibility section of packages/picker/README.md.
• The "Accessibility" section contains notes on any accessibility considerations that affect the component's development. See the notes on cross-root ARIA in Accessibility section of packages/help-text/README.md.

Our component documentation should follow the structure below. See packages/menu/README.md and packages/help-text/README.md for overview.

## Overview

### Usage

<--
Information on how to import the component.
-->

### Anatomy

<--
Information and examples about the parts of the component
(eg., labels, icons, etc.)
of the component. -->

### Options

<--
Information and examples about options
(eg., sizes, variants, states, etc.)
of the component.
-->

### States

<--
Information and examples about states
(eg., disabled, loading, etc.)
of the component.
-->

### Behaviors

<--
Information and examples about
values, events, and methods
of the component.
-->

### Accessibility

<--
Tips and examples on how to use the component accessibly
with notes how accessibility considerations
for how the component was developed.
-->

We use Storybook for developing our components. This gives us a rapid way to test our components in various configurations. The best way to start is to copy one of the existing stories.

To run Storybook, use the command:

yarn storybook