Tooling: Enforce CSS design tokens via Stylelint

vdavid · vdavid · commit 50f2b422052e · 2026-03-18T13:19:24.000+01:00
- Add Stylelint rules banning raw `px` for `font-size`, `border-radius`, raw font stacks for `font-family`, and `z-index` &gt;= 10 — must use `var(--font-size-*)`, `var(--radius-*)`, `var(--font-*)`, `var(--z-*)` tokens
- Add `--radius-xs: 2px` token for progress bars, search highlights, and small swatches
- Fix all existing violations: replace raw values with tokens, add justified `stylelint-disable-next-line` for one-off sizes outside the type scale (emoji icons, decorative text, partial radii)
- Update `AGENTS.md` and `design-system.md` to document the new rules and token
diff --git a/AGENTS.md b/AGENTS.md
@@ -81,6 +81,8 @@ If you don't find these but need them, ask the user. Run the app in dev mode fir
 - ❌ When testing the Tauri app, DO NOT USE THE BROWSER. Use the MCP servers.
 - ❌ Don't ignore linter warnings — fix them or justify with a comment.
 - Always use CSS variables defined in `apps/desktop/src/app.css`. Stylelint catches undefined/hallucinated variables.
+- Never use raw `px` values for `font-size`, `border-radius`, `font-family`, or `z-index` >= 10. Use `var(--font-size-*)`,
+  `var(--radius-*)`, `var(--font-*)`, and `var(--z-*)` tokens. Stylelint enforces this.
 - **Coverage allowlist is a last resort.** Extract pure functions and test them. Only allowlist what genuinely can't be
   tested. Name the specific untestable API in the reason.
 - When adding a new user-facing action, add it to `command-registry.ts` and `handleCommandExecute` in `+page.svelte`.
diff --git a/apps/desktop/.stylelintrc.mjs b/apps/desktop/.stylelintrc.mjs
@@ -19,6 +19,10 @@ export default {
         // Forbid var() with fallback values - all colors should be in app.css
         'declaration-property-value-disallowed-list': {
             '/.*/': ['/var\\(--[\\w-]+\\s*,/'],
+            'font-size': ['/\\dpx/'],
+            'border-radius': ['/\\dpx/'],
+            'z-index': ['/^\\d{2,}/'],
+            'font-family': ['/^(?!var\\(|inherit|unset|initial)/'],
         },
         'custom-property-pattern': '^(color|spacing|font|radius|shadow|transition|z)-.+',
         'declaration-block-no-duplicate-custom-properties': true,
diff --git a/apps/desktop/src/app.css b/apps/desktop/src/app.css
@@ -120,6 +120,7 @@
     --font-size-xl: 20px;
 
     /* === Border radius === */
+    --radius-xs: 2px;
     --radius-sm: 4px;
     --radius-md: 6px;
     --radius-lg: 8px;
@@ -276,10 +277,12 @@
     kbd,
     pre,
     samp {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- CSS reset */
         font-family: monospace, monospace;
     }
 
     pre {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- CSS reset */
         font-size: 1em;
     }
 
@@ -432,6 +435,7 @@ a:focus-visible,
  * This is intentional: we want macOS-native behavior, not web-browser behavior.
  */
 html {
+    /* stylelint-disable-next-line declaration-property-value-disallowed-list -- base size, not a component value */
     font-size: 16px;
 }
 
diff --git a/apps/desktop/src/lib/ai/AiToastContent.svelte b/apps/desktop/src/lib/ai/AiToastContent.svelte
@@ -108,15 +108,15 @@
         width: 100%;
         height: 4px;
         background: var(--color-bg-tertiary);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         overflow: hidden;
         margin-top: 4px;
     }
 
     .progress-bar-fill {
         height: 100%;
         background: var(--color-accent);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         transition: width var(--transition-slow);
     }
 
diff --git a/apps/desktop/src/lib/file-explorer/network/ShareBrowser.svelte b/apps/desktop/src/lib/file-explorer/network/ShareBrowser.svelte
@@ -506,6 +506,7 @@
 
     .error-icon,
     .empty-icon {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- emoji icon, outside type scale */
         font-size: 32px;
     }
 
diff --git a/apps/desktop/src/lib/file-explorer/pane/MtpConnectionView.svelte b/apps/desktop/src/lib/file-explorer/pane/MtpConnectionView.svelte
@@ -202,6 +202,7 @@
     }
 
     .mtp-error .error-icon {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- emoji icon, outside type scale */
         font-size: 32px;
     }
 
diff --git a/apps/desktop/src/lib/file-explorer/pane/NetworkMountView.svelte b/apps/desktop/src/lib/file-explorer/pane/NetworkMountView.svelte
@@ -225,6 +225,7 @@
     }
 
     .mount-error-state .error-icon {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- emoji icon, outside type scale */
         font-size: 32px;
     }
 
