@vc-shell/vc-app-skill 2.0.3-pr227.0c4f2c3 → 2.0.4-pr228.1e79eae

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

@@ -1,7 +1,15 @@
+---
+title: VcContainer
+category: components
+group: layout
+---
+
 # VcContainer
 
 A scrollable content wrapper that fills its parent, provides configurable padding, and optionally shows an inset shadow to indicate overflow. The standard building block for blade body content.
 
+::storybook id="layout-vccontainer--default"
+
 ## When to Use
 
 - Wrap blade body content that may exceed the visible area
@@ -11,6 +19,8 @@ A scrollable content wrapper that fills its parent, provides configurable paddin
 
 ## Basic Usage
 
+::storybook id="layout-vccontainer--with-shadow" height="300"
+
 ```vue
 <VcContainer shadow>
   <p>Scrollable content goes here...</p>

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

@@ -1,7 +1,15 @@
+---
+title: VcHint
+category: components
+group: feedback
+---
+
 # VcHint
 
 A small text component for displaying helper text, validation messages, or supplementary guidance below form fields. It renders as a lightweight `<div>` with muted styling in its default state and switches to a danger color with `role="alert"` when the `error` prop is set, ensuring screen readers announce validation problems immediately.
 
+::storybook id="data-display-vchint--default"
+
 ## When to Use
 
 - Show helper text beneath input fields explaining expected format or constraints
@@ -34,6 +42,8 @@ A small text component for displaying helper text, validation messages, or suppl
 
 ## Common Patterns
 
+::storybook id="data-display-vchint--form-field-hint"
+
 ### Helper Text Below an Input
 
 ```vue
