DOCSEARCHbyAlgolia
Submit Docs

Spectrum Web Components

repository·main·Indexed 23 days ago

https://github.com/adobe/spectrum-web-components

A library of reusable, accessible, and customizable web components that implement Adobe's Spectrum design system. Version 0.0.9 provides a consistent UI foundation for web applications, including components such as Accordion, Action Bar, Action Button, and Action Group.

Tokens
498.1K
Snippets
861
Records
2.3K
Agent score
81%

What's inside Spectrum Web Components

  1. Overview of Spectrum Web Components

    main
    Spectrum Web Components (SWC) is a library of web components that implements Adobe's Spectrum design system. While primarily used by Adobe product teams, it is open-sourced and available for general use. The library is currently undergoing a transition from its first generation (1st-gen) to its second generation (2nd-gen).

  2. Overview of testing types in Spectrum Web Components

    main

    Testing for 2nd-gen components is categorized into three main types to ensure functional correctness, accessibility, and visual consistency.

    • Interaction tests: Use Storybook play functions to verify properties, slots, events, and warnings. These are defined in *.test.ts files.
    • Accessibility tests: Use Playwright combined with aXe to verify the ARIA tree and WCAG compliance. These are defined in *.a11y.spec.ts files.
    • Visual regression tests: Use Storybook and Chromatic to ensure correct rendering across different browsers and themes. These are defined in test/vrt/*.vrt.ts files.

  3. Overview of Linting Tools

    main

    The repository uses centralized linting and formatting configurations located at the root. The primary tools are:

    • ESLint: Handles JavaScript and TypeScript linting using a flat config (eslint.config.js).
    • Stylelint: Handles CSS linting (stylelint.config.js), including a custom swc/header plugin.
    • Prettier: Handles code formatting (.prettierrc.yaml).

    Pre-commit hooks are managed via lint-staged, which automatically runs linting and formatting on staged files during a commit.

  4. Overview of @adobe/swc-tokens

    main

    The @adobe/swc-tokens package is responsible for ingesting Spectrum design token source data and converting it into usable assets for @adobe/spectrum-wc components.

    Key outputs include:

    • CSS Custom Properties: A unified stylesheet for component use.
    • lookupToken(): An exported function used by @adobe/postcss-token to resolve token names to computed values or composed custom properties.
    • Typography Stylesheet: A generated stylesheet containing typography classes.

    Terminology

    • Token: A named design value (e.g., gray-500).
    • Alias: A reference to another token (e.g., {gray-500}).
    • Set: A token with multiple contextual values (e.g., light / dark).
    • Resolved value: A final primitive value.
    • Custom property: A CSS variable (e.g., var(--swc-gray-500)).

  5. Overview of Spectrum Web Components

    main

    Spectrum Web Components is an implementation of Adobe's Spectrum design system. The components are built using the LitElement base class and follow Web Component standards, making them lightweight and framework-agnostic. They are designed to work with any web framework or even without one, as they are encapsulated at the browser level. Key features include:

    • Accessible by default: Built with browser specifications to support screen readers, keyboard navigation, and customized contrast.
    • Lightweight: Uses LitElement to minimize overhead.
    • Standards-based: Uses standard Web Component technologies to create custom elements that behave like native HTML elements.
    • Framework agnostic: Can be integrated into any existing web development environment.

  6. Overview of Spectrum Web Components 2nd Generation packages

    main

    The 2nd generation of Spectrum Web Components is split into two primary packages:

    • @adobe/spectrum-wc-core: Provides abstract base classes that define the behavior and API for 2nd-gen components.
    • @adobe/spectrum-wc: Contains the concrete component implementations including their associated styling.

  7. Testing overview for 2nd gen components

    main

    Second generation (2nd gen) components utilize three distinct testing methodologies:

    1. Interaction Tests: Implemented using Storybook play functions.
    2. Accessibility Tests: Implemented using Playwright.
    3. Visual Regression Testing: Performed through Storybook stories.

    For detailed information on file structure, assertion conventions, coverage thresholds, and flaky test prevention, refer to the full Testing guide.

  9. Check component availability in Spectrum CSS and Web Components

    main

    The Spectrum component inventory tracks the availability of design tokens, CSS implementations, and Web Component implementations for various Spectrum components.

    When choosing a component, note that:

    Some components may have CSS and design token support but lack a Web Component implementation (marked with ❌).

  10. Use Token Intellisense for autocomplete and diagnostics

    main

    The swc-vscode-token extension provides autocomplete and diagnostics for token("...") values sourced from @adobe/swc-tokens.

    Features

    • Autocomplete: Partial, case-insensitive completion for token("...") values.
    • Typography Snippets: Typing a grouped typography token (e.g., type-component-m-regular) and pressing Tab expands into multiple CSS declarations (font-family, font-size, etc.).
    • Smart Editing: Quote balancing, automatic trimming of trailing whitespace, and the ability to resume completions after editing inside existing quotes.
    • Diagnostics:
      • Deprecated tokens: Shows "renamed to..." diagnostics and hover guidance.
      • Deleted tokens: Provides hover guidance suggesting replacements or indicating if a value should be hardcoded to 0.
      • Unknown tokens: Suggests candidates, including renamed tokens.

    Supported Languages

    • CSS
    • PostCSS
    • SCSS
    • JavaScript
    • TypeScript
    /* Example of typography snippet expansion in CSS */
font-family: token("sans-serif-font-family");
font-size: token("font-size-100");
font-weight: token("regular-font-weight");
letter-spacing: token("letter-spacing");
line-height: token("line-height-font-size-100");

  11. Use the `<swc-color-loupe>` component

    main

    The <swc-color-loupe> is a visual-only component used to display a color preview in a teardrop-shaped container. It is designed to assist users (primarily during touch interactions) by showing the selected color over an opacity checkerboard, preventing the user's finger from obscuring the selection.

    Key Characteristics

    • Visual-only: It is decorative and does not have its own accessibility semantics or keyboard interaction.
    • Parent-managed: The component does not manage its own visibility. A parent color component (like <swc-color-area>, <swc-color-slider>, or <swc-color-wheel>) must control the open state.
    • Adaptive Contrast: The loupe uses a white-first adaptive border system to maintain a 3:1 non-text contrast ratio (WCAG 1.4.11) against the underlying color.

  12. What is the swc-color-handle component?

    main

    The swc-color-handle (formerly sp-color-handle) is a non-interactive primitive used as a draggable dot on top of color selection components like sp-color-area, sp-color-slider, or sp-color-wheel.

    It serves to show the currently selected color (over an opacity checkerboard) and automatically displays a swc-color-loupe when touched or interacted with. It does not have its own public methods, events, or slots; instead, it relies on reflected properties to communicate state.