Spectrum CSS provides a standard CSS implementation of the Spectrum design language for internal and 3rd party use on Adobe's platforms.
Check out the documentation site for a demo of every component included in Spectrum CSS.
Spectrum CSS is CSS-only, implementing only the interactivity that can be done with pure CSS. Thus, Spectrum CSS should only be used by implementations of Spectrum, or very simple applications that only need things like typography, checkboxes, textfields, etc.
Adobe maintains separate JavaScript libraries written with React, Angular, and web components that use Spectrum CSS to create fully interactive Spectrum components. These libraries will be open sourced soon.
The preferred method of using Spectrum CSS relies on custom properties to swap out variables for different themes and colorstops. This has the lowest bundle size and the simplest usage, but is incompatible with < IE 11
To use Spectrum CSS with IE 11 or without, see the legacy usage documentation.
Each component is released on npm as a separate, individually versioned package inside of the @spectrum-css org.
To get started, install the following components:
npm install @spectrum-css/vars @spectrum-css/typography @spectrum-css/page @spectrum-css/icon @spectrum-css/button
Installed components will be available in the node_modules/@spectrum-css/ folder.
If you are an existing user of Spectrum CSS and rely on the previous bundle package format, see the legacy usage documentation for details.
Spectrum CSS components have build output that uses CSS custom properties to change themes and scales. This has the lowest bundle size and the simplest usage, but is incompatible with IE 11.
To use Spectrum CSS with IE 11, see the legacy usage documentation.
If you're targeting modern browsers, start by including the base set of variables:
<!-- Include global variables first -->
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-global.css">
<!-- Include only the scales your application needs -->
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-medium-unique.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-large-unique.css">
<!-- Include only the colorstops your application needs -->
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-lightest.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-light.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-dark.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/vars/dist/spectrum-darkest.css">
<!-- Include index-vars.css for all components you need -->
<link rel="stylesheet" href="node_modules/@spectrum-css/page/dist/index-vars.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/typography/dist/index-vars.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/icon/dist/index-vars.css">
<link rel="stylesheet" href="node_modules/@spectrum-css/button/dist/index-vars.css">Then, make sure you've included the relevant classes to choose which scale and colorstop you want:
<html class="spectrum spectrum--medium spectrum--light">Note: If you are importing SVG icon sprite sheets, the .spectrum--medium/.spectrum--large classes should be added to the <html> element so UI icons render in the correct size in IE 11. For browsers that support custom properties, or if you're not using SVG sprite sheets for UI icons and are manually managing icon sizing in your implementation, .spectrum--medium/.spectrum--large can be added to the <body> or other element.
Then you can use components by copy/pasting their code from the documentation.
With the magic of CSS custom properties, you can infinitely nest different color stops and themes, as illustrated here.
Additionally, you can override variables and customize Spectrum CSS' look and feel by re-defining the custom properties in context, like so. See the source in components/*/index-vars.css to determine which custom properties you can override.
Some components require certain "UI icons" to render. To get these icons, you'll need to use loadicons.
For most use cases, you'll want to use spectrum-css-icons.svg so you have support for both scales:
<script src="node_modules/loadicons/index.js"></script>
<script>
loadIcons('node_modules/@spectrum-css/icon/dist/spectrum-css-icons.svg');
</script>Based on which scales you'll be using, you can choose to load different files:
@spectrum-css/icon/dist/spectrum-css-icons.svg- Both medium and large icons for responsive UIs that support both.spectrum--mediumand.spectrum--large@spectrum-css/icon/dist/spectrum-css-icons-medium.svg- Medium icons only, supports.spectrum--mediumonly@spectrum-css/icon/dist/spectrum-css-icons-large.svg- Large icons only, supports.spectrum--largeonly
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.
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 in the bundle package as @spectrum-css/spectrum-css/dist/icons/spectrum-icons.svg. You can import the entire set of icons in all sizes as follows:
loadIcons('node_modules/@adobe/spectrum-css-workflow-icons/dist/spectrum-icons.svg');You can then use the icons in your app. Visit the Spectrum CSS workflow icon list and click on any icon to get the markup.
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.
<html lang="ja">Check out the contributing guidelines for quick start information, and head over to the component documentation and bundle documentation for more information.
Run the following commands:
yarn global add gulp-cli
yarn install
gulp dev
Your dist/ folder should now have a local copy of the Spectrum CSS docs and minimal CSS files, and your browser should be open with the project documentation. Editing any of the .css or .yml files in components/* will update the project documentation and live reload in your browser.
Important: Ensure you have Node.js > 10.10 installed or the build system will not run. Node.js > 12.x is preferred.
Building the project will build and launch the project documentation site in your browser automatically.
See site generation and documentation generation for more information.
The following tasks are available:
gulp build- Performs a build of all components and the top level packagegulp buildComponents- Performs a build of all componentsgulp dev- Performs a lite build (custom properties only), opens your browser with the documentation site, then starts watching components and website filesgulp clean- Cleans all output files for the project and all componentsgulp watch- Assuming a build has already been performed, immediately opens your browser with the documentation site, then starts watching components and website filesgulp buildCombined- Builds the combined output files (dist/spectrum-*.css)gulp buildStandalone- Builds the standalone output files (dist/standalone/spectrum-*.css)gulp release- Performs a release of the top-level packagegulp packageLint- Lint thepackage.jsonfile for each component in the monorepogulp readmeLint- Generate a genericREADME.mdfile for each component in the monorepo
Visual regression testing is implemented by BackstopJS. In order to avoid browser rendering inconsistent issue on different environments, the test needs to run inside of docker container.
Install docker on your machine Download Docker
The reference bitmaps are hosted in a adobe internal repo and published as @spectrum-css/spectrum-css-vr-test-asset. All the reference bitmaps are generated within docker instance. If you want to run test with native environment, you have to regenerate the reference yourself.
gulp dev
The following npm scripts are available for testing:
npm run backstop:approve- Identical to backstop approvenpm run backstop:test- Run test in your local native environmentnpm run backstop:clean- Clean up all the testing reports and test imagesnpm run backstop:docker:test- Run test in your local docker containernpm run backstop:ci:test- Run test in a continuous integration environment like Travis-CInpm run kill-zombies- Kill zombies Chromium instances on your local machine
Both backstop:test and backstop:docker:test accept arguments to customize your test run:
npm run backstop:docker:test- Run test for all the components with color stop aslightand scale asmedium.npm run backstop:docker:test button- Run test forbuttonand its dependents components like action bar, toast etc with color stop aslightand scale asmedium.npm run backstop:docker:test themes=lightest,light scales=medium,large radio- Run test forradioand its dependents components with color stop aslightestandlightand scale asmediumandlarge. It means that a single scenario will run 4 times.npm run backstop:docker:test themes=lightest,light,dark,darkest scales=medium,large- Run test for all the components with all the color and scale combinations. It means that a single scenario will be run 8 times.
Releasing individual components is handled by Lerna. When any component or its dependencies change, Lerna will queue that component (and all of its dependents) up for a release.
To release everything that has changed, simply run:
npm run release
Version numbers are automatically determined, changelogs generated, and packages published.
Bundles are released with a separate command, intended to be ran after individual components are released. To release bundles, simply run:
npm run release-bundles
Version numbers for dependencies and then bundle itself will be updated automatically, a changelog generated, the package published, and the documentation site deployed.