diff --git a/apps/desktop/src/lib/file-explorer/pane/PaneResizer.svelte b/apps/desktop/src/lib/file-explorer/pane/PaneResizer.svelte
@@ -73,7 +73,7 @@
     .handle {
         width: 3px;
         height: 24px;
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         background: var(--color-text-tertiary);
         opacity: 0;
         transition: opacity var(--transition-base);
diff --git a/apps/desktop/src/lib/file-explorer/selection/FileIcon.svelte b/apps/desktop/src/lib/file-explorer/selection/FileIcon.svelte
@@ -66,6 +66,7 @@
         position: absolute;
         bottom: -2px;
         right: -2px;
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- below type scale, tiny badge */
         font-size: 8px;
         line-height: 1;
     }
diff --git a/apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte b/apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte
@@ -330,7 +330,7 @@
     }
 
     .stale-indicator {
-        font-size: 10px;
+        font-size: var(--font-size-xs);
         cursor: help;
     }
 </style>
diff --git a/apps/desktop/src/lib/file-explorer/selection/SortableHeader.svelte b/apps/desktop/src/lib/file-explorer/selection/SortableHeader.svelte
@@ -77,6 +77,7 @@
     }
 
     .sort-indicator {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- below type scale, sort arrows */
         font-size: 8px;
         flex-shrink: 0;
     }
diff --git a/apps/desktop/src/lib/file-explorer/tabs/TabBar.svelte b/apps/desktop/src/lib/file-explorer/tabs/TabBar.svelte
@@ -220,6 +220,7 @@
         right: 0;
         height: 2px;
         background-color: var(--color-accent);
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- partial radius, no token */
         border-radius: 1px 1px 0 0;
     }
 
diff --git a/apps/desktop/src/lib/file-explorer/views/FullList.svelte b/apps/desktop/src/lib/file-explorer/views/FullList.svelte
@@ -569,7 +569,7 @@
     }
 
     .size-stale {
-        font-size: 10px;
+        font-size: var(--font-size-xs);
         line-height: 1;
         margin-left: 2px;
         cursor: help;
diff --git a/apps/desktop/src/lib/indexing/ScanStatusOverlay.svelte b/apps/desktop/src/lib/indexing/ScanStatusOverlay.svelte
@@ -97,12 +97,12 @@
         padding: var(--spacing-xxs) var(--spacing-sm);
         background: var(--color-bg-secondary);
         border: 1px solid var(--color-border);
-        border-radius: 4px;
+        border-radius: var(--radius-sm);
         font-size: var(--font-size-xs);
         color: var(--color-text-secondary);
         pointer-events: none;
         opacity: 0.85;
-        z-index: 10;
+        z-index: var(--z-sticky);
     }
 
     .scan-label {
@@ -126,14 +126,14 @@
         flex: 1;
         height: 4px;
         background: var(--color-bg-tertiary);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         overflow: hidden;
     }
 
     .progress-fill {
         height: 100%;
         background: var(--color-accent);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         transition: width 0.3s ease-out;
     }
 
diff --git a/apps/desktop/src/lib/licensing/AboutWindow.svelte b/apps/desktop/src/lib/licensing/AboutWindow.svelte
@@ -158,11 +158,13 @@
     }
 
     .icon-text {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- decorative, outside type scale */
         font-size: 40px;
         color: white;
     }
 
     .app-name {
+        /* stylelint-disable-next-line declaration-property-value-disallowed-list -- decorative, outside type scale */
         font-size: 28px;
         font-weight: 600;
         margin: 0 0 var(--spacing-xs);
diff --git a/apps/desktop/src/lib/search/SearchDialog.svelte b/apps/desktop/src/lib/search/SearchDialog.svelte
@@ -880,7 +880,7 @@
         align-items: center;
         justify-content: center;
         width: 16px;
-        font-size: 14px;
+        font-size: var(--font-size-md);
         line-height: 1;
     }
 
@@ -891,7 +891,7 @@
     }
 
     .icon-emoji {
-        font-size: 14px;
+        font-size: var(--font-size-md);
         line-height: 1;
     }
 
diff --git a/apps/desktop/src/lib/settings/components/SettingRow.svelte b/apps/desktop/src/lib/settings/components/SettingRow.svelte
@@ -195,6 +195,6 @@
         background-color: var(--color-highlight);
         color: inherit;
         padding: 0 2px;
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
     }
 </style>
diff --git a/apps/desktop/src/lib/settings/components/SettingSlider.svelte b/apps/desktop/src/lib/settings/components/SettingSlider.svelte
@@ -137,14 +137,14 @@
         flex: 1;
         height: 4px;
         background: var(--color-bg-tertiary);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         position: relative;
     }
 
     :global(.slider-range) {
         height: 100%;
         background: var(--color-accent);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
     }
 
     :global(.slider-thumb) {
diff --git a/apps/desktop/src/lib/settings/sections/AdvancedSection.svelte b/apps/desktop/src/lib/settings/sections/AdvancedSection.svelte
@@ -231,7 +231,7 @@
         background-color: var(--color-highlight);
         color: inherit;
         padding: 0 2px;
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
     }
 
     .setting-description {
diff --git a/apps/desktop/src/lib/settings/sections/AiSection.svelte b/apps/desktop/src/lib/settings/sections/AiSection.svelte
@@ -1329,15 +1329,15 @@
         width: 100%;
         height: 4px;
         background: var(--color-bg-tertiary);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         overflow: hidden;
         margin: var(--spacing-xs) 0;
     }
 
     .progress-bar-fill {
         height: 100%;
         background: var(--color-accent);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         transition: width var(--transition-slow);
     }
 
