Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@spectrum-css/bundle-builder

adobe166Apache-2.0deprecated7.0.2

This package has been deprecated and is no longer receiving updates.

The Spectrum CSS top-level builder

readme

GitHub Actions build status on main
GitHub Actions build status on spectrum-two

Spectrum CSS

A CSS-implementation of the Spectrum design language

Features

  • 📖 Robust documentation: Spectrum CSS is designed to be used in partnership with Spectrum's detailed usage guidelines.
  • 🎨 Flexible: Our CSS is customizable, powerful, and designed to work with any JavaScript framework.
  • 🧪 Rigorously tested: These individually-versioned components have been vetted to be accessible and inclusive of global audiences.
  • 📱 Multi-platform support: We support evergreen browsers (minus one version) for scalability and flexibility.

      

Using Spectrum CSS

The preferred method of using Spectrum CSS relies on custom properties to swap out variables for different themes and contexts. This results in the lowest bundle sizes and is one of the simpler approaches.

Functionality

Spectrum CSS is CSS-only, implementing only the interactivity that can be done with pure CSS. We do include some lightweight JS-based interaction for demonstration purposes only in our Storybook and documentation. Spectrum CSS should only be used by implementations of Spectrum, or very simple applications that only need things like typography, checkboxes, text fields, etc.

Adobe maintains separate libraries written with web components and React that work in partnership with Spectrum CSS to create fully interactive Spectrum components.

The Spectrum Web Components library directly imports Spectrum CSS and optimizes it for use with web components.

Installing components

Each component is released on npm as a separate, individually versioned package inside of the @spectrum-css org.

To incorporate Spectrum CSS into your project, you install only the components you need:

yarn add -DW @spectrum-css/tokens @spectrum-css/typography @spectrum-css/page @spectrum-css/icon @spectrum-css/button

Installed components will be available in the node_modules/@spectrum-css/ folder of your project.

All components in this library have a peer dependency on @spectrum-css/tokens, which is a local package that serves up the Spectrum design tokens as CSS custom properties (via Style dictionary). These custom properties are leveraged in all components to create a cohesive visual language and to allow for easy theming. If you choose not to use the provided @spectrum-css/tokens package, you must define your own custom properties or your components will not render correctly. Overriding the tokens is not recommended, however, modifying styles is supported through the use of component-specific --mod prefixed properties. More on this below.

Using components in your project

Spectrum CSS components have build output that is designed to be used in a variety of ways. The most common way to use Spectrum CSS is to include the dist/index.css file for each component you need in your project.

  • index.css - This file includes the component's styles and variable definitions. In this version, token-driven CSS properties1 are mapped to empty --mod prefixed variables (for customization) with a fallback to variables prefixed with --system (used in adjusting results accordion to context or theme) or --spectrum (sourced from the design tokens). This is the file most commonly used to incorporate Spectrum CSS into a project.

    • This file loads both the .spectrum and .spectrum--express contexts which are used to toggle components between two different visual styles. The .spectrum context is the default.
  • index-vars.css - Deprecated. This file is identical to index.css. It is provided as a fallback for older implementations that may have been using it and will be removed. It is recommended to use index.css instead.

  • index-base.css: This file mimics the index.css output, but does not include the .spectrum or .spectrum--express contexts.

    • When using Spectrum CSS in a product that is rendering only one visual language (i.e. only loading the .spectrum context), you can use index-base.css plus the preferred context from the themes directory. i.e., loading index-base.css and themes/spectrum.css to render the default Spectrum visual language.
    • This approach can also be used when you have defined and written your own visual language and only need the base styles from Spectrum CSS. To wire up your own visual language, you would need to define your own custom properties that match those defined in the themes/*.css assets.
  • index-theme.css: This file provides only the visual language for a component. It is used in conjunction with index-base.css and when loaded together, results in a similar result to index.css.

1: Token-driven CSS properties are properties whose values are mapped to a value in the @spectrum-css/tokens package. These values represent design-language and are meant to be used across platforms. Properties specific to web-based implementations will not have a token value assigned and thus not all CSS properties will use custom properties.

Including assets

Start by including the base set of variables:

/* Include tokens */
@import "node_modules/@spectrum-css/tokens/dist/index.css";

