@ncksnydr/config-js 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
 # @ncksnydr/config-js
 
-Shared configuration for TypeScript, ESLint, Prettier and Vitest. Each configuration is a separate entry point, so a Consumer uses only the parts it needs.
+Shared configuration for TypeScript, ESLint, Prettier, Stylelint and Vitest. Each configuration is a separate entry point, so a Consumer uses only the parts it needs.
 
 ## Install
 
 ```sh
-pnpm add --save-dev @ncksnydr/config-js typescript eslint prettier vitest
+pnpm add --save-dev @ncksnydr/config-js typescript eslint prettier stylelint vitest
 ```
 
 ## TypeScript
@@ -96,6 +96,41 @@ Checking formatting...
 
 To fix the layout, run `prettier --write .`.
 
+## Stylelint
+
+Use the configuration as your `stylelint.config.js`:
+
+```js
+export { default } from "@ncksnydr/config-js/stylelint";
+```
+
+The configuration needs Stylelint 18 or later. Then lint your CSS:
+
+```sh
+stylelint "**/*.css"
+```
+
+The configuration holds these rules:
+
+- Colors use `oklch()`. Hex colors, named colors and `rgb()`, `rgba()`, `hsl()` and `hsla()` fail.
+- Primitive tokens, such as `var(--palette-blue-500)` or `var(--scale-3)`, are allowed only in files inside a `tokens/` folder. Other files use semantic tokens.
+- Each `var()` has a fallback, such as `var(--space-md, 1.5rem)`. A custom property that the same file declares needs no fallback.
+- `!important` and `brightness()` fail.
+- Each rule sits inside one of the layers `reset`, `tokens`, `base`, `components` or `utilities`. A top-level `@media` block is the one exception.
+- Top-level `@media` blocks come last in the file.
+- Rules nest at most 3 levels deep.
+- Class names follow BEM in kebab case: `block`, `block__element`, `block--modifier`.
+- Units are limited to `rem`, `px`, `%`, `fr`, `vh`, `dvh`, `svh`, `vw`, `deg`, `ms` and `s`.
+- Each `px` or `rem` length is `1px` or a multiple of `3px`. The check counts `1rem` as `16px`.
+- Custom properties come first, then declarations, then nested rules, then nested at-rules. Declarations are in alphabetical order.
+
+A CSS file that breaks a rule fails the check:
+
+```text
+card.css
+  3:12  ✖  Disallowed hex color "#fff"  color-no-hex
+```
+
 ## Vitest
 
 Use the preset as your `vitest.config.ts`:

package/dist/stylelint/layered.d.ts

@@ -0,0 +1,2 @@
+import stylelint from "stylelint";
+export declare const layered: stylelint.Plugin;

package/dist/stylelint/layered.js

@@ -0,0 +1,47 @@
+import stylelint from "stylelint";
+const { createPlugin, utils: { report, ruleMessages, validateOptions }, } = stylelint;
+const ruleName = "nks/layered";
+const HOUSE_LAYERS = new Set(["reset", "tokens", "base", "components", "utilities"]);
+const houseLayerList = new Intl.ListFormat("en-GB", { type: "disjunction" }).format(HOUSE_LAYERS);
+const messages = ruleMessages(ruleName, {
+    outside: `Put this rule inside @layer ${houseLayerList}.`,
+    undeclared: (name) => `'${name}' is not a house layer. Use ${houseLayerList}.`,
+});
+function isAtRule(node) {
+    return node.type === "atrule";
+}
+function isLayeredOrExempt(styleRule) {
+    for (let parent = styleRule.parent; parent && parent.type !== "root"; parent = parent.parent) {
+        if (parent.type === "rule") {
+            return true;
+        }
+        if (isAtRule(parent)) {
+            const isTopLevelMedia = parent.name === "media" && parent.parent?.type === "root";
+            if (parent.name === "layer" || parent.name.endsWith("keyframes") || isTopLevelMedia) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+const rule = (primary) => (root, result) => {
+    if (!validateOptions(result, ruleName, { actual: primary })) {
+        return;
+    }
+    root.walkAtRules("layer", (atRule) => {
+        const name = atRule.params.split(".")[0]?.trim() ?? "";
+        const isLayerBlock = atRule.nodes !== undefined;
+        if (isLayerBlock && !HOUSE_LAYERS.has(name)) {
+            report({ message: messages.undeclared(name), node: atRule, result, ruleName });
+        }
+    });
+    root.walkRules((styleRule) => {
+        if (!isLayeredOrExempt(styleRule)) {
+            report({ message: messages.outside, node: styleRule, result, ruleName });
+        }
+    });
+};
+rule.ruleName = ruleName;
+rule.messages = messages;
+export const layered = createPlugin(ruleName, rule);
+//# sourceMappingURL=layered.js.map

package/dist/stylelint/layered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layered.js","sourceRoot":"","sources":["../../src/stylelint/layered.ts"],"names":[],"mappings":"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"}

package/dist/stylelint/mediaLast.d.ts

@@ -0,0 +1,2 @@
+import stylelint from "stylelint";
+export declare const mediaLast: stylelint.Plugin;

package/dist/stylelint/mediaLast.js

@@ -0,0 +1,27 @@
+import stylelint from "stylelint";
+const { createPlugin, utils: { report, ruleMessages, validateOptions }, } = stylelint;
+const ruleName = "nks/media-last";
+const messages = ruleMessages(ruleName, {
+    rejected: "Move this above the first top-level @media. Media queries go at the bottom of the file.",
+});
+function isMedia(node) {
+    return node.type === "atrule" && node.name === "media";
+}
+const rule = (primary) => (root, result) => {
+    if (!validateOptions(result, ruleName, { actual: primary })) {
+        return;
+    }
+    let mediaSeen = false;
+    for (const node of root.nodes) {
+        if (isMedia(node)) {
+            mediaSeen = true;
+        }
+        else if (mediaSeen && (node.type === "rule" || node.type === "atrule")) {
+            report({ message: messages.rejected, node, result, ruleName });
+        }
+    }
+};
+rule.ruleName = ruleName;
+rule.messages = messages;
+export const mediaLast = createPlugin(ruleName, rule);
+//# sourceMappingURL=mediaLast.js.map

package/dist/stylelint/mediaLast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaLast.js","sourceRoot":"","sources":["../../src/stylelint/mediaLast.ts"],"names":[],"mappings":"AACA,OAAO,SAAS,MAAM,WAAW,CAAC;AAElC,MAAM,EACJ,YAAY,EACZ,KAAK,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,GACjD,GAAG,SAAS,CAAC;AAEd,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAElC,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE;IACtC,QAAQ,EAAE,yFAAyF;CACpG,CAAC,CAAC;AAEH,SAAS,OAAO,CAAC,IAAe;IAC9B,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;AACzD,CAAC;AAED,MAAM,IAAI,GAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;IACzD,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO;IACT,CAAC;IAED,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAClB,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;aAAM,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;YACzE,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAEzB,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC"}

package/dist/stylelint/scaleOfThree.d.ts

@@ -0,0 +1,2 @@
+import stylelint from "stylelint";
+export declare const scaleOfThree: stylelint.Plugin;

package/dist/stylelint/scaleOfThree.js

@@ -0,0 +1,34 @@
+import stylelint from "stylelint";
+const { createPlugin, utils: { report, ruleMessages, validateOptions }, } = stylelint;
+const ruleName = "nks/scale-of-three";
+const messages = ruleMessages(ruleName, {
+    rejected: (length) => `${length} is off the scale. Use 1px or a multiple of 3px (rem at 16px).`,
+});
+const LENGTH = /(-?\d*\.?\d+)(px|rem)\b/g;
+const PX_PER_REM = 16;
+const SCALE_STEP_PX = 3;
+const HAIRLINE_PX = 1;
+const ROUNDING_TOLERANCE = 1e-9;
+function isOnScale(amount, unit) {
+    const px = Math.abs(unit === "rem" ? amount * PX_PER_REM : amount);
+    const steps = px / SCALE_STEP_PX;
+    const isWholeStep = Math.abs(steps - Math.round(steps)) < ROUNDING_TOLERANCE;
+    return px === HAIRLINE_PX || isWholeStep;
+}
+const rule = (primary) => (root, result) => {
+    if (!validateOptions(result, ruleName, { actual: primary })) {
+        return;
+    }
+    root.walkDecls((decl) => {
+        for (const [length, amount, unit] of decl.value.matchAll(LENGTH)) {
+            const isOffScale = amount !== undefined && unit !== undefined && !isOnScale(Number(amount), unit);
+            if (isOffScale) {
+                report({ message: messages.rejected(length), node: decl, result, ruleName, word: length });
+            }
+        }
+    });
+};
+rule.ruleName = ruleName;
+rule.messages = messages;
+export const scaleOfThree = createPlugin(ruleName, rule);
+//# sourceMappingURL=scaleOfThree.js.map

package/dist/stylelint/scaleOfThree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaleOfThree.js","sourceRoot":"","sources":["../../src/stylelint/scaleOfThree.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,WAAW,CAAC;AAElC,MAAM,EACJ,YAAY,EACZ,KAAK,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,GACjD,GAAG,SAAS,CAAC;AAEd,MAAM,QAAQ,GAAG,oBAAoB,CAAC;AAEtC,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE;IACtC,QAAQ,EAAE,CAAC,MAAc,EAAE,EAAE,CAAC,GAAG,MAAM,gEAAgE;CACxG,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,0BAA0B,CAAC;AAC1C,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,SAAS,SAAS,CAAC,MAAc,EAAE,IAAY;IAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,EAAE,GAAG,aAAa,CAAC;IACjC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,kBAAkB,CAAC;IAC7E,OAAO,EAAE,KAAK,WAAW,IAAI,WAAW,CAAC;AAC3C,CAAC;AAED,MAAM,IAAI,GAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;IACzD,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO;IACT,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QACtB,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,MAAM,UAAU,GAAG,MAAM,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;YAClG,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC7F,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAEzB,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC"}

package/dist/stylelint/varFallback.d.ts

@@ -0,0 +1,2 @@
+import stylelint from "stylelint";
+export declare const varFallback: stylelint.Plugin;

package/dist/stylelint/varFallback.js

@@ -0,0 +1,28 @@
+import stylelint from "stylelint";
+const { createPlugin, utils: { report, ruleMessages, validateOptions }, } = stylelint;
+const ruleName = "nks/var-fallback";
+const messages = ruleMessages(ruleName, {
+    rejected: (name) => `Give var(${name}) a fallback: var(${name}, value).`,
+});
+const BARE_VAR = /var\(\s*(--[\w-]+)\s*\)/g;
+const rule = (primary) => (root, result) => {
+    if (!validateOptions(result, ruleName, { actual: primary })) {
+        return;
+    }
+    const declaredInFile = new Set();
+    root.walkDecls(/^--/, (decl) => {
+        declaredInFile.add(decl.prop);
+    });
+    root.walkDecls((decl) => {
+        for (const [bareVar, name] of decl.value.matchAll(BARE_VAR)) {
+            const needsFallback = name !== undefined && !declaredInFile.has(name);
+            if (needsFallback) {
+                report({ message: messages.rejected(name), node: decl, result, ruleName, word: bareVar });
+            }
+        }
+    });
+};
+rule.ruleName = ruleName;
+rule.messages = messages;
+export const varFallback = createPlugin(ruleName, rule);
+//# sourceMappingURL=varFallback.js.map

package/dist/stylelint/varFallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"varFallback.js","sourceRoot":"","sources":["../../src/stylelint/varFallback.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,WAAW,CAAC;AAElC,MAAM,EACJ,YAAY,EACZ,KAAK,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,GACjD,GAAG,SAAS,CAAC;AAEd,MAAM,QAAQ,GAAG,kBAAkB,CAAC;AAEpC,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE;IACtC,QAAQ,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,YAAY,IAAI,qBAAqB,IAAI,WAAW;CACjF,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAE5C,MAAM,IAAI,GAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;IACzD,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO;IACT,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IACzC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;QAC7B,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QACtB,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5D,MAAM,aAAa,GAAG,IAAI,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtE,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAEzB,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC"}

package/dist/stylelint.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from "stylelint";
+declare const config: Config;
+export default config;

package/dist/stylelint.js

@@ -0,0 +1,49 @@
+import { fileURLToPath } from "node:url";
+import { layered } from "./stylelint/layered.js";
+import { mediaLast } from "./stylelint/mediaLast.js";
+import { scaleOfThree } from "./stylelint/scaleOfThree.js";
+import { varFallback } from "./stylelint/varFallback.js";
+const orderPlugin = fileURLToPath(import.meta.resolve("stylelint-order"));
+const BEM_CLASS = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$/;
+const BRIGHTNESS = /brightness\(/;
+const disallowedEverywhere = { filter: [BRIGHTNESS] };
+function disallowedValueMessage(_property, value) {
+    return BRIGHTNESS.test(value)
+        ? "Do not use brightness()."
+        : "Use a semantic token here. Primitive tokens belong in the token files.";
+}
+const config = {
+    overrides: [
+        {
+            files: ["**/tokens/**/*.css"],
+            rules: {
+                "declaration-property-value-disallowed-list": [disallowedEverywhere, { message: disallowedValueMessage }],
+            },
+        },
+    ],
+    plugins: [layered, mediaLast, orderPlugin, scaleOfThree, varFallback],
+    rules: {
+        "color-named": "never",
+        "color-no-hex": true,
+        "declaration-no-important": true,
+        "declaration-property-value-disallowed-list": [
+            { ...disallowedEverywhere, "/.*/": [/var\(--(palette|scale)-/] },
+            { message: disallowedValueMessage },
+        ],
+        "function-disallowed-list": [["rgb", "rgba", "hsl", "hsla"], { message: "Use oklch()." }],
+        "max-nesting-depth": 3,
+        "nks/layered": true,
+        "nks/media-last": true,
+        "nks/scale-of-three": true,
+        "nks/var-fallback": true,
+        "order/order": ["custom-properties", "declarations", "rules", "at-rules"],
+        "order/properties-alphabetical-order": true,
+        "selector-class-pattern": [
+            BEM_CLASS,
+            { message: "Expected BEM kebab-case: block, block__element, block--modifier" },
+        ],
+        "unit-allowed-list": ["rem", "px", "%", "fr", "vh", "dvh", "svh", "vw", "deg", "ms", "s"],
+    },
+};
+export default config;
+//# sourceMappingURL=stylelint.js.map

package/dist/stylelint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stylelint.js","sourceRoot":"","sources":["../src/stylelint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAE1E,MAAM,SAAS,GAAG,qFAAqF,CAAC;AAExG,MAAM,UAAU,GAAG,cAAc,CAAC;AAElC,MAAM,oBAAoB,GAAG,EAAE,MAAM,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;AAEtD,SAAS,sBAAsB,CAAC,SAAiB,EAAE,KAAa;IAC9D,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAC3B,CAAC,CAAC,0BAA0B;QAC5B,CAAC,CAAC,wEAAwE,CAAC;AAC/E,CAAC;AAED,MAAM,MAAM,GAAW;IACrB,SAAS,EAAE;QACT;YACE,KAAK,EAAE,CAAC,oBAAoB,CAAC;YAC7B,KAAK,EAAE;gBACL,4CAA4C,EAAE,CAAC,oBAAoB,EAAE,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;aAC1G;SACF;KACF;IACD,OAAO,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,CAAC;IACrE,KAAK,EAAE;QACL,aAAa,EAAE,OAAO;QACtB,cAAc,EAAE,IAAI;QACpB,0BAA0B,EAAE,IAAI;QAChC,4CAA4C,EAAE;YAC5C,EAAE,GAAG,oBAAoB,EAAE,MAAM,EAAE,CAAC,yBAAyB,CAAC,EAAE;YAChE,EAAE,OAAO,EAAE,sBAAsB,EAAE;SACpC;QACD,0BAA0B,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;QACzF,mBAAmB,EAAE,CAAC;QACtB,aAAa,EAAE,IAAI;QACnB,gBAAgB,EAAE,IAAI;QACtB,oBAAoB,EAAE,IAAI;QAC1B,kBAAkB,EAAE,IAAI;QACxB,aAAa,EAAE,CAAC,mBAAmB,EAAE,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC;QACzE,qCAAqC,EAAE,IAAI;QAC3C,wBAAwB,EAAE;YACxB,SAAS;YACT,EAAE,OAAO,EAAE,iEAAiE,EAAE;SAC/E;QACD,mBAAmB,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC;KAC1F;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ncksnydr/config-js",
-  "version": "0.2.0",
-  "description": "Shared TypeScript, ESLint, Prettier and Vitest configuration for Nick Snyder's codebases",
+  "version": "0.3.0",
+  "description": "Shared TypeScript, ESLint, Prettier, Stylelint and Vitest configuration for Nick Snyder's codebases",
   "repository": {
     "directory": "packages/config-js",
     "type": "git",
@@ -17,6 +17,10 @@
       "types": "./dist/prettier.d.ts",
       "default": "./dist/prettier.js"
     },
+    "./stylelint": {
+      "types": "./dist/stylelint.d.ts",
+      "default": "./dist/stylelint.js"
+    },
     "./tsconfig": "./tsconfig/base.json",
     "./vitest": {
       "types": "./dist/vitest.d.ts",
@@ -34,6 +38,7 @@
   "peerDependencies": {
     "eslint": "^10.0.0",
     "prettier": "^3.5.0",
+    "stylelint": "^18.0.0",
     "typescript": "^6.0.0",
     "vitest": "^5.0.0"
   },
@@ -44,6 +49,9 @@
     "prettier": {
       "optional": true
     },
+    "stylelint": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     },
@@ -56,12 +64,15 @@
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import-x": "^4.18.1",
+    "stylelint-order": "^8.1.3",
     "typescript-eslint": "^8.72.2"
   },
   "devDependencies": {
     "@types/node": "^26.6.6",
     "eslint": "^10.14.0",
+    "postcss": "^8.5.32",
     "prettier": "^3.10.0",
+    "stylelint": "^18.0.0",
     "typescript": "~6.0.3",
     "vitest": "^5.1.0"
   },

package/src/stylelint/layered.ts

@@ -0,0 +1,62 @@
+import type { AtRule, Node, Rule } from "postcss";
+import stylelint from "stylelint";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "nks/layered";
+
+const HOUSE_LAYERS = new Set(["reset", "tokens", "base", "components", "utilities"]);
+
+const houseLayerList = new Intl.ListFormat("en-GB", { type: "disjunction" }).format(HOUSE_LAYERS);
+
+const messages = ruleMessages(ruleName, {
+  outside: `Put this rule inside @layer ${houseLayerList}.`,
+  undeclared: (name: string) => `'${name}' is not a house layer. Use ${houseLayerList}.`,
+});
+
+function isAtRule(node: Node): node is AtRule {
+  return node.type === "atrule";
+}
+
+function isLayeredOrExempt(styleRule: Rule) {
+  for (let parent = styleRule.parent; parent && parent.type !== "root"; parent = parent.parent) {
+    if (parent.type === "rule") {
+      return true;
+    }
+    if (isAtRule(parent)) {
+      const isTopLevelMedia = parent.name === "media" && parent.parent?.type === "root";
+      if (parent.name === "layer" || parent.name.endsWith("keyframes") || isTopLevelMedia) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+const rule: stylelint.Rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary })) {
+    return;
+  }
+
+  root.walkAtRules("layer", (atRule) => {
+    const name = atRule.params.split(".")[0]?.trim() ?? "";
+    const isLayerBlock = atRule.nodes !== undefined;
+    if (isLayerBlock && !HOUSE_LAYERS.has(name)) {
+      report({ message: messages.undeclared(name), node: atRule, result, ruleName });
+    }
+  });
+
+  root.walkRules((styleRule) => {
+    if (!isLayeredOrExempt(styleRule)) {
+      report({ message: messages.outside, node: styleRule, result, ruleName });
+    }
+  });
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+
+export const layered = createPlugin(ruleName, rule);

package/src/stylelint/mediaLast.ts

@@ -0,0 +1,37 @@
+import type { ChildNode } from "postcss";
+import stylelint from "stylelint";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "nks/media-last";
+
+const messages = ruleMessages(ruleName, {
+  rejected: "Move this above the first top-level @media. Media queries go at the bottom of the file.",
+});
+
+function isMedia(node: ChildNode) {
+  return node.type === "atrule" && node.name === "media";
+}
+
+const rule: stylelint.Rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary })) {
+    return;
+  }
+
+  let mediaSeen = false;
+  for (const node of root.nodes) {
+    if (isMedia(node)) {
+      mediaSeen = true;
+    } else if (mediaSeen && (node.type === "rule" || node.type === "atrule")) {
+      report({ message: messages.rejected, node, result, ruleName });
+    }
+  }
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+
+export const mediaLast = createPlugin(ruleName, rule);

package/src/stylelint/scaleOfThree.ts

@@ -0,0 +1,45 @@
+import stylelint from "stylelint";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "nks/scale-of-three";
+
+const messages = ruleMessages(ruleName, {
+  rejected: (length: string) => `${length} is off the scale. Use 1px or a multiple of 3px (rem at 16px).`,
+});
+
+const LENGTH = /(-?\d*\.?\d+)(px|rem)\b/g;
+const PX_PER_REM = 16;
+const SCALE_STEP_PX = 3;
+const HAIRLINE_PX = 1;
+const ROUNDING_TOLERANCE = 1e-9;
+
+function isOnScale(amount: number, unit: string) {
+  const px = Math.abs(unit === "rem" ? amount * PX_PER_REM : amount);
+  const steps = px / SCALE_STEP_PX;
+  const isWholeStep = Math.abs(steps - Math.round(steps)) < ROUNDING_TOLERANCE;
+  return px === HAIRLINE_PX || isWholeStep;
+}
+
+const rule: stylelint.Rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary })) {
+    return;
+  }
+
+  root.walkDecls((decl) => {
+    for (const [length, amount, unit] of decl.value.matchAll(LENGTH)) {
+      const isOffScale = amount !== undefined && unit !== undefined && !isOnScale(Number(amount), unit);
+      if (isOffScale) {
+        report({ message: messages.rejected(length), node: decl, result, ruleName, word: length });
+      }
+    }
+  });
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+
+export const scaleOfThree = createPlugin(ruleName, rule);

