@codelaw/rules-css 0.0.0-stage → 0.1.0

package/rules/css/alpha-value-notation.md

@@ -0,0 +1,44 @@
+---
+id: css/alpha-value-notation
+title: "Alpha values are percentages"
+languages: [css]
+fix: suggest
+fix_reason: "old browsers accept only numbers for alpha in `rgba()`"
+stability: preview
+options:
+  exceptProperties: { type: "string[]", default: ["opacity", "fill-opacity", "flood-opacity", "stop-opacity", "stroke-opacity"], description: "properties whose alpha is a number" }
+ported_from: [stylelint/alpha-value-notation]
+since: 0.1.0
+---
+
+The alpha channel of a colour function is written as a percentage (`50%`, not `0.5`). The opacity properties (`opacity`, `fill-opacity`, `flood-opacity`, `stop-opacity`, `stroke-opacity`) take numbers instead.
+
+**Why:** One notation for alpha makes values easier to compare at a glance.
+
+```codelaw
+native: css/alpha-value-notation
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+a {
+  color: rgb(0 0 0 / 0.5);
+}
+```
+
+#### Do
+
+```css
+a {
+  color: rgb(0 0 0 / 50%);
+}
+```
+
+## Differences from the source
+
+Ported with stylelint-config-standard's setting, `percentage`; the `number` setting is not offered.

package/rules/css/annotation-no-unknown.md

