Switch from Lucide components to UnoCSS pure-CSS icons

vdavid · vdavid · commit 93548fa625f9 · 2026-04-12T08:43:37.000+02:00
- Replace `@lucide/svelte` (JS components) with UnoCSS Icons preset + `@iconify-json/lucide` (CSS-only, zero runtime)
- Icons rendered via CSS `mask-image` with `currentColor` — recolor dynamically via CSS vars
- Sizing via scoped CSS classes with explicit `px`, not `em`
- Add `uno.config.ts`, UnoCSS Vite plugin, `virtual:uno.css` import in root layout
- Update 3 components: `ErrorPane`, `FullList`, `SelectionInfo`
- Add thorough icon usage docs in `style-guide.md` § Icons (finding, sizing, coloring, checklist)
- Fix stale Tailwind references in `AGENTS.md`, `app.css`, and CLAUDE.md files
- Update `knip.json` and `check-css-unused/allowlist.go` for UnoCSS-generated classes
diff --git a/AGENTS.md b/AGENTS.md
@@ -66,7 +66,8 @@ Core structure:
   - `analytics-dashboard/` - Private metrics dashboard (SvelteKit + CF Pages)
   - `desktop/` - The Tauri desktop app
     - `test/e2e-linux/` - WebDriverIO + tauri-driver tests (Docker, tests real Tauri app)
-    - `src/` - Svelte frontend. Uses SvelteKit with static adapter. TypeScript strict mode. Tailwind v4.
+    - `src/` - Svelte frontend. Uses SvelteKit with static adapter. TypeScript strict mode. Custom CSS with design
+      tokens.
       - `lib/` - Components
       - `routes/` - Routes
     - `src-tauri/` - Latest Rust, Tauri 2, serde, notify, tokio