@@ -129,3 +139,13 @@ Show helper text by default, but swap to an error message when validation fails:
 - [VcLabel](../vc-label/) -- field label component, typically placed above the input
 - [VcBanner](../vc-banner/) -- for longer or more prominent alert messages
 - [VcInput](../../molecules/vc-input/) -- form input component often paired with VcHint
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcHint is a single `<div>` element — no wrapper. `role="alert"` is toggled reactively via `:role` binding when `error` prop changes.
+- CSS variables are scoped with `.vc-hint` selector in `vc-hint.vue` `<style scoped>`.
+- Source: `framework/ui/components/atoms/vc-hint/vc-hint.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcIcon
+category: components
+group: misc
+---
+
 # VcIcon
 
 A unified icon component that renders icons from multiple libraries. Lucide Icons (`lucide-` prefix) are the standard; legacy libraries (FontAwesome, Bootstrap, Material) are deprecated.
 
+::storybook id="layout-vcicon--basic"
+
 ## When to Use
 
 - Display icons in buttons, menus, toolbars, and status indicators
@@ -26,6 +34,8 @@ A unified icon component that renders icons from multiple libraries. Lucide Icon
 | `ariaLabel`  | `string`                                               | —                 | Accessible label for meaningful icons    |
 | `basePath`   | `string`                                               | `"/assets/icons"` | Base path for SVG sprite icons           |
 
+::storybook id="layout-vcicon--all-sizes" height="300"
+
 ## Size Reference
 
 | Size   | Pixels |
@@ -38,6 +48,8 @@ A unified icon component that renders icons from multiple libraries. Lucide Icon
 | `xxl`  | 30px   |
 | `xxxl` | 64px   |
 
+::storybook id="layout-vcicon--all-variants" height="200"
+
 ## Icon Prefix Guide
 
 | Prefix            | Library                | Status                 |
@@ -106,3 +118,15 @@ import MyCustomIcon from "./MyCustomIcon.vue";
 - [VcButton](../vc-button/) — uses VcIcon internally for button icons
 - [VcImage](../vc-image/) — for photos and larger imagery
 - [VcBanner](../vc-banner/) — uses VcIcon for the leading alert icon
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcIcon lives in `framework/ui/components/atoms/vc-icon/`.
+- Icon resolution is handled by a switch on the string prefix: `lucide-` maps to the Lucide component registry; `fa-` / `fas fa-` / `bi-` / `material-` are legacy paths kept for backward compatibility and will be removed in v3.
+- The `svg:` prefix loads from an SVG sprite at `basePath` (default `/assets/icons`) using a `<use>` element. Sprite must be included in the app's static assets.
+- `customSize` takes a number and sets `width`/`height` inline; it overrides the `size` prop class entirely.
+- Color variants (`warning`, `danger`, `success`) apply CSS custom property overrides (`--icon-color`) rather than inline style to allow theme-level customization.
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcImage
+category: components
+group: media
+---
+
 # VcImage
 
 An image display component with predefined sizes, aspect ratio control, and a placeholder for missing sources. Renders images as CSS backgrounds with automatic HTTPS enforcement.
 
+::storybook id="data-display-vcimage--default"
+
 ## When to Use
 
 - Display product thumbnails, profile avatars, or media previews
@@ -30,6 +38,8 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `alt`           | `string`                                                        | —                | Accessible alt text                                                                                                                                |
 | `thumbnailSize` | `ThumbnailSize`                                                 | —                | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
 
+::storybook id="data-display-vcimage--size-variants" height="300"
+
 ## Size Reference
 
 | Size   | Width          |
@@ -83,7 +93,23 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 - Focus ring appears on `:focus-visible` for clickable images
 - HTTP URLs are automatically upgraded to HTTPS when the page is served over HTTPS
 
+!!! tip "Use thumbnailSize for faster load times"
+When displaying images in lists or grids, pass a `thumbnailSize` (e.g. `"128x128"`) to request a pre-scaled variant from the platform CDN instead of loading the full-resolution original. This significantly reduces bandwidth and speeds up initial render.
+
 ## Related Components
 
 - [VcIcon](../vc-icon/) — for symbolic icons rather than photographic content
 - [VcImageTile](../../molecules/vc-image-tile/) — combines VcImage with overlay actions for gallery use
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcImage lives in `framework/ui/components/atoms/vc-image/`.
+- Images are rendered as CSS `background-image` on a `<div>` rather than an `<img>` tag; this enables `background-size: cover/contain` and preserves aspect-ratio without JS.
+- HTTPS enforcement: the `src` watcher rewrites `http://` to `https://` when `window.location.protocol === 'https:'`.
+- `thumbnailSize` appends a query parameter to the URL compatible with Virto Commerce image proxy: `?size=128x128`. This is a platform-specific convention.
+- Aspect ratios are implemented as Tailwind aspect-ratio utility classes (`tw-aspect-square`, `tw-aspect-video`, etc.).
+- Clickable mode adds `role="button"` and forwards keyboard Enter/Space to the click handler, consistent with other atom-level interactive components.
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcLabel
+category: components
+group: misc
+---
+
 # VcLabel
 
 A form field label component with support for required indicators, info tooltips, multilanguage badges, and error states. Renders as a `<label>` when linked to an input via `htmlFor`, or a `<div>` otherwise. VcLabel is the standard way to label any form control in the framework and is used internally by most input molecules (VcInput, VcSelect, VcTextarea, etc.).
 
+::storybook id="data-display-vclabel--default"
+
 ## When to Use
 
 - Label form inputs, selects, and textareas
@@ -48,6 +56,8 @@ A form field label component with support for required indicators, info tooltips
 | `--label-lang-color`     | `var(--neutrals-500)` | Language badge text color      |
 | `--label-error-color`    | `var(--danger-500)`   | Text color in error state      |
 
+::storybook id="data-display-vclabel--required" height="200"
+
 ## Common Patterns
 
 ### Required Field with Tooltip
@@ -144,8 +154,22 @@ Use a different icon for the tooltip trigger:
 - Tooltip icon is focusable and keyboard-accessible via the underlying VcTooltip component
 - Error state changes the visual color but does not add ARIA attributes to the label; pair with `aria-invalid` and `aria-describedby` on the input
 
+::storybook id="data-display-vclabel--with-form-field" height="300"
+
 ## Related Components
 
 - [VcHint](../vc-hint/) -- helper/error text placed below the input
 - [VcTooltip](../vc-tooltip/) -- used internally for the info tooltip
 - [VcInput](../../molecules/vc-input/) -- form input component commonly paired with VcLabel
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcLabel lives in `framework/ui/components/atoms/vc-label/`.
+- The element type (`<label>` vs `<div>`) is determined by a computed `tag` that checks whether `htmlFor` is a non-empty string.
+- The tooltip trigger is rendered by `VcTooltip` (internal molecule); the `tooltipIcon` prop simply passes through to an inner `VcIcon` instance.
+- `multilanguage` + `currentLanguage` render a small pill via an inline `<span>` with `.vc-label__lang` class — not a separate component.
+- VcLabel is the canonical label primitive consumed by `VcInput`, `VcSelect`, `VcTextarea`, `VcCheckbox`, and `VcRadioButton` in `framework/ui/components/molecules/`.
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcLink
+category: components
+group: navigation
+---
+
 # VcLink
 
 A clickable inline link element styled as a button, used for navigation or triggering actions within text or toolbars. Despite its link-like appearance, VcLink renders as a native `<button>` element, which provides correct keyboard behavior and avoids the need for an `href` attribute when the action is handled in JavaScript.
 
+::storybook id="action-vclink--default"
+
 ## When to Use
 
 - Trigger navigation or actions inline with other content
