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.0 to 1.2.1-pr.31.6464149.0
| /** | ||
| * Do not edit directly | ||
| * Generated on Thu, 29 Jun 2023 22:01:06 GMT | ||
| * Generated on Wed, 05 Jul 2023 18:44:53 GMT | ||
| * | ||
@@ -5,0 +5,0 @@ * GitHub: https://github.com/Kong/design-tokens |
| /** | ||
| * Do not edit directly | ||
| * Generated on Thu, 29 Jun 2023 22:01:06 GMT | ||
| * Generated on Wed, 05 Jul 2023 18:44:53 GMT | ||
| * | ||
@@ -5,0 +5,0 @@ * GitHub: https://github.com/Kong/design-tokens |
| { | ||
| "name": "@kong/design-tokens", | ||
| "version": "1.2.0", | ||
| "version": "1.2.1-pr.31.6464149.0", | ||
| "description": "Kong UI Design Tokens and style dictionary", | ||
@@ -5,0 +5,0 @@ "scripts": { |
155
README.md
@@ -5,17 +5,20 @@ # Kong UI Design Tokens | ||
| [](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. | ||
| > **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. | ||
| - [Usage](#usage) | ||
| [](http://commitizen.github.io/cz-cli/) | ||
| - [Tokens](#tokens) | ||
| - [Token Requirements](#token-requirements) | ||
| - [Package Exports](#package-exports) | ||
| - [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) | ||
@@ -25,6 +28,2 @@ - [Committing Changes](#committing-changes) | ||
| ## Usage | ||
| TODO. | ||
| ## Tokens | ||
@@ -50,2 +49,3 @@ | ||
| - 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: | ||
@@ -89,33 +89,93 @@ | ||
| ## Updating Tokens & Local Development | ||
| ### Package Exports | ||
| To get started, install the package dependencies | ||
| This package exports Kong's design tokens in multiple formats: | ||
| ```sh | ||
| yarn install --frozen-lockfile | ||
| - JavaScript tokens (ESM and CJS), along with corresponding TypeScript types | ||
| - SCSS variables | ||
| ## Usage | ||
| ### Installation | ||
| In your host project, install the package **only** as a `devDependency`: | ||
| ```shell | ||
| yarn add -D @kong/design-tokens | ||
| ``` | ||
| ### VS Code extensions | ||
| #### Why a `devDependency`? | ||
| > Note: TODO | ||
| 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. | ||
| ```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)," | ||
| ], | ||
| 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 CSS variables with a fallback value. | ||
| 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. | ||
| ```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 did **not** import the CSS variables. | ||
| 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 | ||
| 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: | ||
| ```html | ||
| <style lang="scss"> | ||
| // Import SCSS variables | ||
| @import "@kong/design-tokens/tokens/scss/variables"; | ||
| .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, for a VitePress site, add the following to your `vite.config.ts` | ||
@@ -127,4 +187,5 @@ | ||
| 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/'), | ||
@@ -134,3 +195,10 @@ }, | ||
| }) | ||
| ``` | ||
| ## Updating Tokens & Local Development | ||
| To get started, install the package dependencies | ||
| ```sh | ||
| yarn install --frozen-lockfile | ||
| ``` | ||
@@ -174,3 +242,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: | ||
@@ -181,10 +249,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) | ||
@@ -194,3 +277,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 | ||
@@ -197,0 +280,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
No v1
QualityPackage 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
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 by5.85%
78557
- Number of lines in readme file
- increased by38.43%
299
Worsened metrics
- Number of low quality alerts
- increased byInfinity%
1
No dependency changes