@ncksnydr/config-js 0.2.0 → 0.4.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`:
@@ -110,7 +145,69 @@ To change a setting, merge the preset with your own configuration:
 import preset from "@ncksnydr/config-js/vitest";
 import { defineConfig, mergeConfig } from "vitest/config";
 
-export default mergeConfig(preset, defineConfig({ test: { include: ["tests/**/*.test.ts"] } }));
+export default mergeConfig(preset, defineConfig({ test: { testTimeout: 10_000 } }));
+```
+
+The preset runs tests in Node. It restores mocks between tests. If it finds no tests, the run fails.
+
+The preset does not set `include`, so Vitest finds test files with its own pattern, such as `*.test.ts` and `*.test.tsx`. To use your own pattern, merge an `include` into the preset.
+
+## React
+
+A React Consumer uses the React presets in place of the plain ones. Each React preset holds the plain preset and adds to it.
+
+### TypeScript for React
+
+Extend the React base in your `tsconfig.json`:
+
+```json
+{
+  "extends": "@ncksnydr/config-js/tsconfig-react"
+}
+```
+
+The React base adds the DOM types. It compiles JSX with React's automatic runtime, so a component file does not import React to use JSX. Install `react` and `@types/react`.
+
+### ESLint for React
+
+Use the React configuration as your `eslint.config.js`:
+
+```js
+export { default } from "@ncksnydr/config-js/eslint-react";
+```
+
+The React configuration adds these rules to `.ts` and `.tsx` files:
+
+- The recommended rules of `eslint-plugin-react`, `eslint-plugin-react-hooks` and `eslint-plugin-jsx-a11y`.
+- A missing dependency in a hook such as `useEffect` is an error, not a warning.
+- `useContext` is banned. Put shared state in a Zustand store.
+- `fireEvent` from `@testing-library/react` is banned. Use `userEvent`.
+- Text cannot be written inside JSX. Put the text in a variable, and use the variable in the JSX. Text in a prop is allowed.
+
+```text
+Welcome.tsx
+  2:13  error  Strings not allowed in JSX files: "Welcome back"  react/jsx-no-literals
+```
+
+The configuration reads the React version from the `react` package that your code imports. Use `boundaries()` with it the same way as with the plain configuration.
+
+### Vitest for React
+
+Use the React preset as your `vitest.config.ts`:
+
+```ts
+export { default } from "@ncksnydr/config-js/vitest-react";
+```
+
+The React preset holds the plain Vitest preset, and runs the tests in Vitest's browser mode, in Chromium through Playwright. The Storybook Vitest addon uses the same browser.
+
+The React preset sets no `include`, so you can add the Storybook Vitest plugin to it. The plugin sets `include` to your stories. It prints a warning when the configuration already has an `include`.
+
+Install Playwright and the Vitest Playwright provider. Then install Chromium once on each machine and in CI:
+
+```sh
+pnpm add --save-dev playwright @vitest/browser-playwright
+pnpm exec playwright install chromium
 ```
 
-The preset runs tests in Node and finds `*.test.ts` files next to the code. It restores mocks between tests. If it finds no tests, the run fails.
+In CI on Linux, use `pnpm exec playwright install --with-deps chromium`. This command also installs the system libraries that Chromium needs.

package/dist/eslint-react.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint/config").ConfigObject[];
+export default _default;

package/dist/eslint-react.js

@@ -0,0 +1,42 @@
+import { fixupPluginRules } from "@eslint/compat";
+import jsxA11y from "eslint-plugin-jsx-a11y";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import { defineConfig } from "eslint/config";
+import base from "./eslint.js";
+const reactWithVersionDetection = fixupPluginRules(react);
+function reactPluginConfig(name) {
+    const config = react.configs.flat[name];
+    if (config === undefined) {
+        throw new Error(`eslint-plugin-react has no flat configuration named "${name}".`);
+    }
+    return { ...config, plugins: { react: reactWithVersionDetection } };
+}
+export default defineConfig(base, {
+    extends: [
+        jsxA11y.flatConfigs.recommended,
+        reactPluginConfig("recommended"),
+        reactPluginConfig("jsx-runtime"),
+        reactHooks.configs.flat.recommended,
+    ],
+    files: ["**/*.{ts,tsx}"],
+    rules: {
+        "no-restricted-imports": [
+            "error",
+            {
+                paths: [
+                    { importNames: ["useContext"], message: "Put shared state in a Zustand store.", name: "react" },
+                    { importNames: ["fireEvent"], message: "Use userEvent.", name: "@testing-library/react" },
+                ],
+            },
+        ],
+        "react-hooks/exhaustive-deps": "error",
+        "react/jsx-no-literals": ["error", { ignoreProps: true, noStrings: true }],
+    },
+    settings: {
+        react: {
+            version: "detect",
+        },
+    },
+});
+//# sourceMappingURL=eslint-react.js.map