@@ -38,6 +46,8 @@ function openDetails() {
 | ------- | ------- | ----------------------------------------------------------- |
 | `click` | none    | Fired when the link is clicked (suppressed when `disabled`) |
 
+::storybook id="action-vclink--navigation-example" height="250"
+
 ## Common Patterns
 
 ### Navigation Bar
@@ -138,3 +148,15 @@ const activeTab = ref("Overview");
 ## Related Components
 
 - [VcButton](../vc-button/) -- for primary actions and form submissions
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcLink lives in `framework/ui/components/atoms/vc-link/`.
+- Renders as a native `<button type="button">` with all default button styles reset via CSS (no background, no border, no padding). The link appearance is achieved purely through color and text-decoration.
+- The `active` prop adds `.vc-link--active` modifier which applies `--link-text-color-active` and removes the hover underline to signal current selection.
+- The `disabled` prop sets both the native `disabled` attribute (removes from tab order) and `aria-disabled="true"` (for assistive technologies that still read disabled buttons).
+- No `href` prop is intentional — VcLink is for JS-driven navigation (e.g., `openBlade`, `router.push`). For real anchor links, use `<a>` or `<router-link>` directly.
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcLoading
+category: components
+group: feedback
+---
+
 # VcLoading
 
 A lightweight animated loading overlay that displays a sweeping progress bar over its parent container. The overlay uses a translucent backdrop with a subtle blur effect, drawing user attention to the animated bar while keeping the underlying content partially visible so users retain context about what is loading.
 
+::storybook id="layout-vcloading--default"
+
 ## When to Use
 
 - Show loading state while fetching data for a blade, card, or section
@@ -46,6 +54,8 @@ const isLoading = ref(true);
 | `--loading-bar-height` | `4px`                   | Height of the progress bar    |
 | `--loading-z-index`    | `9998`                  | Z-index of the overlay layer  |
 
+::storybook id="layout-vcloading--interactive"
+
 ## Recipe: Loading State in a Blade
 
 Blades have a built-in loading mechanism, but you can use VcLoading to cover a specific section within a blade body — for example, loading a chart or a related-items panel independently.
@@ -123,3 +133,14 @@ Override the bar color to match a specific status or brand theme:
 
 - **VcBlade** -- blades use VcLoading internally for their loading state
 - [VcProgress](../vc-progress/) -- determinate progress bar when percentage is known
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The overlay is a single `<div>` with `v-show` (not `v-if`) so it remains in the DOM and retains animation state. `display: none` from `v-show` removes it from the paint tree when inactive.
+- The sweeping bar is a child `<div>` animated via `@keyframes vc-loading-sweep` (translateX from `-100%` to `100%`).
+- `backdrop-filter: blur(3px)` is applied to the overlay div directly; older Safari requires `-webkit-backdrop-filter` as a fallback.
+- Source: `framework/ui/components/atoms/vc-loading/vc-loading.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcProgress
+category: components
+group: feedback
+---
+
 # VcProgress
 
 A horizontal progress bar that visualizes the completion percentage of a task or process. The bar fills smoothly from left to right using a CSS `transform` transition, and an optional striped variant adds an animated diagonal pattern to indicate active processing.
 
+::storybook id="layout-vcprogress--default"
+
 ## When to Use
 
 - Display upload, import, or export progress
@@ -51,6 +59,8 @@ const uploadPercent = ref(45);
 </template>
 ```
 
+::storybook id="layout-vcprogress--striped"
+
 ### Multiple Progress Stages
 
 ```vue
@@ -164,3 +174,13 @@ async function handleUpload(files: FileList) {
 
 - [VcLoading](../vc-loading/) -- indeterminate loading overlay when percentage is unknown
 - [VcHint](../vc-hint/) -- helper text to display percentage or status message below the bar
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The fill width is driven by `transform: scaleX(value / 100)` with `transform-origin: left`, not `width`, for smoother GPU-accelerated animation.
+- The `value` prop is clamped via `Math.min(100, Math.max(0, props.value))` in a computed.
+- Source: `framework/ui/components/atoms/vc-progress/vc-progress.vue`
+
+<!-- internal:end -->

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

@@ -1,6 +1,14 @@
+---
+title: VcRow
+category: components
+group: layout
+---
+
 # VcRow
 
-A simple layout primitive that arranges child elements in a horizontal flexbox row, automatically switching to a CSS grid on mobile viewports. VcRow has no props of its own — it is a purely presentational wrapper that applies consistent flex behavior and responsive breakpoints so you do not have to repeat the same Tailwind utilities across every horizontal layout.
+A simple layout primitive that arranges child elements in a horizontal flexbox row
+
+::storybook id="layout-vcrow--default", automatically switching to a CSS grid on mobile viewports. VcRow has no props of its own — it is a purely presentational wrapper that applies consistent flex behavior and responsive breakpoints so you do not have to repeat the same Tailwind utilities across every horizontal layout.
 
 ## When to Use
 
@@ -100,6 +108,8 @@ The `--row-gap` CSS variable (default `0`) controls spacing. You can also overri
 </template>
 ```
 
+::storybook id="layout-vcrow--with-cards" height="300"
+
 ## Recipe: Form Section with Label and Fields
 
 Use VcRow to place a section label next to a group of fields in a blade detail view:

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

@@ -1,6 +1,14 @@
+---
+title: VcScrollableContainer
+category: components
+group: layout
+---
+
 # VcScrollableContainer
 
-A container component that wraps overflowing content with auto-hiding scroll arrows at the top and bottom edges. The native scrollbar is hidden via CSS, replaced by subtle chevron indicators that appear only when scrolling in that direction is possible. Users can hover over an arrow to scroll continuously or use keyboard arrow keys when the viewport is focused.
+A container component that wraps overflowing content with auto-hiding scroll arrows at the top and bottom edges.
+
+::storybook id="layout-vcscrollablecontainer--default" The native scrollbar is hidden via CSS, replaced by subtle chevron indicators that appear only when scrolling in that direction is possible. Users can hover over an arrow to scroll continuously or use keyboard arrow keys when the viewport is focused.
 
 ## When to Use
 
@@ -50,6 +58,8 @@ import { VcScrollableContainer } from "@vc-shell/framework";
 | `viewportRef`       | `Ref<HTMLElement \| null>` | Direct reference to the viewport DOM element |
 | `updateScrollState` | `() => void`               | Manually recalculate arrow visibility        |
 
+::storybook id="layout-vcscrollablecontainer--custom-speed" height="350"
+
 ## Recipe: Sidebar Filter List in a Blade
 
 ```vue

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

@@ -1,7 +1,15 @@
+---
+title: VcSkeleton
+category: components
+group: feedback
+---
+
 # VcSkeleton
 
 A loading placeholder component that renders animated shimmer shapes (text lines, circles, or rectangular blocks) to indicate content is being fetched.
 
+::storybook id="layout-vcskeleton--default"
+
 ## When to Use
 
 - Show placeholder UI while async data loads for blades, lists, or cards
@@ -47,6 +55,8 @@ The last row automatically renders at 60% width for a natural paragraph feel.
 <VcSkeleton variant="circle" :width="48" :height="48" />
 ```
 
+::storybook id="layout-vcskeleton--card-skeleton" height="450"
+
 ### Card Skeleton
 
 ```vue
@@ -121,3 +131,13 @@ The last row automatically renders at 60% width for a natural paragraph feel.
 
 - [VcLoading](../vc-loading/) -- animated overlay for sections already rendered
 - [VcProgress](../vc-progress/) -- determinate progress bar
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The `text` variant uses an `Array(rows).fill(0)` to render `<span>` elements via `v-for`. The last row gets a `width: 60%` inline style for a natural paragraph taper.
+- Animation uses a CSS `@keyframes` pulse (opacity oscillation), not a moving shimmer, for simplicity and performance.
+- Source: `framework/ui/components/atoms/vc-skeleton/vc-skeleton.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcStatus
+category: components
+group: feedback
+---
+
 # VcStatus
 
 A colored badge that communicates the state of an entity -- such as an order, product, or workflow step -- using semantic color variants.
 
+::storybook id="data-display-vcstatus--default"
+
 ## When to Use
 
 - Display order or fulfillment status (e.g., "Paid", "Pending", "Cancelled")
@@ -31,6 +39,8 @@ import { VcStatus } from "@vc-shell/framework";
 
 ## Common Patterns
 
+::storybook id="data-display-vcstatus--all-variants" height="450"
+
 ### Status in a Table Cell
 
 ```vue
@@ -116,3 +126,13 @@ Each variant has its own set of CSS variables following the pattern `--status-{v
 
 - [VcStatusIcon](../vc-status-icon/) -- boolean check/cross icon for active/inactive states
 - [VcBadge](../vc-badge/) -- numeric count badge overlay
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The `extend` prop switches a CSS class; all color theming is done via `--status-{variant}-*` CSS variables scoped under `.vc-status`.
+- Special variants `"light-danger"`, `"info-dark"`, and `"primary"` are kept for backward compatibility and mapped via a `variantClassMap` in `vc-status.vue`.
+- Source: `framework/ui/components/atoms/vc-status/vc-status.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcStatusIcon
+category: components
+group: feedback
+---
+
 # VcStatusIcon
 
 A simple boolean status indicator that displays a green check icon for active/success or a muted cross icon for inactive/failure. It is designed for compact spaces like table cells and lists where a full text label would be too verbose.
 
+::storybook id="data-display-vcstatusicon--both-statuses"
+
 ## When to Use
 
 - Show on/off or pass/fail state in tables and lists (e.g., "Is Active", "Email Verified")
@@ -104,6 +112,8 @@ import { VcStatusIcon } from "@vc-shell/framework";
 </template>
 ```
 
+::storybook id="data-display-vcstatusicon--in-context"
+
 ## Recipe: Status Icon with Custom Label
 
 VcStatusIcon is intentionally minimal. If you need a text label next to the icon, compose it yourself:
@@ -146,3 +156,13 @@ VcStatusIcon is intentionally minimal. If you need a text label next to the icon
 - [VcStatus](../vc-status/) -- labeled multi-variant status badge for richer state display
 - [VcIcon](../vc-icon/) -- standalone icon component used internally
 - [VcBadge](../vc-badge/) -- inline pill badges for multi-state indicators
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcStatusIcon wraps two `VcIcon` instances in a single `<span>` with `v-if`/`v-else` switching on the `status` prop.
+- Icon size inherits from parent font-size; no dedicated size prop is exposed.
+- Source: `framework/ui/components/atoms/vc-status-icon/vc-status-icon.vue`
+
+<!-- internal:end -->

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

@@ -1,9 +1,17 @@
+---
+title: VcTooltip
+category: components
+group: feedback
+---
+
 # VcTooltip
 
 A floating tooltip that appears on hover or focus to provide contextual information about a trigger element. Powered by Floating UI for automatic positioning, collision detection, and arrow alignment. The tooltip is teleported to the document body for proper stacking above all content.
 
 ## Quick Start
 
+::storybook id="overlay-vctooltip--default"
+
 ```vue
 <template>
   <VcTooltip>
@@ -55,6 +63,8 @@ The `start` and `end` variants align the tooltip to the beginning or end of the
 
 ## Variants
 
+::storybook id="overlay-vctooltip--variants"
+
 Three visual themes control the tooltip's appearance.
 
 ```vue
@@ -172,7 +182,8 @@ The `#tooltip` slot accepts any HTML or Vue components, not just text:
 </VcTooltip>
 ```
 
-> **Caution:** Tooltips should not contain interactive content (buttons, links, inputs). If you need interactive content in a floating panel, use a popover or dropdown component instead.
+!!! warning "No interactive content inside tooltips"
+Tooltips should not contain interactive content (buttons, links, inputs). The tooltip panel has `pointer-events: none` — clicks and keyboard focus inside it are blocked. If you need interactive content in a floating panel, use a popover or dropdown component instead.
 
 ## Recipes
 
@@ -330,3 +341,16 @@ const actions = [
 - [VcHint](../vc-hint/) -- inline hint text below form fields (always visible)
 - [VcLabel](../vc-label/) -- label component with built-in tooltip support via its own `#tooltip` slot
 - [VcIcon](../vc-icon/) -- commonly used as a tooltip trigger for info indicators
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcTooltip uses `@floating-ui/vue` (`useFloating`, `autoUpdate`, `flip`, `shift`, `arrow`, `offset` middleware).
+- The tooltip content is teleported to `<body>` via Vue's `<Teleport>` to escape stacking contexts.
+- Show/hide state is managed with a single `isVisible` ref toggled by `mouseenter`/`mouseleave` and `focusin`/`focusout` on the trigger slot wrapper.
+- The delay timer is stored in a `timeoutId` ref and cleared on `mouseleave` to cancel pending show.
+- Arrow positioning is handled by the `arrowEl` template ref passed to the `arrow` middleware; position is applied via `:style` on the arrow element.
+- Source: `framework/ui/components/atoms/vc-tooltip/vc-tooltip.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcVideo
+category: components
+group: media
+---
+
 # VcVideo
 
 An embedded video player that renders an iframe for external video sources (YouTube, Vimeo, etc.) with an optional label and tooltip. When no source URL is provided, the component displays a centered film icon placeholder instead of a blank space, giving users a clear visual cue that a video can be attached.
 
+::storybook id="data-display-vcvideo--default"
+
 ## When to Use
 
 - Embed product or tutorial videos in blade detail views
@@ -32,6 +40,8 @@ import { VcVideo } from "@vc-shell/framework";
 | `label`   | `string` | --      | Label text displayed above the video               |
 | `tooltip` | `string` | --      | Tooltip text shown on the label's info icon        |
 
+::storybook id="data-display-vcvideo--with-tooltip" height="400"
+
 ## Common Patterns
 
 ### Video with Label and Tooltip
@@ -111,8 +121,23 @@ When `source` is not provided, VcVideo renders a centered film icon placeholder
 - `loading="lazy"` defers iframe load until visible
 - Placeholder state uses `role="img"` with `aria-label="No video source"`
 
+!!! warning "Always use embed URLs, not watch URLs"
+YouTube watch URLs (`youtube.com/watch?v=...`) will be blocked by the browser's frame policy. Always convert to the embed format (`youtube.com/embed/VIDEO_ID`). Vimeo similarly requires `player.vimeo.com/video/VIDEO_ID`.
+
 ## Related Components
 
 - [VcLabel](../vc-label/) -- used internally for the label with tooltip
 - [VcIcon](../vc-icon/) -- renders the placeholder film icon
 - [VcRow](../vc-row/) / [VcCol](../vc-col/) -- layout primitives for placing video alongside other content
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcVideo lives in `framework/ui/components/atoms/vc-video/`.
+- The component is a thin wrapper around a native `<iframe>` — no custom video controls are implemented.
+- The `sandbox` attribute is hardcoded to `allow-scripts allow-same-origin allow-presentation allow-popups`. Apps that need additional iframe permissions must wrap the component or use a plain `<iframe>`.
+- The label is rendered via `VcLabel` (internal atom) with the `tooltip` prop forwarded as the VcLabel tooltip slot content.
+- Placeholder state (`source` is falsy) swaps the iframe for a `<div>` with `role="img"` containing a `VcIcon` with `lucide-film`.
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcWidget
+category: components
+group: misc
+---
+
 # VcWidget
 
 A clickable widget tile with an icon, title, and optional badge counter. Used in blade toolbars and sidebars to trigger blade-level actions or navigation.
 
+::storybook id="data-display-vcwidget--default"
+
 ## When to Use
 
 - Build widget panels in blade sidebars (e.g., "Orders", "Reviews", "Notifications")
@@ -49,6 +57,8 @@ function openNotifications() {
 | ------- | ------- | ------------------------------------------------------------- |
 | `click` | none    | Fired when the widget is clicked (suppressed when `disabled`) |
 
+::storybook id="data-display-vcwidget--sidebar-layout" height="350"
+
 ## Common Patterns
 
 ### Sidebar Widget Panel
@@ -112,3 +122,15 @@ Badge values above 99 are automatically displayed as "99+".
 - [VcBadge](../vc-badge/) -- used internally for the count badge overlay
 - [VcIcon](../vc-icon/) -- used internally for the widget icon
 - [VcButton](../vc-button/) -- for standard action buttons
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcWidget lives in `framework/ui/components/atoms/vc-widget/`.
+- The badge overlay is rendered by embedding `VcBadge` with `isDot`/`content` derived from the `value` prop; values above 99 are truncated to `"99+"` in the component template.
+- `isExpanded` applies `.vc-widget--expanded` modifier; used by the shell sidebar to visually distinguish active navigation state.
+- `horizontal` applies `.vc-widget--horizontal` modifier which switches the internal flex direction from `column` to `row`.
+- The widget registers as a keyboard-interactive element (`role="button"`, Enter/Space handlers) rather than using a `<button>` to allow embedding arbitrary icon components without nesting interactive elements.
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md

@@ -1,3 +1,9 @@
+---
+title: MultilanguageSelector
+category: components
+group: form
+---
+
 # MultilanguageSelector
 
 Compact circular flag button that opens a dropdown for selecting a content language. Designed for use in detail blades where entities have multilingual fields (e.g., product name, offer description, category title). This is distinct from the `LanguageSelector` settings entry, which changes the application UI locale -- `MultilanguageSelector` controls which language version of the content the user is editing.
@@ -10,6 +16,8 @@ Compact circular flag button that opens a dropdown for selecting a content langu
 
 ## Basic Usage
 
+::storybook id="shared-multilanguageselector--interactive"
+
 ```vue
 <script setup lang="ts">
 import { ref } from "vue";
@@ -41,6 +49,8 @@ const languages = [
 
 Each `LanguageOption` has: `{ value: string; label: string; flag?: string }`.
 
+::storybook id="shared-multilanguageselector--disabled"
+
 ## Recipe: Multilingual Product Editing Blade
 
 A typical use case is a product detail blade where the user can edit the name and description in multiple languages: