@stackonward/cli 1.5.3 → 1.6.0

package/dist/resources/components/registry.json

@@ -160,8 +160,16 @@
         "target": "app/assets/icons/brand/.gitkeep"
       },
       {
-        "path": "site-source/app/assets/icons/common/.gitkeep",
-        "target": "app/assets/icons/common/.gitkeep"
+        "path": "site-source/app/assets/icons/brand/android.svg",
+        "target": "app/assets/icons/brand/android.svg"
+      },
+      {
+        "path": "site-source/app/assets/icons/brand/apple.svg",
+        "target": "app/assets/icons/brand/apple.svg"
+      },
+      {
+        "path": "site-source/app/assets/icons/brand/whatsapp.svg",
+        "target": "app/assets/icons/brand/whatsapp.svg"
       },
       {
         "path": "site-source/app/components/app/Header.vue",
@@ -176,29 +184,81 @@
         "target": "app/components/app/Sidebar.vue"
       },
       {
-        "path": "site-source/app/components/site/BackToTop.vue",
-        "target": "app/components/site/BackToTop.vue"
+        "path": "site-source/app/components/checkout/Status.vue",
+        "target": "app/components/checkout/Status.vue"
+      },
+      {
+        "path": "site-source/app/components/checkout/Summary.vue",
+        "target": "app/components/checkout/Summary.vue"
+      },
+      {
+        "path": "site-source/app/components/consent/Banner.vue",
+        "target": "app/components/consent/Banner.vue"
+      },
+      {
+        "path": "site-source/app/components/consent/Settings.vue",
+        "target": "app/components/consent/Settings.vue"
       },
       {
         "path": "site-source/app/components/content/Article.vue",
         "target": "app/components/content/Article.vue"
       },
+      {
+        "path": "site-source/app/components/content/CallToAction.vue",
+        "target": "app/components/content/CallToAction.vue"
+      },
+      {
+        "path": "site-source/app/components/content/Card.vue",
+        "target": "app/components/content/Card.vue"
+      },
+      {
+        "path": "site-source/app/components/content/Compatibility.vue",
+        "target": "app/components/content/Compatibility.vue"
+      },
+      {
+        "path": "site-source/app/components/content/Document.vue",
+        "target": "app/components/content/Document.vue"
+      },
+      {
+        "path": "site-source/app/components/content/Faq.vue",
+        "target": "app/components/content/Faq.vue"
+      },
+      {
+        "path": "site-source/app/components/content/Features.vue",
+        "target": "app/components/content/Features.vue"
+      },
       {
         "path": "site-source/app/components/content/List.vue",
         "target": "app/components/content/List.vue"
       },
       {
-        "path": "site-source/app/components/consent/Settings.vue",
-        "target": "app/components/consent/Settings.vue"
+        "path": "site-source/app/components/content/Reviews.vue",
+        "target": "app/components/content/Reviews.vue"
       },
       {
-        "path": "site-source/app/components/consent/Banner.vue",
-        "target": "app/components/consent/Banner.vue"
+        "path": "site-source/app/components/countdown/Timer.vue",
+        "target": "app/components/countdown/Timer.vue"
+      },
+      {
+        "path": "site-source/app/components/feedback/Toast.vue",
+        "target": "app/components/feedback/Toast.vue"
+      },
+      {
+        "path": "site-source/app/components/google/SignInButton.vue",
+        "target": "app/components/google/SignInButton.vue"
       },
       {
         "path": "site-source/app/components/locale/Menu.vue",
         "target": "app/components/locale/Menu.vue"
       },
+      {
+        "path": "site-source/app/components/site/BackToTop.vue",
+        "target": "app/components/site/BackToTop.vue"
+      },
+      {
+        "path": "site-source/app/components/site/Brand.vue",
+        "target": "app/components/site/Brand.vue"
+      },
       {
         "path": "site-source/app/components/site/Footer.vue",
         "target": "app/components/site/Footer.vue"
@@ -212,16 +272,12 @@
         "target": "app/components/site/Shell.vue"
       },
       {
-        "path": "site-source/app/components/site/Brand.vue",
-        "target": "app/components/site/Brand.vue"
-      },
-      {
-        "path": "site-source/app/components/content/Document.vue",
-        "target": "app/components/content/Document.vue"
+        "path": "site-source/app/components/steps/Progress.vue",
+        "target": "app/components/steps/Progress.vue"
       },
       {
-        "path": "site-source/app/components/feedback/Toast.vue",
-        "target": "app/components/feedback/Toast.vue"
+        "path": "site-source/app/components/steps/Showcase.vue",
+        "target": "app/components/steps/Showcase.vue"
       },
       {
         "path": "site-source/app/components/theme/Menu.vue",
@@ -235,6 +291,22 @@
         "path": "site-source/app/components/ui/GradientBorder.vue",
         "target": "app/components/ui/GradientBorder.vue"
       },
+      {
+        "path": "site-source/app/components/ui/Icon.vue",
+        "target": "app/components/ui/Icon.vue"
+      },
+      {
+        "path": "site-source/app/components/ui/Image.vue",
+        "target": "app/components/ui/Image.vue"
+      },
+      {
+        "path": "site-source/app/components/ui/InfiniteScroll.vue",
+        "target": "app/components/ui/InfiniteScroll.vue"
+      },
+      {
+        "path": "site-source/app/components/ui/Marquee.vue",
+        "target": "app/components/ui/Marquee.vue"
+      },
       {
         "path": "site-source/app/components/ui/Modal.vue",
         "target": "app/components/ui/Modal.vue"
@@ -248,20 +320,12 @@
         "target": "app/components/ui/Text.vue"
       },
       {
-        "path": "site-source/app/components/checkout/Status.vue",
-        "target": "app/components/checkout/Status.vue"
+        "path": "site-source/app/components/ui/Video.vue",
+        "target": "app/components/ui/Video.vue"
       },
       {
-        "path": "site-source/app/components/checkout/Summary.vue",
-        "target": "app/components/checkout/Summary.vue"
-      },
-      {
-        "path": "site-source/app/components/google/SignInButton.vue",
-        "target": "app/components/google/SignInButton.vue"
-      },
-      {
-        "path": "site-source/app/components/ui/InfiniteScroll.vue",
-        "target": "app/components/ui/InfiniteScroll.vue"
+        "path": "site-source/app/components/whatsapp/Chat.vue",
+        "target": "app/components/whatsapp/Chat.vue"
       },
       {
         "path": "site-source/app/components/youtube/Embed.vue",
@@ -275,6 +339,10 @@
         "path": "site-source/app/composables/useConsent.ts",
         "target": "app/composables/useConsent.ts"
       },
+      {
+        "path": "site-source/app/composables/useFloatingBottomStack.ts",
+        "target": "app/composables/useFloatingBottomStack.ts"
+      },
       {
         "path": "site-source/app/composables/useGoogleIdentity.ts",
         "target": "app/composables/useGoogleIdentity.ts"
@@ -295,6 +363,14 @@
         "path": "site-source/app/composables/useToasts.ts",
         "target": "app/composables/useToasts.ts"
       },
+      {
+        "path": "site-source/app/consent/types.ts",
+        "target": "app/consent/types.ts"
+      },
+      {
+        "path": "site-source/app/content/types.ts",
+        "target": "app/content/types.ts"
+      },
       {
         "path": "site-source/app/layouts/app.vue",
         "target": "app/layouts/app.vue"
@@ -303,6 +379,10 @@
         "path": "site-source/app/layouts/default.vue",
         "target": "app/layouts/default.vue"
       },
+      {
+        "path": "site-source/app/navigation/types.ts",
+        "target": "app/navigation/types.ts"
+      },
       {
         "path": "site-source/app/plugins/consent.ts",
         "target": "app/plugins/consent.ts"
@@ -311,6 +391,10 @@
         "path": "site-source/app/plugins/google-identity.client.ts",
         "target": "app/plugins/google-identity.client.ts"
       },
+      {
+        "path": "site-source/app/site/config.ts",
+        "target": "app/site/config.ts"
+      },
       {
         "path": "site-source/app/theme/accordion.ts",
         "target": "app/theme/accordion.ts"
@@ -331,6 +415,18 @@
         "path": "site-source/app/theme/checkbox.ts",
         "target": "app/theme/checkbox.ts"
       },
