@kong/design-tokens - npm Package Compare versions

Comparing version 1.3.0 to 1.3.1-pr.31.297eba1.0

dist/tokens/js/index.d.ts

 /**
  * Do not edit directly
- * Generated on Wed, 05 Jul 2023 17:36:39 GMT
+ * Generated on Thu, 06 Jul 2023 15:45:55 GMT
  * 
+ * Kong Design Tokens
  * GitHub: https://github.com/Kong/design-tokens
@@ -6,0 +7,0 @@ * License: Apache-2.0

package.json

 {
   "name": "@kong/design-tokens",
-  "version": "1.3.0",
+  "version": "1.3.1-pr.31.297eba1.0",
   "description": "Kong UI Design Tokens and style dictionary",
   "scripts": {
-    "build": "yarn build:clean && style-dictionary build",
+    "build": "yarn build:clean && style-dictionary build && yarn copy:tokens-md",
     "build:clean": "rimraf ./dist",
+    "copy:tokens-md": "copy-file dist/tokens/README.md TOKENS.md",
     "lint": "eslint '**/*.{js,ts,vue,json}'",
@@ -23,4 +24,4 @@ "lint:fix": "eslint '**/*.{js,ts,vue,json}' --fix",
   ],
-  "main": "dist/tokens/js/cjs/index.cjs",
-  "module": "dist/tokens/js/index.js",
+  "main": "dist/tokens/js/cjs/index.js",
+  "module": "dist/tokens/js/index.mjs",
   "types": "dist/tokens/js/index.d.ts",
@@ -30,8 +31,8 @@ "exports": {
       "import": {
-        "default": "./dist/tokens/js/index.js",
+        "default": "./dist/tokens/js/index.mjs",
         "types": "./dist/tokens/js/index.d.ts"
       },
       "require": {
-        "default": "./dist/tokens/js/cjs/index.cjs",
-        "types": "./dist/tokens/js/cjs/index.d.cts"
+        "default": "./dist/tokens/js/cjs/index.js",
+        "types": "./dist/tokens/js/cjs/index.d.ts"
       }
@@ -64,2 +65,3 @@ },
     "commitizen": "^4.3.0",
+    "copy-file-util": "^1.1.0",
     "cz-conventional-changelog": "^3.3.0",
@@ -114,3 +116,4 @@ "eslint": "^8.34.0",
             "CHANGELOG.md",
-            "package.json"
+            "package.json",
+            "TOKENS.md"
           ]
@@ -117,0 +120,0 @@ }

README.md

 # Kong UI Design Tokens
 
