Add declaration-property-value-no-unknown (#6511)

Co-authored-by: Masafumi Koba <473530+ybiquitous@users.noreply.github.com>

docs/migration-guide/to-15.md

@@ -2,7 +2,14 @@
 
 This release contains significant or breaking changes.
 
-## Significant change
+## Significant changes
+
+Two significant changes may affect you:
+
+- deprecated stylistic rules
+- added the `declaration-property-value-no-unknown` rule
+
+### Deprecated stylistic rules
 
 We've deprecated [76 of the rules that enforce stylistic conventions](../user-guide/rules.md#deprecated), e.g. [`indentation`](../../lib/rules/indentation/README.md).
 
@@ -42,6 +49,53 @@ There are lots of other rules we don't turn on in the [standard config](https://
 
 If you want to continue using Stylelint to enforce stylistic consistency, you can [migrate the deprecated rules you need to a plugin](../developer-guide/plugins.md).
 
+### Added `declaration-property-value-no-unknown` rule
+
+We added the [`declaration-property-value-no-unknown`](../../lib/rules/declaration-property-value-no-unknown/README.md) rule. It will flag property-value pairs that are unknown in the CSS specifications, for example:
+
+```css
+a {
+  top: red;
+}
+```
+
+The `top` property accepts either a `<length>`, `<percentage>` or the `auto` keyword. The rule will flag `red` as it's a `<color>`.
+
+Many of you have requested this rule, and we plan to add more like it to help you [avoid errors](../user-guide/rules.md#avoid-errors) in your CSS.
+
+To turn it on in your configuration object:
+
+```diff json
+{
+  "extends": ["stylelint-config-standard"],
+  "rules" {
++   "declaration-property-value-no-unknown": true
+    ..
+   }
+}
+```
+
+The rule uses [CSSTree](https://github.com/csstree/csstree) and its [syntax dictionary](https://csstree.github.io/docs/syntax/) of 600+ properties, 350+ types and 100+ functions. You can help identify and plug any gaps in its dictionary by either updating [mdn-data](https://github.com/mdn/data/) or [CSSTree's patch file](https://github.com/csstree/csstree/blob/master/data/patch.json).
+
+If you use values that aren't in the CSS specifications, you can use the rule's secondary options to make the rule more permissive. You can either:
+
+- ignore properties or values outright
+- extend the properties and values syntaxes
+
+The latter ensures only specific exceptions are allowed.
+
+If you currently use the [`stylelint-csstree-validator`](https://www.npmjs.com/package/stylelint-csstree-validator) plugin, you can continue to use it alongside the new rule by limiting the plugin to check only at-rule names and preludes.
+
+```diff json
+{
+  "rules" {
+    "csstree/validator": [true, {
++      "ignoreProperties": ["/.+/"]
+    }]
+  }
+}
+```
+
 ## Breaking changes
 
 Three breaking changes may also affect you:

docs/user-guide/rules.md

@@ -79,6 +79,7 @@ Disallow unknown things with these `no-unknown` rules.
 
 - [`annotation-no-unknown`](../../lib/rules/annotation-no-unknown/README.md): Disallow unknown annotations (Ⓡ & Ⓢ).
 - [`at-rule-no-unknown`](../../lib/rules/at-rule-no-unknown/README.md): Disallow unknown at-rules (Ⓡ & Ⓢ).
+- [`declaration-property-value-no-unknown`](../../lib/rules/declaration-property-value-no-unknown/README.md): Disallow unknown values for properties within declarations.
 - [`function-no-unknown`](../../lib/rules/function-no-unknown/README.md): Disallow unknown functions (Ⓡ & Ⓢ).
 - [`media-feature-name-no-unknown`](../../lib/rules/media-feature-name-no-unknown/README.md): Disallow unknown media feature names (Ⓡ & Ⓢ).
 - [`no-unknown-animations`](../../lib/rules/no-unknown-animations/README.md): Disallow unknown animations.

lib/rules/declaration-property-value-no-unknown/README.md

@@ -0,0 +1,139 @@
+# declaration-property-value-no-unknown
+
+Disallow unknown values for properties within declarations.
+
+<!-- prettier-ignore -->
+```css
+a { top: unknown; }
+/** ↑    ↑
+ * property and value pairs like these */
+```
+
+This is an experimental rule with some false negatives that will be patched in minor releases.
+
+It sometimes overlaps with:
+
+- [`color-no-invalid-hex`](../color-no-invalid-hex/README.md)
+- [`function-no-unknown`](../function-no-unknown/README.md)
+- [`string-no-newline`](../string-no-newline/README.md)
+- [`unit-no-unknown`](../unit-no-unknown/README.md)
+
+If duplicate problems are flagged, you can turn off the corresponding rule.
+
+This rule considers values for properties defined within the CSS specifications to be known. You can use the `propertiesSyntax` and `typesSyntax` secondary options to extend the syntax.
+
+## Options
+
+### `true`
+
+The following patterns are considered problems:
+
+<!-- prettier-ignore -->
+```css
+a { top: red; }
+```
+
+<!-- prettier-ignore -->
+```css
+a { top: unknown; }
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+a { top: 0; }
+```
+
+<!-- prettier-ignore -->
+```css
+a { top: var(--foo); }
+```
+
+## Optional secondary options
+
+### `ignoreProperties: { "property": ["/regex/", /regex/, "non-regex"]|"/regex/"|/regex/|"non-regex" }`
+
+Ignore the specified property and value pairs. Keys in the object indicate property names. If a string in the object is surrounded with `"/"`, it's interpreted as a regular expression. For example, `"/.+/"` matches any strings.
+
+Given:
+
+```json
+{
+  "top": ["unknown"],
+  "/^margin-/": "/^--foo/",
+  "padding": "/.+/",
+  "/.+/": "--unknown-value"
+}
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+a { top: unknown; }
+```
+
+<!-- prettier-ignore -->
+```css
+a { margin-top: --foo-bar; }
+```
+
+<!-- prettier-ignore -->
+```css
+a { padding: invalid; }
+```
+
+<!-- prettier-ignore -->
+```css
+a { width: --unknown-value; }
+```
+
+### `propertiesSyntax: { property: syntax }`
+
+Extend or alter the properties syntax dictionary. [CSS Value Definition Syntax](https://github.com/csstree/csstree/blob/master/docs/definition-syntax.md) is used to define a value's syntax. If a definition starts with `|` it is added to the [existing definition value](https://csstree.github.io/docs/syntax/) if any.
+
+Given:
+
+```json
+{ "size": "<length-percentage>" }
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+a { size: 0; }
+```
+
+<!-- prettier-ignore -->
+```css
+a { size: 10px }
+```
+
+### `typesSyntax: { type: syntax }`
+
+Extend or alter the types syntax dictionary. [CSS Value Definition Syntax](https://github.com/csstree/csstree/blob/master/docs/definition-syntax.md) is used to define a value's syntax. If a definition starts with `|` it is added to the [existing definition value](https://csstree.github.io/docs/syntax/) if any.
+
+Types are something like a preset which allows you to reuse a definition across other definitions. So, you'll likely want to also use the `propertiesSyntax` option when using this option.
+
+Given:
+
+```json
+{
+  "propertiesSyntax": { "top": "| <--foo()>" },
+  "typesSyntax": { "--foo()": "--foo( <length-percentage> )" }
+}
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+a { top: --foo(0); }
+```
+
+<!-- prettier-ignore -->
+```css
+a { top: --foo(10px); }
+```