Add Stylelint

And fix up CSS where it caught problems. CSS is still a mess, though

Author: vdavid

.stylelintrc.json

@@ -0,0 +1,39 @@
+{
+    "extends": ["stylelint-config-standard"],
+    "plugins": ["stylelint-value-no-unknown-custom-properties"],
+    "customSyntax": "postcss-html",
+    "rules": {
+        "csstools/value-no-unknown-custom-properties": [
+            true,
+            {
+                "importFrom": ["src/app.css"]
+            }
+        ],
+        "custom-property-pattern": "^(color|spacing|font)-.+",
+        "declaration-block-no-duplicate-custom-properties": true,
+        "selector-class-pattern": null,
+        "no-descending-specificity": null,
+        "color-hex-length": null,
+        "color-function-notation": null,
+        "alpha-value-notation": null,
+        "value-keyword-case": null,
+        "property-no-vendor-prefix": null,
+        "selector-pseudo-element-colon-notation": null,
+        "font-family-no-duplicate-names": null,
+        "declaration-property-value-keyword-no-deprecated": null,
+        "declaration-block-no-redundant-longhand-properties": null,
+        "comment-empty-line-before": null,
+        "color-function-alias-notation": null,
+        "keyframes-name-pattern": null,
+        "rule-empty-line-before": null,
+        "comment-whitespace-inside": null,
+        "selector-pseudo-class-no-unknown": [
+            true,
+            {
+                "ignorePseudoClasses": ["global"]
+            }
+        ],
+        "shorthand-property-no-redundant-values": null
+    },
+    "ignoreFiles": ["dist/**", "build/**", ".svelte-kit/**", "node_modules/**", "src-tauri/target/**"]
+}

AGENTS.md

@@ -64,7 +64,10 @@ Can use also `./scripts/check.sh --rust`, `./scripts/check.sh --svelte`, `./scri
 or `./scripts/check.sh --help` to see all options.
 
 Can also use `cargo fmt`, `cargo clippy`, `cargo audit`, `cargo deny check`, `cargo nextest run`, `pnpm format`,
-`pnpm lint --fix`, `pnpm test`, `pnpm test:e2e` as needed.
+`pnpm lint --fix`, `pnpm stylelint:fix`, `pnpm test`, `pnpm test:e2e` as needed.
+
+**CSS health checks**: When writing CSS, ALWAYS use variables defined in `src/app.css`. Stylelint catches
+undefined/hallucinated CSS variables.
 
 GitHub Actions workflow in `.github/workflows/ci.yml`:
 

docs/tooling/css-health-checks.md

@@ -0,0 +1,20 @@
+# CSS health checks with Stylelint
+
+We use Stylelint to validate CSS and catch common issues.
+
+Checks for:
+
+- Unused/hallucinated CSS variables
+- Variables to follow the pattern `--color-*`, `--spacing-*`, or `--font-*`.
+- CSS syntax errors
+- General CSS best practices
+
+Run it by `pnpm stylelint:fix` or via `./scripts/check.sh`
+
+## Config
+
+Stylelint is configured in `.stylelintrc.json` with:
+
+1. **`postcss-html` syntax** - Allows parsing `<style>` blocks in `.svelte` files
+2. **`stylelint-value-no-unknown-custom-properties` plugin** - The key plugin that validates CSS variables
+3. **`importFrom: ["src/app.css"]`** - Tells Stylelint which variables are actually defined

package.json

@@ -12,6 +12,8 @@
         "tauri": "node scripts/tauri-wrapper.js",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
+        "stylelint": "stylelint \"src/**/*.{css,svelte}\"",
+        "stylelint:fix": "stylelint \"src/**/*.{css,svelte}\" --fix",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "test": "vitest run",
@@ -45,8 +47,12 @@
         "globals": "^16.5.0",
         "jsdom": "^27.3.0",
         "knip": "^5.77.1",
+        "postcss-html": "^1.8.0",
         "prettier": "^3.7.4",
         "prettier-plugin-svelte": "^3.4.1",
+        "stylelint": "^16.26.1",
+        "stylelint-config-standard": "^39.0.1",
+        "stylelint-value-no-unknown-custom-properties": "^6.1.0",
         "svelte": "^5.46.1",
         "svelte-check": "^4.3.5",
         "svelte-eslint-parser": "^1.4.1",