@kong/design-tokens 1.8.0 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -0
- package/TOKENS.md +1 -1
- package/dist/stylelint-plugin/README.md +55 -0
- package/dist/stylelint-plugin/index.js +3 -0
- package/dist/stylelint-plugin/rules/use-proper-token/index.js +67 -0
- package/dist/stylelint-plugin/rules/use-proper-token/token-map.js +75 -0
- package/dist/stylelint-plugin/utilities/constants.js +10 -0
- package/dist/stylelint-plugin/utilities/extract-tokens-from-value.js +17 -0
- package/dist/stylelint-plugin/utilities/index.js +8 -0
- package/dist/tokens/README.md +1 -1
- package/dist/tokens/css/custom-properties-list.css +1 -1
- package/dist/tokens/css/custom-properties.css +1 -1
- package/dist/tokens/js/cjs/index.d.ts +1 -1
- package/dist/tokens/js/cjs/index.js +1 -1
- package/dist/tokens/js/index.d.ts +1 -1
- package/dist/tokens/js/index.mjs +1 -1
- package/dist/tokens/less/variables.less +1 -1
- package/dist/tokens/scss/_map.scss +1 -1
- package/dist/tokens/scss/_mixins.scss +1 -1
- package/dist/tokens/scss/_variables.scss +1 -1
- package/package.json +12 -9
package/README.md
CHANGED
|
@@ -12,6 +12,7 @@ Kong Design Tokens, via [Style Dictionary](https://github.com/amzn/style-diction
|
|
|
12
12
|
- [JavaScript](#javascript)
|
|
13
13
|
- [Usage](#usage)
|
|
14
14
|
- [Installation](#installation)
|
|
15
|
+
- [Stylelint Plugin](#stylelint-plugin)
|
|
15
16
|
- [Recommended VS Code extension](#recommended-vs-code-extension)
|
|
16
17
|
- [Standalone components](#standalone-components)
|
|
17
18
|
- [Host applications](#host-applications)
|
|
@@ -168,6 +169,12 @@ This package is intended to be consumed by a host component or application that
|
|
|
168
169
|
|
|
169
170
|
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.
|
|
170
171
|
|
|
172
|
+
### Stylelint Plugin
|
|
173
|
+
|
|
174
|
+
This package offers a [Stylelint](https://github.com/stylelint/stylelint) plugin for linting the usage of Kong Design Tokens.
|
|
175
|
+
|
|
176
|
+
[View the Stylelint plugin docs for usage instructions](./stylelint-plugin/README.md)
|
|
177
|
+
|
|
171
178
|
### Recommended VS Code extension
|
|
172
179
|
|
|
173
180
|
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`:
|
package/TOKENS.md
CHANGED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# @kong/design-tokens/stylelint-plugin
|
|
2
|
+
|
|
3
|
+
[Stylelint](https://github.com/stylelint/stylelint) plugin for linting design tokens.
|
|
4
|
+
|
|
5
|
+
- [Usage](#usage)
|
|
6
|
+
- [Rules](#rules)
|
|
7
|
+
- [`use-proper-token`](#use-proper-token)
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
Install `@kong/design-tokens` and `stylelint` packages as a `devDependency` in your project
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
yarn add -D @kong/design-tokens stylelint
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
In your stylelint config file, add the plugin and enable rules that you want to use:
|
|
18
|
+
|
|
19
|
+
```javascript
|
|
20
|
+
plugins: [
|
|
21
|
+
'@kong/design-tokens/stylelint-plugin'
|
|
22
|
+
],
|
|
23
|
+
rules: {
|
|
24
|
+
'@kong/design-tokens/use-proper-token': [true, {
|
|
25
|
+
disableFix: true,
|
|
26
|
+
severity: 'error' // You can also configure as `warning`
|
|
27
|
+
}]
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Rules
|
|
32
|
+
|
|
33
|
+
### `use-proper-token`
|
|
34
|
+
|
|
35
|
+
Rule that parses CSS properties for inappropriate tokens being referenced.
|
|
36
|
+
|
|
37
|
+
For example, the `kui-color-text-primary` token **should** be used as a value for `color`, but **should not** be used for `background-color`.
|
|
38
|
+
|
|
39
|
+
#### :red_circle: Incorrect
|
|
40
|
+
|
|
41
|
+
```scss
|
|
42
|
+
.foo {
|
|
43
|
+
// This **will** trigger an error, text color token used for background-color property
|
|
44
|
+
background-color: $kui-color-text-primary;
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
#### :green_circle: Correct
|
|
49
|
+
|
|
50
|
+
```scss
|
|
51
|
+
.foo {
|
|
52
|
+
// This **will NOT** trigger an error, appropriate token for the property
|
|
53
|
+
color: $kui-color-text-primary;
|
|
54
|
+
}
|
|
55
|
+
```
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
const stylelint = require('stylelint')
|
|
2
|
+
const { ruleMessages, validateOptions, report } = stylelint.utils
|
|
3
|
+
const PROPERTY_TOKEN_MAP = require('./token-map')
|
|
4
|
+
const { KONG_TOKEN_PREFIX, extractTokensFromValue, RULE_NAME_PREFIX } = require('../../utilities')
|
|
5
|
+
|
|
6
|
+
const ruleName = `${RULE_NAME_PREFIX}/use-proper-token`
|
|
7
|
+
const messages = ruleMessages(ruleName, {
|
|
8
|
+
unexpected: (token, property) => `Unexpected usage of '${token}' token in '${property}' property.`,
|
|
9
|
+
})
|
|
10
|
+
const meta = {
|
|
11
|
+
// TODO: add separate docs file for all rules
|
|
12
|
+
url: 'https://github.com/Kong/design-tokens/blob/main/stylelint-plugin/README.md',
|
|
13
|
+
fixable: false,
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const ruleFunction = () => {
|
|
17
|
+
return (postcssRoot, postcssResult) => {
|
|
18
|
+
const validOptions = validateOptions(postcssResult, ruleName, {})
|
|
19
|
+
|
|
20
|
+
if (!validOptions) {
|
|
21
|
+
return
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
postcssRoot.walkDecls((decl) => {
|
|
25
|
+
/**
|
|
26
|
+
* PostCSS AST declaration node
|
|
27
|
+
* Docs: https://postcss.org/api/#declaration
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
const declProp = decl.prop
|
|
31
|
+
const declValue = decl.value
|
|
32
|
+
const hasToken = [`--${KONG_TOKEN_PREFIX}`, `$${KONG_TOKEN_PREFIX}`].some(pattern => declValue.includes(pattern))
|
|
33
|
+
if (!hasToken) {
|
|
34
|
+
return
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const tokenProperty = Object.keys(PROPERTY_TOKEN_MAP).find(key => key.split(',').some(prop => prop === declProp))
|
|
38
|
+
|
|
39
|
+
// check if the property is in the property map
|
|
40
|
+
const isEnforcedProp = !!tokenProperty
|
|
41
|
+
if (!isEnforcedProp) {
|
|
42
|
+
return
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const valueTokens = extractTokensFromValue(declValue)
|
|
46
|
+
const appropriateTokens = PROPERTY_TOKEN_MAP[tokenProperty].map(token => KONG_TOKEN_PREFIX.concat(token))
|
|
47
|
+
const inappropriateTokens = valueTokens.filter(vToken => !appropriateTokens.some(aToken => vToken.includes(aToken)))
|
|
48
|
+
|
|
49
|
+
if (inappropriateTokens.length) {
|
|
50
|
+
inappropriateTokens.forEach((token) => {
|
|
51
|
+
report({
|
|
52
|
+
message: messages.unexpected(token, declProp),
|
|
53
|
+
node: decl,
|
|
54
|
+
result: postcssResult,
|
|
55
|
+
ruleName,
|
|
56
|
+
})
|
|
57
|
+
})
|
|
58
|
+
}
|
|
59
|
+
})
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
ruleFunction.ruleName = ruleName
|
|
64
|
+
ruleFunction.messages = messages
|
|
65
|
+
ruleFunction.meta = meta
|
|
66
|
+
|
|
67
|
+
module.exports = stylelint.createPlugin(ruleName, ruleFunction)
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Map of CSS properties and their corresponding allowed design tokens
|
|
3
|
+
* Example: `background,background-color` CSS properties allowed tokens are `color-background` and `method-color-background`
|
|
4
|
+
*
|
|
5
|
+
* key: CSS Property name
|
|
6
|
+
* value: Array of valid Kong Design Tokens, without the `kui-` prefix
|
|
7
|
+
*
|
|
8
|
+
* To enforce no token should be used for a CSS property, set the value to an empty array.
|
|
9
|
+
*/
|
|
10
|
+
const PROPERTY_TOKEN_MAP = {
|
|
11
|
+
background: ['color-background', 'method-color-background'],
|
|
12
|
+
'background-color': ['color-background', 'method-color-background'],
|
|
13
|
+
'background-size': [],
|
|
14
|
+
border: ['border-radius', 'border-width', 'color-border'],
|
|
15
|
+
'border-bottom': ['border-radius', 'border-width', 'color-border'],
|
|
16
|
+
'border-bottom-color': ['color-border'],
|
|
17
|
+
'border-bottom-left-radius': ['border-radius'],
|
|
18
|
+
'border-bottom-right-radius': ['border-radius'],
|
|
19
|
+
'border-bottom-width': ['border-width'],
|
|
20
|
+
'border-color': ['color-border'],
|
|
21
|
+
'border-left': ['border-radius', 'border-width', 'color-border'],
|
|
22
|
+
'border-left-color': ['color-border'],
|
|
23
|
+
'border-left-width': ['border-width'],
|
|
24
|
+
'border-radius': ['border-radius'],
|
|
25
|
+
'border-right': ['border-radius', 'border-width', 'color-border'],
|
|
26
|
+
'border-right-color': ['color-border'],
|
|
27
|
+
'border-right-width': ['border-width'],
|
|
28
|
+
'border-spacing': ['space'],
|
|
29
|
+
'border-top': ['border-radius', 'border-width', 'color-border'],
|
|
30
|
+
'border-top-color': ['color-border'],
|
|
31
|
+
'border-top-left-radius': ['border-radius'],
|
|
32
|
+
'border-top-right-radius': ['border-radius'],
|
|
33
|
+
'border-top-width': ['border-width'],
|
|
34
|
+
'border-width': ['border-width'],
|
|
35
|
+
bottom: [],
|
|
36
|
+
color: ['color-text', 'method-color-text'],
|
|
37
|
+
'column-gap': ['space'],
|
|
38
|
+
'column-width': [],
|
|
39
|
+
fill: ['color-text', 'method-color-text'],
|
|
40
|
+
font: ['font-family', 'font-size', 'font-weight'],
|
|
41
|
+
'font-family': ['font-family'],
|
|
42
|
+
'font-size': ['font-size'],
|
|
43
|
+
'font-weight': ['font-weight'],
|
|
44
|
+
gap: ['space'],
|
|
45
|
+
height: [],
|
|
46
|
+
inset: [],
|
|
47
|
+
left: [],
|
|
48
|
+
'letter-spacing': [],
|
|
49
|
+
'line-height': ['line-height'],
|
|
50
|
+
margin: ['space'],
|
|
51
|
+
'margin-bottom': ['space'],
|
|
52
|
+
'margin-left': ['space'],
|
|
53
|
+
'margin-right': ['space'],
|
|
54
|
+
'margin-top': ['space'],
|
|
55
|
+
'max-height': [],
|
|
56
|
+
'max-width': [],
|
|
57
|
+
'min-height': [],
|
|
58
|
+
'min-width': [],
|
|
59
|
+
outline: [],
|
|
60
|
+
'outline-color': [],
|
|
61
|
+
'outline-width': [],
|
|
62
|
+
padding: ['space'],
|
|
63
|
+
'padding-bottom': ['space'],
|
|
64
|
+
'padding-left': ['space'],
|
|
65
|
+
'padding-right': ['space'],
|
|
66
|
+
'padding-top': ['space'],
|
|
67
|
+
right: [],
|
|
68
|
+
'row-gap': ['space'],
|
|
69
|
+
stroke: ['color-text', 'method-color-text'],
|
|
70
|
+
'text-decoration-color': ['color-text', 'method-color-text'],
|
|
71
|
+
top: [],
|
|
72
|
+
width: [],
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
module.exports = PROPERTY_TOKEN_MAP
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
const { KONG_TOKEN_PREFIX } = require('./constants')
|
|
2
|
+
|
|
3
|
+
// returns an array of unique design tokens found in a css value
|
|
4
|
+
const extractTokensFromValue = (cssValue) => {
|
|
5
|
+
const regex = new RegExp(`${KONG_TOKEN_PREFIX}[a-z0-9-]+`, 'gi')
|
|
6
|
+
const matches = cssValue.match(regex)
|
|
7
|
+
|
|
8
|
+
if (!matches) {
|
|
9
|
+
return []
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
const uniqueTokens = [...new Set(matches)]
|
|
13
|
+
|
|
14
|
+
return uniqueTokens
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
module.exports = extractTokensFromValue
|
package/dist/tokens/README.md
CHANGED
package/dist/tokens/js/index.mjs
CHANGED
package/package.json
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kong/design-tokens",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.9.0",
|
|
4
4
|
"description": "Kong UI Design Tokens and style dictionary",
|
|
5
5
|
"scripts": {
|
|
6
|
-
"build": "yarn build:clean && style-dictionary build && yarn copy:tokens-doc",
|
|
6
|
+
"build": "yarn build:clean && style-dictionary build && yarn copy:tokens-doc && yarn copy:stylelint-plugin",
|
|
7
7
|
"build:clean": "rimraf ./dist",
|
|
8
8
|
"copy:tokens-doc": "shx cp -f './dist/tokens/README.md' './TOKENS.md'",
|
|
9
|
+
"copy:stylelint-plugin": "shx cp -R './stylelint-plugin' './dist/stylelint-plugin/'",
|
|
9
10
|
"lint": "eslint '**/*.{js,ts,vue,json}'",
|
|
10
11
|
"lint:fix": "eslint '**/*.{js,ts,vue,json}' --fix",
|
|
11
12
|
"sandbox": "run-p sandbox:open watch:tokens",
|
|
@@ -40,7 +41,8 @@
|
|
|
40
41
|
}
|
|
41
42
|
},
|
|
42
43
|
"./package.json": "./package.json",
|
|
43
|
-
"./tokens/*": "./dist/tokens/*"
|
|
44
|
+
"./tokens/*": "./dist/tokens/*",
|
|
45
|
+
"./stylelint-plugin": "./dist/stylelint-plugin/index.js"
|
|
44
46
|
},
|
|
45
47
|
"repository": {
|
|
46
48
|
"type": "git",
|
|
@@ -53,10 +55,10 @@
|
|
|
53
55
|
"url": "https://github.com/Kong/design-tokens/issues"
|
|
54
56
|
},
|
|
55
57
|
"devDependencies": {
|
|
56
|
-
"@commitlint/cli": "^17.6.
|
|
57
|
-
"@commitlint/config-conventional": "^17.6.
|
|
58
|
+
"@commitlint/cli": "^17.6.7",
|
|
59
|
+
"@commitlint/config-conventional": "^17.6.7",
|
|
58
60
|
"@digitalroute/cz-conventional-changelog-for-jira": "^8.0.1",
|
|
59
|
-
"@evilmartians/lefthook": "^1.4.
|
|
61
|
+
"@evilmartians/lefthook": "^1.4.6",
|
|
60
62
|
"@semantic-release/changelog": "^6.0.3",
|
|
61
63
|
"@semantic-release/git": "^10.0.1",
|
|
62
64
|
"@typescript-eslint/eslint-plugin": "^5.62.0",
|
|
@@ -71,15 +73,16 @@
|
|
|
71
73
|
"eslint-plugin-jsonc": "^2.9.0",
|
|
72
74
|
"eslint-plugin-n": "^16.0.1",
|
|
73
75
|
"eslint-plugin-promise": "^6.1.1",
|
|
76
|
+
"eslint-plugin-sort-keys-fix": "^1.1.2",
|
|
74
77
|
"eslint-plugin-vue": "^9.15.1",
|
|
75
78
|
"npm-run-all": "^4.1.5",
|
|
76
79
|
"rimraf": "^5.0.1",
|
|
77
|
-
"sass": "^1.
|
|
80
|
+
"sass": "^1.64.0",
|
|
78
81
|
"semantic-release": "^21.0.7",
|
|
79
82
|
"shx": "^0.3.4",
|
|
80
83
|
"style-dictionary": "^3.8.0",
|
|
81
84
|
"typescript": "^5.1.6",
|
|
82
|
-
"vite": "^4.4.
|
|
85
|
+
"vite": "^4.4.6",
|
|
83
86
|
"vite-plugin-restart": "^0.3.1",
|
|
84
87
|
"vitepress": "^1.0.0-beta.5",
|
|
85
88
|
"vue": "^3.3.4",
|
|
@@ -134,7 +137,7 @@
|
|
|
134
137
|
}
|
|
135
138
|
},
|
|
136
139
|
"volta": {
|
|
137
|
-
"node": "18.
|
|
140
|
+
"node": "18.17.0",
|
|
138
141
|
"yarn": "1.22.19"
|
|
139
142
|
}
|
|
140
143
|
}
|