package/src/stylelint/varFallback.ts

@@ -0,0 +1,39 @@
+import stylelint from "stylelint";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "nks/var-fallback";
+
+const messages = ruleMessages(ruleName, {
+  rejected: (name: string) => `Give var(${name}) a fallback: var(${name}, value).`,
+});
+
+const BARE_VAR = /var\(\s*(--[\w-]+)\s*\)/g;
+
+const rule: stylelint.Rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary })) {
+    return;
+  }
+
+  const declaredInFile = new Set<string>();
+  root.walkDecls(/^--/, (decl) => {
+    declaredInFile.add(decl.prop);
+  });
+
+  root.walkDecls((decl) => {
+    for (const [bareVar, name] of decl.value.matchAll(BARE_VAR)) {
+      const needsFallback = name !== undefined && !declaredInFile.has(name);
+      if (needsFallback) {
+        report({ message: messages.rejected(name), node: decl, result, ruleName, word: bareVar });
+      }
+    }
+  });
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+
+export const varFallback = createPlugin(ruleName, rule);

package/src/stylelint.ts

@@ -0,0 +1,56 @@
+import { fileURLToPath } from "node:url";
+import type { Config } from "stylelint";
+import { layered } from "./stylelint/layered.js";
+import { mediaLast } from "./stylelint/mediaLast.js";
+import { scaleOfThree } from "./stylelint/scaleOfThree.js";
+import { varFallback } from "./stylelint/varFallback.js";
+
+const orderPlugin = fileURLToPath(import.meta.resolve("stylelint-order"));
+
+const BEM_CLASS = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$/;
+
+const BRIGHTNESS = /brightness\(/;
+
+const disallowedEverywhere = { filter: [BRIGHTNESS] };
+
+function disallowedValueMessage(_property: string, value: string) {
+  return BRIGHTNESS.test(value)
+    ? "Do not use brightness()."
+    : "Use a semantic token here. Primitive tokens belong in the token files.";
+}
+
+const config: Config = {
+  overrides: [
+    {
+      files: ["**/tokens/**/*.css"],
+      rules: {
+        "declaration-property-value-disallowed-list": [disallowedEverywhere, { message: disallowedValueMessage }],
+      },
+    },
+  ],
+  plugins: [layered, mediaLast, orderPlugin, scaleOfThree, varFallback],
+  rules: {
+    "color-named": "never",
+    "color-no-hex": true,
+    "declaration-no-important": true,
+    "declaration-property-value-disallowed-list": [
+      { ...disallowedEverywhere, "/.*/": [/var\(--(palette|scale)-/] },
+      { message: disallowedValueMessage },
+    ],
+    "function-disallowed-list": [["rgb", "rgba", "hsl", "hsla"], { message: "Use oklch()." }],
+    "max-nesting-depth": 3,
+    "nks/layered": true,
+    "nks/media-last": true,
+    "nks/scale-of-three": true,
+    "nks/var-fallback": true,
+    "order/order": ["custom-properties", "declarations", "rules", "at-rules"],
+    "order/properties-alphabetical-order": true,
+    "selector-class-pattern": [
+      BEM_CLASS,
+      { message: "Expected BEM kebab-case: block, block__element, block--modifier" },
+    ],
+    "unit-allowed-list": ["rem", "px", "%", "fr", "vh", "dvh", "svh", "vw", "deg", "ms", "s"],
+  },
+};
+
+export default config;