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

package/runtime/knowledge/docs/ui/components/molecules/vc-accordion/vc-accordion.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcAccordion
+category: components
+group: data-display
+---
+
 # VcAccordion
 
 Collapsible content sections with smooth CSS grid animations, customizable collapsed heights with fade-out preview, and four visual variants. Supports both data-driven rendering via `items` array and slot-based composition with `VcAccordionItem`.
@@ -17,6 +23,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="action-vcaccordion--default"
+
 ```vue
 <template>
   <VcAccordion
@@ -38,6 +46,9 @@ const faqItems = [
 
 ## Features
 
+!!! tip "Use v-model to control initial open state"
+Without `v-model`, no items are expanded on mount. Pass an initial value to pre-open a specific item.
+
 ### Visual Variants
 
 Four variants control the visual grouping and spacing of accordion items.
@@ -78,6 +89,8 @@ const items = [
 </script>
 ```
 
+::storybook id="action-vcaccordion--bordered-variant"
+
 ### Multiple Open Items
 
 Set `multiple` to `true` to allow expanding several items simultaneously. The `v-model` value becomes an array.
@@ -86,6 +99,8 @@ Set `multiple` to `true` to allow expanding several items simultaneously. The `v
 <VcAccordion v-model="openItems" :items="items" :multiple="true" />
 ```
 
+::storybook id="action-vcaccordion--multiple-open"
+
 ### Partial Content Preview (collapsedHeight)
 
 When `collapsedHeight` > 0, collapsed items show that many pixels of content with a fade-out gradient. The chevron only appears when content overflows.
@@ -262,6 +277,8 @@ interface AccordionItem {
 
 - [VcAccordionItem](./_internal/vc-accordion-item/) -- individual accordion panel (used internally and available via the default slot)
 
+::storybook id="action-vcaccordion--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.

package/runtime/knowledge/docs/ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcBreadcrumbs
+category: components
+group: navigation
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props) · [Slots](#slots) · [CSS Variables](#css-variables) · [Accessibility](#accessibility)
+
 # VcBreadcrumbs
 
 Navigation breadcrumb trail that displays the user's location within a hierarchy and adaptively collapses middle items into a dropdown when horizontal space is limited.
 
+::storybook id="navigation-vcbreadcrumbs--default"
+
 ## When to Use
 
 - Showing the user's current position in a blade navigation hierarchy
@@ -51,6 +62,8 @@ interface Breadcrumbs {
 
 ## Adaptive Overflow
 
+::storybook id="navigation-vcbreadcrumbs--many-items"
+
 VcBreadcrumbs monitors the container width with `useAdaptiveItems` and automatically collapses middle items into a dropdown when they do not fit. The first and last items stay visible; overflow items appear behind a "more" button (vertical ellipsis).
 
 The collapse algorithm uses a reverse strategy -- it hides items starting from the left (after the first) so the current page (last item) always remains visible.
@@ -64,6 +77,8 @@ The collapse algorithm uses a reverse strategy -- it hides items starting from t
 
 ## Separated Style
 
+::storybook id="navigation-vcbreadcrumbs--separated"
+
 Enable slash separators between items with the `separated` prop:
 
 ```vue
@@ -275,3 +290,15 @@ clickHandler: () => { navigate(); return true; }
 - [VcDropdown](../vc-dropdown/) -- Used internally to render the overflow menu
 - [VcBreadcrumbsItem](./_internal/vc-breadcrumbs-item/) -- Internal sub-component for individual breadcrumb rendering
 - [VcButton](../../atoms/vc-button/) -- Can be used inside the `trigger` slot for a styled overflow button
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Overflow detection uses `useAdaptiveItems` composable with `calculationStrategy: "reverse"` — items are hidden starting from the second item (left side), keeping the last item (current page) always visible.
+- `MORE_BUTTON_WIDTH = 36` and `INITIAL_ITEM_WIDTH = 60` are conservative estimates used in the initial layout pass before DOM measurement.
+- The `VcDropdown` instance for the overflow menu uses `floating` and `placement="bottom-start"`.
+- `VcBreadcrumbsItem` is an internal sub-component in `_internal/vc-breadcrumbs-item/` — not exported from the index.
+- The `useBreadcrumbs` composable lives in `framework/core/composables/useBreadcrumbs/`.
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-checkbox/vc-checkbox.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcCheckbox
+category: components
+group: form
+---
+
 # VcCheckbox
 
 A checkbox component supporting boolean toggling, array-based multi-selection, indeterminate state, three size variants, and animated check/uncheck transitions. Works as both a standalone boolean toggle and a member of a multi-select group.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables).
+
+::storybook id="form-vccheckbox--basic"
+
 ## When to Use
 
 - Single boolean toggle with an inline label (e.g., "I agree to terms")
@@ -69,6 +80,8 @@ const selected = ref<string[]>([]);
 
 ### Size Variants
 
+::storybook id="form-vccheckbox--sizes"
+
 Three sizes are available via the `size` prop:
 
 | Size   | Value           | Pixel dimension |
@@ -85,6 +98,8 @@ Three sizes are available via the `size` prop:
 
 ### Indeterminate State (Select All)
 
+::storybook id="form-vccheckbox--indeterminate"
+
 The `indeterminate` prop renders a horizontal dash instead of a checkmark. This is commonly used for "select all" checkboxes where only some children are selected.
 
 ```vue
@@ -355,3 +370,15 @@ const selected = ref<string[]>([]);
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcCheckbox uses a visually hidden native `<input type="checkbox">` for full keyboard and screen reader support. The custom visual (`vc-checkbox__custom-input`) mirrors its state via CSS sibling selectors (`:checked + .vc-checkbox__custom-input`).
+- Indeterminate state is set imperatively (`checkboxRef.value.indeterminate = val`) since HTML does not support `indeterminate` as an attribute — a watcher syncs the prop to the DOM property.
+- Check/uncheck icons use Vue `<Transition name="vc-checkbox-check">` with `@keyframes` animations for the scale/opacity effect.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-checkbox/vc-checkbox.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcCheckboxGroup
+category: components
+group: form
+---
+
 # VcCheckboxGroup
 
 Accessible checkbox group that wraps multiple checkboxes in a semantic fieldset with shared label, hint, error state, and layout control.
 
+::storybook id="form-vccheckboxgroup--default"
+
 ## When to Use
 
 - Selecting multiple options from a set (e.g., notification channels, feature flags)
@@ -75,6 +83,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 
 ### Horizontal Layout
 
+::storybook id="form-vccheckboxgroup--horizontal"
+
 ```vue
 <VcCheckboxGroup
   v-model="permissions"
@@ -90,6 +100,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 
 ### With Disabled Option
 
+::storybook id="form-vccheckboxgroup--with-disabled-option"
+
 ```vue
 <VcCheckboxGroup
   v-model="selected"
@@ -135,3 +147,14 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcCheckboxGroup delegates rendering to `VcInputGroup` (semantic fieldset wrapper) and renders `VcCheckbox` items from the `options` array, or passes through the default slot for custom layouts.
+- The group generates a unique `name` attribute via `useId()` when none is provided, ensuring native radio group behavior.
+- `normalizedModelValue` guards against non-array `modelValue` to avoid runtime errors when the parent passes `undefined`.
+- Source file: `framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-color-input/vc-color-input.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcColorInput
+category: components
+group: form
+---
+
+!!! tip "Quick reference"
+See [Key Props](#key-props) for the full prop table, or jump to [Common Patterns](#common-patterns) for copy-paste examples.
+
 # VcColorInput
 
 A color input that combines a text field for hex values with a clickable color swatch that opens the native browser color picker. Accepts hex codes and CSS color names.
 
+::storybook id="form-vccolorinput--default"
+
 ## Overview
 
 Color selection is needed in various admin scenarios: configuring brand colors, setting category badges, defining product attribute colors, or customizing theme variables. The native HTML `<input type="color">` provides a color picker but lacks text entry, validation, and consistent styling.
@@ -53,6 +64,8 @@ const color = ref<string | null>(null);
 
 ### With Validation
 
+::storybook id="form-vccolorinput--with-error"
+
 ```vue
 <template>
   <VcColorInput
@@ -198,3 +211,14 @@ The native color picker does not support alpha/transparency. If you need RGBA co
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- The swatch button is a native `<button type="button">` that triggers a hidden `<input type="color">` via programmatic `.click()`. The native color picker is not visible — only the swatch button is.
+- Color synchronization: typing in the text field updates `modelValue` directly; selecting from the native picker emits the new hex value and also updates the text field.
+- The component does NOT validate hex format — any string is accepted as-is and the swatch will display whatever color the browser interprets.
+- Source file: `framework/ui/components/molecules/vc-color-input/vc-color-input.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcDatePicker
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcDatePicker
 
 A date and datetime picker that wraps the [VueDatePicker](https://vue3datepicker.com/) library with the standard form field chrome (label, hint, error, focus ring). Formats dates using the browser's locale and automatically detects 12-hour vs. 24-hour time format.
 
+::storybook id="form-vcdatepicker--default"
+
 ## When to Use
 
 - Selecting a single date value (e.g., delivery date, publication date)
@@ -39,6 +50,8 @@ const date = ref<Date | null>(null);
 
 ### Date vs. DateTime Mode
 
+::storybook id="form-vcdatepicker--date-time"
+
 The `type` prop controls whether the picker shows a date-only calendar or includes an inline time picker.
 
 ```vue
@@ -130,6 +143,8 @@ const form = reactive({
 
 ### States
 
+::storybook id="form-vcdatepicker--with-error"
+
 ```vue
 <!-- Required -->
 <VcDatePicker v-model="date" label="Due date" required />
@@ -345,3 +360,15 @@ Uses the same `--input-*` variables as VcInput for consistent styling across all
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Wraps the third-party `VueDatePicker` component. The underlying library is `@vuepic/vue-datepicker`.
+- 12h/24h auto-detection uses the `Intl.DateTimeFormat` API with a sentinel date (midnight on 2023-01-01) to check if the locale's time representation contains "AM" or "PM".
+- The `datePickerOptions` prop is spread onto `<VueDatePicker>` via `v-bind`. Props explicitly set on `VcDatePicker` take precedence over `datePickerOptions` entries of the same name.
+- The `maxDate` for date-only mode is capped at `9999-12-31` to prevent the underlying library from crashing on out-of-range dates.
+- Source file: `framework/ui/components/molecules/vc-date-picker/vc-date-picker.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md

@@ -1,3 +1,12 @@
+---
+title: VcDropdown
+category: components
+group: navigation
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props) · [Events](#events) · [Slots](#slots) · [CSS Variables](#css-variables) · [Accessibility](#accessibility)
+
 # VcDropdown
 
 A headless, accessible dropdown primitive for building menus and listboxes. Provides floating positioning via `@floating-ui`, full keyboard navigation, slot-based rendering, and configurable close behavior. This is a low-level building block -- for form field selection, use VcSelect instead.
@@ -17,6 +26,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="overlay-vcdropdown--action-menu"
+
 ```vue
 <template>
   <VcDropdown
@@ -97,6 +108,8 @@ Build rich action menus by customizing the `#item` slot with icons, labels, and
 
 ### Listbox Mode (Selection Switcher)
 
+::storybook id="overlay-vcdropdown--workspace-switcher"
+
 Use `role="listbox"` for option-selection patterns. Combine with `isItemActive` to highlight the current selection and `aria-selected` is set automatically.
 
 ```vue
@@ -369,3 +382,17 @@ By default, `padded` is `true`, which adds compact padding and rounded item back
 - [VcDropdownPanel](../vc-dropdown-panel/) -- floating panel with header, footer, and scrollable content
 - [VcSelect](../vc-select/) -- form field dropdown for selecting values with label and validation
 - [VcMenu](../vc-menu/) -- sidebar navigation menu
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `VcDropdown` is a generic component (`generic="T"`). TypeScript infers `T` from the `items` prop, giving type-safe `item-click` payloads and slot props.
+- Floating positioning uses `useFloatingPosition` (a thin wrapper around `@floating-ui/vue`) with `autoUpdate: true` when `floating` is enabled — the panel recalculates its position on scroll/resize.
+- Teleport target is determined by `useTeleportTarget`. When `floating` is `true`, the panel is teleported to avoid z-index stacking context issues.
+- Keyboard navigation (`ArrowDown`, `ArrowUp`, `Home`, `End`, `Enter`/`Space`, `Escape`) is handled in `onPanelKeydown`. Escape also attaches a document-level listener when the dropdown is open to catch events that bubble past the panel.
+- `syncFocusedIndex` is called on open to pre-focus the active item (via `isItemActive`) or the first item.
+- The `VcDropdownItem` internal sub-component (in `_internal/VcDropdownItem.vue`) is used by `VcBreadcrumbs` for its overflow menu items.
+- Default `zIndex` is `9300` (matches the CSS custom property `--z-critical-dropdown`).
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcDropdownPanel
+category: components
+group: navigation
+---
+
 # VcDropdownPanel
 
 Floating dropdown panel positioned relative to an anchor element, with header, scrollable content, and optional footer. Built on `@floating-ui/vue`.
 
+::storybook id="overlay-vcdropdownpanel--default"
+
 ## When to Use
 
 - Rich dropdown content with a title bar and action buttons (e.g., filter panels, settings popovers)
@@ -70,6 +78,8 @@ const open = ref(false);
 
 ## Common Patterns
 
+::storybook id="overlay-vcdropdownpanel--with-footer"
+
 ### Filter Panel with Footer Actions
 
 ```vue
@@ -142,3 +152,15 @@ const open = ref(false);
 
 - [VcDropdown](../vc-dropdown/) — headless dropdown for simple item lists
 - [VcSelect](../vc-select/) — form field selection dropdown
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Click-outside detection uses a `pointerdown` listener on `document` rather than a backdrop overlay. This ensures clicks on high-z-index siblings (sidebar, other teleported panels) are still caught.
+- `panelAnchorRegistry` (`panel-anchor-registry.ts`) is a `WeakMap<Element, HTMLElement | null>` that maps each open panel's DOM element to its anchor. This is used to distinguish child panels (whose anchor lives inside this panel) from sibling/parent panels when deciding whether to close on outside click.
+- Nested VcSelect dropdowns teleported to `<body>` are exempt from click-outside via an ARIA `aria-controls` check: if the clicked `.vc-select__dropdown` has an `id` that matches an `aria-controls` attribute inside this panel, the close is suppressed.
+- The panel exposes a `close()` method via `defineExpose` for use with template refs.
+- `useTeleportTarget` resolves the teleport destination (typically `body`) respecting any custom portal container.
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-editor/vc-editor.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcEditor
+category: components
+group: form
+---
+
 # VcEditor
 
 A rich text editor built on TipTap that supports both Markdown and HTML content. Includes a customizable toolbar, multiple view modes (WYSIWYG, preview, source, split), fullscreen editing, image upload, character limits, and plugin-style custom toolbar buttons.
@@ -17,6 +23,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="form-vceditor--default" height="500"
+
 ```vue
 <template>
   <VcEditor
@@ -50,6 +58,9 @@ The editor header provides four view modes plus a fullscreen toggle:
 
 The editor automatically detects whether content is Markdown or HTML based on pattern analysis and outputs in the same format. HTML content is auto-formatted with Prettier in source/split views.
 
+!!! note "Content format is auto-detected"
+VcEditor detects whether content is Markdown or HTML and outputs in the same format. If you pass Markdown input, you will get Markdown output. If you need HTML output, start with HTML content.
+
 ### Custom Toolbar Configuration
 
 Limit which toolbar buttons appear by passing a `toolbar` array. Only the specified buttons will render. Available toolbar names:
@@ -80,6 +91,8 @@ When `assetsFolder` is provided, the image toolbar button becomes functional. Cl
 
 Multiple images can be selected at once. The upload accepts any image file type (`image/*`).
 
+::storybook id="form-vceditor--custom-toolbar" height="500"
+
 ### Custom Toolbar Buttons (Plugin System)
 
 Extend the toolbar with custom buttons or dropdowns. Each custom button specifies an `id`, `label`, `icon`, `action` callback, and optional `group`/`order` for positioning.
@@ -133,6 +146,8 @@ Pass extra TipTap extensions via the `extensions` prop to augment the built-in s
 <VcEditor v-model="content" :extensions="[Highlight.configure({ multicolor: true })]" />
 ```
 
+::storybook id="form-vceditor--with-custom-buttons" height="500"
+
 ### Validation with vee-validate Field
 
 Integrate with vee-validate's `Field` component for form-level validation.
@@ -283,6 +298,8 @@ const content = ref("<h1>Title</h1>");
 - [VcTextarea](../vc-textarea/) -- plain multi-line text input (no formatting)
 - [VcInput](../vc-input/) -- single-line text input
 
+::storybook id="form-vceditor--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.

package/runtime/knowledge/docs/ui/components/molecules/vc-field/vc-field.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcField
+category: components
+group: form
+---
+
 # VcField
 
 Read-only display component for labeled information, supporting various content types like text, dates, links, and emails.
@@ -18,6 +24,8 @@ The component uses a vertical layout by default (label above value), but support
 
 ## Basic Usage
 
+::storybook id="form-vcfield--default"
+
 ```vue
 <template>
   <VcField
@@ -31,6 +39,9 @@ import { VcField } from "@vc-shell/framework";
 </script>
 ```
 
+!!! tip "Prefer VcField over disabled VcInput for read-only data"
+VcField renders without form-field chrome (borders, focus rings, placeholders) and formats content in a type-aware way. A disabled `VcInput` carries unnecessary visual noise for display-only scenarios.
+
 ## Key Props
 
 | Prop          | Type                                                  | Default      | Description                                               |
@@ -91,6 +102,8 @@ Each `type` value renders the content differently:
 </template>
 ```
 
+::storybook id="form-vcfield--link" height="300"
+
 ### Horizontal Layout with Custom Ratio
 
 Use horizontal layout for compact key-value displays where the label and value sit side by side. The `aspectRatio` controls the relative widths of the label and value columns:
@@ -121,6 +134,8 @@ Use horizontal layout for compact key-value displays where the label and value s
 </template>
 ```
 
+::storybook id="form-vcfield--horizontal"
+
 ### Copyable ID Fields
 
 The copy button provides visual feedback (checkmark icon for 1 second) after a successful copy:
@@ -211,6 +226,8 @@ In `orientation="horizontal"` the component reserves the `aspectRatio[0]` track
 - [VcLabel](../../atoms/vc-label/) -- standalone label atom used internally
 - [VcCol](../../atoms/vc-col/) -- column layout atom used for aspect ratio
 
+::storybook id="form-vcfield--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.

package/runtime/knowledge/docs/ui/components/molecules/vc-file-upload/vc-file-upload.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcFileUpload
+category: components
+group: form
+---
+
 # VcFileUpload
 
 Drag-and-drop file upload zone with file type filtering, validation, loading state, and error display. Provides both drag-and-drop and click-to-browse interactions in a single drop zone.
@@ -15,6 +21,8 @@ Drag-and-drop file upload zone with file type filtering, validation, loading sta
 
 ## Quick Start
 
+::storybook id="form-vcfileupload--default"
+
 ```vue
 <template>
   <VcFileUpload
@@ -75,6 +83,9 @@ Integrate with vee-validate for file validation rules such as size limits:
 
 When validation fails, the error is displayed below the drop zone using the built-in `VcHint` component. The `upload` event is only emitted when validation passes.
 
+!!! warning "FileList is not a plain Array"
+The `upload` event emits a `FileList` object, not `File[]`. Always convert with `Array.from(files)` before calling array methods like `.map()` or `.filter()`.
+
 ## Loading State
 
 Show a loading overlay while files are being processed or uploaded:
@@ -102,6 +113,8 @@ Override the default drag-and-drop instructions and icon:
 
 The default icon is `"lucide-cloud-upload"`. The default text is pulled from the `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.DRAG_HERE` and `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.BROWSE` locale keys.
 
+::storybook id="form-vcfileupload--loading"
+
 ## Error Display
 
 Errors can come from three sources (by priority): the `errorMessage` prop, vee-validate `rules`, or the `error` slot for fully custom rendering.
@@ -120,6 +133,8 @@ Errors can come from three sources (by priority): the `errorMessage` prop, vee-v
 
 When any error is present, the drop zone border changes to the error color and a ring appears.
 
+::storybook id="form-vcfileupload--with-error-message"
+
 ## Disabled State
 
 Disable all interactions (drag, drop, click, keyboard):
@@ -316,6 +331,8 @@ async function onUpload(files: FileList) {
 - [VcImageTile](../vc-image-tile/) -- Image display tile used inside galleries
 - [VcHint](../../atoms/vc-hint/) -- Used internally for error message display
 
+::storybook id="form-vcfileupload--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.

package/runtime/knowledge/docs/ui/components/molecules/vc-form/vc-form.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcForm
+category: components
+group: form
+---
+
 # VcForm
 
 A lightweight `<form>` wrapper that provides consistent styling, prevents default browser submission, and serves as the standard container for validated form fields in blade detail views.
@@ -16,6 +22,8 @@ A lightweight `<form>` wrapper that provides consistent styling, prevents defaul
 
 ## Quick Start
 
+::storybook id="form-vcform--basic"
+
 ```vue
 <template>
   <VcForm @submit="handleSubmit">
@@ -50,6 +58,9 @@ function handleSubmit() {
 
 ---
 
+!!! note "Form validation is handled by vee-validate"
+VcForm itself does not validate fields — it only provides the `<form>` wrapper. Use vee-validate's `Field` component around each input that needs validation rules.
+
 ## Features
 
 ### Basic Form Layout (VcForm + VcRow + VcCol)
@@ -174,6 +185,8 @@ const bladeToolbar = ref<IBladeToolbar[]>([
 
 ---
 
+::storybook id="form-vcform--with-fieldsets" height="500"
+
 ## Recipes
 
 ### Complete CRUD Blade Form
@@ -303,6 +316,8 @@ onBeforeClose(async () => {
 </script>
 ```
 
+::storybook id="form-vcform--horizontal-layout" height="400"
+
 ### Form with Mixed Field Types
 
 Demonstrates inputs, selects, checkboxes, and switches together in a single form.

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

@@ -1,3 +1,9 @@
+---
+title: VcImageTile
+category: components
+group: data-display
+---
+
 # VcImageTile
 
 Square image tile with skeleton loading, fade-in transition, and a slide-up action tray on hover (desktop) or tap (touch devices).
@@ -10,6 +16,8 @@ Square image tile with skeleton loading, fade-in transition, and a slide-up acti
 
 ## Basic Usage
 
+::storybook id="action-vcimagetile--default"
+
 ```vue
 <template>
   <div style="width: 160px;">
@@ -73,6 +81,8 @@ interface VcImageTileActions {
 
 ## Common Patterns
 
+::storybook id="action-vcimagetile--all-actions"
+
 ### Image Grid
 
 ```vue
@@ -114,6 +124,8 @@ interface VcImageTileActions {
 </VcImageTile>
 ```
 
+::storybook id="action-vcimagetile--skeleton"
+
 ### Skeleton State
 
 When `src` is not provided or the image is still loading, a shimmer animation skeleton is displayed automatically. No additional configuration is needed.