@@ -1435,7 +1435,7 @@
         display: inline-block;
         width: 8px;
         height: 8px;
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
     }
 
     .ram-free-space {
@@ -1534,7 +1534,7 @@
         box-shadow: var(--shadow-md);
         max-height: 200px;
         overflow-y: auto;
-        z-index: 10;
+        z-index: var(--z-sticky);
     }
 
     .combobox-option {
diff --git a/apps/desktop/src/lib/settings/sections/AppearanceSection.svelte b/apps/desktop/src/lib/settings/sections/AppearanceSection.svelte
@@ -338,7 +338,7 @@
     .format-help code {
         background: var(--color-bg-tertiary);
         padding: 1px 4px;
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         font-family: var(--font-mono);
     }
 </style>
diff --git a/apps/desktop/src/routes/debug/+page.svelte b/apps/desktop/src/routes/debug/+page.svelte
@@ -1117,7 +1117,7 @@
         justify-content: center;
         width: 14px;
         height: 14px;
-        font-size: 10px;
+        font-size: var(--font-size-xs);
         font-weight: 600;
         font-style: italic;
         font-family: var(--font-system), sans-serif;
diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
@@ -762,7 +762,7 @@
 
     mark {
         background: var(--color-highlight);
-        border-radius: 2px;
+        border-radius: var(--radius-xs);
         padding: 0 1px;
         margin: 0 -1px;
     }
diff --git a/docs/design-system.md b/docs/design-system.md
@@ -243,13 +243,13 @@ Tailwind's spacing scale (base 4px). No custom tokens needed.
 
 | Token | Value | Role |
 |-------|-------|------|
+| `--radius-xs` | 2px | Progress bars, search highlights, tiny swatches |
 | `--radius-sm` | 4px | Chips, inline tags, compact inputs |
 | `--radius-md` | 6px | Buttons, standard inputs |
 | `--radius-lg` | 8px | Dialogs, cards, larger containers |
 | `--radius-full` | 9999px | Circles, pills |
 
-Consolidate the existing 3px (10 uses) to `--radius-sm`. The scale intentionally uses small values — large radii look
-web-native, not macOS-native.
+The scale intentionally uses small values — large radii look web-native, not macOS-native.
 
 ### Website
 

Original file line number	Diff line number	Diff line change
`@@ -506,6 +506,7 @@`
`506`	`506`
`507`	`507`	`.error-icon,`
`508`	`508`	`.empty-icon {`
	`509`	`+ /* stylelint-disable-next-line declaration-property-value-disallowed-list -- emoji icon, outside type scale */`
`509`	`510`	`font-size: 32px;`
`510`	`511`	`}`
`511`	`512`
Original file line number	Diff line number	Diff line change
`@@ -202,6 +202,7 @@`
`202`	`202`	`}`
`203`	`203`
`204`	`204`	`.mtp-error .error-icon {`
	`205`	`+ /* stylelint-disable-next-line declaration-property-value-disallowed-list -- emoji icon, outside type scale */`
`205`	`206`	`font-size: 32px;`
`206`	`207`	`}`
`207`	`208`
Original file line number	Diff line number	Diff line change
`@@ -225,6 +225,7 @@`
`225`	`225`	`}`
`226`	`226`
`227`	`227`	`.mount-error-state .error-icon {`
	`228`	`+ /* stylelint-disable-next-line declaration-property-value-disallowed-list -- emoji icon, outside type scale */`
`228`	`229`	`font-size: 32px;`
`229`	`230`	`}`
`230`	`231`
Original file line number	Diff line number	Diff line change
`@@ -66,6 +66,7 @@`
`66`	`66`	`position: absolute;`
`67`	`67`	`bottom: -2px;`
`68`	`68`	`right: -2px;`
	`69`	`+ /* stylelint-disable-next-line declaration-property-value-disallowed-list -- below type scale, tiny badge */`
`69`	`70`	`font-size: 8px;`
`70`	`71`	`line-height: 1;`
`71`	`72`	`}`
Original file line number	Diff line number	Diff line change
`@@ -330,7 +330,7 @@`
`330`	`330`	`}`
`331`	`331`
`332`	`332`	`.stale-indicator {`
`333`		`- font-size: 10px;`
	`333`	`+ font-size: var(--font-size-xs);`
`334`	`334`	`cursor: help;`
`335`	`335`	`}`
`336`	`336`	`</style>`