-Kong's Design Tokens and **Style Dictionary**, created with [Style Dictionary](https://github.com/amzn/style-dictionary).
+Kong Design Tokens, via [Style Dictionary](https://github.com/amzn/style-dictionary).
 
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
-
 > **Note**: Repository and documentation is a work in progress. This package is currently for Kong internal-use only, but is published publicly in order to consume in our OSS projects.
 
-A **Style Dictionary** is a build system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, or anything you can think of.
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 
-- [Usage](#usage)
 - [Tokens](#tokens)
   - [Token Requirements](#token-requirements)
+  - [Token Formats](#token-formats)
+  - [SCSS Variables](#scss-variables)
+- [Usage](#usage)
+  - [Installation](#installation)
+  - [Standalone components](#standalone-components)
+  - [Host applications](#host-applications)
 - [Updating Tokens \& Local Development](#updating-tokens--local-development)
-  - [VS Code extensions](#vs-code-extensions)
-  - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
   - [Development Sandbox](#development-sandbox)
   - [Lint and fix](#lint-and-fix)
   - [Build for production](#build-for-production)
+  - [VS Code extension](#vs-code-extension)
   - [Token Update Workflow](#token-update-workflow)
@@ -24,6 +26,2 @@ - [Committing Changes](#committing-changes)
 
-## Usage
-
-TODO.
-
 ## Tokens
@@ -33,20 +31,21 @@
 
-Directory | Description
----------|----------
-`/tokens/alias` | The `alias` directory **must** only contain alias values that point directly to a raw CSS value. Any tokens defined within the `alias` directory **will not** be exposed in the package exports.
-`/tokens/source` | The `source` directory contains all tokens that **will be** available for consumption from the package exports.
+[View the lists of available tokens here](TOKENS.md), or keep reading for more information.
 
 ### Token Requirements
 
-- Tokens **must** be defined in the corresponding JSON files within the `/tokens` directory
-  - The `category` of each token should be its own directory.
-  - Each `type` of token should be a file in the `category` directory, named `{type}.json`
-  - If there is only a single `type` of token within a `category`, you **should** name the file `index.json`
-- Token keys **must** be lowercase and snake_case
-- Token keys **must** be defined in normal alphabetical order
-- Tokens defined in the `/tokens/source/` directory **WILL** be exported in the build files.
-- Tokens defined in the `/tokens/alias/` directory can be utilized/referenced within the `/tokens/source/` files; however, these tokens will **NOT** be exported in the build files.
-- Token aliases (e.g. color aliases) **must not** be exposed/exported from the production build
-- Tokens at the "root" of their structure **must** be defined with a key of `"_"` to allow for nested child tokens. Example:
+- Tokens **must** be defined in the corresponding JSON files within the `/tokens` directory in one of two sub-directories:
 
+    Directory | Description
+    ---------|----------
+    `/tokens/alias` | The `alias` directory **must** only contain alias values that point directly to a raw CSS value. Any tokens defined within the `alias` directory **will not** be exposed in the package exports. Tokens defined in the `/tokens/alias/` directory can be utilized/referenced within the `/tokens/source/` files; however, these tokens will **NOT** be exported in the build files.
+    `/tokens/source` | The `source` directory contains all tokens that **will be** available for consumption from the package exports.
+
+- Token keys **must** be lowercase, snake_case, and defined in normal alphabetical order (rules enforced by the eslint config)
+- The `category` of each token should be its own directory (e.g. `tokens/color/`)
+- Each `type` of token should be a file in the `category` directory, named `{type}.json` (e.g. `tokens/color/background.json`)
+- If there is only a single `type` of token within a `category`, you **should** name the file `index.json` (e.g. `tokens/line-height/index.json`)
+- Component tokens **must** be defined within the `/tokens/source/components/` directory. All tokens for a component should be defined in a single JSON file, `{component-name}.json`, with the name of the component as the top-level property in the file.
+- Token aliases (e.g. color aliases) **must not** be exposed/exported from the package exports
+- Tokens at the "root" of their structure **must** be defined with a key of `"_"` to allow for nested child tokens.
+
     <details>
@@ -88,35 +87,136 @@
 
-## Updating Tokens & Local Development
+### Token Formats
 
-To get started, install the package dependencies
+The `@kong/design-tokens` package exports tokens in multiple formats:
 
-```sh
-yarn install --frozen-lockfile
+- SCSS variables
+- JavaScript tokens (ESM and CJS), along with corresponding TypeScript types
+
+Exports are available from the package root, meaning you do not need to include the `dist/` directory in your imports:
+
+```ts
+import { KUI_COLOR_BACKGROUND_PRIMARY_STRONG } from '@kong/design-tokens/tokens/js'
 ```
 
-### VS Code extensions
+### SCSS Variables
 
-> Note: TODO
+SCSS variables can be utilized in your project's SCSS files or in-component style blocks (this assumes your app is already configured to compile Sass).
 
-```json
-{
-  "cssVariables.lookupFiles": [
-    "**/*.css",
-    "**/*.scss",
-    "node_modules/@kong/design-tokens/dist/tokens/css/variables.css",
-  ],
-  "scss.scannerExclude": [
-    "**/.git",
-    "**/bower_components",
-    "**/node_modules/!(@kong/design-tokens),"
-  ],
+To use the SCSS variables, you need to import them into your component or app stylesheet so they are available throughout your project utilizing one of the methods below:
+
+#### Import into your app or component's stylesheet or style block
+
+```scss
+@import '@kong/design-tokens/tokens/scss/variables';
+```
+
+#### Globally import with Vite
+
+If your component or application utilizes [Vite](https://vitejs.dev/) to build and compile, you may add the following configuration to your `vite.config.ts` to import the SCSS variables into all components within your project
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        // Inject the @kong/design-tokens SCSS variables to make them available for all components.
+        additionalData: '@import "@kong/design-tokens/tokens/scss/variables";',
+      },
+    },
+  },
+})
+```
+
+## Usage
+
+### Installation
+
+In your host project, install the package **only** as a `devDependency`:
+
+```shell
+yarn add -D @kong/design-tokens
+```
+
+#### Why a `devDependency`?
+
+This package is intended to be consumed by a host component or application that will be compiled before publishing. This means when the component or app is compiled, any tokens it consumes (e.g. SCSS tokens, JavaScript variables, etc.) will be replaced during the build with the static token value.
+
+This strategy alleviates the need for a consuming application to need to install the `@kong/design-tokens` package when using a component that utilizes the tokens under-the-hood.
+
+### Standalone components
+
+The primary consideration when using Kong's design tokens in **components** is to determine if the component needs to allow for downstream customization.
+
+**If your component does not need to offer any customization, only utilize the SCSS and JavaScript design tokens in your component.**
+
+If your component _does_ want to offer customization, you will want to reference the corresponding token CSS variable with a fallback SCSS variable.
+
+#### Component Example
+
+As an example, in Kong's [Kongponents](https://kongponents.konghq.com) Vue component library, we want to offer deep levels of customization to allow for an _external_ host application to override component styles. Enabling customization is easy by using the Kong Design Token's CSS variables with SCSS variable values as the fallback.
+
+```html
+<style lang="scss">
+// Import SCSS variables
+@import "@kong/design-tokens/tokens/scss/variables";
+
+.my-component-class {
+  color: var(--kui-color-text-primary, $kui-color-text-primary);
+  font-weight: var(--kui-font-weight-semibold, $kui-font-weight-semibold);
+  padding: var(--kui-space-20, $kui-space-20) var(--kui-space-40, $kui-space-40);
 }
+</style>
 ```
 
-### Server-Side Rendering (SSR)
+Inspecting the example above, you will notice that we fist import the SCSS variables. We then set each style property to the CSS variable, using the SCSS static variable as the fallback.
 
-If your host app utilizes SSR, you may need to resolve aliases to the package exports.
+**Important**: notice we do **not** import CSS variables.
 
-For example, for a VitePress site, add the following to your `vite.config.ts`
+When Kongponents are imported and used in a host application, the components will utilize the SCSS fallback values by default since the CSS variables are undefined. This is the normal usage and works great for most applications.
 
+If your application wants to customize some of the properties, it's easy by simply defining the CSS variables you want to override inside of your host application, as shown here:
+
+```html
+<style>
+// You may scope the variable to `root:` to impact the whole application...
+:root {
+  --kui-color-text-primary: green;
+}
+
+// ...or scope the variable to a specific container to keep the changes isolated
+table .my-table-row {
+  --kui-color-text-primary: purple;
+}
+</style>
+```
+
+Now that we have set a value for the CSS variable `--kui-color-text-primary` in our host application, any instance of this CSS variable in the components will utilize our custom value instead of the default value.
+
+### Host applications
+
+Typically, a host application should only utilize the SCSS and/or JavaScript variables to define its styles. Host applications typically **do not need to be customized** after compile time, meaning there is no reason to use the CSS variables with SCSS variable fallbacks. Here's an example:
+
+```html
+<style lang="scss">
+// Import SCSS variables
+@import "@kong/design-tokens/tokens/scss/variables";
+
+// We directly reference the SCSS variables here which will be replaced with static values during the build
+.my-app-custom-class {
+  color: $kui-color-text-primary;
+  font-weight: $kui-font-weight-semibold;
+  padding: $kui-space-20 $kui-space-40;
+}
+</style>
+```
+
+#### Server-Side Rendering (SSR)
+
+If your host application utilizes SSR, you may need to resolve aliases to the package exports.
+
+For example, in a [VitePress](https://vitepress.vuejs.org/) site, add the following to your `vite.config.ts`
+
 ```ts
@@ -126,4 +226,5 @@ export default defineConfig({
     alias: {
-      // We must alias `@kong/design-tokens` imports to specifically utilize the esm build
+      // Explicitly alias the SCSS file since we are overriding the default import below
       '@kong/design-tokens/tokens/scss/variables': path.resolve(__dirname, '../node_modules/@kong/design-tokens/dist/tokens/scss/variables.scss'),
+      // Alias `@kong/design-tokens` imports to specifically utilize the esm build
       '@kong/design-tokens': path.resolve(__dirname, '../node_modules/@kong/design-tokens/dist/tokens/js/'),
@@ -133,3 +234,10 @@ },
 })
+```
 
+## Updating Tokens & Local Development
+
+To get started, install the package dependencies
+
+```sh
+yarn install --frozen-lockfile
 ```
@@ -173,3 +281,3 @@
 
-For example, if I want to add a new `icons` folder, I'd update the `exports` entry as shown here:
+For example, if I want to add a new `my-feature` folder, I'd update the `exports` entry as shown here:
 
@@ -180,10 +288,24 @@ ```jsonc
   "./tokens/*": "./dist/tokens/*",
-  "./icons/*": "./dist/icons/*" // New directory
+  "./my-feature/*": "./dist/my-feature/*" // New directory
 }
 ```
 
+### VS Code extension
+
+To get auto-completion of the SCSS variables in your project, you can add the [SCSS IntelliSense extension](https://marketplace.visualstudio.com/items?itemName=mrmlnc.vscode-scss) to VS Code on your machine along with the corresponding settings object which will auto-import the variables for auto-completion. Notice that we are explicitly not excluding `node_modules`:
+
+```jsonc
+// settings.json
+{
+  "scss.scannerExclude": [
+    "**/.git",
+    "**/bower_components"
+  ]
+}
+```
+
 ### Token Update Workflow
 
-1. Pull down the latest code by running `git pull origin main`
-2. Checkout a new branch for your changes with `git checkout -b {type}/{jira-ticket}-{description}` - as an example, `feat/khcp-1234-add-color-tokens`
+1. Ensure you are on the `main` branch, then pull down the latest code by running `git checkout main && git pull origin main`
+2. Checkout a new branch for your changes with `git checkout -b {type}/{jira-ticket}-{description}` - as an example, `git checkout feat/khcp-1234-add-color-tokens`
 3. Add/edit the tokens in the `/tokens` directory as needed, ensuring to adhere to the [Token Requirements](#token-requirements)
@@ -193,3 +315,3 @@ 4. Before committing your changes, locally run `yarn lint` to ensure you do not have any linting errors. If you have errors, you can try running `yarn lint:fix` to resolve
 6. Push your branch up to the remote with `git push origin {branch-name}`
-7. Open a pull request and request review
+7. Open a pull request and request a review
 
@@ -196,0 +318,0 @@ ### Committing Changes

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

113016

increased by69.47%

Number of package files

11

increased by22.22%

Lines of code

946

increased by70.14%

Number of lines in readme file

338

increased by56.48%

Worsened metrics

Dev dependency count

30

increased by3.45%

Number of low quality alerts

1

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes