@vc-shell/vc-app-skill 2.0.3 → 2.0.4

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:

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 -->