/*
  For components with no other contexts available, load the
  index.css file from the component's package. These are components
  that do not have a spectrum or express context available.
*/
@import "node_modules/@spectrum-css/page/dist/index.css";
@import "node_modules/@spectrum-css/typography/dist/index.css";
@import "node_modules/@spectrum-css/icon/dist/index.css";

/*
  For components with multiple contexts available, load only the context you need (spectrum or express) by sourcing index-base.css and the theme you need from the themes directory.
*/
@import "node_modules/@spectrum-css/button/dist/index-base.css";
@import "node_modules/@spectrum-css/button/dist/themes/spectrum.css";

Tokens values are mapped to context-specific classes which can be applied to the <html> element or at any place in your DOM where you wish to encapsulate or alter the visual language of your Spectrum components.

All available contexts should be defined in order to load all the appropriate custom properties for the components you are using.

Visual language

  • .spectrum - The default visual language for Spectrum CSS
  • .spectrum--express - A variant of the standard visual language

Scales

Scales represent the browsing context of the user. They are used to adjust the size of components to improve readability and usability on different devices.

  • .spectrum--medium - The default scale for Spectrum CSS, used for desktop and tablet devices
  • .spectrum--large - A larger scale for Spectrum CSS, used for mobile devices and other small screens to create a more touch-friendly experience

Themes (colorstops)

Themes represent the color scheme of the user's browsing context. They are used to adjust the color of components to improve readability and usability in different environments.

  • .spectrum--light - The default theme for Spectrum CSS, used for light mode
  • .spectrum--dark - A darker theme for Spectrum CSS, used for dark mode

Other modes are available but are in the process of being deprecated and should not be used in new projects.

Example

Put together, we would define the context for our application in the following way:

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

To switch to Express, add the .spectrum--express class to the <html> element:

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

Note the spectrum--express class is added to the existing classes; spectrum should always be present to ensure the correct visual language is loaded.

Components can then be added by following the semantic guidance found in the Spectrum CSS documentation.

Because CSS custom properties honor the cascading nature of CSS, you can infinitely nest different contexts. For example, you could have a .spectrum--dark context inside of a .spectrum--light context, and components will honor the innermost context.

Modifying components

You can override variables and modify Spectrum CSS' look and feel by re-defining the custom properties in context. Look for the Custom Property API section in each component to determine which custom properties you can override. See Action Button for a complete example.

Importing UI icons

Some components require certain "UI icons" to render. These icons are released within the @spectrum-css/ui-icons package and are used by components like @spectrum-css/icon and @spectrum-css/actionbutton.

Based on which scales you'll be using, you can choose to load different files:

  • spectrum-css-icons.svg - Both medium and large icons for responsive UIs that support both .spectrum--medium and .spectrum--large

  • spectrum-css-icons-medium.svg - Medium icons only, supports .spectrum--medium only

  • spectrum-css-icons-large.svg - Large icons only, supports .spectrum--large only

Note: If you're using spectrum-css-icons.svg, be sure to add .spectrum--medium or .spectrum--large to the <html> element, or you'll see both medium and large icons at once.

Importing workflow icons

If your app has any level of complexity, you'll need "workflow" icons to indicate actions. These icons are not required to render the base components, and instead are used within buttons or menu items for actions like share, play, justify, save, etc.

These icons are released within the @adobe/spectrum-css-workflow-icons package. Visit the Spectrum workflow icon list and click on any icon to get the SVG markup.

Language support

To take advantage of locale specific changes such as placeholders not italicizing Japanese, your application should specify a Content-Language response header or set the lang attribute.

In addition, you should set the dir attribute for components to render correctly.

For English, a left-to-right language:

<html lang="en" dir="ltr"></html>

For Arabic, a right-to-left language:

<html lang="ar" dir="rtl"></html>

Browser support

We maintain a relatively modern codebase that supports the latest two versions of evergreen web browsers. The current list of browsers officially supported by Spectrum CSS can be found in the browserslist section of the project's package.json file. This setting is used by the build tools when the source files are built. If you require additional browser support for your project, the CSS can processed further with your chosen tools.

  • latest 2 Edge versions
  • latest 2 Chrome versions
  • latest 2 Firefox versions
  • latest 2 Safari versions
  • latest 2 iOS versions

Optimizing Spectrum CSS

Spectrum CSS is designed to be as modern and flexible as possible, and as such, leaves room for consumers to optimize in their own way. There are many tools and techniques you can use to optimize CSS for your project such as tree shaking, purging, and minification. If you are loading the entire set of @spectrum-css/tokens for example, you can safely tree shake the tokens to only include the variables you are using, often leading to a significant reduction in file size.

