@vc-shell/vc-app-skill 2.0.3-pr227.0c4f2c3 → 2.0.4-pr228.833ff5f

package/runtime/knowledge/docs/modules/assets-manager/assets-manager.docs.md

@@ -1,3 +1,10 @@
+---
+title: Assets Manager
+category: reference
+group: modules
+slug: assets-manager
+---
+
 # Assets Manager Module
 
 A built-in blade module for managing file assets (images, documents, archives). Provides upload, delete, reorder, and preview functionality via a table-based UI.
@@ -32,17 +39,27 @@ The blade reads its configuration from `options` via `useBlade<AssetsManagerOpti
 
 ## Usage
 
-Open the Assets Manager as a child blade:
+The canonical pattern is to bind the manager to a writable `computed` over a field of the parent entity, so that uploads/removes/reorders propagate back into the form. `confirmRemove` is wired to the framework's popup service rather than `window.confirm`.
 
 ```typescript
-import { markRaw } from "vue";
-import { useBlade, useAssetsManager } from "@vc-shell/framework";
+import { computed, markRaw } from "vue";
+import { useBlade, useAssetsManager, usePopup } from "@vc-shell/framework";
 
 const { openBlade } = useBlade();
+const { showConfirmation } = usePopup();
+
+// Two-way binding: the manager mutates `productAssets.value`, which writes
+// straight back to `item.value.productData.assets`.
+const productAssets = computed({
+  get: () => item.value?.productData?.assets ?? [],
+  set: (val) => {
+    if (item.value?.productData) item.value.productData.assets = val;
+  },
+});
 
