@spectrum-css/tokens - npm Package Compare versions

Comparing version 15.2.0 to 16.0.0

package.json

 {
 	"name": "@spectrum-css/tokens",
-	"version": "15.2.0",
+	"version": "16.0.0",
 	"description": "The Spectrum CSS tokens package",
 	"license": "Apache-2.0",
 	"author": "Adobe",
-	"homepage": "https://opensource.adobe.com/spectrum-css/",
+	"homepage": "https://opensource.adobe.com/spectrum-css",
 	"repository": {
@@ -16,29 +16,45 @@ "type": "git",
 	},
-	"main": "dist/index.css",
+	"exports": {
+		".": "./dist/css/index.css",
+		"./*.md": "./*.md",
+		"./dist/*": "./dist/*",
+		"./dist/index.css": "./dist/css/index.css",
+		"./package.json": "./package.json"
+	},
+	"main": "dist/css/index.css",
 	"files": [
 		"dist",
-		"CHANGELOG.md",
-		"README.md",
+		"*.md",
 		"package.json"
 	],
+	"scripts": {
+		"format": "run-p \"format:*\"",
+		"format:content": "prettier --write --cache --log-level error --ignore-unknown --no-error-on-unmatched-pattern *.md **/*.md",
+		"format:scripts": "eslint --fix --cache --no-error-on-unmatched-pattern *.{js,json} {tasks,utilities}/*.js",
+		"lint": "run-p \"lint:*\"",
+		"lint:scripts": "eslint --cache --no-error-on-unmatched-pattern --report-unused-disable-directives *.{js,json} {tasks,utilities}/*.js"
+	},
 	"devDependencies": {
-		"@adobe/spectrum-tokens": "12.25.0",
+		"@adobe/spectrum-tokens": "0.0.0-s2-foundations-20241121221506",
+		"@adobe/token-diff-generator": "^1.3.0",
 		"@nxkit/style-dictionary": "^6.0.0",
 		"@spectrum-tools/postcss-rgb-mapping": "workspace:^",
-		"cssnano": "^7.0.3",
-		"cssnano-preset-advanced": "^7.0.6",
+		"eslint": "^8.57.0",
+		"npm-run-all2": "^7.0.2",
 		"postcss": "^8.5.0",
 		"postcss-cli": "^11.0.0",
-		"postcss-import": "^16.1.0",
-		"postcss-licensing": "^2.0.0",
 		"postcss-sorting": "^9.1.0",
 		"prettier": "^3.4.2",
 		"style-dictionary": "^3.9.2",
-		"style-dictionary-sets": "^2.3.0"
+		"style-dictionary-sets": "^2.3.0",
+		"stylelint": "^16.9.0"
 	},
 	"keywords": [
+		"design-system",
 		"spectrum",
-		"css",
-		"design system",
-		"adobe"
+		"spectrum-css",
+		"adobe",
+		"adobe-spectrum",
+		"tokens",
+		"css"
 	],
@@ -45,0 +61,0 @@ "publishConfig": {

README.md

@@ -7,22 +7,62 @@ # @spectrum-css/tokens
 
-## Output
+## Glossary
 
-The output is concatenated into a single `dist/index.css` for use in Spectrum CSS. This entire file should be imported, and the relevant classes should be toggled to swap out core tokens.
+- **Core tokens**: The base set of design data that define the system. These are the key-value pairs that are used to build the design system and are sourced from the design team via @adobe/spectrum-tokens. You can find the relevant versioning information in the `package.json` file.
+- **Custom properties**: These are CSS variables generated from the core tokens using the StyleDictionary build process. These are used in the CSS base styles to apply the design system to the components in a way that can respond to changes in color, scale, or context.
+- **Context**: This terms refers to the design language an application wants to use. Contexts previously supported were Spectrum and Express. The current system supports only Spectrum but has committed to offering backward compatibility through at least December 2024.
+- **Color**: This term refers to the color mode. The current system supports light and dark only. The lightest and darkest color modes were deprecated in the final version for **14.x**.
+- **Scale**: This term refers to the scale of the design system. The current system supports medium and large scales. The large scale is used for mobile applications and the medium scale is used for desktop applications.
+- **System variables**: These are randomly generated variable names (prefixed with `--system`) that are used to map the component-level class styles to the core tokens from the desired context. These are generated by the `postcss-add-theming-layer` plugin as part of the build and should not be relied upon for naming consistency across releases. **Do not attempt to overwrite or extend these variables in your application.**
 
-On the `<html>` element, start with `.spectrum`, add in `.spectrum--light`, then `.spectrum--medium`. To switch to Express, add `.spectrum--express`.
+## Backwards compatibility for Spectrum 1 and Express
 
+Though the token data in this package focus on only the current context (Spectrum 2), our team is committed to offering backwards compatibility for Spectrum 1 and Express through at least December of 2024.
+
+To this end, every component that requires backward mapping support will include:
+
+- Spectrum 1: `dist/themes/spectrum.css`
+- Express: `dist/themes/express.css`
+- Spectrum 2: `dist/themes/spectrum-two.css`
+
+Consumers should load only the mappings for the components they are using in their application. This will ensure that the component-level mappings are aligned with the base CSS for each component. Spectrum 1 and Express component mappings should be loaded with the `global-vars.css` and appropriate color and scale assets from the last version of the tokens package: **v14.x**. Loading the Spectrum 1 or Express component-level mappings with the Spectrum 2 global variables will result in incorrect values being applied to the components and will break the desired design for the component.
+
+## Usage
+
+The output is concatenated into a single `dist/index.css` for use in a vanilla HTML application. This entire file should be imported, and the relevant classes should be toggled to swap out core tokens.
+
+On the `<body>` element, start with `.spectrum`, add in `.spectrum--light`, then `.spectrum--medium`. To switch to another context, add `.spectrum--legacy` or `.spectrum--express`.
+
+For additional guidance on which assets to load, see the architecture section below.
+
+## Architecture
+
+All compiled assets are shipped from the `dist` folder. Most of the assets are available in the `dist/css` folder. The component-level mappings for Spectrum 1, Express, and Spectrum 2 exist in the components output as theme assets. These should be loaded with the appropriate global variables and color and scale assets from the last version of the tokens package: **v14.x**.
+
+### Global core tokens
+
+- `global-vars.css`: Shared global, unchanging tokens.
+- `light-vars.css`: Tokens specific to the light color.
+- `dark-vars.css`: Tokens specific to the dark color.
+- `medium-vars.css`: Tokens specific to the medium (desktop) scale.
+- `large-vars.css`: Tokens specific to the large (mobile) scale.
+- `index.css`: The above files rolled up into 1 css file for convenience; best for use in a vanilla HTML application.
+
 ## Overrides and additions
 
-Overrides and additions to core tokens can be added to `custom.css`.
+Overrides and additions to core tokens can be added to `custom/*-vars.css`.
 
-Ensure that you correctly scope any added tokens:
+Ensure that you add new values to the appropriate color, or scale file:
 
-- `.spectrum` - Global, unchanging tokens or tokens specific to the Spectrum flavor
-- `.spectrum--express` - Tokens specific to the Express flavor
-- `.spectrum--lightest` - Tokens specific to the light color stop (soon to be deprecated)
-- `.spectrum--light` - Tokens specific to the light color stop
-- `.spectrum--dark` - Tokens specific to the dark color stop
-- `.spectrum--darkest` - Tokens specific to the darkest color stop
-- `.spectrum--medium` - Tokens specific to the medium (desktop) scale
-- `.spectrum--large` - Tokens specific to the large (mobile) scale
-- `.spectrum--express.spectrum--*` - Tokens specific to the Express flavor for any of the above color stops and scales
+- `global-vars.css` - Shared global, unchanging tokens
+- `light-vars.css` - Tokens specific to the light color
+- `dark-vars.css` - Tokens specific to the dark color
+- `medium-vars.css` - Tokens specific to the medium (desktop) scale
+- `large-vars.css` - Tokens specific to the large (mobile) scale
+
+Values added here will be copied over and concatenated with the custom properties being generated from the core tokens by StyleDictionary.
+
+## Breaking changes from v14 to v15
+
+There are no additional contextual folders (i.e., `dist/css/spectrum/`) because this package supports no other theming systems outside of the component token mappings. All global tokens are found in the `dist/css` folder.
+
+For more notes on how the token data has changed, see the [@adobe/spectrum-tokens](https://github.com/adobe/spectrum-tokens/releases) release documentation.

No alert changes

Improved metrics

Total package byte prevSize

864526

increased by11.88%

Lines of code

20033

increased by1.65%

Number of lines in readme file

68

increased by142.86%

Worsened metrics

Number of package files

10

decreased by-60%

No dependency changes