chore: update styling guide

Author: TarunAdobe

PULL_REQUESTS.md

@@ -103,7 +103,6 @@ Incomplete templates may delay the review process.
 -   `breaking-change`: PR contains changes that break backward compatibility
 -   `help-wanted`: Extra attention is needed on this PR
 -   `on-hold`: PR needs more discussion.
--   `Spectrum CSS`: An issue or pull request specific to the CSS being used by components.
 -   `Component: [Name]`: PR effects this component
 
 Apply labels promptly to help maintainers prioritize and manage the review queue.

README.md

@@ -37,7 +37,7 @@ Creating a new component from the command line can be done by running the follow
 $ yarn new-package
 ```
 
-This will scaffold your component's required architecture by prompting you for 2 data points - the desired name for your package and the name of the Spectrum CSS asset from which you will be building.
+This will scaffold your component's required architecture by prompting you for the desired name for your package.
 
 ? **SWC package name (i.e. color-area)**
 
@@ -134,7 +134,7 @@ Visual regression testing is done against screens derived from the exports of th
 
 #### Keeping CI assets updated
 
-If you find the `visual-*` jobs failing on CircleCI for reasons that you expect (you've updated the Spectrum CSS dependencies, you've added new tests, etc.) then you will need to update the golden images cache key before your build will pass. You can review and share the diffs for a test pass via a URL shaped like `vrt--spectrum-wc.netlify.app/${branchName}`. Before updating the cache key, be sure that the updated caches are both complete (there are times when process errors prevent images from being correctly created or when certain test passes take longer than others) and appear as expected. If you agree with the updated cache content, update the golden images cache key as follows.
+If you find the `visual-*` jobs failing on CircleCI for reasons that you expect (you've updated components css, you've added new tests, etc.) then you will need to update the golden images cache key before your build will pass. You can review and share the diffs for a test pass via a URL shaped like `vrt--spectrum-wc.netlify.app/${branchName}`. Before updating the cache key, be sure that the updated caches are both complete (there are times when process errors prevent images from being correctly created or when certain test passes take longer than others) and appear as expected. If you agree with the updated cache content, update the golden images cache key as follows.
 
 Your failing branch will have created a new cache with a key of `v1-golden-images-{{ .Revision }}-<< parameters.regression_color >>-<< parameters.regression_scale >>-<< parameters.dir >>-{{ epoch }}`. Here `{{ .Revision }}` outlines the git commit hash of the current CI pass. In `.circleci/config.yml`, you will use that to update the cache that is requested at the beginning of the `run-regressions` job. As part of the review site, the git commit hash will be listed in the side navigation UI for easy access, use this number to update the `current_golden_images_hash` paramater that appears as follows:
 

STYLING.md

@@ -6,20 +6,58 @@ This document outlines the details of the CSS styling for Spectrum Web Component
 
 For each component in the project, there are upto 3 CSS files:
 
--   `spectrum-[component-name].css` - This is the 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 for the component. 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.
+-   `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.
 
 ### How to update the component styling
 
 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 system-specific, it goes to `[component-name]-overrides.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.
 
-## Global styling (WIP)
+The process to update these two css files is the same and is as follows:
 
-SWC project uses styles package to manage the global css tokens for all three themes. The styles package can be found in `tools/styles`.
+Example:
 
-Hopefully, we'd never need to edit the styles package directly as these files were built from the processing of tokens package in the spectrum-css project before the cutoff.
+```css
+: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.
+
+## Global styling
+
+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 likelhood, 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.
+
+### How to update the global styling
+
+In our styles package, we have separation of vars for different contexts i.e, size and color.
+
+#### Updating size-specific vars
+
+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.
+
+#### Updating color-specific vars
+
+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.