diff --git a/README.md b/README.md index d0a8f098d6b..dc8d057f9f2 100644 --- a/README.md +++ b/README.md @@ -1,170 +1,150 @@ -# Spectrum CSS +
-Spectrum CSS provides a standard CSS implementation of the Spectrum design language for internal and 3rd party use on Adobe's platforms. +![GitHub Actions build status on main](https://img.shields.io/github/actions/workflow/status/adobe/spectrum-css/production.yml?branch=main&style=for-the-badge&label=main)
![GitHub Actions build status on spectrum-two](https://img.shields.io/github/actions/workflow/status/adobe/spectrum-css/production.yml?branch=spectrum-two&style=for-the-badge&label=spectrum-two) -1. [Show me a demo](#show-me-a-demo) -1. [Where is the JavaScript?](#where-is-the-javascript) -1. [Using Spectrum CSS](#using-spectrum-css) -1. [Contributing](#contributing) +
-## Show me a demo +

Spectrum CSS

+

A CSS-implementation of the Spectrum design language

-Check out the [component viewer](http://opensource.adobe.com/spectrum-css/preview) for a demo of every component included in Spectrum CSS or spin it up locally with: `yarn start`. This preview is driven by [Storybook](https://storybook.js.org/docs/web-components/get-started/introduction), a development tool that enables rapid prototyping and test suite integration. + -Alternatively, you can preview the [documentation site](http://opensource.adobe.com/spectrum-css/) or spin up the site locally with: `yarn dev`. +## Features -## Where is the JavaScript? +* ๐Ÿ“– **Robust documentation**: Spectrum CSS is designed to be used in partnership with [Spectrum's detailed usage guidelines](https://spectrum.adobe.com/). +* ๐ŸŽจ **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. -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, text fields, etc. - -Adobe maintains separate JavaScript libraries written with [web components](https://opensource.adobe.com/spectrum-web-components/) and [React](https://react-spectrum.adobe.com/react-spectrum/index.html) that use Spectrum CSS to create fully interactive Spectrum components. +     [](https://opensource.adobe.com/spectrum-css/get-started.html)   [](https://opensource.adobe.com/spectrum-css/preview/) ## Using Spectrum CSS -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 and below. +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. -### Browser support +### 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. -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](https://github.com/adobe/spectrum-css/blob/main/package.json). 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. +Adobe maintains separate libraries written with [web components](https://opensource.adobe.com/spectrum-web-components/) and [React](https://react-spectrum.adobe.com/react-spectrum/index.html) that work in partnership with Spectrum CSS to create fully interactive Spectrum components. -- last 2 Edge versions -- last 2 Chrome versions -- last 2 Firefox versions -- last 2 Safari versions -- last 2 iOS versions +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](https://www.npmjs.com/org/spectrum-css). +Each component is released on npm as a separate, individually versioned package inside of the [@spectrum-css](https://www.npmjs.com/org/spectrum-css) org. -To get started, install the following components: +To incorporate Spectrum CSS into your project, you install only the components you need: ```shell -yarn install @spectrum-css/vars @spectrum-css/typography @spectrum-css/page @spectrum-css/icon @spectrum-css/button +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. +Installed components will be available in the `node_modules/@spectrum-css/` folder of your project. -### Using components +All components in this library have a peer dependency on [`@spectrum-css/tokens`](tokens), which is a local package that serves up the [Spectrum design tokens](https://github.com/adobe/spectrum-tokens) as CSS custom properties (via [Style dictionary](https://amzn.github.io/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. -Spectrum CSS components have build output that uses CSS custom properties to change themes and scales. Start by including the base set of variables: +### Using components in your project -```html - - - - - - - - - - - - - - - - - - - - +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 properties[1](#token-footnote) 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: + +```css +/* 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"; ``` -Make sure you've included the relevant classes to choose which scale and colorstop you want: +Tokens values are mapped to context-specific classes which can be applied to the `` 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 ``` -To switch to Express, load vars from `@spectrum-css/expressvars` instead of `@spectrum-css/vars` and add the `.spectrum--express` class to the `` element: +To switch to Express, **add** the `.spectrum--express` class to the `` element: ```html - - - - - - - - - - - + ``` -Components can then be added by leveraging the code from [the documentation](http://opensource.adobe.com/spectrum-css/). +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](http://opensource.adobe.com/spectrum-css/). -Because CSS custom properties honor the cascading nature of CSS, you can infinitely nest different colorstops and themes, [as illustrated here](https://codepen.io/lazd/pen/axXMRL). +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 [ActionButton for a complete example](https://opensource.adobe.com/spectrum-css/actionbutton.html#modified). +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](https://opensource.adobe.com/spectrum-css/actionbutton.html#custompropertiesapi). ### Importing UI icons -Some components require certain "UI icons" to render. To get these icons, you'll need to use [`loadicons`](https://www.npmjs.com/package/loadicons). +Some components require certain "UI icons" to render. These icons are released within the [`@spectrum-css/ui-icons`](https://www.npmjs.com/package/@spectrum-css/ui-icons) package and are used by components like `@spectrum-css/icon` and `@spectrum-css/actionbutton`. -For most use cases, you'll want to use `spectrum-css-icons.svg` so you have support for both scales: +Based on which scales you'll be using, you can choose to load different files: -```js - - -``` +* `spectrum-css-icons.svg` - Both medium and large icons for responsive UIs that support both `.spectrum--medium` and `.spectrum--large` -Based on which scales you'll be using, you can choose to load different files: +* `spectrum-css-icons-medium.svg` - Medium icons only, supports `.spectrum--medium` only -- `@spectrum-css/ui-icons/dist/spectrum-css-icons.svg` - Both medium and large icons for responsive UIs that support both `.spectrum--medium` and `.spectrum--large` -- `@spectrum-css/icon/dist/spectrum-css-icons-medium.svg` - Medium icons only, supports `.spectrum--medium` only -- `@spectrum-css/icon/dist/spectrum-css-icons-large.svg` - Large icons only, supports `.spectrum--large` 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 `` element, or you'll see both medium and large icons at once. @@ -172,21 +152,13 @@ Based on which scales you'll be using, you can choose to load different files: 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`](https://www.npmjs.com/package/@adobe/spectrum-css-workflow-icons) package. After installing the package, you can import the entire set of icons in all sizes as follows: - -```js -loadIcons( - "node_modules/@adobe/spectrum-css-workflow-icons/dist/spectrum-icons.svg" -); -``` - -You can then use the icons in your app. Visit the [Spectrum workflow icon list](https://spectrum.adobe.com/page/icons/) and click on any icon to get the markup. +These icons are released within the [`@adobe/spectrum-css-workflow-icons`](https://www.npmjs.com/package/@adobe/spectrum-css-workflow-icons) package. Visit the [Spectrum workflow icon list](https://spectrum.adobe.com/page/icons/) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language) or set the [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang). -In addition, you must set the `dir` attribute for components to render correctly. +In addition, you should set the `dir` attribute for components to render correctly. For English, a left-to-right language: @@ -200,177 +172,91 @@ For Arabic, a right-to-left language: ``` -### Variable fallbacks - -Each component has a `dist/vars.css` file that contains declarations for each component-level variable used by the component. The CSS in `dist/index-vars.css` references these variables, but has fallbacks for the global variables or hardcoded value that that the component-level variables resolve to. - -As such, **you do not need to include `dist/vars.css`** unless: - -1. You wish to reference the component-level variables used by a component in external CSS (i.e. `--spectrum-divider-medium-height`) -2. You have upgraded `@spectrum-css/vars`, but have not updated a component (such as `@spectrum-css/divider`) and do not want to update the component-level variables used by that component +### Browser support -When this file is imported, if in updated version of `@spectrum-css/vars` changed global variables (such as a global color, `--spectrum-global-color-gray-300`), you will get those updates. However, if the updated version of `@spectrum-css/vars` changed component-level variables (such as the height of a medium divider, `--spectrum-divider-medium-height`), you will not get those updates. As such, this file can be used to lock-in the basic visual style of a component while still allowing for system-level updates. +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. -In most cases, this file will not be required, so you can safely ignore it. If you see unexpected visual changes creeping into components that you have not updated, `dist/vars.css` may correct them. +* 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 flexible as possible, and as such, leaves room for optimization. Let's assume you've included a few components as dependencies in your `package.json`: - -```json -{ - "name": "my-project", - "devDependencies": { - "@spectrum-css/button": "^3.0.0", - "@spectrum-css/page": "^3.0.0", - "@spectrum-css/vars": "^3.0.0" - } -} -``` +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. -You've created an `index.css` that imports a few components, a scale, and a color-theme: - -```css -@import "node_modules/@spectrum-css/vars/dist/spectrum-global.css"; -@import "node_modules/@spectrum-css/vars/dist/spectrum-medium.css"; -@import "node_modules/@spectrum-css/vars/dist/spectrum-light.css"; -@import "node_modules/@spectrum-css/page/dist/index-vars.css"; -@import "node_modules/@spectrum-css/button/dist/index-vars.css"; -``` +## Contributing -To build an more optimized bundle, you can employ a few simple PostCSS plugins. First, install them: +A very special thank you to all of our [contributors]() without whom this project would not be possible. -```shell -yarn add -D postcss-import postcss-varfallback postcss-dropunusedvars cssnano -``` +Want to join the team? Check out the [contributing guidelines](.github/CONTRIBUTING.md) for quick start information. - +### Getting started -Next, create a `postcss.config.js`: +To get started with Spectrum CSS, you'll start by cloning the repository: -```js -module.exports = { - plugins: [ - require("postcss-import"), - require("postcss-varfallback"), - require("postcss-dropunusedvars"), - require("cssnano"), - ], -}; +```shell +git clone https://github.com/adobe/spectrum-css.git ``` -Finally, include PostCSS in your build process, or run it from the command line: +or if you're using the GitHub CLI: ```shell -postcss -o dist/index.min.css index.css +gh repo clone adobe/spectrum-css ``` -`dist/index.min.css` file will contain a much slimmer version of Spectrum CSS customized to only include the variables used by the components that you imported. If you've referenced any of variables Spectrum CSS defines in your CSS, they will be perserved as well. - -If you need an even smaller bundle, you can employ a tool such as [PurifyCSS](https://github.com/purifycss/purifycss) to strip unused CSS classes from the output. - -### Customizing Spectrum CSS - - - -You can employ `postcss-transformselectors` to change the classnames Spectrum CSS uses. For instance, you may want to use bare `h1`/`h2`/`h3` instead of `.spectrum-Heading.spectrum-Heading--size*`. - -To do this, first install the plugin: +To ensure your Node environment is always aligned with the project, we strongly recommend using [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating). Once you have nvm installed, you can run: -```js -npm i postcss-transformselectors --save-dev +```shell +nvm use ``` -Then, add something like this to your `postcss.config.js`: - -```js -module.exports = { - plugins: [ - require("postcss-transformselectors")({ - replace: [ - { search: ".spectrum-Heading--sizeXXL", replace: "h1" }, - { search: ".spectrum-Heading--sizeXL", replace: "h2" }, - { search: ".spectrum-Heading--sizeL", replace: "h3" }, - ], - transform: (selector) => { - if (selector.startsWith(".spectrum-Heading")) { - // Operate on each selector in a selector list - return selector - .split(",") - .map((selectorPart) => { - // Create separate selectors for each reference to .spectrum-Heading - return ["h1", "h2", "h3"] - .map((h) => { - return selectorPart.replace(".spectrum-Heading", h); - }) - .join(","); - }) - .join(","); - } - - // Don't mess with things that don't have .spectrum-Heading in them - return selector; - }, - }), - ], -}; -``` +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. -## 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](.github/CONTRIBUTING.md) for quick start information. - -### Building - -Run the following commands: +Then, install the dependencies: ```shell yarn install ``` -**Important:** Requires at least Node 18.x. +**Important:** Requires >= Node 18.8.1 and Yarn 1.22.0. + +To spin up the local development environment, run: ```shell yarn start ``` -This will spin up the local development environment ([Storybook](https://storybook.js.org/docs/web-components/get-started/introduction)). Editing any of the `.css` or the `.stories.js` files in `components/*` will live reload in your browser. +This will spin up the project's [Storybook](https://storybook.js.org/docs/web-components/get-started/introduction). 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](https://nx.dev/) to speed up the build process. If you are seeing unexpected results, you can clear the cache by running `yarn nx reset`. ### Tasks -This project includes several small scripts to help with common tasks. - -- `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 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. -- `yarn refresh:directory`: This will remove any deprecated package folders that are no longer in use. The goal is to make migrating to a new project architecture easier for the most number of users. -- `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). - -### CLI - The following tasks are available: -- `yarn build:all` - Performs a build of all components, documentation site, and storybook -- `yarn build` - Performs a build of all components -- `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 clean` - Cleans all output files for the project and all components - -### Releasing the website - -To publish the latest version of the website, run the following command: - -```shell -yarn release:site +* `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](http://opensource.adobe.com/spectrum-css/) locally: + +```sh +yarn dev ``` - -This will build the website and all dependent assets and push the changes to the `gh-pages` branch. From there, an organizational hook will pick up the changes and publish them to [https://opensource.adobe.com/spectrum-css/](https://opensource.adobe.com/spectrum-css/); they should be available after a few minutes.