+      {
+        "path": "site-source/app/theme/drawer.ts",
+        "target": "app/theme/drawer.ts"
+      },
+      {
+        "path": "site-source/app/theme/form-field.ts",
+        "target": "app/theme/form-field.ts"
+      },
+      {
+        "path": "site-source/app/theme/icon.ts",
+        "target": "app/theme/icon.ts"
+      },
       {
         "path": "site-source/app/theme/index.ts",
         "target": "app/theme/index.ts"
@@ -347,6 +443,10 @@
         "path": "site-source/app/theme/pagination.ts",
         "target": "app/theme/pagination.ts"
       },
+      {
+        "path": "site-source/app/theme/radio-group.ts",
+        "target": "app/theme/radio-group.ts"
+      },
       {
         "path": "site-source/app/theme/select.ts",
         "target": "app/theme/select.ts"
@@ -355,6 +455,10 @@
         "path": "site-source/app/theme/stepper.ts",
         "target": "app/theme/stepper.ts"
       },
+      {
+        "path": "site-source/app/theme/textarea.ts",
+        "target": "app/theme/textarea.ts"
+      },
       {
         "path": "site-source/app/theme/toast.ts",
         "target": "app/theme/toast.ts"
@@ -362,25 +466,9 @@
       {
         "path": "site-source/app/theme/tooltip.ts",
         "target": "app/theme/tooltip.ts"
-      },
-      {
-        "path": "site-source/app/consent/types.ts",
-        "target": "app/consent/types.ts"
-      },
-      {
-        "path": "site-source/app/content/types.ts",
-        "target": "app/content/types.ts"
-      },
-      {
-        "path": "site-source/app/navigation/types.ts",
-        "target": "app/navigation/types.ts"
-      },
-      {
-        "path": "site-source/app/site/config.ts",
-        "target": "app/site/config.ts"
       }
     ],
-    "dependencies": [],
+    "dependencies": ["@stackonward/composables"],
     "devDependencies": [],
     "registryDependencies": [],
     "framework": "nuxt",

package/dist/resources/components/vue/ui/BottomSheet.vue