package/dist/eslint-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eslint-react.js","sourceRoot":"","sources":["../src/eslint-react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,OAAO,MAAM,wBAAwB,CAAC;AAC7C,OAAO,KAAK,MAAM,qBAAqB,CAAC;AACxC,OAAO,UAAU,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,IAAI,MAAM,aAAa,CAAC;AAE/B,MAAM,yBAAyB,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;AAE1D,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,IAAI,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,yBAAyB,EAAE,EAAE,CAAC;AACtE,CAAC;AAED,eAAe,YAAY,CAAC,IAAI,EAAE;IAChC,OAAO,EAAE;QACP,OAAO,CAAC,WAAW,CAAC,WAAW;QAC/B,iBAAiB,CAAC,aAAa,CAAC;QAChC,iBAAiB,CAAC,aAAa,CAAC;QAChC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW;KACpC;IACD,KAAK,EAAE,CAAC,eAAe,CAAC;IACxB,KAAK,EAAE;QACL,uBAAuB,EAAE;YACvB,OAAO;YACP;gBACE,KAAK,EAAE;oBACL,EAAE,WAAW,EAAE,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,IAAI,EAAE,OAAO,EAAE;oBAC/F,EAAE,WAAW,EAAE,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,wBAAwB,EAAE;iBAC1F;aACF;SACF;QACD,6BAA6B,EAAE,OAAO;QACtC,uBAAuB,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;KAC3E;IACD,QAAQ,EAAE;QACR,KAAK,EAAE;YACL,OAAO,EAAE,QAAQ;SAClB;KACF;CACF,CAAC,CAAC"}

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":"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,aAAa,CAAC;AAE/B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;AAErF,MAAM,cAAc,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AAElG,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,+BAA+B,cAAc,GAAG;IACzD,UAAU,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,IAAI,+BAA+B,cAAc,GAAG;CACvF,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,IAAU;IAC1B,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAe;IACxC,KAAK,IAAI,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7F,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,KAAK,MAAM,CAAC;YAClF,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,eAAe,EAAE,CAAC;gBACpF,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,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,WAAW,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE;QACnC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACvD,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC;QAChD,IAAI,YAAY,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE;QAC3B,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3E,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,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC"}

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/dist/vitest-react.d.ts

@@ -0,0 +1,3 @@
+import { type ViteUserConfig } from "vitest/config";
+declare const preset: ViteUserConfig;
+export default preset;

package/dist/vitest-react.js

@@ -0,0 +1,15 @@
+import { playwright } from "@vitest/browser-playwright";
+import { defineConfig, mergeConfig } from "vitest/config";
+import plain from "./vitest.js";
+const preset = mergeConfig(plain, defineConfig({
+    test: {
+        browser: {
+            enabled: true,
+            headless: true,
+            instances: [{ browser: "chromium" }],
+            provider: playwright(),
+        },
+    },
+}));
+export default preset;
+//# sourceMappingURL=vitest-react.js.map

package/dist/vitest-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-react.js","sourceRoot":"","sources":["../src/vitest-react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAuB,MAAM,eAAe,CAAC;AAC/E,OAAO,KAAK,MAAM,aAAa,CAAC;AAEhC,MAAM,MAAM,GAAmB,WAAW,CACxC,KAAK,EACL,YAAY,CAAC;IACX,IAAI,EAAE;QACJ,OAAO,EAAE;YACP,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;YACpC,QAAQ,EAAE,UAAU,EAAE;SACvB;KACF;CACF,CAAC,CACH,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/vitest.d.ts

@@ -1,2 +1,3 @@
-declare const _default: import("vite").UserConfig;
-export default _default;
+import { type ViteUserConfig } from "vitest/config";
+declare const preset: ViteUserConfig;
+export default preset;

package/dist/vitest.js

@@ -1,10 +1,10 @@
 import { defineConfig } from "vitest/config";