Contributing

A very special thank you to all of our contributors without whom this project would not be possible.

Want to join the team? Check out the contributing guidelines for quick start information.

Getting started

To get started with Spectrum CSS, you'll start by cloning the repository:

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

or if you're using the GitHub CLI:

gh repo clone adobe/spectrum-css

To ensure your Node environment is always aligned with the project, we strongly recommend using nvm. Once you have nvm installed, you can run:

nvm use

This will ensure the correct version of node is installed and used for the project. You always want to run nvm use when you first clone the project and whenever you switch branches.

Then, install the dependencies:

yarn install

Important: Requires >= Node 18.8.1 and Yarn 1.22.0.

To spin up the local development environment, run:

yarn start

This will spin up the project's Storybook. Editing any of the *.css or the *.stories.js files in components/* will live reload in your browser.

This project is leveraging caching from Nx to speed up the build process. If you are seeing unexpected results, you can clear the cache by running yarn nx reset.

Tasks

The following tasks are available:

  • yarn clean - Cleans all output files for the project and all components
  • yarn build - Performs a build of all components
  • yarn build:all - Performs a build of all components, documentation site, and storybook
  • yarn dev - Performs a component build, runs storybook, and serves the documentation on the default port (3000), then starts watching components and website files
  • yarn compare: This compares the current version of components with the previous versions published to NPM and output a list of all the changes that have been made. This is useful for reviewing changes before a release. The information is provided in the command-line output as well as in a simple web page that is opened in your default browser upon completion. The web page includes links to the visual diffs for each component when the file sizes have changed.
    • Components with no changes are not included in the output.
    • To run comparisons on one or multiple components, yarn compare accepts a list of components as arguments. For example, yarn compare button will compare the current version of the button component with the previous version published to NPM. yarn compare button checkbox will compare the current version of the button and checkbox components with the previous versions published to NPM.
    • Named components should be space-separated.
    • Running yarn compare with no inputs will automatically run against all packages.
    • Note that you must run yarn build before running yarn compare to ensure that the latest build is being compared.
  • yarn lint: Provides helpful updates and warnings for a component's package.json file. This helps keep all components in alignment.
    • Use yarn lint --fix to automatically fix any issues that are found.
    • To run on a single component, use yarn linter accordion (where accordion is the name of the component or components you want to lint).
  • yarn refresh:env: This copies values for the project's .env file (an asset never committed to the repo as it contains login secrets) by using the .env.example file as a template. This script is useful when you need to update the .env file with new values from the .env.example file or when you checkout or clean the repo and need to restore the .env file.

Documentation

To spin up the documentation site locally:

yarn dev

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

7.0.2

🗓 2024-02-26 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

7.0.1

🗓 2024-02-20 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

7.0.0

🗓 2024-02-15 • 📝 Commits