-const assetsManager = useAssetsManager(product.assets, {
-  uploadPath: () => `/catalog/${product.id}`,
-  confirmRemove: () => confirm("Delete selected assets?"),
+const assetsManager = useAssetsManager(productAssets, {
+  uploadPath: () => `/catalog/${item.value?.id}`,
+  confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"),
 });
 
 openBlade({
@@ -54,7 +71,6 @@ openBlade({
     // manager.items.value and manager.loading.value access.
     manager: markRaw(assetsManager),
     disabled: !canEdit.value,
-    hiddenFields: ["sortOrder"],
   },
 });
 ```
@@ -66,8 +82,8 @@ openBlade({
 - **Delete**: Toolbar delete button (requires selection) and per-row action button.
 - **Reorder**: Drag-and-drop row reordering when not in readonly mode.
 - **Detail view**: Clicking a row opens an `AssetsDetails` child blade for single-asset editing.
-- **Mobile**: Responsive card layout for mobile viewports.
-- **Empty state**: Shows upload prompt when no assets exist (or "No assets" in readonly mode).
+- **Non-image assets**: Files without an image extension render a colored badge with the uppercased extension (`PDF`, `DOCX`, `ZIP`, ...) instead of a thumbnail.
+- **Empty state**: Shows upload prompt when no assets exist; the empty-state action button opens the file picker.
 
 ## Toolbar
 
@@ -81,11 +97,72 @@ openBlade({
 - **Always use `markRaw()` when passing manager through blade options.** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects, so `manager.items` would become a plain array instead of `Ref<AssetLike[]>` — breaking `.value` access. `markRaw()` prevents this by telling Vue not to make the manager reactive.
 - The `manager` object (from `useAssetsManager()`) owns the reactive asset list and all mutation methods. The blade reads `manager.items` and calls `manager.upload()`, `manager.remove()`, `manager.removeMany()`, `manager.reorder()`, and `manager.updateItem()`.
 - The `disabled` prop makes the entire blade readonly: no upload, no delete, no reorder.
-- Asset thumbnails use `isImage()` from shared utilities to determine if an image preview or a file-type icon should be shown.
+- Asset thumbnails use `isImage()` from `@core/utilities/assets` to decide between an image preview (`VcImage`) and a colored extension badge (`getExtensionColor` + `getExtensionLabel`).
 - The module uses `useBlade()` internally to open the detail sub-blade.
+- The `manager` instance can be reused as a `useBladeWidgets` badge source — its `items.value.length` updates reactively as uploads/removes happen inside the blade, so a parent widget showing the asset count refreshes without an extra round-trip.
+
+## Recipes
+
+### Open from a blade widget
+
+Most callers don't open `AssetsManager` directly — they expose it as one of the parent blade's widgets. The widget shows the asset count as a live badge and opens the manager on click. The manager is created once per parent blade and reused across openings.
+
+```typescript
+import { computed, markRaw, type Ref, type ComputedRef } from "vue";
+import { useBlade, useBladeWidgets, useAssetsManager, usePopup } from "@vc-shell/framework";
+
+interface Entity {
+  id?: string;
+  productData?: { assets?: Asset[] };
+}
+
+export function useEntityWidgets(opts: { item: Ref<Entity | undefined>; disabled: ComputedRef<boolean>; isVisible: ComputedRef<boolean> }) {
+  const { item, disabled, isVisible } = opts;
+  const { openBlade } = useBlade();
+  const { showConfirmation } = usePopup();
+
+  const entityAssets = computed({
+    get: () => item.value?.productData?.assets ?? [],
+    set: (val) => {
+      if (item.value?.productData) item.value.productData.assets = val;
+    },
+  });
+
+  const assetsManager = useAssetsManager(entityAssets, {
+    uploadPath: () => `/catalog/${item.value?.id}`,
+    confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"),
+  });
+
+  const assetsCount = computed(() => entityAssets.value.length);
+
+  return useBladeWidgets([
+    {
+      id: "AssetsWidget",
+      icon: "lucide-file",
+      title: "WIDGETS.ASSETS",
+      badge: assetsCount,
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "AssetsManager",
+          options: {
+            manager: markRaw(assetsManager),
+            disabled: disabled.value,
+          },
+        }),
+    },
+  ]);
+}
+```
+
+Key points:
+
+- `useAssetsManager` is invoked once at widget-setup time, not inside `onClick`. Recreating it per click would lose pending state and break optimistic updates.
+- `disabled.value` is unwrapped at click time. Passing the raw `ComputedRef` would work too, but the blade reads `options.value?.disabled` as a plain value.
+- `assetsCount` reads from the source array (not from `assetsManager.items`), but both stay in sync because the manager mutates the same array via the setter.
 
 ## Related
 
 - `framework/core/composables/useAssetsManager/` -- `useAssetsManager`, `AssetLike`, `UseAssetsManagerReturn`
-- `framework/shared/utilities/assets.ts` -- `isImage`, `getFileThumbnail`, `readableSize`
-- `framework/core/utilities/date/` -- `formatDateRelative` for creation dates
+- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
+- `framework/modules/assets/components/assets-details/` -- `AssetsDetails` child blade opened on row click

package/runtime/knowledge/docs/shell/_internal/popup/common/popup-common.docs.md

@@ -1,3 +1,10 @@
+---
+title: PopupCommon
+category: composables
+group: utilities
+internal: true
+---
+
 # Popup Common Components
 
 Pre-configured popup variants for warning, error, and info dialogs. Built on a shared `VcPopupBase` component that wraps the `VcPopup` organism.

package/runtime/knowledge/docs/shell/auth/ChangePasswordPage/change-password-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: ChangePasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ChangePasswordPage
 
 Change password page with current, new, and confirm password fields. Supports a `forced` mode for expired passwords that displays an info banner and is triggered by post-login redirect. This full-page variant is used when the user must change their password before accessing the application (e.g., expired password policy). For voluntary password changes from within the app, the `ChangePasswordButton` in the settings menu opens a popup instead.

package/runtime/knowledge/docs/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: ForgotPasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ForgotPasswordPage
 
 Password recovery page where the user enters their email to receive a reset link. Shows a masked-email confirmation on success. This page is part of the standard authentication flow in vc-shell and handles the first step of password recovery: collecting the user's email address and dispatching a reset email through the platform API.

package/runtime/knowledge/docs/shell/auth/InvitePage/invite-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: InvitePage
+category: composables
+group: utilities
+internal: true
+---
+
 # InvitePage
 
 Invitation acceptance page where an invited user sets their password. Validates the invitation token on mount, displays the pre-filled email, and provides password/confirm fields. On successful acceptance, the user is automatically signed in and redirected to the main application. This page is the final step in the user invitation flow initiated from the VirtoCommerce Platform admin.

package/runtime/knowledge/docs/shell/auth/LoginPage/login-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: LoginPage
+category: composables
+group: utilities
+internal: true
+---
+
 # LoginPage
 
 Full-page login screen with username/password form, SSO external provider support, and forgot-password navigation. Wraps `VcAuthLayout` and uses `useUserManagement` for authentication. This is the primary entry point for user authentication in vc-shell applications, supporting both standard credential-based login and SSO/external provider authentication.

package/runtime/knowledge/docs/shell/auth/ResetPasswordPage/reset-password-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: ResetPasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ResetPasswordPage
 
 Password reset page reached via an email link containing a token. Validates the token on mount, then shows password and confirm-password fields. On success, the user is automatically signed in and redirected to the main application. This page is the second step of the password recovery flow, following the `ForgotPasswordPage` which dispatches the reset email.

package/runtime/knowledge/docs/shell/auth/sign-in/sign-in.docs.md

@@ -1,3 +1,10 @@
+---
+title: SignIn
+category: composables
+group: utilities
+internal: true
+---
+
 # SignIn (External Providers)
 
 Components and composable for SSO / external authentication provider integration. Renders provider buttons on the login page and handles the external sign-in redirect flow. This module supports any OAuth2/OpenID Connect provider configured on the VirtoCommerce Platform (Google, Azure AD, ADFS, Okta, etc.) and provides a clean abstraction over the redirect-based authentication flow.

package/runtime/knowledge/docs/shell/components/change-password/change-password.docs.md

@@ -1,3 +1,10 @@
+---
+title: ChangePassword
+category: composables
+group: utilities
+internal: true
+---
+
 # Change Password Component
 
 A modal dialog for changing the current user's password, with real-time validation and forced-change support.

package/runtime/knowledge/docs/shell/components/change-password-button/change-password-button.docs.md

@@ -1,3 +1,10 @@
+---
+title: ChangePasswordButton
+category: composables
+group: utilities
+internal: true
+---
+
 # ChangePasswordButton
 
 Settings menu action that opens the change-password popup through the popup handler system. This component bridges the settings menu and the password change form: it injects `CloseSettingsMenuKey` to dismiss the parent menu before showing the password popup, ensuring a clean transition. The popup itself renders a form with current password, new password, and confirm password fields, with real-time password policy validation.

package/runtime/knowledge/docs/shell/components/error-interceptor/error-interceptor.docs.md

@@ -1,3 +1,10 @@
+---
+title: ErrorInterceptor
+category: composables
+group: utilities
+internal: true
+---
+
 # Error Interceptor
 
 A renderless component that captures Vue `onErrorCaptured` errors and surfaces them to child slots or the blade error banner.

package/runtime/knowledge/docs/shell/components/language-selector/language-selector.docs.md

@@ -1,3 +1,10 @@
+---
+title: LanguageSelector
+category: composables
+group: utilities
+internal: true
+---
+
 # LanguageSelector
 
 Settings menu entry that displays the current UI language and opens a cascading submenu for switching between available locales. Uses the framework `useLanguages` composable and the global vue-i18n locale list. When the user selects a different language, the entire application UI updates immediately without a page reload.

package/runtime/knowledge/docs/shell/components/logout-button/logout-button.docs.md

@@ -1,3 +1,10 @@
+---
+title: LogoutButton
+category: composables
+group: utilities
+internal: true
+---
+
 # LogoutButton
 
 Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeStack()` to close open child blades so the user does not return to stale blade state on next login.

package/runtime/knowledge/docs/shell/components/notification-dropdown/notification-dropdown.docs.md

@@ -1,3 +1,10 @@
+---
+title: NotificationDropdown
+category: composables
+group: utilities
+internal: true
+---
+
 # NotificationDropdown
 
 Dropdown panel that displays the push notification history in reverse chronological order. This component renders a scrollable list of all received push notifications, backed by the `useNotifications()` composable. It automatically marks unread notifications as read when the dropdown is closed (unmounted), updating the unread badge count in the toolbar.

package/runtime/knowledge/docs/shell/components/notification-template/notification-template.docs.md

@@ -1,3 +1,10 @@
+---
+title: NotificationTemplate
+category: composables
+group: utilities
+internal: true
+---
+
 # NotificationTemplate
 
 Base template for rendering a single push notification with title, relative timestamp, optional icon, and a default slot for extra detail content. This component provides the standard layout that all notification types share, while allowing domain-specific content to be injected through the default slot.

package/runtime/knowledge/docs/shell/components/settings-menu/settings-menu.docs.md

@@ -1,3 +1,10 @@
+---
+title: SettingsMenu
+category: composables
+group: utilities
+internal: true
+---
+
 # SettingsMenu
 
 Container component that renders registered settings menu items grouped by category and sorted by order. Items are registered through the `useSettingsMenu` service, not through component props. This decoupled architecture allows any module in the application to contribute settings entries without modifying the menu component itself.

package/runtime/knowledge/docs/shell/components/settings-menu-item/settings-menu-item.docs.md

@@ -1,3 +1,10 @@
+---
+title: SettingsMenuItem
+category: composables
+group: utilities
+internal: true
+---
+
 # SettingsMenuItem
 
 Individual menu row used inside the settings menu. Displays an icon, title, optional current value, and a chevron indicator for sub-menus. Supports click and hover trigger actions.

package/runtime/knowledge/docs/shell/components/sidebar/sidebar.docs.md

@@ -1,3 +1,10 @@
+---
+title: Sidebar
+category: composables
+group: utilities
+internal: true
+---
+
 # Sidebar Component
 
 A responsive sidebar wrapper that conditionally renders content inside a `VcSidebar` panel or inline, based on viewport and expansion state.

package/runtime/knowledge/docs/shell/components/theme-selector/theme-selector.docs.md

@@ -1,3 +1,10 @@
+---
+title: ThemeSelector
+category: composables
+group: utilities
+internal: true
+---
+
 # ThemeSelector
 
 Settings menu entry that shows the current theme and opens a cascading submenu to switch between registered themes. Uses the `useTheme()` composable for theme management and shows a toast notification when the theme changes, confirming the switch to the user.

package/runtime/knowledge/docs/shell/components/user-dropdown-button/user-dropdown-button.docs.md

@@ -1,3 +1,10 @@
+---
+title: UserDropdownButton
+category: composables
+group: utilities
+internal: true
+---
+
 # UserDropdownButton
 
 User account trigger displayed in the shell sidebar footer. Shows the user's avatar, display name, and role. On desktop it opens a floating settings menu dropdown anchored to the button; on mobile it opens a full sidebar panel that slides in from the left. The component automatically adapts its layout based on the sidebar's expanded/collapsed state.

package/runtime/knowledge/docs/shell/dashboard/dashboard-charts/dashboard-charts.docs.md

@@ -1,3 +1,10 @@
+---
+title: DashboardCharts
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardCharts
 
 Suite of dashboard chart components (line, bar, donut) built on Unovis. Each chart accepts a generic data array, a `ChartConfig` for series colors/labels, and supports hover tooltips, legends, and optional range filtering.

package/runtime/knowledge/docs/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md

@@ -1,3 +1,10 @@
+---
+title: DashboardWidgetCard
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardWidgetCard
 
 Modern dashboard widget card with header, optional KPI stats area, action buttons, content body, and footer. Used within the GridStack dashboard layout for displaying metrics, feeds, and charts.

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md

@@ -1,3 +1,10 @@
+---
+title: DraggableDashboard
+category: composables
+group: utilities
+internal: true
+---
+
 # DraggableDashboard
 
 Gridstack.js-powered dashboard container that renders registered widgets in a drag-and-drop grid layout. Automatically persists layout changes to localStorage and supports widget resizing. This is the main dashboard component used as the landing page in vc-shell applications, providing a customizable overview with KPI widgets, charts, quick actions, and data summaries.

package/runtime/knowledge/docs/ui/components/atoms/vc-badge/vc-badge.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcBadge
+category: components
+group: misc
+---
+
 # VcBadge
 
 A small indicator component for displaying counts, status dots, or short text labels. Supports two rendering modes: **positioned overlay** on a slotted element (e.g., notification count on a bell icon), or **standalone inline** badge (e.g., a tag/pill label in a list). Inline badges use a softer color palette with tinted backgrounds, while overlay badges use solid fills for maximum contrast.
 
+::storybook id="data-display-vcbadge--default"
+
 ## When to Use
 
 - Show unread notification counts on icons or buttons
@@ -18,6 +26,8 @@ A small indicator component for displaying counts, status dots, or short text la
 </VcBadge>
 ```
 
+::storybook id="data-display-vcbadge--variants" height="300"
+
 ## Key Props
 
 | Prop             | Type                                                                       | Default     | Description                                               |
@@ -34,6 +44,8 @@ A small indicator component for displaying counts, status dots, or short text la
 | `right`          | `string`                                                                   | --          | Custom right offset (requires `customPosition`)           |
 | `ariaLabel`      | `string`                                                                   | --          | Custom accessible label for the badge                     |
 
+::storybook id="data-display-vcbadge--use-cases" height="350"
+
 ## Common Patterns
 
 ### Notification Count on an Icon
@@ -125,3 +137,15 @@ Fine-tune the badge position relative to its parent:
 - [VcIcon](../vc-icon/) -- commonly used as slotted content inside badges
 - [VcBanner](../vc-banner/) -- for longer contextual messages and alerts
 - [VcStatus](../vc-status/) -- labeled multi-variant status indicator
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcBadge lives in `framework/ui/components/atoms/vc-badge/`.
+- Overlay mode uses `position: absolute` on the badge element; the parent slot wrapper is set to `position: relative` via the `.vc-badge` CSS class.
+- The `inline` prop switches the root element from `<span class="vc-badge">` (overlay) to `<span class="vc-badge--inline">` with no position context.
+- Color palette tokens: overlay uses `--{variant}-500` fills; inline uses `--{variant}-50` background + `--{variant}-700` text, defined in `framework/assets/styles/theme/colors.scss`.
+- Clickable mode integrates `role="button"` and keyboard handlers directly in the component — no separate button wrapper — to preserve the overlay stacking context.
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-banner/vc-banner.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcBanner
+category: components
+group: feedback
+---
+
 # VcBanner
 
 A contextual alert component for displaying important messages, warnings, or status information. VcBanner supports four semantic variants (`info`, `warning`, `danger`, `success`), each with a distinct accent color and left border stripe. Long content is automatically collapsed behind a "Show more" toggle, keeping the blade layout clean while still giving users access to the full message.
 
+::storybook id="action-vcbanner--default"
+
 ## When to Use
 
 - Display validation errors or decline reasons on detail blades
@@ -19,6 +27,8 @@ A contextual alert component for displaying important messages, warnings, or sta
 </VcBanner>
 ```
 
+::storybook id="action-vcbanner--all-variants" height="500"
+
 ## Key Props
 
 | Prop              | Type                                           | Default  | Description                                                   |
@@ -157,3 +167,13 @@ Override the default "Show more" button with a custom trigger:
 - [VcCard](../vc-card/) -- for general-purpose content containers
 - [VcIcon](../vc-icon/) -- used internally for the leading icon
 - [VcBadge](../vc-badge/) -- for inline status pill labels
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- Legacy variants `"light-danger"`, `"info-dark"`, and `"primary"` are mapped in `vc-banner.vue` via a computed `resolvedVariant`. A `console.warn` is emitted in development mode only.
+- The collapse animation is driven by `max-height` CSS transition with a JS-measured `scrollHeight`. The `--vc-banner-collapsed-height` CSS variable is injected inline as a style binding.
+- Source: `framework/ui/components/atoms/vc-banner/vc-banner.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-button/vc-button.docs.md

@@ -1,6 +1,14 @@
+---
+title: VcButton
+category: components
+group: misc
+---
+
 # VcButton
 
-A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application -- from toolbar buttons and form submissions to inline table actions and navigation.
+A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application — from toolbar buttons and form submissions to inline table actions and navigation.
+
+::storybook id="action-vcbutton--primary"
 
 ## When to Use
 
@@ -33,6 +41,8 @@ import { VcButton } from "@vc-shell/framework";
 
 VcButton provides 9 visual variants organized into three emphasis levels.
 
+::storybook id="action-vcbutton--all-variants" height="500"
+
 ### Filled Variants (High Emphasis)
 
 Solid background colors for primary and prominent actions.
@@ -85,6 +95,8 @@ No border or background, used for inline or de-emphasized actions.
 
 Five size options cover all common use cases from toolbar icons to prominent CTAs.
 
+::storybook id="action-vcbutton--all-sizes"
+
 ```vue
 <VcButton size="sm">Small</VcButton>
 <VcButton size="default">Default</VcButton>
@@ -101,7 +113,8 @@ Five size options cover all common use cases from toolbar icons to prominent CTA
 | `icon`    | 36x36px | 0 (square)                    | Toolbar icon buttons                |
 | `icon-sm` | 24x24px | 0 (square)                    | Table cell actions, inline controls |
 
-> **Note:** Legacy aliases `xs` (maps to `sm`) and `base` (maps to `default`) are supported for backward compatibility.
+!!! note "Legacy size aliases"
+`xs` (maps to `sm`) and `base` (maps to `default`) are supported for backward compatibility but should not be used in new code.
 
 ## Icons
 
@@ -122,6 +135,8 @@ The `icon` prop accepts a string (icon identifier like `lucide-plus`) or a Vue c
 
 ## Loading State
 
+::storybook id="action-vcbutton--loading"
+
 When `loading` is `true`, the button shows a spinner in place of its icon and becomes non-interactive:
 
 ```vue
@@ -213,6 +228,9 @@ VcButton integrates with `VcButtonGroup` via provide/inject. The group can set a
 </template>
 ```
 
+!!! warning "Don't disable buttons during async actions"
+Use the `loading` prop, not `disabled`. A disabled button gives no progress feedback; a loading button shows a spinner and announces busy state via `aria-busy`.
+
 ## Common Mistakes
 
 ### Missing aria-label on icon-only buttons
@@ -300,6 +318,15 @@ All visual properties are customizable through CSS custom properties. Each varia
 
 ## Related Components
 
-- [VcIcon](../vc-icon/) -- used internally for button icons
-- [VcBadge](../vc-badge/) -- can wrap a button to show notification counts
-- [VcButtonGroup](./vc-button-group.vue) -- groups buttons with shared size context
+- [VcIcon](../vc-icon/) — used internally for button icons
+- [VcBadge](../vc-badge/) — can wrap a button to show notification counts
+- `VcButtonGroup` — groups buttons with shared size context (see component source for usage)
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcButton calls `e.preventDefault()` on click to support `link` variant pattern. Form submit buttons must use `type="submit"` to bypass this.
+- `VcButtonGroup` integration is via provide/inject (`vcButtonGroupSize` injection key in `framework/injection-keys.ts`).
+- Size aliases `xs`/`base` are kept for vendor-portal backward compatibility — slated for removal in v3.
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-card/vc-card.docs.md

@@ -1,6 +1,14 @@
+---
+title: VcCard
+category: components
+group: layout
+---
+
 # VcCard
 
-A bordered container with an optional header, icon, action buttons, and collapsible body. VcCard groups related content into visually distinct sections on blades and detail views. It supports three color variants for semantic meaning and smooth animated collapse/expand.
+A bordered container with an optional header, icon, action buttons, and collapsible body.
+
+::storybook id="data-display-vccard--default" VcCard groups related content into visually distinct sections on blades and detail views. It supports three color variants for semantic meaning and smooth animated collapse/expand.
 
 ## When to Use
 
@@ -45,6 +53,8 @@ The icon renders at `xl` size using the `VcIcon` component. It inherits the head
 
 ## Variants
 
+::storybook id="data-display-vccard--all-variants" height="400"
+
 Three variants control the header's background and text color to communicate semantic meaning.
 
 ```vue
@@ -74,6 +84,8 @@ Three variants control the header's background and text color to communicate sem
 
 ## Collapsible Sections
 
+::storybook id="data-display-vccard--collapsable" height="300"
+
 Enable collapse/expand behavior by setting `is-collapsable`. The card header becomes clickable and shows a chevron indicator.
 
 ```vue
@@ -173,7 +185,8 @@ Replace the entire header content using the `#header` slot. This overrides the d
 </VcCard>
 ```
 
-> **Note:** The `header` prop must be set (even to an empty string) for the header section to render. If neither `header` prop nor `#header` slot is provided, no header is displayed.
+!!! note "Header required for header section"
+The `header` prop must be set (even to an empty string) for the header section to render. If neither `header` prop nor `#header` slot is provided, no header is displayed.
 
 ## Fill Mode
 

package/runtime/knowledge/docs/ui/components/atoms/vc-col/vc-col.docs.md

@@ -1,6 +1,14 @@
+---
+title: VcCol
+category: components
+group: layout
+---
+
 # VcCol
 
-A flexbox column layout primitive that stacks its children vertically. Designed to work with `VcRow` for proportional multi-column layouts. The `size` prop maps directly to `flex-grow`, so columns with higher values consume more horizontal space relative to their siblings.
+A flexbox column layout primitive that stacks its children vertically.
+
+::storybook id="layout-vccol--default" Designed to work with `VcRow` for proportional multi-column layouts. The `size` prop maps directly to `flex-grow`, so columns with higher values consume more horizontal space relative to their siblings.
 
 ## When to Use
 
@@ -68,6 +76,8 @@ A flexbox column layout primitive that stacks its children vertically. Designed
 </VcCol>
 ```
 
+::storybook id="layout-vccol--content-layout" height="400"
+
 ## Recipe: Blade Detail Form with Sidebar
 
 A common blade layout places metadata in a narrow sidebar column and form fields in the wider main column: