DOCSEARCHbyAlgolia
Submit Docs

Spectrum CSS

repository·main·Indexed 23 days ago

https://github.com/adobe/spectrum-css

A CSS-based implementation of Adobe's Spectrum design language providing flexible, accessible, and framework-agnostic UI components. The repository includes a suite of PostCSS plugins (postcss-add-theming-layer, postcss-property-rollup, and @spectrum-tools/postcss-rgb-mapping) and Stylelint plugins (stylelint-no-missing-var, stylelint-suit-naming-pattern, stylelint-use-logical, and @spectrum-tools/stylelint-no-unknown-custom-properties) to manage design tokens, theming layers, and CSS variable validation.

Tokens
38.7K
Snippets
37
Records
372
Agent score
76%

What's inside spectrum-css

  2. How to swap between S2 Foundations, S1, and Express contexts

    main

    To render a component that can be easily swapped between S2 Foundations, S1, or Express contexts, load index-base.css along with the index-theme.css file. You can then leverage the appropriate context classes on a parent element:

    • .spectrum--legacy for S1
    • .spectrum--express for Express

  4. Choose between Spectrum 1, Express, and Spectrum 2 Foundations

    main

    Spectrum CSS components (starting from version 6.0.0) act as a bridge between Spectrum 1 (S1), Express, and Spectrum 2 (S2) designs using a "system" layer. This allows you to swap component appearances by loading different token versions and using specific context classes.

    Design Targets

    • Spectrum 2 (S2) Foundations: Load assets with @spectrum-css/tokens at v16 or higher.
    • Spectrum 1 (S1) or Express: Load assets with @spectrum-css/tokens at v14.x or v15.x.
    • Full Spectrum 2 (S2): For a complete S2 implementation (not just foundations), use the next tag releases.

    Switching Contexts

    To render a component that can be easily swapped between S2 Foundations, S1, or Express, load index-base.css along with index-theme.css and use the following context classes:

    • .spectrum--legacy for S1
    • .spectrum--express for Express

  5. Switch between Spectrum 1, Express, and Spectrum 2 Foundations

    main

    Starting with version 6.0.0, Spectrum CSS introduces a bridge between Spectrum 1 (S1) and Spectrum 2 (S2) designs called "Spectrum 2 Foundations". This allows you to swap component appearances by leveraging a "system" layer that remaps component-level tokens to the appropriate dataset.

    Choosing your design context

    • For Spectrum 2 Foundations: Load assets with @spectrum-css/tokens at v16 or higher.
    • For Spectrum 1 or Express: Load assets with @spectrum-css/tokens at v14.x or v15.x.
    • For fully migrated S2 designs: Use the next tag releases instead of the foundations release. Note that the foundations release is what is used in Spectrum Web Components 1.x.

    Loading CSS assets

    Depending on your requirements, use the following files:

    • S2 Foundations only: Use index.css. This contains all base styles plus the system mappings for S2 Foundations.
    • S1 or Express only: Use index-base.css combined with the desired theme file from themes/(spectrum|express).css.
    • Swappable contexts: To allow a component to switch between S2 Foundations, S1, or Express, load index-base.css along with index-theme.css. You can then trigger the appearance using context classes:
      • .spectrum--legacy for S1
      • .spectrum--express for Express

  6. Understand Spectrum 2 Foundations and design bridging

    main

    Version 5.0.0 introduced "Spectrum 2 Foundations," which acts as a bridge between Spectrum 1 (S1) and Spectrum 2 (S2) designs. This version uses a "system" layer to remap component-level tokens to appropriate token datasets, allowing consumers to swap appearances between S1, Express, and S2.

    Design Compatibility Requirements

    To achieve specific looks, you must pair the component with the correct version of @spectrum-css/tokens:

    • For S2 appearance: Load assets with @spectrum-css/tokens at v16 or higher.
    • For S1 or Express appearance: Load assets with @spectrum-css/tokens at v14.x or v15.x.

    Note: If you require a fully migrated S2 design (not just Foundations), use the next tag releases instead. This version is used in Spectrum Web Components 1.x.

  7. Switch between Spectrum S1, Express, and S2 Foundations

    main

    Starting with version 7.0.0, Spectrum CSS introduces a 'foundations' layer that allows you to swap component appearances by leveraging a system layer that remaps component-level tokens to appropriate token datasets.

    To achieve different design looks, you must pair the correct CSS assets with the appropriate version of @spectrum-css/tokens:

    • For Spectrum 2 (S2) Foundations: Load assets with @spectrum-css/tokens at v16 or higher.
    • For Spectrum 1 (S1) or Express: Load assets with @spectrum-css/tokens at v14.x or v15.x.

    Note: If you require a fully migrated S2 design (not just the foundations bridge), use the next tag releases. The foundations release is used in Spectrum Web Components 1.x.

  8. How to use Spectrum 1 or Express styles

    main

    To use Spectrum 1 (S1) or Express designs with the foundations release, you must load assets with @spectrum-css/tokens at v14.x or v15.x.

    If you are publishing only an S1 or Express component, use index-base.css combined with the desired theme file from the themes/ directory (e.g., spectrum.css or express.css).

  9. Configure Spectrum CSS visual context and themes

    main

    Spectrum CSS uses CSS classes applied to a container (usually the <html> element) to define the visual language, scale, and theme. Because of CSS cascading, you can nest these contexts.

    Visual Language

    • .spectrum: Default (Spectrum 2 foundations).
    • .spectrum--legacy: Legacy Spectrum 1 (Deprecated).
    • .spectrum--express: Express variant (Deprecated).

    Scales (Browsing Context)

    • .spectrum--medium: Default for desktop and tablet.
    • .spectrum--large: Larger scale for mobile/touch devices.

    Themes (Colorstops)

    • .spectrum--light: Default light mode.
    • .spectrum--dark: Dark mode.

    Implementation Example

    To set a medium, light Spectrum 2 context, use: <html class="spectrum spectrum--medium spectrum--light"></html>

    <html class="spectrum spectrum--medium spectrum--light"></html>

  10. Build optimizations in @spectrum-css/popover v7.1.0

    main
    Starting from version 7.1.0, all component CSS files are processed through cssnano (a lightweight optimizer). This reduces file size by removing unnecessary whitespace, specifically within var() functions, to improve minification efficiency. This change does not impact component rendering.

  11. How to use Spectrum 2 Foundations, S1, and Express styles

    main

    Spectrum CSS provides a bridge between Spectrum 1 (S1), Express, and Spectrum 2 (S2) designs via 'Spectrum 2 Foundations'. This allows you to swap component appearances by leveraging a 'system' layer that remaps component-level tokens to appropriate datasets.

    Achieving S2 Appearance

    To render components with S2 Foundations, you must load assets with @spectrum-css/tokens at v16 or higher.

    Achieving S1 or Express Appearance

    To render S1 or Express components, load assets with @spectrum-css/tokens at v14.x or v15.x.

    Switching Contexts Dynamically

    To create a component that can be easily swapped between S2 Foundations, S1, or Express contexts, load index-base.css along with the index-theme.css file. Use the following CSS context classes to trigger the desired look:

    • .spectrum--legacy for S1
    • .spectrum--express for Express

    Note: For a fully migrated S2 design (not just Foundations), use the next tag releases. This foundations release is used in Spectrum Web Components 1.x.

  12. Implement Spectrum 2 Foundations via the system layer

    main

    Spectrum 2 (S2) Foundations provides a bridge between Spectrum 1 (S1), Express, and S2 designs. It uses a "system" layer that remaps component-level tokens to appropriate token datasets, allowing you to swap appearances by changing the context.

    To achieve the S2 Foundations look, you must load assets with @spectrum-css/tokens at v16 or higher.

    For S1 or Express designs, use @spectrum-css/tokens at v14.x or v15.x.