spectrum-web-components

name	spectrum-web-components
description	Build UIs with Spectrum Web Components (SWC), Adobe's Spectrum 1 web component library. Use when developers are working with @spectrum-web-components/* packages or sp-* custom elements. Includes component API references, usage examples, accessibility guidance, and integration guides.
license	Apache-2.0
metadata	{"author":"Adobe","website":"https://opensource.adobe.com/spectrum-web-components/"}

Spectrum Web Components (Spectrum 1)

Spectrum Web Components (SWC) is Adobe's Spectrum 1 design system implemented as framework-agnostic web components. Elements are prefixed with sp- and each ships as an independent npm package under @spectrum-web-components.

Upgrading to Spectrum 2? Use the migrate-swc-gen1-to-gen2 skill instead, which includes per-component migration guides and a full coexistence walkthrough.

Quick start

Install the components you need (each component is its own package):

yarn add @spectrum-web-components/theme \
         @spectrum-web-components/button \
         @spectrum-web-components/badge

All sp-* components must be wrapped in <sp-theme> to receive Spectrum CSS tokens:

<script type="module">
  import '@spectrum-web-components/theme/sp-theme.js';
  import '@spectrum-web-components/theme/scale-medium.js';
  import '@spectrum-web-components/theme/theme-light.js';
  import '@spectrum-web-components/button/sp-button.js';
</script>

<sp-theme system="spectrum" scale="medium" color="light">
  <sp-button variant="accent">Save</sp-button>
</sp-theme>

Key concepts

• <sp-theme> is required — it provides all design tokens (color, scale, spacing, typography) to descendant sp-* elements via CSS custom properties. See What is a theme? for a full explanation of system, color, scale, direction, and language attributes.

• Per-package install — each component (@spectrum-web-components/button, @spectrum-web-components/badge, etc.) is imported separately so your bundle only includes what you use.

• Side-effectful import — importing the .js entry registers the custom element:

  import '@spectrum-web-components/button/sp-button.js';
  

  Import the class directly for extension or typing:

  import { Button } from '@spectrum-web-components/button';
  

• Spectrum 2 theme bridge — apply system="spectrum-two" to <sp-theme> to adopt Spectrum 2 visual tokens on Gen 1 components. This is useful when running Gen 1 and Gen 2 side-by-side during a gradual migration.

• React — use @swc-react/* wrapper packages for first-class React event handling. See Using SWC with React.

• Accessibility — sp-* components expose correct ARIA roles, labels, and keyboard navigation. Labels are typically provided via the label attribute or the default slot; see each component's API reference for specifics.

Documentation structure

The references/ directory contains guides and one Markdown file per component. Read the component file for its API, slots, events, CSS custom properties, and usage examples.

Guides

{{GUIDE_LIST}}

Components

One file per component in references/components/ (e.g. references/components/sp-badge.md). Read the file for props, slots, events, CSS custom properties, and usage examples.

Available components: {{COMPONENT_NAMES}}.

{{COMPONENT_LIST}}