@kong/stylelint-plugin-design-tokens 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 Kong, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,126 @@
+# @kong/stylelint-plugin-design-tokens
+
+[Stylelint](https://github.com/stylelint/stylelint) plugin for linting design tokens.
+
+- [Usage](#usage)
+- [Rules](#rules)
+  - [`use-proper-token`](#use-proper-token)
+  - [`token-var-usage`](#token-var-usage)
+
+## Usage
+
+Install `@kong/stylelint-plugin-design-tokens` and `stylelint` packages as a `devDependency` in your project
+
+```sh
+pnpm add -D @kong/stylelint-plugin-design-tokens stylelint
+```
+
+In your stylelint config file, add the plugin and enable rules that you want to use:
+
+```javascript
+plugins: [
+  '@kong/stylelint-plugin-design-tokens'
+],
+rules: {
+  '@kong/design-tokens/use-proper-token': [true, {
+    disableFix: true,
+    severity: 'error' // You can also configure as `warning`
+  }]
+}
+```
+
+## Rules
+
+### `use-proper-token`
+
+Rule that parses CSS properties for inappropriate tokens being referenced.
+
+For example, the `kui-color-text-primary` token **should** be used as a value for `color`, but **should not** be used for `background-color`.
+
+#### :red_circle: Incorrect usage
+
+```scss
+.foo {
+  // This **will** trigger an error, text color token used for background-color property
+  background-color: $kui-color-text-primary;
+}
+```
+
+#### :green_circle: Correct usage
+
+```scss
+.foo {
+  // This **will NOT** trigger an error, appropriate token for the property
+  color: $kui-color-text-primary;
+}
+```
+
+### `token-var-usage`
+
+Rule that ensures SCSS design tokens are properly used as fallback values in CSS custom properties.
+
+SCSS tokens (e.g., `$kui-color-text-primary`) **must** be wrapped in the `var()` function with the corresponding CSS custom property as the first argument and the SCSS token as the fallback. The format must be exact: `var(--kui-token-name, $kui-token-name)` with exactly one space after the comma and no other spaces.
+
+For cases where SCSS interpolation is needed (e.g., when defining CSS custom properties), the interpolated format is also valid: `var(--kui-token-name, #{$kui-token-name})`.
+
+This approach provides progressive enhancement: browsers use the CSS custom property (which can be overridden), with the SCSS token as a compile-time fallback.
+
+#### :red_circle: Incorrect usage
+
+```scss
+.foo {
+  // Direct SCSS token usage without var()
+  color: $kui-color-text-primary;
+}
+
+.bar {
+  // Missing space after the comma
+  color: var(--kui-color-text-primary,$kui-color-text-primary);
+}
+
+.baz {
+  // Extra spaces
+  color: var(--kui-color-text-primary,  $kui-color-text-primary);
+}
+
+.qux {
+  // Standalone interpolation without var() - no auto-fix provided
+  // Developer must determine correct usage based on context
+  color: #{$kui-color-text-primary};
+}
+```
+
+#### :green_circle: Correct usage
+
+```scss
+.foo {
+  // Proper format with CSS custom property and SCSS fallback
+  color: var(--kui-color-text-primary, $kui-color-text-primary);
+}
+
+.bar {
+  // Interpolated format (useful when defining CSS custom properties)
+  --vc-white: var(--kui-color-text-inverse, #{$kui-color-text-inverse});
+}
+```
+
+#### Limitations
+
+The `token-var-usage` rule has some known limitations:
+
+1. **Multi-line `var()` declarations**: The rule currently does not handle `var()` function calls that span multiple lines. To ensure proper linting and auto-fixing, keep your `var()` declarations on a single line:
+
+   ```scss
+   // ❌ May produce unexpected behavior
+   font-size: var(
+     --kui-font-size-40,
+     $kui-font-size-40
+   );
+
+   // ✅ Works correctly
+   font-size: var(--kui-font-size-40, $kui-font-size-40);
+   ```
+
+2. **Standalone interpolation**: SCSS tokens wrapped only in interpolation syntax (e.g., `#{$kui-color-text-primary}`) without `var()` cannot be auto-fixed. The rule will flag these cases, but you must manually determine the correct usage based on your context—whether to use the standard `var()` format or the interpolated `var()` format.
+
+3. **Complex SCSS expressions**: The rule is designed to work with direct token references. Complex SCSS expressions involving tokens (e.g., calculations, functions) may not be properly detected or auto-fixed.

package/index.mjs

@@ -0,0 +1,4 @@
+import useProperToken from './rules/use-proper-token/index.mjs'
+import tokenVarUsage from './rules/token-var-usage/index.mjs'
+
+export default [useProperToken, tokenVarUsage]

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kong/stylelint-plugin-design-tokens",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Stylelint plugin for Kong UI design tokens",
+  "exports": {
+    ".": "./index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "rules",
+    "utilities",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "stylelint": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kong/design-tokens.git"
+  },
+  "homepage": "https://github.com/Kong/design-tokens/packages/stylelint-plugin-design-tokens/",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.19.5",
+    "pnpm": ">=10.28.2"
+  },
+  "scripts": {
+    "lint": "eslint ."
+  }
+}

package/rules/token-var-usage/index.mjs

@@ -0,0 +1,341 @@
+import stylelint from 'stylelint'
+import { KONG_TOKEN_PREFIX, RULE_NAME_PREFIX } from '../../utilities/index.mjs'
+
+const { ruleMessages, validateOptions, report } = stylelint.utils
+const ruleName = `${RULE_NAME_PREFIX}/token-var-usage`
+const messages = ruleMessages(ruleName, {
+  expected: 'SCSS tokens must be used as fallback values in CSS custom properties. Use format: var(--kui-design-token, $kui-design-token) or var(--kui-design-token, #{$kui-design-token}) for interpolation, with exactly one space after the comma and no other spaces.',
+})
+const meta = {
+  url: 'https://github.com/Kong/design-tokens/blob/main/stylelint-plugin/README.md',
+  fixable: true,
+}
+
+// Convert SCSS token ($kui-token) to CSS token (--kui-token)
+const getCssToken = (scssToken) => {
+  const tokenName = scssToken.substring(1) // Remove $
+  return `--${tokenName}`
+}
+
+// Find all occurrences of a token in a value
+const findAllTokenOccurrences = (value, token) => {
+  const occurrences = []
+  let searchIndex = 0
+  while (true) {
+    const index = value.indexOf(token, searchIndex)
+    if (index === -1) {
+      break
+    }
+    occurrences.push(index)
+    searchIndex = index + 1
+  }
+  return occurrences
+}
+
+// Check if token is inside standalone interpolation (#{$token}) without var() wrapper
+const isTokenInStandaloneInterpolation = (value, tokenIndex, token) => {
+  // Check if token is inside #{...}
+  const beforeToken = value.substring(0, tokenIndex)
+  const afterTokenStart = tokenIndex + token.length
+
+  // Look for #{ before the token
+  const interpolationStartIndex = beforeToken.lastIndexOf('#{')
+  if (interpolationStartIndex === -1) {
+    return false
+  }
+
+  // Check if there's anything between #{ and the token (should be nothing or whitespace)
+  const betweenInterpolationAndToken = value.substring(interpolationStartIndex + 2, tokenIndex)
+  if (betweenInterpolationAndToken.trim() !== '') {
+    return false
+  }
+
+  // Look for } after the token
+  const afterToken = value.substring(afterTokenStart)
+  const interpolationEndMatch = afterToken.match(/^\s*}/)
+  if (!interpolationEndMatch) {
+    return false
+  }
+
+  // Now check if this #{$token} is inside a var() function
+  // If it is, it's not "standalone" interpolation
+  const fullBeforeToken = value.substring(0, interpolationStartIndex)
+  const varStartIndex = fullBeforeToken.lastIndexOf('var(')
+
+  if (varStartIndex !== -1) {
+    // Check if the var() contains this interpolation
+    // Find the closing paren of the var()
+    let parenCount = 0
+    let searchIndex = varStartIndex
+
+    while (searchIndex < value.length) {
+      const char = value[searchIndex]
+      if (char === '(') {
+        parenCount++
+      } else if (char === ')') {
+        parenCount--
+        if (parenCount === 0) {
+          // Found the closing paren
+          // Check if our token is inside this var()
+          if (tokenIndex < searchIndex) {
+            // Token is inside the var(), so this is NOT standalone interpolation
+            return false
+          }
+          break
+        }
+      }
+      searchIndex++
+    }
+  }
+
+  return true
+}
+
+// Check if token at given position is properly wrapped in var()
+// Accepts both formats:
+// - var(--token, $token) with exactly one space after comma
+// - var(--token, #{$token}) with exactly one space after comma (interpolated)
+const isTokenProperlyWrapped = (value, tokenIndex, token, cssToken) => {
+  // Use regex to find all var(--token, $token) or var(--token, #{$token}) patterns
+  // Escape regex metacharacters in token so it is treated literally in the pattern
+  const escapedToken = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  // Pattern 1: var(--token, $token)
+  const pattern1 = new RegExp(`var\\(${cssToken}, ${escapedToken}\\)`, 'g')
+
+  // Pattern 2: var(--token, #{$token})
+  const pattern2 = new RegExp(`var\\(${cssToken}, #{${escapedToken}}\\)`, 'g')
+
+  // Check both patterns
+  const patterns = [pattern1, pattern2]
+
+  for (const pattern of patterns) {
+    // Reset lastIndex for each pattern
+    pattern.lastIndex = 0
+
+    let match
+    while ((match = pattern.exec(value)) !== null) {
+      const matchStart = match.index
+      const matchEnd = matchStart + match[0].length
+
+      // Check if our token at tokenIndex is inside this match
+      const tokenEndIndex = tokenIndex + token.length
+      if (tokenIndex >= matchStart && tokenEndIndex <= matchEnd) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+const ruleFunction = () => {
+  return (postcssRoot, postcssResult) => {
+    const validOptions = validateOptions(postcssResult, ruleName, {})
+
+    if (!validOptions) {
+      return
+    }
+
+    postcssRoot.walkDecls((decl) => {
+      const declValue = decl.value
+
+      // Extract all SCSS tokens (starting with $kui-)
+      const scssTokenRegex = new RegExp(`\\$${KONG_TOKEN_PREFIX}[a-z0-9-]+`, 'g')
+      const scssTokens = declValue.match(scssTokenRegex)
+
+      // If no SCSS tokens are used, skip validation
+      if (!scssTokens || scssTokens.length === 0) {
+        return
+      }
+
+      // Get unique SCSS tokens
+      const uniqueScssTokens = Array.from(new Set(scssTokens))
+
+      // Check if each SCSS token is properly wrapped in var()
+      // Pattern: var(--kui-token-name, $kui-token-name)
+      const improperlyUsedTokens = []
+
+      uniqueScssTokens.forEach((scssToken) => {
+        const cssToken = getCssToken(scssToken)
+        const tokenOccurrences = findAllTokenOccurrences(declValue, scssToken)
+
+        // Check each occurrence to see if it's properly wrapped
+        const hasImproperUsage = tokenOccurrences.some((tokenIndex) => {
+          return !isTokenProperlyWrapped(declValue, tokenIndex, scssToken, cssToken)
+        })
+
+        if (hasImproperUsage) {
+          improperlyUsedTokens.push(scssToken)
+        }
+      })
+
+      if (improperlyUsedTokens.length > 0) {
+        // Create fix function
+        const fix = () => {
+          let fixedValue = declValue
+          const replacements = []
+
+          // First, identify all positions that need to be replaced
+          improperlyUsedTokens.forEach((scssToken) => {
+            const cssToken = getCssToken(scssToken)
+            const tokenOccurrences = findAllTokenOccurrences(declValue, scssToken)
+            const properFormat = `var(${cssToken}, ${scssToken})`
+
+            tokenOccurrences.forEach((tokenIndex) => {
+              // Check if this occurrence is in proper format
+              if (!isTokenProperlyWrapped(declValue, tokenIndex, scssToken, cssToken)) {
+                // Skip auto-fix for tokens in standalone interpolation (e.g., #{$token})
+                // Let the developer decide the appropriate fix
+                if (isTokenInStandaloneInterpolation(declValue, tokenIndex, scssToken)) {
+                  return
+                }
+
+                // Find the var() expression containing this token
+                const beforeToken = declValue.substring(0, tokenIndex)
+                const varStartIndex = beforeToken.lastIndexOf('var(')
+                const lastClosingParenBeforeToken = beforeToken.lastIndexOf(')')
+
+                if (varStartIndex === -1 || lastClosingParenBeforeToken > varStartIndex) {
+                  // No enclosing var( found for this token (either no var( at all, or the nearest
+                  // var( was already closed before the token, e.g. `var(--x) $kui-space-40`)
+                  replacements.push({
+                    start: tokenIndex,
+                    end: tokenIndex + scssToken.length,
+                    replacement: properFormat,
+                  })
+                  return
+                }
+
+                // Find the matching closing parenthesis
+                let parenCount = 0
+                let searchIndex = varStartIndex
+                let varEndIndex = -1
+
+                while (searchIndex < declValue.length) {
+                  const char = declValue[searchIndex]
+                  if (char === '(') {
+                    parenCount++
+                  } else if (char === ')') {
+                    parenCount--
+                    if (parenCount === 0) {
+                      varEndIndex = searchIndex
+                      break
+                    }
+                  }
+                  searchIndex++
+                }
+
+                if (varEndIndex !== -1) {
+                  // Extract the var() content
+                  const varContent = declValue.substring(varStartIndex + 4, varEndIndex) // +4 to skip 'var('
+
+                  // Check if there's a comma (indicating primary property + fallback)
+                  const commaIndex = varContent.indexOf(',')
+
+                  if (commaIndex !== -1) {
+                    // Extract primary property and fallback
+                    const primaryProperty = varContent.substring(0, commaIndex).trim()
+                    const fallbackValue = varContent.substring(commaIndex + 1).trim()
+
+                    // Check if primary property is a CSS custom property (not a kui- token reference)
+                    // and if the token is in the fallback part
+                    const fallbackStartInOriginal = varStartIndex + 4 + commaIndex + 1
+
+                    if (tokenIndex >= fallbackStartInOriginal && primaryProperty.startsWith('--')) {
+                      // Token is in fallback position and there's a valid CSS property
+                      // Replace all $kui- tokens in the fallback with var(--kui-token)
+                      let newFallback = fallbackValue
+
+                      // Find all $kui- tokens in the fallback
+                      const fallbackTokenRegex = new RegExp(`\\$${KONG_TOKEN_PREFIX}[a-z0-9-]+`, 'g')
+                      const fallbackTokens = fallbackValue.match(fallbackTokenRegex)
+
+                      if (fallbackTokens) {
+                        // Replace each token with var() wrapper, from end to start to avoid offset issues
+                        const fallbackReplacements = []
+                        fallbackTokens.forEach((fbToken) => {
+                          const fbCssToken = getCssToken(fbToken)
+                          const fbTokenOccurrences = findAllTokenOccurrences(fallbackValue, fbToken)
+
+                          fbTokenOccurrences.forEach((fbTokenIndex) => {
+                            fallbackReplacements.push({
+                              start: fbTokenIndex,
+                              end: fbTokenIndex + fbToken.length,
+                              token: fbToken,
+                              cssToken: fbCssToken,
+                            })
+                          })
+                        })
+
+                        // Sort by position descending
+                        fallbackReplacements.sort((a, b) => b.start - a.start)
+
+                        // Apply replacements
+                        fallbackReplacements.forEach(({ start, end, token, cssToken }) => {
+                          newFallback = newFallback.substring(0, start) + `var(${cssToken}, ${token})` + newFallback.substring(end)
+                        })
+                      }
+
+                      // Construct the new var() with preserved primary property
+                      const newVarExpression = `var(${primaryProperty}, ${newFallback})`
+
+                      replacements.push({
+                        start: varStartIndex,
+                        end: varEndIndex + 1,
+                        replacement: newVarExpression,
+                      })
+                      return
+                    }
+                  }
+
+                  // Default case: replace the entire var() expression with proper format
+                  replacements.push({
+                    start: varStartIndex,
+                    end: varEndIndex + 1,
+                    replacement: properFormat,
+                  })
+                }
+              }
+            })
+          })
+
+          // Sort replacements by position (descending) to avoid offset issues
+          replacements.sort((a, b) => b.start - a.start)
+
+          // Remove duplicates (same start position)
+          const uniqueReplacements = []
+          const seenStarts = new Set()
+          replacements.forEach((replacement) => {
+            if (!seenStarts.has(replacement.start)) {
+              seenStarts.add(replacement.start)
+              uniqueReplacements.push(replacement)
+            }
+          })
+
+          // Apply replacements from end to start
+          uniqueReplacements.forEach(({ start, end, replacement }) => {
+            fixedValue = fixedValue.substring(0, start) + replacement + fixedValue.substring(end)
+          })
+
+          decl.value = fixedValue
+        }
+
+        report({
+          message: messages.expected,
+          node: decl,
+          result: postcssResult,
+          ruleName,
+          fix,
+        })
+      }
+    })
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+ruleFunction.meta = meta
+
+export default stylelint.createPlugin(ruleName, ruleFunction)
+

package/rules/use-proper-token/index.mjs

@@ -0,0 +1,73 @@
+import stylelint from 'stylelint'
+import { PROPERTY_TOKEN_MAP } from './token-map.mjs'
+import { KONG_TOKEN_PREFIX, extractTokensFromValue, RULE_NAME_PREFIX } from '../../utilities/index.mjs'
+
+const { ruleMessages, validateOptions, report } = stylelint.utils
+const ruleName = `${RULE_NAME_PREFIX}/use-proper-token`
+const messages = ruleMessages(ruleName, {
+  unexpected: (token, property) => `Unexpected usage of '${token}' token in '${property}' property.`,
+})
+const meta = {
+  url: 'https://github.com/Kong/design-tokens/blob/main/stylelint-plugin/README.md',
+  fixable: false,
+}
+
+const ruleFunction = () => {
+  return (postcssRoot, postcssResult) => {
+    const validOptions = validateOptions(postcssResult, ruleName, {})
+
+    if (!validOptions) {
+      return
+    }
+
+    postcssRoot.walkDecls((decl) => {
+      /**
+       * PostCSS AST declaration node
+       * Docs: https://postcss.org/api/#declaration
+       */
+
+      const declProp = decl.prop
+      const declValue = decl.value
+      // check if the value contains a token as CSS or SCSS variable
+      const hasToken = [`--${KONG_TOKEN_PREFIX}`, `$${KONG_TOKEN_PREFIX}`].some(pattern => declValue.includes(pattern))
+      if (!hasToken) {
+        // skip validating if the value does not contain a token
+        return
+      }
+
+      const tokenProperty = Object.keys(PROPERTY_TOKEN_MAP).find(key => key.split(',').some(prop => prop === declProp))
+
+      // check if the property is in the property map
+      const isEnforcedProp = !!tokenProperty
+      if (!isEnforcedProp) {
+        return
+      }
+
+      const valueTokens = extractTokensFromValue(declValue)
+      // get the appropriate tokens for the property and create regex for each
+      // regex pattern: /kui-(?:[a-z0-9-]+-)?token(?:-[a-z0-9-]+)?$/
+      // this allows to match both regular and component tokens
+      const appropriateTokens = PROPERTY_TOKEN_MAP[tokenProperty].map(token => new RegExp(KONG_TOKEN_PREFIX + '(?:[a-z0-9-]+-)?' + token + '(?:-[a-z0-9-]+)?$'))
+      // filter out tokens that are not appropriate for the property
+      const inappropriateTokens = valueTokens.filter(vToken => !appropriateTokens.some(aTokenRegex => aTokenRegex.test(vToken)))
+
+      if (inappropriateTokens.length) {
+        // report the error for each inappropriate token
+        inappropriateTokens.forEach((token) => {
+          report({
+            message: messages.unexpected(token, declProp),
+            node: decl,
+            result: postcssResult,
+            ruleName,
+          })
+        })
+      }
+    })
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+ruleFunction.meta = meta
+
+export default stylelint.createPlugin(ruleName, ruleFunction)

package/rules/use-proper-token/token-map.mjs

@@ -0,0 +1,81 @@
+/**
+ * Map of CSS properties and their corresponding allowed design tokens
+ * Example: for `background-color` CSS property allowed tokens are `color-background` and `method-color-background`
+ *
+ * As long as tokens follow this pattern, they don't need to be added to the arrays in the map:
+ * - starts with a prefix `kui-`
+ * - optionally followed by a component name in kebab-case
+ * - followed by a token name in kebab-case
+ * - optionally followed by a variant name in kebab-case
+ * Examples: `kui-analytics-chart-background-color-inverse`, `kui-color-background`, `kui-color-background-inverse`
+ *
+ * key: CSS Property name
+ * value: Array of valid Kong Design Tokens, without the `kui-` prefix
+ *
+ * ! To enforce no token should be used for a CSS property, set the value to an empty array.
+ */
+export const PROPERTY_TOKEN_MAP = {
+  background: ['color-background', 'status-color'],
+  'background-color': ['color-background', 'status-color'],
+  'background-size': [],
+  border: ['border-radius', 'border-width', 'color-border'],
+  'border-bottom': ['border-radius', 'border-width', 'color-border'],
+  'border-bottom-color': ['color-border'],
+  'border-bottom-left-radius': ['border-radius'],
+  'border-bottom-right-radius': ['border-radius'],
+  'border-bottom-width': ['border-width'],
+  'border-color': ['color-border'],
+  'border-left': ['border-radius', 'border-width', 'color-border'],
+  'border-left-color': ['color-border'],
+  'border-left-width': ['border-width'],
+  'border-radius': ['border-radius'],
+  'border-right': ['border-radius', 'border-width', 'color-border'],
+  'border-right-color': ['color-border'],
+  'border-right-width': ['border-width'],
+  'border-spacing': ['space'],
+  'border-top': ['border-radius', 'border-width', 'color-border'],
+  'border-top-color': ['color-border'],
+  'border-top-left-radius': ['border-radius'],
+  'border-top-right-radius': ['border-radius'],
+  'border-top-width': ['border-width'],
+  'border-width': ['border-width'],
+  bottom: [],
+  'box-shadow': ['border-width', 'color-border', 'shadow'],
+  color: ['color-text', 'icon-color', 'status-color'],
+  'column-gap': ['space'],
+  'column-width': [],
+  fill: ['color-text', 'status-color'],
+  font: ['font-family', 'font-size', 'font-weight'],
+  'font-family': ['font-family'],
+  'font-size': ['font-size'],
+  'font-weight': ['font-weight'],
+  gap: ['space'],
+  height: ['icon-size'],
+  inset: [],
+  left: [],
+  'letter-spacing': ['letter-spacing'],
+  'line-height': ['line-height'],
+  margin: ['space'],
+  'margin-bottom': ['space'],
+  'margin-left': ['space'],
+  'margin-right': ['space'],
+  'margin-top': ['space'],
+  'max-height': ['icon-size'],
+  'max-width': ['icon-size', 'breakpoint'],
+  'min-height': ['icon-size'],
+  'min-width': ['icon-size', 'breakpoint'],
+  outline: ['border-width', 'color-border'],
+  'outline-color': ['color-border'],
+  'outline-width': ['border-width'],
+  padding: ['space', 'padding'],
+  'padding-bottom': ['space', 'padding'],
+  'padding-left': ['space', 'padding'],
+  'padding-right': ['space', 'padding'],
+  'padding-top': ['space', 'padding'],
+  right: [],
+  'row-gap': ['space'],
+  stroke: ['color-text', 'status-color'],
+  'text-decoration-color': ['color-text'],
+  top: [],
+  width: ['icon-size', 'breakpoint'],
+}

package/utilities/constants.mjs

@@ -0,0 +1,5 @@
+// prefix for all tokens
+export const KONG_TOKEN_PREFIX = 'kui-'
+
+// prefix for all rule names
+export const RULE_NAME_PREFIX = '@kong/design-tokens'

package/utilities/extract-tokens-from-value.mjs

@@ -0,0 +1,15 @@
+import { KONG_TOKEN_PREFIX } from './constants.mjs'
+
+// returns an array of unique design tokens found in a CSS value
+export default function(cssValue) {
+  const regex = new RegExp(`${KONG_TOKEN_PREFIX}[a-z0-9-]+`, 'gi')
+  const matches = cssValue.match(regex)
+
+  if (!matches) {
+    return []
+  }
+
+  const uniqueTokens = [...new Set(matches)]
+
+  return uniqueTokens
+}

package/utilities/index.mjs

@@ -0,0 +1,8 @@
+import { KONG_TOKEN_PREFIX, RULE_NAME_PREFIX } from './constants.mjs'
+import extractTokensFromValue from './extract-tokens-from-value.mjs'
+
+export {
+  KONG_TOKEN_PREFIX,
+  extractTokensFromValue,
+  RULE_NAME_PREFIX,
+}