diff --git a/apps/icons-gallery/README.md b/apps/icons-gallery/README.md
index a68779a6..285b5168 100644
--- a/apps/icons-gallery/README.md
+++ b/apps/icons-gallery/README.md
@@ -4,6 +4,7 @@
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Vue 3](https://img.shields.io/badge/Vue-3.x-4FC08D?logo=vue.js)](https://vuejs.org/)
+[![Vite](https://img.shields.io/badge/Vite-6.x-646CFF?logo=vite)](https://vitejs.dev/)
 
 ---
 
@@ -28,19 +29,19 @@ The application is deployed on **Azion's Edge Platform** for low-latency global
 
 | Layer | Technology | Purpose |
 |-------|------------|---------|
-| **Framework** | Vue 3 (Composition API) | Reactive UI components |
+| **Framework** | Vue 3 (Composition API, `<script setup>`) | Reactive UI components |
+| **Build** | Vite | Dev server, bundling, preview |
 | **Styling** | Tailwind CSS | Utility-first CSS framework |
-| **Icons** | @aziontech/icons | Icon font package (workspace dependency) |
-| **Color Picker** | vue3-colorpicker | Color selection widget |
-| **Build** | Vue CLI | Development server and bundling |
-| **Testing** | Jest + Vue Test Utils | Unit testing |
+| **Icons** | `@aziontech/icons` | Icon font + catalog (workspace dependency) |
+| **Color Picker** | `vue3-colorpicker` | Color selection widget |
+| **Testing** | Vitest + jsdom | Unit testing |
 | **Deployment** | Azion Edge Platform | Global edge deployment |
 
 ### Application Flow
 
 ```mermaid
 flowchart TD
-    A[User visits gallery] --> B[Load icons.json]
+    A[User visits gallery] --> B[Import catalog from @aziontech/icons]
     B --> C[Render icon grid]
     C --> D{User interaction}
     D -->|Search| E[Filter icons by name/keywords]
@@ -69,9 +70,9 @@ flowchart TB
         H[Size Slider] --> I[Update size state]
         J[Theme Toggle] --> K[Dark/Light mode]
     end
-    L[icons.json] --> M[Icon metadata]
+    L["@aziontech/icons/catalog"] --> M[Icon metadata]
     M --> App.vue
-    N[@aziontech/icons] --> O[Icon fonts CSS]
+    N["@aziontech/icons"] --> O[Icon fonts CSS]
     O --> App.vue
 ```
 
@@ -82,32 +83,31 @@ flowchart TB
 ```
 apps/icons-gallery/
 ├── public/
-│   ├── favicon.ico          # Site favicon
-│   └── index.html           # HTML template
+│   └── favicon.ico          # Site favicon
 ├── src/
 │   ├── components/
 │   │   ├── IconCard.vue     # Individual icon display card
 │   │   └── SearchBar.vue    # Search input with filtering
 │   ├── App.vue              # Main application component
-│   ├── icons.json           # Icon metadata (name, class, keywords)
 │   ├── main.css             # Global styles and Tailwind imports
 │   ├── main.js              # Application entry point
 │   └── theme.js             # Dark/light theme management
 ├── tests/
 │   └── unit/
+│       ├── __mocks__/
 │       ├── iconDownload.spec.js  # Download functionality tests
-│       └── jest.setup.js         # Jest configuration
-├── azion/                    # Azion deployment config
-│   ├── args.json            # Build arguments
+│       └── jest.setup.js         # Vitest setup file (legacy filename)
+├── azion/
+│   ├── args.json            # Build arguments for Azion CLI
 │   └── azion.json           # Edge application manifest
 ├── azion.config.cjs         # Azion project configuration
-├── babel.config.js          # Babel configuration
-├── jest.config.js           # Jest test configuration
+├── index.html               # Vite HTML entry point
 ├── jsconfig.json            # JavaScript/IDE configuration
 ├── package.json             # Dependencies and scripts
 ├── postcss.config.js        # PostCSS configuration
 ├── tailwind.config.js       # Tailwind CSS configuration
-└── vue.config.js            # Vue CLI configuration
+├── vite.config.js           # Vite dev/build configuration
+└── vitest.config.js         # Vitest test configuration
 ```
 
 ### Key Files Explained
@@ -117,17 +117,20 @@ apps/icons-gallery/
 | [`src/App.vue`](src/App.vue) | Main component containing icon grid, controls, and state management |
 | [`src/components/IconCard.vue`](src/components/IconCard.vue) | Renders individual icon with hover actions (copy code, copy image, download) |
 | [`src/components/SearchBar.vue`](src/components/SearchBar.vue) | Search input with real-time filtering |
-| [`src/icons.json`](src/icons.json) | Metadata for all icons including name, class, and searchable keywords |
 | [`src/theme.js`](src/theme.js) | Theme initialization and toggle functionality |
+| [`vite.config.js`](vite.config.js) | Vite dev server (port 3333) and build config |
+| [`vitest.config.js`](vitest.config.js) | Vitest config (jsdom environment, setup file) |
 | [`azion.config.cjs`](azion.config.cjs) | Edge deployment configuration with caching rules |
 
+Icon metadata is **not** stored locally — it is imported at runtime from `@aziontech/icons/catalog` (resolved to `packages/icons/dist/catalog.json`).
+
 ---
 
 ## Getting Started
 
 ### Prerequisites
 
-- Node.js 18+ 
+- Node.js 18+
 - pnpm (workspace package manager)
 
 ### Installation
@@ -137,77 +140,89 @@ This app is part of a pnpm monorepo. From the workspace root:
 ```bash
 # Install all workspace dependencies
 pnpm install
-
-# Or install only for this app
-cd apps/icons-gallery
-pnpm install
 ```
 
 ### Development Server
 
 ```bash
-# Start development server on port 3333
+# From the app directory
 pnpm serve
 
 # Or from workspace root
 pnpm --filter icons-gallery serve
 ```
 
-The app will be available at `http://localhost:3333` with hot module replacement enabled.
+The app will be available at `http://localhost:3333` with HMR enabled (configured in `vite.config.js`).
 
 ### Build for Production
 
 ```bash
-# Build for Vue CLI output
+# Standard Vite build → ./dist
 pnpm build
 
-# Build for Azion Edge deployment
+# Build optimized for Azion Edge Platform
 pnpm build:azion
 ```
 
-The production build outputs to `dist/` directory.
-
 ---
 
 ## Available Scripts
 
 | Script | Description |
 |--------|-------------|
-| `pnpm serve` | Start development server with HMR on port 3333 |
-| `pnpm build` | Build production bundle via Vue CLI |
+| `pnpm serve` | Start Vite dev server with HMR on port 3333 |
+| `pnpm build` | Build production bundle via Vite |
 | `pnpm build:azion` | Build optimized for Azion Edge Platform |
-| `pnpm test:unit` | Run Jest unit tests |
-| `pnpm lint` | Run ESLint on source files |
-| `pnpm format` | Format code with Prettier |
 | `pnpm preview` | Preview production build with Vite |
-| `pnpm publish` | Deploy to Azion Edge Platform (local mode) |
+| `pnpm test:unit` | Run Vitest unit tests once |
+| `pnpm test:unit:watch` | Run Vitest in watch mode |
+| `pnpm lint` | Run ESLint with autofix |
+| `pnpm format` | Format `src/` with Prettier |
+| `pnpm publish` | Deploy to Azion Edge Platform (`azion deploy --local --debug`) |
 
 ---
 
 ## Configuration
 
-### Vue CLI (`vue.config.js`)
+### Vite (`vite.config.js`)
 
 ```javascript
-module.exports = {
-  publicPath: '/',
-  devServer: {
-    port: 3333,           // Development server port
-    historyApiFallback: true,  // SPA routing support
-    hot: true,            // Hot module replacement
-    open: true            // Auto-open browser
+import vue from '@vitejs/plugin-vue'
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
+  },
+  server: { port: 3333, open: true }
+})
+```
+
+### Vitest (`vitest.config.js`)
+
+```javascript
+import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./tests/unit/jest.setup.js'],
+    include: ['tests/unit/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    globals: true
   }
-}
+})
 ```
 
 ### Tailwind CSS (`tailwind.config.js`)
 
-Extends the root workspace Tailwind configuration:
-
 ```javascript
 module.exports = {
-  content: ['./src/**/*.{vue,js,ts}'],
-  // Uses workspace-level theme extensions
+  content: ['./index.html', './src/**/*.{vue,js,ts}']
+  // Theme extensions defined inline.
 }
 ```
 
@@ -224,9 +239,9 @@ Configures edge deployment with:
 
 ## Icon Showcase
 
-The gallery displays icons from two font families:
+The gallery displays icons from two font families. Counts below match the current `@aziontech/icons/catalog` snapshot:
 
-### Azionicons (`ai`) — 87 Icons
+### Azionicons (`ai`) — 88 icons
 
 Azion-specific product and platform icons organized by category:
 
@@ -274,7 +289,7 @@ Azion-specific product and platform icons organized by category:
 | Ask Azion | `ai ai-ask-azion` | AI assistant |
 | Marketplace | `ai ai-marketplace` | Marketplace services |
 
-### PrimeIcons (`pi`) — 315+ Icons
+### PrimeIcons (`pi`) — 314 icons
 
 General-purpose UI icons from the PrimeIcons library. Some commonly used icons:
 
@@ -318,24 +333,14 @@ General-purpose UI icons from the PrimeIcons library. Some commonly used icons:
 
 ## Adding New Icons
 
-When new icons are added to `@aziontech/icons`, update the gallery:
+The gallery has no local icon list — it consumes the catalog generated by `@aziontech/icons`. To make new icons show up:
 
-1. **Rebuild the icons package**:
+1. Add the icon to `packages/icons` (SVG sources + catalog entry as the package's build expects).
+2. Rebuild the icons package:
    ```bash
-   cd packages/icons
-   pnpm build
-   ```
-
-2. **Update `src/icons.json`** with the new icon entry:
-   ```json
-   {
-     "icon": "ai ai-new-icon",
-     "keywords": "new, icon, keywords",
-     "name": "ai-new-icon"
-   }
+   pnpm --filter @aziontech/icons build
    ```
-
-3. **Verify** the icon displays correctly in the gallery.
+3. Restart the gallery dev server (`pnpm serve`) — the new icon appears automatically once `packages/icons/dist/catalog.json` is regenerated.
 
 ---
 
@@ -343,8 +348,6 @@ When new icons are added to `@aziontech/icons`, update the gallery:
 
 ### Azion Edge Platform
 
-The gallery is designed for deployment on Azion's Edge Platform:
-
 ```bash
 # Build for edge deployment
 pnpm build:azion
@@ -353,6 +356,8 @@ pnpm build:azion
 pnpm publish
 ```
 
+> The `publish` script in this app does **not** publish to npm — it calls `azion deploy --local --debug`. The name is preserved for legacy automation reasons.
+
 #### Deployment Architecture
 
 ```mermaid
@@ -376,24 +381,21 @@ The deployment configuration includes:
 
 ## Testing
 
-### Unit Tests
-
 ```bash
-# Run all unit tests
+# Run all unit tests once
 pnpm test:unit
 
-# Run with coverage
-pnpm test:unit -- --coverage
+# Watch mode
+pnpm test:unit:watch
 ```
 
-Tests are located in `tests/unit/` and use Jest with Vue Test Utils.
+Tests live in `tests/unit/` and run on **Vitest** with the **jsdom** environment. The setup file is `tests/unit/jest.setup.js` (filename kept for git-history continuity after the Jest → Vitest migration).
 
-### Test Coverage
+### Current Coverage
 
 | Module | Tests |
 |--------|-------|
-| Icon Download | PNG/SVG download functionality |
-| Components | Vue component rendering |
+| Icon Download | PNG/SVG download helpers (`iconDownload.spec.js`) |
 
 ---
 
@@ -426,7 +428,7 @@ Tests are located in `tests/unit/` and use Jest with Vue Test Utils.
 
 | Package | Description |
 |---------|-------------|
-| [@aziontech/icons](../../packages/icons/README.md) | Icon font library (azionicons + primeicons) |
+| [`@aziontech/icons`](../../packages/icons/README.md) | Icon font library (azionicons + primeicons) |
 
 ---