Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@kong/design-tokens
Advanced tools
@kong/design-tokens - npm Package Compare versions
Comparing version 1.2.1-pr.31.372de31.0 to 1.2.1-pr.31.db7c48e.0
| /** | ||
| * Do not edit directly | ||
| * Generated on Tue, 04 Jul 2023 21:52:35 GMT | ||
| * Generated on Wed, 05 Jul 2023 22:01:22 GMT | ||
| * | ||
@@ -5,0 +5,0 @@ * GitHub: https://github.com/Kong/design-tokens |
| /** | ||
| * Do not edit directly | ||
| * Generated on Tue, 04 Jul 2023 21:52:35 GMT | ||
| * Generated on Wed, 05 Jul 2023 22:01:22 GMT | ||
| * | ||
@@ -5,0 +5,0 @@ * GitHub: https://github.com/Kong/design-tokens |
| { | ||
| "name": "@kong/design-tokens", | ||
| "version": "1.2.1-pr.31.372de31.0", | ||
| "version": "1.2.1-pr.31.db7c48e.0", | ||
| "description": "Kong UI Design Tokens and style dictionary", | ||
@@ -5,0 +5,0 @@ "scripts": { |
197
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). | ||
| > **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. | ||
| [](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 publically 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. | ||
| - [Tokens](#tokens) | ||
| - [Token Requirements](#token-requirements) | ||
| - [Package Exports](#package-exports) | ||
| - [Token Formats](#token-formats) | ||
| - [SCSS Variables](#scss-variables) | ||
| - [Usage](#usage) | ||
| - [In components](#in-components) | ||
| - [In a host application](#in-a-host-application) | ||
| - [Customization](#customization) | ||
| - [Reusability](#reusability) | ||
| - [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) | ||
@@ -33,21 +30,19 @@ - [Committing Changes](#committing-changes) | ||
| 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. | ||
| ### 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 | ||
| - 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` | ||
| - 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> | ||
@@ -89,14 +84,65 @@ | ||
| ### Package Exports | ||
| ### Token Formats | ||
| This package exports Kong's design tokens in multiple formats: | ||
| The `@kong/design-tokens` package exports tokens in multiple formats: | ||
| - SCSS variables | ||
| - JavaScript tokens (ESM and CJS), along with corresponding TypeScript types | ||
| - SCSS variables | ||
| - CSS variables, exported raw as well as within a SCSS mixin for scoping the parent container | ||
| 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' | ||
| ``` | ||
| ### SCSS Variables | ||
| 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). | ||
| 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 | ||
| ### In components | ||
| ### 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. | ||
@@ -106,6 +152,8 @@ | ||
| If your component _does_ want to offer customization, you will want to reference CSS variables with a fallback value. | ||
| If your component _does_ want to offer customization, you will want to reference the corresponding token CSS variable with a fallback SCSS variable. | ||
| 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 Kong's Design System's CSS variables with the SCSS variable as the fallback. | ||
| #### 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 | ||
@@ -126,3 +174,3 @@ <style lang="scss"> | ||
| **Important**: notice we did **not** import the CSS variables. | ||
| **Important**: notice we do **not** import CSS variables. | ||
@@ -149,5 +197,5 @@ 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. | ||
| ### In a host application | ||
| ### Host applications | ||
| Most commonly, a host application should 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 fallbacks. Here's an example: | ||
| 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: | ||
@@ -159,2 +207,3 @@ ```html | ||
| // We directly reference the SCSS variables here which will be replaced with static values during the build | ||
| .my-app-custom-class { | ||
@@ -168,39 +217,8 @@ color: $kui-color-text-primary; | ||
| ### Customization | ||
| #### Server-Side Rendering (SSR) | ||
| ### Reusability | ||
| If your host application utilizes SSR, you may need to resolve aliases to the package exports. | ||
| ## Updating Tokens & Local Development | ||
| For example, in a [VitePress](https://vitepress.vuejs.org/) site, add the following to your `vite.config.ts` | ||
| To get started, install the package dependencies | ||
| ```sh | ||
| yarn install --frozen-lockfile | ||
| ``` | ||
| ### VS Code extensions | ||
| > Note: TODO | ||
| ```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)," | ||
| ], | ||
| } | ||
| ``` | ||
| ### Server-Side Rendering (SSR) | ||
| If your host app utilizes SSR, you may need to resolve aliases to the package exports. | ||
| For example, for a VitePress site, add the following to your `vite.config.ts` | ||
| ```ts | ||
@@ -210,4 +228,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/'), | ||
@@ -217,3 +236,10 @@ }, | ||
| }) | ||
| ``` | ||
| ## Updating Tokens & Local Development | ||
| To get started, install the package dependencies | ||
| ```sh | ||
| yarn install --frozen-lockfile | ||
| ``` | ||
@@ -257,3 +283,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: | ||
@@ -264,10 +290,25 @@ ```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: | ||
| ```jsonc | ||
| // settings.json | ||
| { | ||
| "scss.scannerExclude": [ | ||
| "**/.git", | ||
| "**/bower_components", | ||
| "**/node_modules/!(@kong/design-tokens)," | ||
| ] | ||
| } | ||
| ``` | ||
| ### 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) | ||
@@ -277,3 +318,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 | ||
@@ -280,0 +321,0 @@ ### Committing Changes |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis 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
- increased by2.67%
79851
- Number of lines in readme file
- increased by13.85%
337
No dependency changes