@kong/design-tokens 2.0.0-pr.91.e870166.0 → 2.0.0

package/README.md

@@ -1,8 +1,6 @@
-# Kong UI Design Tokens
+# @kong/design-tokens
 
-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.
+Kong Design Tokens for Konnect, via [Style Dictionary](https://github.com/amzn/style-dictionary).
 
 - [Tokens](#tokens)
   - [Token Formats](#token-formats)
@@ -12,22 +10,21 @@ Kong Design Tokens, via [Style Dictionary](https://github.com/amzn/style-diction
   - [JavaScript](#javascript)
 - [Usage](#usage)
   - [Installation](#installation)
-  - [Stylelint Plugin](#stylelint-plugin)
-  - [Recommended VS Code extension](#recommended-vs-code-extension)
   - [Standalone components](#standalone-components)
   - [Host applications](#host-applications)
-- [Updating Tokens \& Local Development](#updating-tokens--local-development)
+- [Updating Tokens & Local Development](#updating-tokens--local-development)
   - [Token Requirements](#token-requirements)
   - [Development Sandbox](#development-sandbox)
   - [Lint and fix](#lint-and-fix)
   - [Build for production](#build-for-production)
   - [Token Update Workflow](#token-update-workflow)
   - [Committing Changes](#committing-changes)
+  - [Approvals](#approvals)
   - [Package Publishing](#package-publishing)
 
 ## Tokens
 
-All design tokens **must** be placed inside of the `/tokens` directory in one of two sub-directories.
+All design tokens **must** be placed inside of the `packages/design-tokens/tokens/` directory in one of two sub-directories.
 
 [View the lists of available tokens here](TOKENS.md), or keep reading for more information.
 
@@ -40,7 +37,7 @@ The `@kong/design-tokens` package exports tokens in multiple formats:
 - [CSS Custom Properties](#css-custom-properties)
 - [JavaScript](#javascript) (ESM, CJS, and JSON), 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:
+Exports are available from the package root meaning you do not need to include the `dist/` directory in your imports:
 
 ```ts
 // Notice that for JavaScript/TypeScript, we can just import from the root
@@ -160,7 +157,7 @@ The package also exports a JSON file of all tokens from `@kong/design-tokens/tok
 In your host project, install the package **only** as a `devDependency`:
 
 ```shell
-yarn add -D @kong/design-tokens
+pnpm add -D @kong/design-tokens
 ```
 
 #### Why a `devDependency`?
@@ -171,25 +168,7 @@ This strategy alleviates the need for a consuming application to need to install
 
 ### Stylelint Plugin
 
-This package offers a [Stylelint](https://github.com/stylelint/stylelint) plugin for linting the usage of Kong Design Tokens.
-
-[View the Stylelint plugin docs for usage instructions](./stylelint-plugin/README.md)
-
-### Recommended VS Code extension
-
-To get auto-completion of the SCSS variables in your project within VS Code, 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"
-  ]
-}
-```
-
-If you are installing the package as a `devDependency` in your project, you can add a `/.vscode/settings.json` file into your project that will enforce these settings in your project for all developers.
+This package used to bundle a Stylelint plugin. It is now a standalone package. See [`@kong/stylelint-plugin-design-tokens`](../stylelint-plugin-design-tokens/README.md).
 
 ### Standalone components
 
@@ -283,7 +262,7 @@ export default defineConfig({
       // 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/'),
+      '@kong/design-tokens': path.resolve(__dirname, '../node_modules/@kong/design-tokens/dist/tokens/js/index.mjs'),
     },
   },
 })
@@ -291,15 +270,15 @@ export default defineConfig({
 
 ## Updating Tokens & Local Development
 
-To get started, install the package dependencies
+To get started, install the package dependencies from the repo root:
 
 ```sh
-yarn install --frozen-lockfile
+pnpm install
 ```
 
 ### Token Requirements
 
-- Tokens **must** be defined in the corresponding JSON files within the `/tokens` directory in one of two sub-directories:
+- Tokens **must** be defined in the corresponding JSON files within the `packages/design-tokens/tokens/` directory in one of two sub-directories:
 
     Directory | Description
     ---------|----------
@@ -352,15 +331,21 @@ yarn install --frozen-lockfile
 
 ### Development Sandbox
 
-This repository includes a Vue sandbox (see the `/sandbox` directory) to allow you to experiment with consuming tokens.
+This package includes a Vue sandbox (see the `sandbox/` directory) to allow you to experiment with consuming tokens.
 
-To start the sandbox:
+To start the sandbox, run from the **repo root**:
 
 ```sh
-yarn sandbox
+pnpm sandbox:design-tokens
 ```
 
-This command will simultaneously start the Vite dev server and initialize a watcher on the `/tokens` directory. If any files in the `/tokens` directory are modified, the sandbox will automatically run the build command to update the tokens and then restart the Vite dev server (simulating hot module reload).
+Or from within this package directory:
+
+```sh
+pnpm sandbox
+```
+
+This command will simultaneously start the Vite dev server and initialize a watcher on the `tokens/` directory. If any files in the `tokens/` directory are modified, the sandbox will automatically run the build command to update the tokens and then restart the Vite dev server (simulating hot module reload).
 
 Updating any files within the sandbox itself will also trigger hot module reload as expected.
 
@@ -370,21 +355,35 @@ Lint package files, and optionally auto-fix detected issues.
 
 ```sh
 # Lint only
-yarn lint
+pnpm lint
 
 # Lint and fix
-yarn lint:fix
+pnpm lint:fix
 ```
 
+### Shared build utilities
+
+Build-time utilities — Style Dictionary transforms, string helpers, and the file-header factory — live in this package's own `utilities/` directory and are exported from `utilities/index.mjs`.
+
+**Package-specific** build utilities (e.g. transforms or formatters that only apply to `@kong/design-tokens`) should be added to `utilities/` and exported from `utilities/index.mjs`.
+
 ### Build for production
 
-Utilize the `style-dictionary` CLI to build the token assets for production based on the configuration in `/config.js`.
+Utilize the `style-dictionary` CLI to build the token assets for production based on the configuration in `config.mjs`.
+
+From this package directory:
 
 ```sh
-yarn build
+pnpm build
 ```
 
-If additional sub-directories (other than `dist/tokens`) are added to the `dist/` directory in `/config.js`, you will also need to create a new corresponding entry in the `package.json > exports` section to allow for importing into the host project without `dist/` in the path.
+Or from the repo root:
+
+```sh
+pnpm --filter @kong/design-tokens build
+```
+
+If additional sub-directories (other than `dist/tokens`) are added to the `dist/` directory in `config.mjs`, you will also need to create a new corresponding entry in the `package.json > exports` section to allow for importing into the host project without `dist/` in the path.
 
 For example, if I want to add a new `my-feature` folder, I'd update the `exports` entry as shown here:
 
@@ -399,10 +398,10 @@ For example, if I want to add a new `my-feature` folder, I'd update the `exports
 ### Token Update Workflow
 
 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)
-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
-5. Commit your changes, adhering to [Conventional Commits](#committing-changes). To make this easier, you're encouraged to run `yarn commit` to help build your commit message
+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 `packages/design-tokens/tokens/` directory as needed, ensuring to adhere to the [Token Requirements](#token-requirements)
+4. Before committing your changes, locally run `pnpm lint` to ensure you do not have any linting errors. If you have errors, you can try running `pnpm lint:fix` to resolve
+5. Commit your changes, adhering to [Conventional Commits](#committing-changes). To make this easier, you're encouraged to run `pnpm commit` from the repo root to help build your commit message
 6. Push your branch up to the remote with `git push origin {branch-name}`
 7. Open a pull request and request a review
 
@@ -414,10 +413,10 @@ This repo uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.
 
 [Commitizen](https://github.com/commitizen/cz-cli) and [Commitlint](https://github.com/conventional-changelog/commitlint) are used to help build and enforce commit messages.
 
-It is **highly recommended** to use the following command in order to create your commits:
+It is **highly recommended** to use the following command from the repo root in order to create your commits:
 
 ```sh
-yarn commit
+pnpm commit
 ```
 
 This will trigger the Commitizen interactive prompt for building your commit message.
@@ -426,11 +425,19 @@ This will trigger the Commitizen interactive prompt for building your commit mes
 
 [Lefthook](https://github.com/evilmartians/lefthook) is used to manage Git Hooks within the repo.
 
-- A `commit-msg` hook is automatically setup that enforces commit message stands with `commitlint`, see [`lefthook.yml`](./lefthook.yaml)
+- A `commit-msg` hook is automatically setup that enforces commit message standards with `commitlint`
 - A `pre-push` hook is used that runs `eslint` before allowing you to push your changes to the repository
 
 Additionally, CI will use `commitlint` to validate the commits associated with a PR in the `Lint and Validate` job.
 
+### Approvals
+
+- All pull requests require review and approval from authorized team members.
+- Automated approvals through workflows are strictly prohibited.
+  - There is an exception for automated pull request approvals originating from generated dependency updates that satisfy status checks and other requirements.
+- Protected branches require at least one approval from code owners.
+- All status checks must pass before a pull request may be merged.
+
 ### Package Publishing
 
-This repository utilizes [Semantic Release](https://github.com/semantic-release/semantic-release) for automated package publishing and version updates.
+This package is published automatically via [lerna-lite](https://github.com/lerna-lite/lerna-lite) in independent mode. Releases are triggered by conventional commits on `main`, `alpha`, and `beta` branches.