@@ -0,0 +1,44 @@
+---
+id: css/annotation-no-unknown
+title: "No unknown `!` annotations"
+languages: [css]
+fix: manual
+fix_reason: "the intended annotation is the author's call"
+stability: preview
+options:
+  ignoreAnnotations: { type: "string[]", default: [], description: "annotations to accept; `/regex/` for a pattern" }
+ported_from: [stylelint/annotation-no-unknown]
+since: 0.1.0
+---
+
+A declaration ends in no `!` annotation other than `!important`.
+
+**Why:** A misspelt annotation such as `!imprtant` makes the browser drop the whole declaration.
+
+```codelaw
+native: css/annotation-no-unknown
+```
+
+## How to fix
+
+1. Correct the spelling to `!important`, or remove the annotation.
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+a {
+  color: green !imprtant;
+}
+```
+
+#### Do
+
+```css
+a {
+  color: green !important;
+}
+```

package/rules/css/at-rule-descriptor-no-unknown.md

@@ -0,0 +1,46 @@
+---
+id: css/at-rule-descriptor-no-unknown
+title: "No unknown descriptors inside at-rules"
+languages: [css]
+fix: manual
+fix_reason: "whether to remove or move the declaration is the author's call"
+stability: preview
+ported_from: [stylelint/at-rule-descriptor-no-unknown]
+since: 0.1.0
+---
+
+Inside `@font-face`, `@counter-style`, `@property`, `@font-palette-values`, `@page`, `@view-transition`, `@color-profile` and `@font-feature-values`, every declaration is a descriptor that at-rule defines.
+
+**Why:** An at-rule ignores descriptors it does not define, so a misplaced property silently does nothing.
+
+```codelaw
+native: css/at-rule-descriptor-no-unknown
+```
+
+## How to fix
+
+1. Check the descriptor name against the at-rule's specification.
+2. Fix its spelling, or move the declaration into a style rule where it applies.
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("inter.woff2");
+  color: red;
+}
+```
+
+#### Do
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("inter.woff2");
+}
+```

package/rules/css/at-rule-descriptor-value-no-unknown.md

@@ -0,0 +1,50 @@
+---
+id: css/at-rule-descriptor-value-no-unknown
+title: "No unknown keyword values for at-rule descriptors"
+languages: [css]
+fix: manual
+fix_reason: "the intended value is the author's call"
+stability: preview
+ported_from: [stylelint/at-rule-descriptor-value-no-unknown]
+since: 0.1.0
+---
+
+Descriptors that take a fixed set of keywords — `font-display`, `system`, `inherits`, `navigation` and the like — use one of them, and the `syntax` of `@property` is a string.
+
+**Why:** The browser drops a descriptor with a value it does not recognise, so the at-rule falls back to its default.
+
+```codelaw
+native: css/at-rule-descriptor-value-no-unknown
+```
+
+## How to fix
+
+1. Replace the value with one the descriptor accepts.
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("inter.woff2");
+  font-display: quick;
+}
+```
+
+#### Do
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("inter.woff2");
+  font-display: swap;
+}
+```
+
+## Differences from the source
+
+Checks keyword-valued descriptors and the `@property` `syntax` type only; stylelint validates every descriptor value against the full CSSTree grammar, whose data derives from MDN data (CC0), which codelaw does not ship.

package/rules/css/at-rule-no-deprecated.cases.md

@@ -0,0 +1,13 @@
+# Cases: css/at-rule-no-deprecated
+
+### case: @viewport has no fix
+
+```css
+@viewport {
+  width: device-width;
+}
+```
+
+```expect
+1:1 css/at-rule-no-deprecated
+```

package/rules/css/at-rule-no-deprecated.md

@@ -0,0 +1,47 @@
+---
+id: css/at-rule-no-deprecated
+title: "No deprecated at-rules"
+languages: [css]
+fix: auto
+stability: preview
+options:
+  ignoreAtRules: { type: "string[]", default: [], description: "at-rules to accept; `/regex/` for a pattern" }
+ported_from: [stylelint/at-rule-no-deprecated]
+since: 0.1.0
+---
+
+The sheet uses no at-rule that was removed from or deprecated by the CSS specifications: `@viewport`, `@document` and `@nest`.
+
+**Why:** Browsers dropped or never shipped these at-rules, so what they wrap does not apply.
+
+```codelaw
+native: css/at-rule-no-deprecated
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+.card {
+  @nest .theme-dark & {
+    color: white;
+  }
+}
+```
+
+#### Do
+
+```css
+.card {
+  .theme-dark & {
+    color: white;
+  }
+}
+```
+
+## Differences from the source
+
+Only `@nest` has a fix (drop the keyword); `@viewport` and `@document` are reported without one.

package/rules/css/at-rule-no-unknown.cases.md

@@ -0,0 +1,25 @@
+# Cases: css/at-rule-no-unknown
+
+### case: @charset is not an at-rule here
+
+```css
+@charset "utf-8";
+```
+
+```expect
+(none)
+```
+
+### case: vendor-prefixed known at-rules
+
+```css
+@-webkit-keyframes fade {
+  from {
+    opacity: 0;
+  }
+}
+```
+
+```expect
+(none)
+```

package/rules/css/at-rule-no-unknown.md

@@ -0,0 +1,49 @@
+---
+id: css/at-rule-no-unknown
+title: "No unknown at-rules"
+languages: [css]
+fix: manual
+fix_reason: "the intended at-rule is the author's call"
+stability: preview
+options:
+  ignoreAtRules: { type: "string[]", default: [], description: "at-rules to accept, such as a preprocessor's; `/regex/` for a pattern" }
+ported_from: [stylelint/at-rule-no-unknown]
+since: 0.1.0
+---
+
+Every at-rule is one the CSS specifications define (a vendor prefix is allowed).
+
+**Why:** A browser skips an at-rule it does not know, block and all, so a typo silently disables its contents.
+
+```codelaw
+native: css/at-rule-no-unknown
+```
+
+## How to fix
+
+1. Correct the at-rule name.
+2. If a build tool handles it (`@tailwind`, `@include`), add it to `ignoreAtRules`.
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+@keyframe fade {
+  from {
+    opacity: 0;
+  }
+}
+```
+
+#### Do
+
+```css
+@keyframes fade {
+  from {
+    opacity: 0;
+  }
+}
+```

package/rules/css/at-rule-no-vendor-prefix.md

