halo-dark-mode-plugin/.agents/skills/halo-plugin-dev/references/ui-tooling.md

UI Tooling

Recommended third-party tools for plugin frontend development that work well alongside Halo's UI framework.

---

Icons: unplugin-icons + Iconify

unplugin-icons provides on-demand icon imports from Iconify with full IDE support (auto-completion, hover preview).

Installation

pnpm add -D unplugin-icons @iconify/json

For smaller bundles, install only the icon sets you need: pnpm add -D @iconify-json/ri @iconify-json/mdi

Vite Configuration

// ui/vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import Icons from "unplugin-icons/vite";

export default defineConfig({
  plugins: [
    vue(),
    Icons({
      compiler: "vue3",
      autoInstall: true,
    }),
  ],
});

Rsbuild Configuration

// ui/rsbuild.config.mjs
import { defineConfig } from "@rsbuild/core";
import { pluginVue } from "@rsbuild/plugin-vue";
import Icons from "unplugin-icons/rspack";

export default defineConfig({
  plugins: [pluginVue()],
  tools: {
    rspack: {
      plugins: [Icons({ compiler: "vue3" })],
    },
  },
});

Always set compiler: 'vue3' so icons are rendered as Vue components.

Usage in Vue

Import icons directly from the ~icons/ virtual module:

// ui/src/index.ts
import RiImage2Line from '~icons/ri/image-2-line';
import MdiHome from '~icons/mdi/home';

// Use as a regular Vue component
// Common pattern: pass to markRaw() for menu icons
{
  menu: {
    icon: markRaw(RiImage2Line),
  },
}

<script setup lang="ts">
import RiImage2Line from "~icons/ri/image-2-line";
</script>

<template>
  <RiImage2Line class="w-4 h-4" />
</template>

Browse icons at icones.js.org or iconify.design.

---

Atomic CSS: UnoCSS

UnoCSS is an instant atomic CSS engine that provides Tailwind-compatible utilities with zero runtime overhead.

Installation

pnpm add -D unocss @unocss/webpack

Vite Configuration

// ui/vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import UnoCSS from "unocss/vite";

export default defineConfig({
  plugins: [vue(), UnoCSS()],
});

Add the CSS import in your entry file:

// ui/src/index.ts
import "uno.css";

Rsbuild Configuration

// ui/rsbuild.config.mjs
import { defineConfig } from "@rsbuild/core";
import { pluginVue } from "@rsbuild/plugin-vue";
import { UnoCSSRspackPlugin } from "@unocss/webpack/rspack";

export default defineConfig({
  plugins: [pluginVue()],
  tools: {
    rspack: {
      plugins: [UnoCSSRspackPlugin()],
    },
  },
});

Add the CSS import:

// ui/src/index.ts
import "uno.css";

Configuration File

Create ui/uno.config.ts:

import { defineConfig, presetWind3, transformerCompileClass } from "unocss";

export default defineConfig({
  presets: [presetWind3()],
  transformers: [transformerCompileClass()],
});

Usage in Vue

<template>
  <div class="flex items-center gap-2 px-4 py-2 bg-gray-100 rounded">
    <span class="text-sm font-medium text-gray-700">Hello</span>
  </div>
</template>

Use UnoCSS for layout, spacing, and any custom component styling when @halo-dev/components does not provide the needed primitive; use @halo-dev/components for standard business UI.