@@ -151,6 +152,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`.
 - 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
@@ -15,7 +15,8 @@
     "webdriverio",
     "@crabnebula/tauri-driver",
     "@crabnebula/test-runner-backend",
-    "axe-core"
+    "axe-core",
+    "@iconify-json/lucide"
   ],
   "ignoreExportsUsedInFile": true,
   "project": ["src/**/*.{ts,svelte}"],
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
@@ -39,7 +39,6 @@
     "@crabnebula/tauri-plugin-drag": "^2.1.0",
     "@leeoniya/ufuzzy": "^1.0.19",
     "@logtape/logtape": "^2.0.4",
-    "@lucide/svelte": "^0.577.0",
     "@tauri-apps/api": "^2.10.1",
     "@tauri-apps/plugin-dialog": "^2.7.0",
     "@tauri-apps/plugin-fs": "^2.5.0",
@@ -54,6 +53,7 @@
     "@crabnebula/tauri-driver": "^2.0.9",
     "@crabnebula/test-runner-backend": "^0.2.6",
     "@eslint/js": "^10.0.1",
+    "@iconify-json/lucide": "1.2.96",
     "@playwright/test": "^1.58.2",
     "@srsholmes/tauri-playwright": "^0.2.1",
     "@sveltejs/adapter-static": "^3.0.10",
@@ -62,6 +62,7 @@
     "@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",
     "@wdio/cli": "^9.27.0",
     "@wdio/globals": "^9.27.0",
@@ -90,6 +91,7 @@
     "tsx": "^4.21.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.57.1",
+    "unocss": "66.6.6",
     "vite": "^8.0.2",
     "vitest": "^4.1.0",
     "webdriverio": "^9.27.0"
diff --git a/apps/desktop/src/app.css b/apps/desktop/src/app.css
@@ -2,7 +2,7 @@
  * See /.interface-design/system.md for the design system specification.
  *
  * These variables serve as the single source of truth for all colors, spacing,
- * and typography. They can be used in both scoped CSS and Tailwind classes.
+ * and typography. They are used in scoped CSS throughout the app.
  *
  * Future: Can be modified at runtime for user theme customization. */
 
diff --git a/apps/desktop/src/lib/file-explorer/CLAUDE.md b/apps/desktop/src/lib/file-explorer/CLAUDE.md
@@ -164,8 +164,8 @@ 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. Lucide icon signals severity: ⚠ `TriangleAlert` in warning color for
-  transient, ⊘ `CircleAlert` in error color for serious, no icon for needs-action
+- **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
 - **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
diff --git a/apps/desktop/src/lib/file-explorer/pane/ErrorPane.svelte b/apps/desktop/src/lib/file-explorer/pane/ErrorPane.svelte
@@ -5,7 +5,6 @@
     import { isMacOS } from '$lib/shortcuts/key-capture'
     import Button from '$lib/ui/Button.svelte'
     import { renderErrorMarkdown } from './error-pane-utils'
-    import { TriangleAlert, CircleAlert } from '@lucide/svelte'
 
     interface Props {
         friendly: FriendlyError
@@ -66,13 +65,9 @@
     <div class="content">
         <h2 class="title">
             {#if friendly.category === 'serious'}
-                <span class="title-icon icon-error">
-                    <CircleAlert size={20} strokeWidth={2} />
-                </span>
+                <span class="title-icon icon-error i-lucide:circle-alert" style="width: 20px; height: 20px;"></span>
             {:else if friendly.category === 'transient'}
-                <span class="title-icon icon-warning">
-                    <TriangleAlert size={20} strokeWidth={2} />
-                </span>
+                <span class="title-icon icon-warning i-lucide:triangle-alert" style="width: 20px; height: 20px;"></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,7 +47,7 @@ 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 (Lucide `Hourglass` icon in accent color) appears in `selection-summary` when `isScanning()` is true and
+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.
 
 Filename truncation in `file-info` mode uses a ResizeObserver + throwaway `<span>` measurement for middle truncation
diff --git a/apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte b/apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte
@@ -20,7 +20,6 @@
     } from '../views/full-list-utils'
     import { isScanning } from '$lib/indexing/index-state.svelte'
     import { tooltip } from '$lib/tooltip/tooltip'
-    import { Hourglass } from '@lucide/svelte'
     import type { VolumeSpaceInfo } from '$lib/tauri-commands'
     import { formatDiskSpaceStatus } from '../disk-space-utils'
 
@@ -311,7 +310,7 @@
                     selected{/if}.
                 {#if showSelectionStale}
                     <span class="stale-indicator" use:tooltip={'Updating index — size may change.'}
-                        ><Hourglass size={12} color="var(--color-accent)" /></span
+                        ><span class="i-lucide:hourglass stale-icon"></span></span
                     >
                 {/if}
             {:else if hasFiles}
@@ -325,7 +324,7 @@
                     {pluralize(totalDirs, 'dir', 'dirs')}{/if}.
                 {#if showSelectionStale}
                     <span class="stale-indicator" use:tooltip={'Updating index — size may change.'}
-                        ><Hourglass size={12} color="var(--color-accent)" /></span
+                        ><span class="i-lucide:hourglass stale-icon"></span></span
                     >
                 {/if}
             {/if}
@@ -390,4 +389,11 @@
         vertical-align: middle;
         cursor: help;
     }
+
+    .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
@@ -15,8 +15,8 @@ without DOM performance issues.
   dual-size display helpers: `getDisplaySize()` (picks logical/physical/smart), `hasSizeMismatch()`,
   `buildFileSizeTooltip()`, `buildDirSizeTooltip()`, `buildSelectionSizeTooltip()`
 - **FullList.svelte** – Reads `listing.sizeDisplay` (via `getSizeDisplayMode()`) and `listing.sizeMismatchWarning` (via
-  `getSizeMismatchWarning()`) settings. Uses Lucide `CircleAlert` for size mismatch warnings and `Hourglass` for stale
-  index indicators
+  `getSizeMismatchWarning()`) settings. Uses UnoCSS/Lucide `i-lucide:circle-alert` for size mismatch warnings and
+  `i-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
@@ -39,7 +39,6 @@
     } from '$lib/settings/reactive-settings.svelte'
     import { iconCacheCleared } from '$lib/icon-cache'
     import { tooltip } from '$lib/tooltip/tooltip'
