diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 875626817c..0c880342c7 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -367,6 +367,23 @@ No `plan` param on the 11ty side — that's only used on the pricing table, whic
 
 Every hand-written `<a class="ff-btn ...">` pointing at one of the five destinations has been migrated to these macros — there should be no new ones. A link to a URL outside the five fixed destinations (e.g. `/ai/`) is not part of this system and stays hand-written.
 
+## Icons
+
+**Stock icons:** use `<UIcon name="i-heroicons-x" />` or `<UIcon name="i-lucide-x" />` (`@iconify-json/heroicons`/`@iconify-json/lucide` are already installed). Always `<UIcon>`, never bare `<Icon>` — same component, `UIcon` is just the codebase convention.
+
+`<UIcon>` renders as a masked `<span>`, not an `<svg>` — no intrinsic aspect ratio, so give it an explicit size (`w-6 h-6`) rather than `w-full h-full`.
+
+**FlowFuse's own custom icon art** lives as raw SVGs in `src/_includes/components/icons/*.svg`:
+- **Header/nav:** `nuxt/utils/navIcons.ts` + `NavIcon.vue`, which renders a real inline `<svg>` — needed because the header's CSS targets `<path>` elements directly, which a `<UIcon>` span doesn't have.
+- **Everywhere else:** a one-off SFC under `nuxt/components/icons/` (e.g. `GithubIcon.vue`) with the SVG pasted into the template:
+  ```vue
+  <!-- nuxt/components/icons/GithubIcon.vue -->
+  <template>
+    <svg class="fill-current" viewBox="0 0 24 24"><path d="..." /></svg>
+  </template>
+  ```
+  Nuxt auto-imports it by folder + filename, used directly like any other component: `<IconsGithubIcon class="h-5" />` (see `AppFooter.vue`).
+
 ## Naming conventions
 
 - All slugs: **kebab-case**
diff --git a/nuxt/components/DifferentiatorCards.vue b/nuxt/components/DifferentiatorCards.vue
index 7dd1943c3c..62fe5985c4 100644
--- a/nuxt/components/DifferentiatorCards.vue
+++ b/nuxt/components/DifferentiatorCards.vue
@@ -48,7 +48,7 @@ withDefaults(defineProps<{
       :key="diff.heading"
       class="rounded-lg bg-gradient-to-br from-indigo-50/50 to-red-50/50 p-6 pt-8 flex flex-col gap-4 text-center md:text-left"
     >
-      <Icon :name="diff.icon" class="w-6 h-6 text-indigo-600 mx-auto md:mx-0" />
+      <UIcon :name="diff.icon" class="w-6 h-6 text-indigo-600 mx-auto md:mx-0" />
       <h3 class="text-xl font-semibold text-indigo-600">{{ diff.heading }}</h3>
       <p v-if="diff.lead" class="font-medium leading-snug m-0 -mb-6">{{ diff.lead }}</p>
       <p class="mb-0" :class="descriptionClass" v-html="diff.description" />
diff --git a/nuxt/pages/index.vue b/nuxt/pages/index.vue
index 6414362107..db7096de78 100644
--- a/nuxt/pages/index.vue
+++ b/nuxt/pages/index.vue
@@ -186,7 +186,7 @@ useSchemaOrg([
                   <div class="flex flex-col items-center sm:items-start">
                       <div class="flex flex-col justify-center md:justify-start gap-3 w-full">
                           <div class="w-8 h-8 m-auto sm:m-0 text-red-400">
-                              <Icon :name="section.svgPath" class="w-full h-full" />
+                              <UIcon :name="section.svgPath" class="w-full h-full" />
                           </div>
                           <div class="w-full flex flex-row gap-3 mx-auto md:m-0">
                               <p class="w-full font-semibold md:m-0 text-gray-600">
@@ -256,7 +256,7 @@ useSchemaOrg([
                   </p>
                   <NuxtLink :to="item.linkHref" class="flex items-center gap-1.5 text-blue-600 hover:underline max-md:justify-center mt-3">
                       {{ item.linkText }}
-                      <Icon name="i-heroicons-arrow-long-right-solid" class="w-6 h-6" />
+                      <UIcon name="i-heroicons-arrow-long-right-solid" class="w-6 h-6" />
                   </NuxtLink>
               </div>
           </div>
@@ -330,7 +330,7 @@ useSchemaOrg([
                   <div class="flex flex-col gap-8">
                       <div class="flex items-center gap-3">
                           <div class="w-8 h-8 shrink-0 text-red-400">
-                              <Icon name="i-heroicons-bolt" class="w-full h-full" />
+                              <UIcon name="i-heroicons-bolt" class="w-full h-full" />
                           </div>
                           <p class="text-red-400 text-2xl font-medium m-0">AI accelerates the build</p>
                       </div>
@@ -338,14 +338,14 @@ useSchemaOrg([
                   </div>
                   <a href="/ai/" class="group hover:no-underline flex items-center justify-end gap-1.5 text-indigo-600 mt-6">
                       <span class="group-hover:underline">Learn more about FlowFuse AI</span>
-                      <span class="w-5 h-5 shrink-0 flex items-center [&>svg]:w-full [&>svg]:h-full"><Icon name="i-heroicons-arrow-long-right-solid" /></span>
+                      <span class="w-5 h-5 shrink-0 flex items-center [&>svg]:w-full [&>svg]:h-full"><UIcon name="i-heroicons-arrow-long-right-solid" /></span>
                   </a>
               </div>
               <div class="border-2 border-red-200 rounded-lg p-6 flex flex-col justify-between bg-gradient-to-tl from-red-50/50 to-transparent">
                   <div class="flex flex-col gap-8">
                       <div class="flex items-center gap-3">
                           <div class="w-8 h-8 shrink-0 text-red-400">
-                              <Icon name="i-heroicons-shield-check" class="w-full h-full" />
+                              <UIcon name="i-heroicons-shield-check" class="w-full h-full" />
                           </div>
                           <p class="text-red-400 text-2xl font-medium m-0">FlowFuse governs the result</p>
                       </div>
@@ -359,7 +359,7 @@ useSchemaOrg([
                        PostHog as this one-off style. -->
                   <NuxtLink to="/book-demo/" class="group hover:no-underline flex items-center justify-end gap-1.5 text-indigo-600 mt-6" @click="capture('cta-book-demo', { position: 'ai', variant: 'text' })">
                       <span class="group-hover:underline">Book a demo</span>
-                      <span class="w-5 h-5 shrink-0 flex items-center [&>svg]:w-full [&>svg]:h-full"><Icon name="i-heroicons-arrow-long-right-solid" /></span>
+                      <span class="w-5 h-5 shrink-0 flex items-center [&>svg]:w-full [&>svg]:h-full"><UIcon name="i-heroicons-arrow-long-right-solid" /></span>
                   </NuxtLink>
               </div>
           </div>