@@ -63,7 +63,11 @@ onBeforeUnmount(() => {
   <Teleport to="body">
     <Transition name="bottom-sheet-fade">
       <div v-if="modelValue" class="bottom-sheet" role="presentation">
-        <button class="bottom-sheet__overlay" aria-label="Close sheet" @click="handleOverlayClick" />
+        <button
+          class="bottom-sheet__overlay"
+          aria-label="Close sheet"
+          @click="handleOverlayClick"
+        />
         <section class="bottom-sheet__panel" role="dialog" aria-modal="true" :aria-label="title">
           <div v-if="showHandle" class="bottom-sheet__handle" aria-hidden="true" />
           <header v-if="title || description || $slots.header" class="bottom-sheet__header">

package/dist/resources/components/vue/ui/ScrollArea.vue

@@ -86,7 +86,8 @@ function pointerUp(event: PointerEvent): void {
 defineExpose({
   scrollTo,
   scrollToTop: (smooth = true) => scrollTo(position().x, 0, smooth),
-  scrollToBottom: (smooth = true) => scrollTo(position().x, viewport.value?.scrollHeight ?? 0, smooth),
+  scrollToBottom: (smooth = true) =>
+    scrollTo(position().x, viewport.value?.scrollHeight ?? 0, smooth),
   getScrollPosition: position,
 });
 </script>

package/dist/resources/registry.json

@@ -21,7 +21,7 @@
     "name": "@stackonward/cli",
     "description": "StackOnward project and resource CLI",
     "type": "npm",
-    "version": "^1.5.3"
+    "version": "^1.6.0"
   },
   "@stackonward/cms-client": {
     "name": "@stackonward/cms-client",

package/dist/resources/templates/base/.claude/docs/architecture-template.md

@@ -389,8 +389,9 @@ Adding features to an existing module or making significant changes. Does not re
 ## 3. Database Changes
 
 For each new/modified field:
+
 | Column | Type | Nullable | Default | Comment | Table |
-|--------|------|----------|---------|---------|-------|
+| ------ | ---- | -------- | ------- | ------- | ----- |
 
 Migration SQL:
 

package/dist/resources/templates/base/AGENTS.md

@@ -47,6 +47,12 @@ The selected stack has complete coding rules in `.claude/docs/stack.md`. Shared
 
 **Read the selected stack and applicable nested `CLAUDE.md` before writing code.**
 
+## Visual Design Standards (CRITICAL)
+
+For a stack with a visual interface, **MUST** read the design standard identified by `.claude/docs/stack.md` before choosing icons, colors, sizing or component overrides. Use that stack's installed component system, token owner and asset conventions. Icon artwork, accessible labels and interactive target size are separate responsibilities; local size changes must use the existing component contract.
+
+**FORBIDDEN**: inventing a second icon library or theme implementation for an existing capability. Non-visual stacks do not acquire UI dependencies or a required design document from this rule.
+
 ## Technology Stack and Environment
 
 Read `package.json`, `.env.example`, configuration consumers and `.claude/docs/stack.md` before changing dependencies or environment variables. A sample variable does not prove that runtime code reads it. Nuxt uses `pnpm dev` / `pnpm preview`; MCP uses `pnpm start:stdio` after build. Never put private credentials in Nuxt public configuration or MCP tool output.
@@ -423,6 +429,7 @@ Durable standards belong in `.claude/docs/`; concrete designs and evidence belon
 
 - [ ] Read changed owners, nested rules, dependencies and direct consumers.
 - [ ] Contracts, enum authority, configuration and lifecycle are consistent.
+- [ ] Visual changes follow the installed stack design standard, token/component owner and accessibility contract.
 - [ ] Relevant success, validation, authorization and recovery behavior is verified.
 - [ ] Declared stack checks pass; unavailable checks are reported accurately.
 - [ ] No secrets, dead imports or deferred production code enter the diff.

package/dist/resources/templates/base/CLAUDE.md

@@ -47,6 +47,12 @@ The selected stack has complete coding rules in `.claude/docs/stack.md`. Shared
 
 **Read the selected stack and applicable nested `CLAUDE.md` before writing code.**
 
+## Visual Design Standards (CRITICAL)
+
+For a stack with a visual interface, **MUST** read the design standard identified by `.claude/docs/stack.md` before choosing icons, colors, sizing or component overrides. Use that stack's installed component system, token owner and asset conventions. Icon artwork, accessible labels and interactive target size are separate responsibilities; local size changes must use the existing component contract.
+
+**FORBIDDEN**: inventing a second icon library or theme implementation for an existing capability. Non-visual stacks do not acquire UI dependencies or a required design document from this rule.
+
 ## Technology Stack and Environment
 
 Read `package.json`, `.env.example`, configuration consumers and `.claude/docs/stack.md` before changing dependencies or environment variables. A sample variable does not prove that runtime code reads it. Nuxt uses `pnpm dev` / `pnpm preview`; MCP uses `pnpm start:stdio` after build. Never put private credentials in Nuxt public configuration or MCP tool output.
@@ -423,6 +429,7 @@ Durable standards belong in `.claude/docs/`; concrete designs and evidence belon
 
 - [ ] Read changed owners, nested rules, dependencies and direct consumers.
 - [ ] Contracts, enum authority, configuration and lifecycle are consistent.
+- [ ] Visual changes follow the installed stack design standard, token/component owner and accessibility contract.
 - [ ] Relevant success, validation, authorization and recovery behavior is verified.
 - [ ] Declared stack checks pass; unavailable checks are reported accurately.
 - [ ] No secrets, dead imports or deferred production code enter the diff.

package/dist/resources/templates/nuxt/.claude/docs/stack.md

@@ -132,6 +132,7 @@ Nuxt component directories remain namespaces. `components/site/Header.vue` is `H
 | NX-H3  | Per-page hardcoded theme overrides                        | Existing token/theme owner                              |
 | NX-H4  | Direct DOM mutation for reactive UI                       | Vue refs and state                                      |
 | NX-H5  | Global component CSS leaking across routes                | Utility classes or scoped owner styles                  |
+| NX-H6  | Parallel icon libraries/renderers or global SVG overrides | UiIcon, local Lucide, Nuxt UI slots and DESIGN.md       |
 | NX-E1  | Business enum metadata copied into pages                  | Actual backend metadata/generated contract              |
 | NX-E2  | Invented `useEnum` endpoint                               | Use installed owner and declared contract               |
 | NX-M1  | Mixed locale persistence formats                          | Explicit locale boundary mapping                        |
@@ -371,6 +372,18 @@ const emit = defineEmits<{ submit: [] }>();
 
 Use Tailwind utilities and theme tokens. Scoped CSS is for behavior that utilities cannot express cleanly. Dark/light modes must use the same semantic tokens; never fix one page with a hardcoded light background that breaks dark mode.
 
+### Icon Design Contract
+
+**MUST** read [DESIGN.md](../../DESIGN.md) for icon geometry, the size scale, semantic colors and acceptance. The installed system uses local Lucide functional icons and a separate `brand` collection. `UiIcon` owns standalone `name`, `size?: string | number` and `label?: string`; Nuxt UI controls retain their internal icon slots and use the same provider.
+
+The ordinary default is 20px through `app/theme/icon.ts` and `--site-icon-md`. Choose one `size-icon-*` utility or explicit `size` value when the caller requires another size. Preserve source geometry and proportional strokes. Functional colors inherit semantic tokens; brand proportions and identity colors remain asset-owned.
+
+✅ `<UiIcon name="i-lucide-search" />` uses the shared default; `<UiIcon name="i-lucide-search" class="size-icon-sm" />` selects a local scale level.
+
+❌ A second icon wrapper, handwritten duplicate SVG, mixed functional family, competing `size`/size class or global `svg` style bypasses the design owner.
+
+Icon-only controls retain at least 44 × 44px targets and accessible names on the button/link. Decorative icons omit `label`; standalone meaning supplies a localized `label`. Do not communicate status only through color. Keep `fallbackToApi: false`, register local brand assets in `nuxt.config.ts` and verify missing icon names against the installed collection.
+
 ### Complete Create/Edit Form, Recovery and Close Lifecycle
 
 The component below consumes the three owners defined in section VI. It includes a real query-driven list, create/edit entry, typed validation, mutation submission, post-save refresh and failure recovery. All types/functions it imports are defined above or exported by the installed framework. Nuxt UI's `validate` callback avoids adding an uninstalled schema library to this template.
@@ -664,7 +677,7 @@ Read [Architecture](architecture.md), [Security and Lifecycle](security-lifecycl
 - [ ] Private configuration never enters public payloads.
 - [ ] Every visible action maps to a real implementation and error path.
 - [ ] All applicable NX-S/A/T/C/H/E/M/P/U rules are checked.
-- [ ] Design coverage includes children, overlays and loading/empty/error/forbidden states.
+- [ ] Design coverage includes children, overlays, icon sizes/names/targets and loading/empty/error/forbidden states.
 - [ ] `pnpm typecheck` and `pnpm build` pass for code/contract changes.
 - [ ] Browser and network evidence proves the touched interactions.
 - [ ] No uninstalled lint/test/authorization capability is claimed.

package/dist/resources/templates/nuxt/DESIGN.md

@@ -0,0 +1,146 @@
+# Nuxt Design Standard
+
+This document defines the visual contract for the application-owned Nuxt UI foundation. Read it with the [Nuxt Engineering Standard](.claude/docs/stack.md) before changing icons, controls or theme defaults. Application branding remains in its own assets and semantic color tokens.
+
+## Design Decisions
+
+| Decision               | Primary-source pattern                                                                                                                             | Application choice                                                                         | Reason                                                                        |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Functional icon family | [Lucide specification](https://lucide.dev/contribute/icons/specification) defines a consistent canvas, stroke and visual weight.                   | Use the installed Lucide collection with its original geometry.                            | One family keeps related actions visually coherent.                           |
+| Size hierarchy         | [Carbon icon usage](https://carbondesignsystem.com/elements/icons/usage/) uses a small, consistent scale and separates artwork from touch targets. | Use 16/20/24/32px for interface icons; 20px is the ordinary default.                       | Central sizing supports both compact and prominent contexts.                  |
+| Accessible meaning     | [Lucide accessibility](https://lucide.dev/how-to/accessibility) distinguishes decorative, standalone and interactive icons.                        | Hide decoration; label standalone meaning or the interactive control that owns an action.  | Assistive technology announces each meaning once.                             |
+| Rendering and delivery | [Nuxt Icon](https://nuxt.com/modules/icon) supports application defaults, local collections and SVG rendering.                                     | Reuse Nuxt Icon through `UiIcon`, bundle Lucide locally and disable external API fallback. | SSR and client rendering use the same locally owned assets and configuration. |
+
+## Ownership
+
+| Owner                                            | Contract                                                                                    |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `app/assets/css/site-shell.css`                  | `--site-icon-*` size tokens, `size-icon-*` Tailwind aliases and semantic colors             |
+| `app/theme/icon.ts`                              | Nuxt Icon defaults: 20px token, SVG mode, non-shrinking alignment and decorative attributes |
+| `app/app.config.ts`                              | Composes `icon` defaults and the Nuxt UI theme                                              |
+| `app/components/ui/Icon.vue`                     | Typed `name`, `size` and accessible `label` adapter                                         |
+| `app/theme/button.ts`, `input.ts`, `checkbox.ts` | Internal icon slots and the control's geometry                                              |
+| `nuxt.config.ts`                                 | Locally bundled `lucide`, `brand` SVG collection and `fallbackToApi: false`                 |
+| `app/assets/icons/brand/`                        | Reviewed third-party identity assets                                                        |
+
+Registry-installed source belongs to this application. **MUST** change the owning token or component when a repeated pattern changes. A one-location size choice stays at its caller. **FORBIDDEN**: adding a second icon component, runtime registry, icon font or icon library for an existing Lucide capability.
+
+## Functional Icon Geometry
+
+Functional icons **MUST** use `i-lucide-*` names from the installed collection. Their design uses a square 24 × 24 viewBox, 2-unit centered strokes, rounded open-path caps and rounded joins. Preserve the family's edge clearance, internal spacing and visual balance; identical CSS dimensions alone do not establish equal optical weight. These constraints follow the [Lucide specification](https://lucide.dev/contribute/icons/specification).
+
+Keep the original aspect ratio and geometry when rendering at another size. Strokes scale proportionally with the viewBox; the 2-unit source stroke is not a fixed 2 CSS-pixel stroke at every display size. **FORBIDDEN**: per-location stroke-width overrides, non-uniform scaling, padding embedded in duplicate SVGs or arbitrary `translate` corrections. Align icons and text with the control's flex/grid layout. A family-level optical issue is resolved in the asset or by selecting a clearer existing icon.
+
+Use the same icon for the same action across routes. Distinct actions must not share an ambiguous symbol in the same context. Prefer familiar action/object meanings and retain text for unfamiliar actions. Selection, loading and error states use the established control and status contracts; a spinner alone does not explain what is pending.
+
+## Size Scale
+
+Values use rem and therefore follow the user's root text size. Pixel equivalents below assume a 16px root.
+
+| Token / utility                     | Value          | Intended use                                             |
+| ----------------------------------- | -------------- | -------------------------------------------------------- |
+| `--site-icon-xs` / `size-icon-xs`   | 0.75rem / 12px | Internal checkbox mark only                              |
+| `--site-icon-sm` / `size-icon-sm`   | 1rem / 16px    | Compact inline or control icon                           |
+| `--site-icon-md` / `size-icon-md`   | 1.25rem / 20px | Default functional icon, navigation and ordinary actions |
+| `--site-icon-lg` / `size-icon-lg`   | 1.5rem / 24px  | Prominent control or section icon                        |
+| `--site-icon-xl` / `size-icon-xl`   | 2rem / 32px    | Status or feature illustration                           |
+| `--site-icon-2xl` / `size-icon-2xl` | 2.5rem / 40px  | Large status or feature illustration                     |
+| `--site-icon-3xl` / `size-icon-3xl` | 3rem / 48px    | Large empty-state or explanatory illustration            |
+
+Use the default unless the surrounding component calls for another level. Buttons and inputs map `xs`/`sm` to 16px, `md`/`lg` to 20px and `xl` to 24px; the button's `2xl` also uses 24px. Internal Nuxt UI icons keep their component slot ownership and share the same Nuxt Icon provider. Do not manually duplicate an icon already provided by a control's `icon`, `leading-icon` or `trailing-icon` prop.
+
+An icon-only button or link **MUST** expose a target of at least 44 × 44 CSS pixels, including on narrow viewports. The artwork can remain 16, 20 or 24px. This separates visual density from interaction size, as described by [Carbon](https://carbondesignsystem.com/elements/icons/usage/) and [Lucide](https://lucide.dev/how-to/accessibility). Control padding, minimum dimensions and focus behavior belong to the interactive wrapper.
+
+## Component API and Overrides
+
+`UiIcon` accepts `name: string`, `size?: string | number` and `label?: string`. Numeric `size` values are CSS pixels; strings accept CSS lengths, including rem and token references. Without `size`, the application default is `var(--site-icon-md)`.
+
+✅ **Use the shared default or one explicit size mechanism.**
+
+```vue
+<UiIcon name="i-lucide-image" />
+<UiIcon name="i-lucide-image" class="size-icon-lg" />
+<UiIcon name="i-lucide-image" :size="24" />
+<UiIcon name="i-lucide-image" size="var(--site-icon-xl)" />
+```
+
+`size-icon-*` is the preferred local scale selection. Use `size` when a measured integration requires a specific value. **MUST** choose one sizing mechanism for an instance; `size` and a sizing class must not compete. Color is supplied with semantic classes or inherited from the parent, not a separate icon-specific color prop.
+
+❌ **Competing sizes and page-owned artwork bypass the shared contract.**
+
+```vue
+<UiIcon name="i-lucide-image" :size="18" class="size-icon-lg" />
+<svg viewBox="0 0 32 20" class="h-4 w-7" stroke-width="3" />
+```
+
+**FORBIDDEN**: global `svg` width, height, stroke or fill rules. They also affect logos, charts, cropping overlays and other non-icon graphics. Nuxt's path-aware component naming remains enabled; standalone application icons use `UiIcon`, while Nuxt UI controls render their own internal icons.
+
+## Color and Brand Assets
+
+Functional icons inherit `currentColor`. Use the same semantic foreground as adjacent text, or an explicit semantic role such as `text-primary`, `text-success` or `text-warning`. Hover, active, disabled and focus states come from the control/theme owner. A status must also have recognizable shape or text; color alone is insufficient.
+
+Verify foreground/background contrast in each supported theme. Meaningful interface icons must reach at least 3:1 against adjacent colors under [WCAG non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html); ordinary paired text requires at least 4.5:1. Aim for 4.5:1 for icons where practical, following the stronger [Carbon guidance](https://carbondesignsystem.com/elements/icons/usage/). Use the product's accessible interaction token instead of assuming its logo color is suitable for a small control. Inactive controls are exempt from the non-text contrast requirement, but their disabled state must remain understandable within the labeled control.
+
+Third-party identities are local `brand:*` assets, including `brand:apple`, `brand:android` and `brand:whatsapp`. Preserve their proportions and any required identity colors; monochrome variants inherit the foreground only when the supplied asset supports that treatment. Product logos use the product's approved assets and brand specification. **FORBIDDEN**: recoloring a provider logo as a generic status icon, forcing logos into Lucide geometry or embedding a product's palette in shared icon defaults.
+
+Local brand files use concise kebab-case names under `app/assets/icons/brand/`. Nuxt config registers that collection. Do not restore obsolete `common:*` names, slash-name conversion, compatibility aliases or global SVG symbol injection.
+
+## Accessible Names and Interaction
+
+`UiIcon` is decorative by default: `aria-hidden="true"` and `focusable="false"`. A non-empty `label` exposes `role="img"` and an accessible name. The label describes meaning, not the icon's filename. These defaults implement the distinctions in the [Lucide accessibility guide](https://lucide.dev/how-to/accessibility).
+
+✅ **Nearby text owns the meaning; the icon stays decorative.**
+
+```vue
+<span class="inline-flex items-center gap-2 text-success">
+  <UiIcon name="i-lucide-circle-check" />
+  Ready
+</span>
+```
+
+✅ **A standalone semantic icon receives a localized label.**
+
+```vue
+<UiIcon name="i-lucide-circle-check" :label="t('status.ready')" class="text-success" />
+```
+
+✅ **An icon action is labeled on its semantic button.**
+
+```vue
+<UiButton
+  square
+  color="neutral"
+  variant="ghost"
+  icon="i-lucide-x"
+  :aria-label="t('actions.close')"
+  @click="close"
+/>
+```
+
+❌ **A labeled picture is not a keyboard-operable, named action.**
+
+```vue
+<UiIcon name="i-lucide-x" label="Close" @click="close" />
+```
+
+Use the existing locale owner for labels, visible focus on controls and the component's keyboard behavior. A tooltip supplements a control's name; it does not replace that name. Do not add `label` to an icon that repeats its button's accessible name or adjacent text.
+
+## Additions and Verification
+
+1. Search existing component, navigation and state owners for the same meaning; reuse the established Lucide name and component before adding an asset.
+2. Confirm the chosen name exists in the installed local collection. Keep `fallbackToApi: false`; an unbundled icon is a missing dependency or registration, not a reason to fetch a public icon API.
+3. Review any new brand asset for ownership, intrinsic dimensions, aspect ratio and identity color. Keep product-only assets in the product. A genuinely missing functional symbol requires an explicit design decision before another collection is introduced.
+4. Keep glyph size, control hit target and text alignment separate. Inspect optical weight at 16/20/24/32px, the ordinary 20px default, an explicit override and the component's actual size variants.
+5. Verify decorative versus meaningful accessibility, keyboard action/focus, status text, loading/disabled states, light/dark contrast and narrow layout. Inspect actual rendered SVG dimensions and viewBox; a successful typecheck alone is not visual evidence.
+6. For shared-source changes, verify source → registry → packed CLI → externally generated application. The generated `/ui` catalog provides default, size, semantic-label, brand and control examples. Application-specific routes verify their own composition.
+
+### Acceptance Checklist
+
+- [ ] Functional icons come from the installed Lucide family; brand assets remain separate.
+- [ ] The 20px default, selected size tokens and explicit `size` override render correctly without competing size declarations.
+- [ ] Source geometry and proportional strokes are preserved; no arbitrary per-icon offsets or global SVG overrides exist.
+- [ ] Icon-only controls retain at least 44 × 44px targets and visible keyboard focus.
+- [ ] Decorative icons are silent; standalone meaning and actions have names at the correct owner.
+- [ ] Status remains understandable without color, and supported themes have adequate contrast.
+- [ ] Icons resolve from local assets/bundles with no external icon API fallback.
+- [ ] Changed shared assets, rules and defaults survive packed CLI generation and the generated app's checks.

package/dist/resources/templates/nuxt/app/app.config.ts

@@ -1,7 +1,9 @@
 import siteUiTheme from "./theme";
+import icon from "./theme/icon";
 
 export default defineAppConfig({
   ui: siteUiTheme,
+  icon,
   siteShell: {
     name: "{{projectName}}",
     descriptionKey: "site.description",

package/dist/resources/templates/nuxt/app/pages/app/index.vue

@@ -50,7 +50,7 @@ useSeo({
         <span>Output mix</span>
         <ul class="workspace-page__formats">
           <li v-for="format in outputFormats" :key="format">
-            <UIcon name="i-lucide-check" />
+            <UiIcon name="i-lucide-check" class="text-primary" />
             {{ format }}
           </li>
         </ul>
@@ -119,7 +119,13 @@ useSeo({
   gap: 18px;
   border: 1px solid var(--site-color-border);
   border-radius: var(--site-radius-lg);
-  background: linear-gradient(180deg, rgb(168 101 80 / 4%), transparent), var(--site-color-surface);
+  background:
+    linear-gradient(
+      180deg,
+      color-mix(in srgb, var(--site-color-primary) 4%, transparent),
+      transparent
+    ),
+    var(--site-color-surface);
   padding: 20px;
 }
 
@@ -148,7 +154,7 @@ useSeo({
   gap: 12px;
   border: 1px solid var(--site-color-border);
   border-radius: var(--site-radius-md);
-  background: rgb(168 101 80 / 4%);
+  background: color-mix(in srgb, var(--site-color-primary) 4%, transparent);
   padding: 14px;
 }
 
@@ -193,10 +199,6 @@ useSeo({
   color: var(--site-color-muted);
 }
 
-.workspace-page__formats svg {
-  color: var(--site-color-primary);
-}
-
 .workspace-page__metric strong {
   color: var(--site-color-primary);
   font-size: 58px;