This document outlines the details of the CSS styling for Spectrum Web Components.

For each component in the project, there are upto 3 CSS files:

• spectrum-[component-name].css - This is the main CSS file for the component that is generated by the last build from the Spectrum CSS project before the cutoff.
• [component-name]-overrides.css - This is the CSS file for the component that contains the system overrides which take different values in different themes. It was also generated by the last build from the Spectrum CSS project before the cutoff.
• [component-name].css - This is the main CSS file which imports the spectrum-[component-name].css and [component-name]-overrides.css files and additionally contains the component's custom styles which are not part of the Spectrum CSS project.

We will try to keep the concerns separate for the component styling and so depending on the changes, we will need to update the component styling in the following ways:

• If it's a fix to the core visual structure or token usage, it belongs in spectrum-[component-name].css.
• If it's something unique to SWC or a workaround, then [component-name].css is acceptable — but should be reviewed for long-term cleanup.

The process to update these two css files is the same and is as follows:

Example:

:host {
    - --spectrum-accordion-item-height: var(--spectrum-component-height-200);
    + --spectrum-accordion-item-height: var(--spectrum-component-height-300);
}

This will just work! As long as the --spectrum-component-height-300 variable exists in the tokens package.

• If it's an update to how a component looks in one particular theme, it belongs in [component-name]-overrides.css.

The process to update the overrides file involves a few extra steps:

1. Update the [component-name]-overrides.css file to contain the new styles.
2. Make sure the new --system- variable exists in the tokens package. This variable can be found in the tools/styles/tokens/[express | spectrum]/system-theme-bridge.css file or the tools/styles/tokens-v2/system-theme-bridge.css file depending on the theme.
3. If the variable doesn't exist, we will need to add it to the correct file.

SWC project uses styles package to manage the global css tokens for all three themes. The styles package can be found in tools/styles. There is one very small caveat in the way we manage the styles package. We have two different tokens packages, one for the express + spectrum theme and one for the spectrum 2 theme.

• styles/tokens - This is the tokens package for the express + spectrum theme.
• styles/tokens-v2 - This is the tokens package for the spectrum 2 theme.

NOTE: In all likelihood, you would only need to do minor changes to the styles package. However, if you feel like you need to make major changes to the styles package, the correct approach would be to start a discussion among the team and figure out a plan together.

In our styles package, we have separation of separate variables for different contexts i.e, size and color.

If you're updating a size (e.g. --spectrum-accordion-item-height) variable, you'll need to update the tools/styles/tokens/[express | spectrum]/[large | medium]-vars.css file or the tools/styles/tokens-v2/[large | medium]-vars.css file depending on the theme.

If you're updating a color (e.g. --spectrum-accordion-background-color) variable, you'll need to update the tools/styles/tokens/[express | spectrum]/[dark | light]-vars.css file or the tools/styles/tokens-v2/[dark | light]-vars.css file depending on the theme.

NOTE: If the variable that you're updating is not present in those files, chances are that this variable had the same value for both contexts in that tokens package. In that case, if you want the variable to continue to have the same value then you can update the tools/styles/[tokens | tokens-v2]/index.css file. Or if you want to make the variable context-specific, then you can add those new values in both of the files like we talked about above.