-    import { Hourglass, CircleAlert } from '@lucide/svelte'
     import type { RenameState } from '../rename/rename-state.svelte'
 
     interface Props {
@@ -507,7 +506,7 @@
                                     {/each}
                                     {#if indexing}
                                         <span class="size-stale" use:tooltip={'Updating index — size may change.'}
-                                            ><Hourglass size={12} color="var(--color-accent)" /></span
+                                            ><span class="i-lucide:hourglass icon-indicator"></span></span
                                         >
                                     {/if}
                                     {#if showSizeMismatchWarning && hasSizeMismatch(file.recursiveSize, file.recursivePhysicalSize)}
@@ -531,7 +530,7 @@
                                                     dirTooltipHtml,
                                             }}
                                         >
-                                            <CircleAlert size={12} color="var(--color-accent)" />
+                                            <span class="i-lucide:circle-alert icon-indicator"></span>
                                         </span>
                                     {/if}
                                 {:else if indexing}
@@ -649,6 +648,13 @@
         color: var(--color-text-secondary);
     }
 
+    .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 {
         display: inline-flex;
         align-items: center;
diff --git a/apps/desktop/src/routes/+layout.svelte b/apps/desktop/src/routes/+layout.svelte
@@ -5,6 +5,7 @@
      * 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/uno.config.ts b/apps/desktop/uno.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'unocss'
+import presetIcons from '@unocss/preset-icons'
+
+export default defineConfig({
+  presets: [
+    presetIcons({
+      extraProperties: {
+        display: 'inline-block',
+        'vertical-align': 'middle',
+        'flex-shrink': '0',
+      },
+    }),
+  ],
+})
diff --git a/apps/desktop/vite.config.js b/apps/desktop/vite.config.js
@@ -1,12 +1,11 @@
 import { defineConfig } from 'vite'
 import { sveltekit } from '@sveltejs/kit/vite'
-// Tailwind removed — JIT scanning caused 15s dev startup delay
-// See docs/notes/2026-01-01-debugging-startup-time.md in git history before 2026-02-14
+import UnoCSS from 'unocss/vite'
 
 const host = process.env.TAURI_DEV_HOST
 
 export default defineConfig(async () => ({
-  plugins: [sveltekit()],
+  plugins: [UnoCSS(), sveltekit()],
 
   build: {
     chunkSizeWarningLimit: 1000,
diff --git a/docs/style-guide.md b/docs/style-guide.md
@@ -107,6 +107,84 @@ Only add JSDoc that actually adds info. No tautologies.
 - For the full design system (color tokens, typography scale, spacing, component patterns), see
   [design-system.md](design-system.md).
 
+### 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`).
+
+#### 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`.
+
+#### 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`)
+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
+<!-- Basic usage — inherits parent text color -->
+<span class="i-lucide:triangle-alert"></span>
+
+<!-- With explicit size (use px via scoped CSS, not inline em) -->
+<span class="i-lucide:hourglass my-icon-class"></span>
+```
+
+#### 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:
+
+```svelte
+<span class="i-lucide:circle-alert detail-icon"></span>
+
+<style>
+    .detail-icon {
+        width: 12px;
+        height: 12px;
+    }
+</style>
+```
+
+#### 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
+- **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
+  .my-icon {
+      /* stylelint-disable-next-line declaration-property-value-disallowed-list -- icon indicator, not body text */
+      color: var(--color-accent);
+  }
+  ```
+- **For semantic colors**: Use `var(--color-warning)`, `var(--color-error)`, etc. directly — these aren't restricted
+
+#### 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.
+
+#### 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`
+
 ## Design
 
 See [design-principles.md](design-principles.md) for product design values (UX, accessibility, cancellation, platform
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

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`* See /.interface-design/system.md for the design system specification.`
`3`	`3`	`*`
`4`	`4`	`* These variables serve as the single source of truth for all colors, spacing,`
`5`		`- * and typography. They can be used in both scoped CSS and Tailwind classes.`
	`5`	`+ * and typography. They are used in scoped CSS throughout the app.`
`6`	`6`	`*`
`7`	`7`	`* Future: Can be modified at runtime for user theme customization. */`
`8`	`8`