Add declaration-property-value-no-unknown

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,19 @@ 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 and turned it on in our [recommended](https://www.npmjs.com/package/stylelint-config-recommended) and [standard](https://www.npmjs.com/package/stylelint-config-standard) configs.
+
+The rule checks for unknown property-value pairs in declarations. 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 is a powerful approach that ensures only specific exceptions are allowed.
+
+We hope to add more rules like this to Stylelint that help you [avoid errors](../user-guide/rules.md#avoid-errors) in your code.
+
 ## 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 property 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,123 @@
+# declaration-property-value-no-unknown
+
+Disallow unknown values for property within declarations.
+
+<!-- prettier-ignore -->
+```css
+a { top: unknown; }
+/** ↑    ↑
+ * property and value pairs like these */
+```
+
+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: 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 properties. Keys in the object indicate property names. If a string in the object is surrounded with `"/"`, it is 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); }
+```