♻️ Code refactoring

  • quickaction:deprecate component; support this in docs (#2304)(84e1ee9)

    ###
    🛑 BREAKING CHANGES
    
        *
        **quickaction:** @spectrum-css/quickaction deprecated

This component has been deprecated. Use an action bar to allow users to perform actions on either a single or multiple items at the same time, instead.

6.3.2

🗓 2024-02-12 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

6.3.1

🗓 2024-02-06

Note: Version bump only for package @spectrum-css/bundle-builder

6.3.0

🗓 2024-02-05 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

6.2.0

🗓 2024-01-29 • 📝 Commits

✨ Features

*migrate build packages to postcss v8 (#2460)(bd6c40e)

6.1.2

🗓 2024-01-16 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

6.1.1

🗓 2024-01-16 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

6.1.0

🗓 2023-12-12 • 📝 Commits

✨ Features

6.0.0

🗓 2023-12-12 • 📝 Commits

*feat(icon,ui-icons)!: migrate the icon compiler to a distinct package (#2343)(d73d594), closes#2343

    ###
    🛑 BREAKING CHANGES

        *
         - @spectrum-css/icon will no longer contain SVG assets; it will be a purely CSS package with all SVG assets migrated to the new @spectrum-css/ui-icons package.
  • NEW: @spectrum-css/ui-icons package for all SVG icons in the UI set.

5.0.1

🗓 2023-12-04 • 📝 Commits

🐛 Bug fixes

*docs watch unable to find package.json(a6d23b9)

5.0.0

🗓 2023-11-15 • 📝 Commits

🔙 Reverts

*gulp and build updates (#2121)(03a37f5), closes#2099

*feat(vars,expressvars)!: deprecate packages (#2244)(5eb391c), closes#2244

    ###
    🛑 BREAKING CHANGES

        *
        as no additional changes have been or are planned to be made to

these legacy token packages, these assets no longer need to exist in the monorepo structure for Spectrum CSS.

4.0.14

🗓 2023-11-13 • 📝 Commits

🔙 Reverts

*gulp and build updates (#2121)(03a37f5), closes#2099

4.0.13

🗓 2023-08-07 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.12

🗓 2023-07-31 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.11

🗓 2023-07-24 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.10

🗓 2023-06-21 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.9

🗓 2023-06-01 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.8

🗓 2023-05-17 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.7

🗓 2023-05-09 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.6

🗓 2023-05-02 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.5

🗓 2023-04-26 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.4

🗓 2023-04-25 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.3

🗓 2023-04-25 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.2

🗓 2023-04-25 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.1

🗓 2023-04-17 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

4.0.0

🗓 2023-04-03 • 📝 Commits

  • fix(tokens)!: rgb transform to split out rgb values from css attributes (#1590) (b714db4), closes #1590

🛑 BREAKING CHANGES

  • transforms color tokens to split out their rgb values

Co-authored-by: castastrophe castastrophe@users.noreply.github.com

3.4.5

🗓 2023-03-13 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.4.4

🗓 2023-01-25 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.4.3

🗓 2023-01-18 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.4.2

🗓 2023-01-13 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.4.1

🗓 2023-01-13 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.4.0

🗓 2022-09-12 • 📝 Commits

✨ Features

  • adding port customiztion and re-launch for watch (5c7aeef)
  • watch covers components/commons (5d1b682)

🐛 Bug fixes

  • dev hanging on yaml error and dev opening browser tabs (fbfc622)
  • made browser open message more perfect (dad62eb)

3.3.1

🗓 2022-07-22 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.3.0

🗓 2022-06-16 • 📝 Commits

✨ Features

3.2.0

🗓 2022-01-05 • 📝 Commits

✨ Features

  • break out ClearButton and LogicButton into their own packages (3cc0a5f)

3.1.0

🗓 2021-12-14 • 📝 Commits

✨ Features

  • break out ClearButton and LogicButton into their own packages (a2092ab)

3.0.4

🗓 2021-11-16 • 📝 Commits

🐛 Bug fixes

  • actually fail when you fail (6a49a99)
  • fetch package publish date from npm registry (71fd187)

3.0.3

🗓 2021-10-25 • 📝 Commits

🐛 Bug fixes

  • fetch package publish date from npm registry (71fd187)

3.0.2

🗓 2021-09-29 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.0.2-alpha.1

🗓 2021-07-19 • 📝 Commits

🐛 Bug fixes

  • added expressvars build to release task (bc447b1)

3.0.2-alpha.0

🗓 2021-04-27 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.0.1

🗓 2021-03-10 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.0.0

🗓 2021-02-02 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

3.0.0-beta.0

🗓 2020-12-04 • 📝 Commits

✨ Features

  • disable legacy build in output (f1ef983)
  • error and warning reporting for variable use (0460d39)
  • support FORCE=true environment variable to allow broken components (f725a17)

🐛 Bug fixes

  • correct usage of ActionButton in site templates (be0c83a)

🛑 BREAKING CHANGES

  • this completely removes legacy build artifacts and IE 11 support

2.0.2-beta.0

🗓 2020-09-23 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

2.0.1

🗓 2020-06-19 • 📝 Commits

Note: Version bump only for package @spectrum-css/bundle-builder

2.0.0

🗓 2020-03-12 • 📝 Commits

✨ Features

  • remove DecoratedTextfield (a1017a8)

🛑 BREAKING CHANGES

  • DecoratedTextfield has been removed in favor of Textfield docs: don't include DecoratedTextfield anymore

1.1.0

🗓 2020-02-10 • 📝 Commits

✨ Features

1.0.1

🗓 2019-11-07 • 📝 Commits

🐛 Bug fixes

  • add missing variables to -unique files, closes #336 (3c9337f)

1.0.0

🗓 2019-10-08

✨ Features