Swap UnoCSS for unplugin-icons to restore FE hot reload

vdavid · vdavid · commit 00906566ae90 · 2026-04-22T15:15:56.000+02:00
- UnoCSS's dev plugin was regenerating `virtual:uno.css` on every Svelte save, trickling through the root layout and triggering SvelteKit's TDZ crash (sveltejs/kit#15287). Root-layout HMR became unreliable across the app. - `unplugin-icons` (v23.0.1) with `@iconify-json/lucide` replaces UnoCSS. Icons are inline SVG Svelte components imported as `~icons/lucide/{name}` — tree-shaken, no runtime JS beyond the SVG itself, no virtual-CSS module in the HMR path. - Updated the three users (`ErrorPane`, `FullList`, `SelectionInfo`), sizing via explicit `width`/`height` props and coloring via a wrapping `<span>` with a scoped class (same `currentColor` mechanic as before). - Removed `unocss`, `@unocss/preset-icons`, `uno.config.ts`, the `virtual:uno.css` import, and the icon-class entries in `scripts/check-css-unused/allowlist.go`. - Added `src/unplugin-icons.d.ts` for the `~icons/*` virtual module types; registered the `Icons()` plugin in `vite.config.js` and `vitest.config.ts`; added `ignoreUnresolved: ["~icons/.+"]` to `knip.json`. - `hmr-recovery.ts` stays in place — it's defense-in-depth against any future root-layout HMR TDZ crash, not specific to UnoCSS. - Docs refreshed: `AGENTS.md`, `docs/style-guide.md` § Icons, and the three colocated `CLAUDE.md` files.
diff --git a/AGENTS.md b/AGENTS.md
@@ -159,9 +159,9 @@ resilience, and common pitfalls.
   `withGlobalTauri: true` in dev mode is a security risk.
 - ❌ 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.
-- **Icons**: We use UnoCSS with the Icons preset (`@iconify-json/lucide`). Icons are pure CSS classes like
-  `i-lucide:triangle-alert` — no JS imports. See `docs/style-guide.md` § Icons for usage, sizing, coloring, and how to
-  find new icons. When adding a new icon, also add it to `scripts/check-css-unused/allowlist.go`.
+- **Icons**: We use `unplugin-icons` with `@iconify-json/lucide`. Import as Svelte components from
+  `~icons/lucide/{icon-name}` (inline SVGs, no runtime cost). See `docs/style-guide.md` § Icons for usage, sizing,
+  coloring, and how to find new icons.
 - 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.
diff --git a/apps/desktop/knip.json b/apps/desktop/knip.json
@@ -2,6 +2,7 @@
   "$schema": "https://unpkg.com/knip@5/schema.json",
   "ignoreBinaries": ["only-allow", "rustc"],
   "ignore": ["src/lib/tauri-commands/**"],
+  "ignoreUnresolved": ["~icons/.+"],
   "ignoreDependencies": [
     "oxlint",
     "@tauri-apps/cli",
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
@@ -48,7 +48,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@iconify-json/lucide": "1.2.96",
+    "@iconify-json/lucide": "1.2.102",
     "@playwright/test": "^1.58.2",
     "@srsholmes/tauri-playwright": "^0.2.1",
     "@sveltejs/adapter-static": "^3.0.10",
@@ -57,7 +57,6 @@
     "@tauri-apps/cli": "^2.10.1",
     "@testing-library/svelte": "^5.3.1",
     "@types/node": "^25.5.0",
-    "@unocss/preset-icons": "66.6.6",
     "@vitest/coverage-v8": "^4.1.0",
     "axe-core": "^4.11.1",
     "eslint": "^10.1.0",
@@ -80,7 +79,7 @@
     "tsx": "^4.21.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.57.1",
-    "unocss": "66.6.6",
+    "unplugin-icons": "23.0.1",
     "vite": "^8.0.2",
     "vitest": "^4.1.0"
   }
diff --git a/apps/desktop/src/lib/file-explorer/CLAUDE.md b/apps/desktop/src/lib/file-explorer/CLAUDE.md
@@ -177,8 +177,9 @@ and actionable error experience.
 Receives a `FriendlyError` struct from Rust (all content is pre-baked on the backend, the frontend doesn't do any error
 classification or OS-specific logic):
 
-- **Title**: large text, always in accent color. UnoCSS/Lucide icon signals severity: ⚠ `i-lucide:triangle-alert` in
-  warning color for transient, ⊘ `i-lucide:circle-alert` in error color for serious, no icon for needs-action
+- **Title**: large text, always in accent color. Lucide icon (via `unplugin-icons`) signals severity: ⚠
+  `~icons/lucide/triangle-alert` in warning color for transient, ⊘ `~icons/lucide/circle-alert` in error color for
+  serious, no icon for needs-action
 - **Folder path**: shown in secondary text so the user knows exactly which folder is affected
 - **Explanation**: rendered as markdown via `snarkdown` — plain-language description of what happened
 - **Suggestion**: rendered as markdown — actionable steps, often provider-specific (for example, "Open **MacDroid** and
@@ -226,20 +227,12 @@ to O(visible). See [benchmarks](../../../../../docs/notes/non-reactive-file-stor
 
 ## Gotchas
 
-**UnoCSS content list is manually tracked.** `uno.config.ts` lists the specific files that use UnoCSS classes
-(`i-lucide:*` icons) so UnoCSS only watches those files during dev, not the entire `src/` tree. Without this, every file
-change triggers 6-7 redundant HMR updates. When adding UnoCSS classes to a new file, add that file to the
-`content.filesystem` array in `uno.config.ts`.
-
-**UnoCSS triggers SvelteKit root-layout HMR crash.** `virtual:uno.css` regenerates on every Svelte file save. Because
-it's imported in the root `+layout.svelte`, Vite treats it as a root-layout change, which forces SvelteKit to rebuild
-the entire route tree. SvelteKit's client router (`client.js:373`, `get_navigation_result_from_branch`) crashes with
+**Root-layout HMR can trigger a SvelteKit TDZ crash.** When an HMR update propagates through the root `+layout.svelte`
+(for example, `app.css` changes), SvelteKit's client router can crash with
 `ReferenceError: Cannot access 'component' before initialization` — a TDZ error where a route component module hasn't
-finished importing during the rebuild. This is a SvelteKit bug (sveltejs/kit#15287, observed with SvelteKit 2.55.0 /
-Svelte 5.54.1 / Vite 8.0.2). Workaround: `import.meta.hot.accept(() => { import.meta.hot!.invalidate() })` in the root
-layout catches the update and triggers a clean full page reload instead of the broken HMR path. Side effect: edits to
-the root layout or its deps (app.css, virtual:uno.css) cause a full reload instead of hot-swap. Leaf component edits are
-unaffected — SvelteKit handles those fine. If sveltejs/kit#15287 gets fixed, the workaround can be removed.
+finished importing during the rebuild. This is a SvelteKit bug (sveltejs/kit#15287). `$lib/hmr-recovery.ts` catches the
+crash and forces a clean page reload. The recovery listener is imported from `+layout.ts` (a stable module that survives
+layout component re-evaluation). If sveltejs/kit#15287 gets fixed, the workaround can be removed.
 
 ## Tabs (`tabs/`)
 
diff --git a/apps/desktop/src/lib/file-explorer/pane/ErrorPane.svelte b/apps/desktop/src/lib/file-explorer/pane/ErrorPane.svelte
@@ -1,5 +1,7 @@
 <script lang="ts">
     import { onDestroy } from 'svelte'
+    import IconCircleAlert from '~icons/lucide/circle-alert'
+    import IconTriangleAlert from '~icons/lucide/triangle-alert'
     import type { FriendlyError } from '../types'
     import { openPrivacySettings } from '$lib/tauri-commands'
     import { isMacOS } from '$lib/shortcuts/key-capture'
@@ -65,9 +67,9 @@
     <div class="content">
         <h2 class="title">
             {#if friendly.category === 'serious'}
-                <span class="title-icon icon-error i-lucide:circle-alert" style="width: 20px; height: 20px;"></span>
+                <span class="title-icon icon-error"><IconCircleAlert width="20" height="20" /></span>
             {:else if friendly.category === 'transient'}
-                <span class="title-icon icon-warning i-lucide:triangle-alert" style="width: 20px; height: 20px;"></span>
+                <span class="title-icon icon-warning"><IconTriangleAlert width="20" height="20" /></span>
             {/if}
             {friendly.title}
         </h2>
diff --git a/apps/desktop/src/lib/file-explorer/selection/CLAUDE.md b/apps/desktop/src/lib/file-explorer/selection/CLAUDE.md
@@ -47,8 +47,9 @@ In `selection-summary` mode, directory recursive sizes are included in the size
 index). The `hasOnlyDirs` branch shows size triads when `totalSize > 0`; when sizes are unavailable (indexing off), it
 falls back to showing only dir count and percentage.
 
-Stale indicator (UnoCSS/Lucide `i-lucide:hourglass` icon in accent color) appears in `selection-summary` when
-`isScanning()` is true and directories are selected, because dir sizes may be incomplete during scanning.
+Stale indicator (Lucide hourglass icon via `~icons/lucide/hourglass`, rendered in accent color) appears in
+`selection-summary` when `isScanning()` is true and directories are selected, because dir sizes may be incomplete during
+scanning.
 
 Filename truncation in `file-info` mode uses the `useShortenMiddle` action with `preferBreakAt: '.'` to preserve file
 extensions. The action uses pretext for canvas-based measurement and a built-in ResizeObserver.
diff --git a/apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte b/apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte
@@ -1,4 +1,5 @@
 <script lang="ts">
+    import IconHourglass from '~icons/lucide/hourglass'
     import type { FileEntry, ListingStats } from '../types'
     import {
         buildDateTooltip,
@@ -220,8 +221,8 @@
                 {pluralize(totalDirs, 'dir', 'dirs')}{#if totalSize === 0}
                     selected{/if}.
                 {#if showSelectionStale}
-                    <span class="stale-indicator" use:tooltip={'Updating index — size may change.'}
-                        ><span class="i-lucide:hourglass stale-icon"></span></span
+                    <span class="stale-indicator stale-icon" use:tooltip={'Updating index — size may change.'}
+                        ><IconHourglass width="12" height="12" /></span
                     >
                 {/if}
             {:else if hasFiles}
@@ -234,8 +235,8 @@
                     &nbsp;and {formatNumber(selectedDirs)} of {formatNumber(totalDirs)}
                     {pluralize(totalDirs, 'dir', 'dirs')}{/if}.
                 {#if showSelectionStale}
-                    <span class="stale-indicator" use:tooltip={'Updating index — size may change.'}
-                        ><span class="i-lucide:hourglass stale-icon"></span></span
+                    <span class="stale-indicator stale-icon" use:tooltip={'Updating index — size may change.'}
+                        ><IconHourglass width="12" height="12" /></span
                     >
                 {/if}
             {/if}
@@ -303,7 +304,5 @@
     .stale-icon {
         /* stylelint-disable-next-line declaration-property-value-disallowed-list -- small icon indicator, not body text */
         color: var(--color-accent);
-        width: 12px;
-        height: 12px;
     }
 </style>
diff --git a/apps/desktop/src/lib/file-explorer/views/CLAUDE.md b/apps/desktop/src/lib/file-explorer/views/CLAUDE.md
@@ -20,8 +20,8 @@ without DOM performance issues.
 - **measure-brief-column-widths.ts** – `measureWidestFilename()`: widest filename's pixel width in a Brief column,
   measured via pretext. Caller adds icon/gap/padding chrome and clamps to the min/max column-width range.
 - **FullList.svelte** – Reads `listing.sizeDisplay` (via `getSizeDisplayMode()`) and `listing.sizeMismatchWarning` (via
-  `getSizeMismatchWarning()`) settings. Uses UnoCSS/Lucide `i-lucide:circle-alert` for size mismatch warnings and
-  `i-lucide:hourglass` for stale index indicators
+  `getSizeMismatchWarning()`) settings. Uses Lucide icons (via `unplugin-icons`): `~icons/lucide/circle-alert` for size
+  mismatch warnings and `~icons/lucide/hourglass` for stale index indicators
 - **dir-size-display.test.ts** – Tests for `getDirSizeDisplayState` / `buildDirSizeTooltip` (functions in
   `full-list-utils.ts`)
 - **view-modes.test.ts** – Integration tests for hidden-file filtering and directory listing structure (uses
diff --git a/apps/desktop/src/lib/file-explorer/views/FullList.svelte b/apps/desktop/src/lib/file-explorer/views/FullList.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+    import IconCircleAlert from '~icons/lucide/circle-alert'
+    import IconHourglass from '~icons/lucide/hourglass'
     import type { FileEntry, SortColumn, SortOrder, SyncStatus } from '../types'
     import { calculateVirtualWindow, getScrollToPosition } from './virtual-scroll'
     import { startSelectionDragTracking, type DragFileInfo } from '../drag/drag-drop'
@@ -595,8 +597,8 @@
                                         <span class={triad.tierClass}>{triad.value}</span>
                                     {/each}
                                     {#if indexing}
-                                        <span class="size-stale" use:tooltip={'Updating index — size may change.'}
-                                            ><span class="i-lucide:hourglass icon-indicator"></span></span
+                                        <span class="size-stale icon-indicator" use:tooltip={'Updating index — size may change.'}
+                                            ><IconHourglass width="12" height="12" /></span
                                         >
                                     {/if}
                                     {#if showSizeMismatchWarning && hasSizeMismatch(file.recursiveSize, file.recursivePhysicalSize)}
@@ -613,14 +615,14 @@
                                         {@const dirTooltipHtml =
                                             typeof dirTooltip === 'object' ? dirTooltip.html : dirTooltip}
                                         <span
-                                            class="size-mismatch"
+                                            class="size-mismatch icon-indicator"
                                             use:tooltip={{
                                                 html:
                                                     'Content and on-disk sizes differ significantly.<br><br>' +
                                                     dirTooltipHtml,
                                             }}
                                         >
-                                            <span class="i-lucide:circle-alert icon-indicator"></span>
+                                            <IconCircleAlert width="12" height="12" />
                                         </span>
                                     {/if}
                                 {:else if indexing}
@@ -764,8 +766,6 @@
     .icon-indicator {
         /* stylelint-disable-next-line declaration-property-value-disallowed-list -- small icon indicator, not body text */
         color: var(--color-accent);
-        width: 12px;
-        height: 12px;
     }
 
     .size-stale {
diff --git a/apps/desktop/src/routes/+layout.svelte b/apps/desktop/src/routes/+layout.svelte
@@ -5,7 +5,6 @@
      * Other windows (viewer, debug) get only this minimal layout.
      */
     import { onMount } from 'svelte'
-    import 'virtual:uno.css'
     import '../app.css'
     import { initLogger } from '$lib/logging/logger'
 
diff --git a/apps/desktop/src/unplugin-icons.d.ts b/apps/desktop/src/unplugin-icons.d.ts
@@ -0,0 +1 @@
+/// <reference types="unplugin-icons/types/svelte" />
diff --git a/apps/desktop/tsconfig.json b/apps/desktop/tsconfig.json
@@ -11,7 +11,7 @@
     "strict": true,
     "moduleResolution": "bundler"
   },
-  "include": ["src", "scripts", "vite.config.js", "vitest.config.ts", "playwright.config.ts", "uno.config.ts"]
+  "include": ["src", "scripts", "vite.config.js", "vitest.config.ts", "playwright.config.ts"]
   // Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
   // except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
   //
diff --git a/apps/desktop/uno.config.ts b/apps/desktop/uno.config.ts
diff --git a/apps/desktop/vite.config.js b/apps/desktop/vite.config.js
@@ -1,11 +1,11 @@
 import { defineConfig } from 'vite'
 import { sveltekit } from '@sveltejs/kit/vite'
-import UnoCSS from 'unocss/vite'
+import Icons from 'unplugin-icons/vite'
 
 const host = process.env.TAURI_DEV_HOST
 
 export default defineConfig(async () => ({
-  plugins: [UnoCSS(), sveltekit()],
+  plugins: [Icons({ compiler: 'svelte' }), sveltekit()],
 
   build: {
     chunkSizeWarningLimit: 1000,
diff --git a/apps/desktop/vitest.config.ts b/apps/desktop/vitest.config.ts
@@ -1,9 +1,10 @@
 import { defineConfig } from 'vitest/config'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
+import Icons from 'unplugin-icons/vite'
 import path from 'path'
 
 export default defineConfig({
-  plugins: [svelte()],
+  plugins: [Icons({ compiler: 'svelte' }), svelte()],
   test: {
     include: ['src/**/*.test.ts'],
     environment: 'jsdom',
diff --git a/docs/style-guide.md b/docs/style-guide.md
@@ -111,59 +111,63 @@ Only add JSDoc that actually adds info. No tautologies.
 
 ### Icons
 
-We use [UnoCSS](https://unocss.dev/) with the [Icons preset](https://unocss.dev/presets/icons) for UI icons. This
-renders icons as **pure CSS** (no JS components, no runtime overhead). The icon data comes from the
-[Iconify](https://iconify.design/) ecosystem. We currently use the **Lucide** icon set (`@iconify-json/lucide`).
+We use [`unplugin-icons`](https://github.com/unplugin/unplugin-icons) with `@iconify-json/lucide` for UI icons. Each
+icon is imported as a Svelte component and rendered as an **inline SVG** (tree-shaken; only the icons you import ship).
+The icon data comes from the [Iconify](https://iconify.design/) ecosystem. We currently use the **Lucide** icon set.
 
 #### How it works
 
-UnoCSS generates CSS at build time. For monochrome icons, the SVG becomes a CSS `mask-image` with
-`background-color: currentColor`, so the icon inherits the text color of its parent. Config:
-`apps/desktop/uno.config.ts`.
+At build time, `unplugin-icons` turns an import like `~icons/lucide/triangle-alert` into a tiny Svelte component
+containing the inline SVG. The SVG uses `stroke="currentColor"`, so the icon inherits the text color of its parent.
 
 #### Finding icons
 
 1. Go to [icones.js.org](https://icones.js.org/) and select the **Lucide** collection to stay visually consistent
 2. Search by keyword (for example, "warning", "folder", "check")
-3. When you find a candidate, its class name is `i-lucide:{icon-name}` (for example, `i-lucide:triangle-alert`)
+3. The icon name (for example `triangle-alert`) maps to the import path `~icons/lucide/triangle-alert`
 4. **Always pick icons from the same set** (Lucide) for visual cohesion (consistent stroke width and style)
 
 If you're an AI agent looking for icons: search at `https://icones.js.org/collection/lucide?s={search+terms}`, suggest
 candidates to the user with the search URL and terms so they can browse and pick, then use the chosen icon name.
 
 #### Using icons in templates
 
-Icons are plain `<span>` elements with a UnoCSS class. **No imports needed.**
-
 ```svelte
+<script lang="ts">
+    import IconTriangleAlert from '~icons/lucide/triangle-alert'
+</script>
+
 <!-- Basic usage — inherits parent text color -->
-<span class="i-lucide:triangle-alert"></span>
+<IconTriangleAlert />
 
-<!-- With explicit size (use px via scoped CSS, not inline em) -->
-<span class="i-lucide:hourglass my-icon-class"></span>
+<!-- With explicit size (use px props, not em) -->
+<IconTriangleAlert width="12" height="12" />
 ```
 
-#### Sizing
-
-UnoCSS icons default to `1em × 1em` (scales with font size). We override this with **explicit px sizes via scoped CSS
-classes**, not inline styles, to keep sizing predictable and consistent:
+For styling (color, layout), wrap the icon in a `<span>` with a scoped CSS class. Applying a parent's scoped class
+directly to a component's root can be brittle; the wrapping span keeps the usual scoped-style semantics.
 
 ```svelte
-<span class="i-lucide:circle-alert detail-icon"></span>
+<span class="my-icon"><IconCircleAlert width="12" height="12" /></span>
 
 <style>
-    .detail-icon {
-        width: 12px;
-        height: 12px;
+    .my-icon {
+        display: inline-flex;
+        color: var(--color-warning);
     }
 </style>
 ```
 
+#### Sizing
+
+Pass explicit `width` / `height` props (in px) on the icon. Don't use `em` — sizing should be predictable and not float
+with surrounding text size.
+
 #### Coloring
 
 Icons use `currentColor` by default — they inherit the parent's text color. To color an icon:
 
-- **Preferred**: Set `color` on the parent element, or use a scoped CSS class on the icon
+- **Preferred**: Set `color` on the parent element (a wrapping `<span>` with a scoped CSS class)
 - **For accent color**: Use a scoped class with a stylelint disable comment (because `color: var(--color-accent)` is
   disallowed by default for a11y reasons — it has insufficient contrast as text):
   ```css
@@ -177,16 +181,14 @@ Icons use `currentColor` by default — they inherit the parent's text color. To
 #### Adding a new icon set
 
 If Lucide doesn't have what you need, install another Iconify set (for example, `pnpm add -D @iconify-json/mdi` for
-Material Design Icons). Then add it to the `ignoreDependencies` list in `knip.json` and to the `allowedUndefinedClasses`
-in `scripts/check-css-unused/allowlist.go`. Prefer sticking to one set per context for visual consistency.
+Material Design Icons). Import from `~icons/mdi/{icon-name}`. Prefer sticking to one set per context for visual
+consistency.
 
 #### Checklist for adding a new icon
 
 1. Find the icon at [icones.js.org](https://icones.js.org/) in the Lucide collection
-2. Use it as `<span class="i-lucide:{name} my-class"></span>`
-3. Set size via a scoped CSS class (not inline style, not `em`)
-4. Set color via scoped CSS or parent inheritance
-5. Add the class name to `scripts/check-css-unused/allowlist.go` → `allowedUndefinedClasses`
+2. Import it: `import IconName from '~icons/lucide/{icon-name}'`
+3. Render it: `<IconName width="16" height="16" />` (or wrap in a `<span>` with a scoped class for color/layout)
 
 ## Design
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/scripts/check-css-unused/allowlist.go b/scripts/check-css-unused/allowlist.go