-export default defineConfig({
+const preset = defineConfig({
     test: {
         environment: "node",
-        include: ["**/*.test.ts"],
-        restoreMocks: true,
         passWithNoTests: false,
+        restoreMocks: true,
     },
 });
+export default preset;
 //# sourceMappingURL=vitest.js.map

package/dist/vitest.js.map

@@ -1 +1 @@
-{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../src/vitest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE;QACJ,WAAW,EAAE,MAAM;QACnB,OAAO,EAAE,CAAC,cAAc,CAAC;QACzB,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;KACvB;CACF,CAAC,CAAC"}
+{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../src/vitest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,eAAe,CAAC;AAElE,MAAM,MAAM,GAAmB,YAAY,CAAC;IAC1C,IAAI,EAAE;QACJ,WAAW,EAAE,MAAM;QACnB,eAAe,EAAE,KAAK;QACtB,YAAY,EAAE,IAAI;KACnB;CACF,CAAC,CAAC;AAEH,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.4.0",
+  "description": "Shared TypeScript, ESLint, Prettier, Stylelint and Vitest configuration for Nick Snyder's codebases",
   "repository": {
     "directory": "packages/config-js",
     "type": "git",
@@ -13,14 +13,27 @@
       "types": "./dist/eslint.d.ts",
       "default": "./dist/eslint.js"
     },
+    "./eslint-react": {
+      "types": "./dist/eslint-react.d.ts",
+      "default": "./dist/eslint-react.js"
+    },
     "./prettier": {
       "types": "./dist/prettier.d.ts",
       "default": "./dist/prettier.js"
     },
+    "./stylelint": {
+      "types": "./dist/stylelint.d.ts",
+      "default": "./dist/stylelint.js"
+    },
     "./tsconfig": "./tsconfig/base.json",
+    "./tsconfig-react": "./tsconfig/react.json",
     "./vitest": {
       "types": "./dist/vitest.d.ts",
       "default": "./dist/vitest.js"
+    },
+    "./vitest-react": {
+      "types": "./dist/vitest-react.d.ts",
+      "default": "./dist/vitest-react.js"
     }
   },
   "files": [
@@ -32,18 +45,30 @@
     "tsconfig"
   ],
   "peerDependencies": {
+    "@vitest/browser-playwright": "^5.0.0",
     "eslint": "^10.0.0",
+    "playwright": "^1.65.0",
     "prettier": "^3.5.0",
+    "stylelint": "^18.0.0",
     "typescript": "^6.0.0",
     "vitest": "^5.0.0"
   },
   "peerDependenciesMeta": {
+    "@vitest/browser-playwright": {
+      "optional": true
+    },
     "eslint": {
       "optional": true
     },
+    "playwright": {
+      "optional": true
+    },
     "prettier": {
       "optional": true
     },
+    "stylelint": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     },
@@ -52,16 +77,28 @@
     }
   },
   "dependencies": {
+    "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import-x": "^4.18.1",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "stylelint-order": "^8.1.3",
     "typescript-eslint": "^8.72.2"
   },
   "devDependencies": {
+    "@types/eslint-plugin-jsx-a11y": "^6.10.1",
     "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "@vitest/browser-playwright": "^5.1.0",
     "eslint": "^10.14.0",
+    "playwright": "^1.65.0",
+    "postcss": "^8.5.32",
     "prettier": "^3.10.0",
+    "react": "^19.3.1",
+    "stylelint": "^18.0.0",
     "typescript": "~6.0.3",
     "vitest": "^5.1.0"
   },

package/src/eslint-react.ts

@@ -0,0 +1,45 @@
+import { fixupPluginRules } from "@eslint/compat";
+import type { Linter } from "eslint";
+import jsxA11y from "eslint-plugin-jsx-a11y";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import { defineConfig } from "eslint/config";
+import base from "./eslint.js";
+
+const reactWithVersionDetection = fixupPluginRules(react);
+
+function reactPluginConfig(name: string): Linter.Config {
+  const config = react.configs.flat[name];
+  if (config === undefined) {
+    throw new Error(`eslint-plugin-react has no flat configuration named "${name}".`);
+  }
+  return { ...config, plugins: { react: reactWithVersionDetection } };
+}
+
+export default defineConfig(base, {
+  extends: [
+    jsxA11y.flatConfigs.recommended,
+    reactPluginConfig("recommended"),
+    reactPluginConfig("jsx-runtime"),
+    reactHooks.configs.flat.recommended,
+  ],
+  files: ["**/*.{ts,tsx}"],
+  rules: {
+    "no-restricted-imports": [
+      "error",
+      {
+        paths: [
+          { importNames: ["useContext"], message: "Put shared state in a Zustand store.", name: "react" },
+          { importNames: ["fireEvent"], message: "Use userEvent.", name: "@testing-library/react" },
+        ],
+      },
+    ],
+    "react-hooks/exhaustive-deps": "error",
+    "react/jsx-no-literals": ["error", { ignoreProps: true, noStrings: true }],
+  },
+  settings: {
+    react: {
+      version: "detect",
+    },
+  },
+});

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;

package/src/vitest-react.ts

@@ -0,0 +1,19 @@
+import { playwright } from "@vitest/browser-playwright";
+import { defineConfig, mergeConfig, type ViteUserConfig } from "vitest/config";
+import plain from "./vitest.js";
+
+const preset: ViteUserConfig = mergeConfig(
+  plain,
+  defineConfig({
+    test: {
+      browser: {
+        enabled: true,
+        headless: true,
+        instances: [{ browser: "chromium" }],
+        provider: playwright(),
+      },
+    },
+  }),
+);
+
+export default preset;

package/src/vitest.ts

@@ -1,10 +1,11 @@
-import { defineConfig } from "vitest/config";
+import { defineConfig, type ViteUserConfig } from "vitest/config";
 
-export default defineConfig({
+const preset: ViteUserConfig = defineConfig({
   test: {
     environment: "node",
-    include: ["**/*.test.ts"],
-    restoreMocks: true,
     passWithNoTests: false,
+    restoreMocks: true,
   },
 });
+
+export default preset;

package/tsconfig/react.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["DOM", "DOM.Iterable", "ES2024"]
+  }
+}