@@ -0,0 +1,44 @@
+---
+id: css/at-rule-no-vendor-prefix
+title: "No vendor-prefixed at-rules"
+languages: [css]
+fix: suggest
+fix_reason: "browsers that need the prefix lose the rule"
+stability: preview
+options:
+  ignoreAtRules: { type: "string[]", default: [], description: "at-rules to accept; `/regex/` for a pattern" }
+ported_from: [stylelint/at-rule-no-vendor-prefix]
+since: 0.1.0
+---
+
+At-rules a build tool prefixes, such as `@-webkit-keyframes`, are written without the prefix.
+
+**Why:** Prefixing is a build step; hand-written prefixes go stale and duplicate code.
+
+```codelaw
+native: css/at-rule-no-vendor-prefix
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+@-webkit-keyframes fade {
+  from {
+    opacity: 0;
+  }
+}
+```
+
+#### Do
+
+```css
+@keyframes fade {
+  from {
+    opacity: 0;
+  }
+}
+```

package/rules/css/at-rule-prelude-no-invalid.md

@@ -0,0 +1,52 @@
+---
+id: css/at-rule-prelude-no-invalid
+title: "At-rule preludes follow their grammar"
+languages: [css]
+fix: manual
+fix_reason: "the intended prelude is the author's call"
+stability: preview
+options:
+  ignoreAtRules: { type: "string[]", default: ["media"], description: "at-rules not to check; `@media` is left to `css/media-query-no-invalid`" }
+ported_from: [stylelint/at-rule-prelude-no-invalid]
+since: 0.1.0
+---
+
+The prelude of an at-rule — what comes between its name and its block — has the shape the at-rule needs: a dashed name for `@property`, a valid name for `@keyframes` and `@counter-style`, layer names for `@layer`, a URL for `@import`, nothing for `@font-face`.
+
+**Why:** A browser drops an at-rule whose prelude is invalid, with everything inside it.
+
+```codelaw
+native: css/at-rule-prelude-no-invalid
+```
+
+## How to fix
+
+1. Rewrite the prelude in the form the at-rule's specification gives.
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+@property size {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+```
+
+#### Do
+
+```css
+@property --size {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+```
+
+## Differences from the source
+
+Checks `@property`, `@font-palette-values`, `@position-try`, `@counter-style`, `@keyframes`, `@layer`, `@import`, `@namespace`, `@charset` and the at-rules that take no prelude; `@supports`, `@container`, `@page` and `@scope` preludes are not checked, as stylelint checks them with the CSSTree grammar codelaw does not ship.

package/rules/css/block-no-redundant-nested-style-rules.md

@@ -0,0 +1,40 @@
+---
+id: css/block-no-redundant-nested-style-rules
+title: "No `& { \u2026 }` wrapper"
+languages: [css]
+fix: suggest
+fix_reason: "declarations moved out of the wrapper change place relative to the nested rules around it"
+stability: preview
+ported_from: [stylelint/block-no-redundant-nested-style-rules]
+since: 0.1.0
+---
+
+A nested style rule whose selector is only `&` is not used: its declarations go straight in the parent block.
+
+**Why:** `& { … }` selects the same elements as its parent, so the wrapper only adds nesting.
+
+```codelaw
+native: css/block-no-redundant-nested-style-rules
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+a {
+  & {
+    color: red;
+  }
+}
+```
+
+#### Do
+
+```css
+a {
+  color: red;
+}
+```

package/rules/css/color-function-alias-notation.md

@@ -0,0 +1,42 @@
+---
+id: css/color-function-alias-notation
+title: "`rgb()` and `hsl()`, not `rgba()` and `hsla()`"
+languages: [css]
+fix: suggest
+fix_reason: "browsers before 2018 ignore an alpha channel in `rgb()`"
+stability: preview
+ported_from: [stylelint/color-function-alias-notation]
+since: 0.1.0
+---
+
+Colours use `rgb()` and `hsl()`; their aliases `rgba()` and `hsla()` are not used.
+
+**Why:** The aliases are exactly equivalent today; one spelling is easier to search and read.
+
+```codelaw
+native: css/color-function-alias-notation
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+a {
+  color: rgba(0 0 0 / 50%);
+}
+```
+
+#### Do
+
+```css
+a {
+  color: rgb(0 0 0 / 50%);
+}
+```
+
+## Differences from the source
+
+Ported with stylelint-config-standard's setting, `without-alpha`.

package/rules/css/color-function-notation.md

@@ -0,0 +1,42 @@
+---
+id: css/color-function-notation
+title: "Space-separated colour functions"
+languages: [css]
+fix: suggest
+fix_reason: "browsers before 2018 understand only the comma syntax"
+stability: preview
+ported_from: [stylelint/color-function-notation]
+since: 0.1.0
+---
+
+`rgb()`, `rgba()`, `hsl()` and `hsla()` use the modern space-separated syntax, with ` / ` before the alpha, not commas.
+
+**Why:** The modern syntax is the one newer colour functions (`lab()`, `oklch()`) share.
+
+```codelaw
+native: css/color-function-notation
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+a {
+  color: rgb(0, 0, 0);
+}
+```
+
+#### Do
+
+```css
+a {
+  color: rgb(0 0 0);
+}
+```
+
+## Differences from the source
+
+Ported with stylelint-config-standard's setting, `modern`; values with `var()` inside are skipped.

package/rules/css/color-hex-length.cases.md

@@ -0,0 +1,13 @@
+# Cases: css/color-hex-length
+
+### case: fragments in URLs are not colours
+
+```css
+a {
+  mask: url(#ffffff);
+}
+```
+
+```expect
+(none)
+```

package/rules/css/color-hex-length.md

@@ -0,0 +1,41 @@
+---
+id: css/color-hex-length
+title: "Short hex colours"
+languages: [css]
+fix: auto
+stability: preview
+ported_from: [stylelint/color-hex-length]
+since: 0.1.0
+---
+
+Hex colours use the short form when there is one: `#fff`, not `#ffffff`.
+
+**Why:** The short form says the same in fewer characters.
+
+```codelaw
+native: css/color-hex-length
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+a {
+  color: #ffffff;
+}
+```
+
+#### Do
+
+```css
+a {
+  color: #fff;
+}
+```
+
+## Differences from the source
+
+Ported with stylelint-config-standard's setting, `short`.

package/rules/css/comment-no-empty.md

@@ -0,0 +1,38 @@
+---
+id: css/comment-no-empty
+title: "No empty comments"
+languages: [css]
+fix: auto
+stability: preview
+ported_from: [stylelint/comment-no-empty]
+since: 0.1.0
+---
+
+Every comment has some text.
+
+**Why:** An empty comment carries nothing and is usually left over from an edit.
+
+```codelaw
+native: css/comment-no-empty
+```
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+/**/
+a {
+  color: red;
+}
+```
+
+#### Do
+
+```css
+a {
+  color: red;
+}
+```

package/rules/css/container-name-pattern.md

@@ -0,0 +1,45 @@
+---
+id: css/container-name-pattern
+title: "Container names are kebab-case"
+languages: [css]
+fix: manual
+fix_reason: "renaming must update every use of the name"
+stability: preview
+options:
+  pattern: { type: "string", default: "^(--)?([a-z][a-z0-9]*)(-[a-z0-9]+)*$", description: "a regular expression names must match" }
+ported_from: [stylelint/container-name-pattern]
+since: 0.1.0
+---
+
+Names given in `container-name`, `container` and `@container` match a pattern, kebab-case by default.
+
+**Why:** A consistent naming scheme makes names predictable across a codebase.
+
+```codelaw
+native: css/container-name-pattern
+```
+
+## How to fix
+
+1. Rename the container to match the pattern.
+2. Update every `@container` query that uses it.
+
+## Examples
+
+### CSS
+
+#### Don't
+
+```css
+.card {
+  container-name: cardGrid;
+}
+```
+
+#### Do
+
+```css
+.card {
+  container-name: card-grid;
+}
+```