@retailcrm/embed-ui-v1-components 0.9.18 → 0.9.21

package/docs/profiles/UiField.yml

@@ -3,6 +3,7 @@ summary: >
   UiField is a remote-only form field wrapper. It connects a label and an inner control through
   id and ARIA data, supports a hint tooltip near the label, and exposes an addon zone on the
   right side of the headline.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uifield--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -208,21 +209,6 @@ composition:
     - title: Safe field wiring
       notes: Use slot props for semantics, not just for visual wrapping.
 
-examples:
-  - title: Text field with propagated semantics
-    goal: Build a text field with correct ARIA wiring.
-    code: |
-      <UiField id="comment" label="Comment" hint="Visible to managers">
-        <template #default="field">
-          <UiTextbox
-            :id="field.id"
-            :input-attributes="{
-              'aria-labelledby': field.ariaLabelledby,
-              'aria-invalid': field.ariaInvalid,
-            }"
-          />
-        </template>
-      </UiField>
 
 ai_notes:
   do:

package/docs/profiles/UiImage.yml

@@ -2,6 +2,7 @@ component: UiImage
 summary: >
   UiImage is a generic image display component with optional resize and crop hints.
   Use it for regular visual content rather than identity avatars.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiimage--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -37,3 +38,30 @@ geometry:
 ai_notes:
   do:
     - Use UiImage for general media and UiAvatar for people or identity.
+    - Provide alt text unless the image is purely decorative in the host context.
+  avoid:
+    - Do not use for status icons or avatars.
+
+behavior:
+  notes:
+    - resize and crop are image processing hints, not layout containers.
+    - Intrinsic image dimensions still matter unless the parent constrains size.
+
+composition:
+  works_well_with:
+    - UiAvatar
+    - UiSkeleton
+  patterns:
+    - title: Content image
+      notes: Use for product, attachment, or preview images where real media is the content.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.

package/docs/profiles/UiInfobox.yml

@@ -2,6 +2,7 @@ component: UiInfobox
 summary: >
   UiInfobox is a richer explanatory block for inline product, warning, or helper content.
   It can be closable and expandable.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiinfobox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -43,3 +44,35 @@ geometry:
 ai_notes:
   do:
     - Use UiInfobox for richer guidance blocks, not tiny alerts.
+    - Use expandable when secondary explanation would otherwise make the screen noisy.
+  avoid:
+    - Do not use for transient success or error states; use UiAlert.
+
+behavior:
+  notes:
+    - shown controls visibility.
+    - expandable and expanded control progressive disclosure.
+    - warning changes the visual tone for cautionary guidance.
+
+composition:
+  works_well_with:
+    - UiAlert
+    - UiCollapse
+  patterns:
+    - title: Product guidance
+      notes: Use near the related form or table, not as a decorative card.
+    - title: Long explanation
+      notes: Prefer expandable content when the text is useful but not always needed.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-infobox

package/docs/profiles/UiLink.yml

@@ -2,6 +2,7 @@ component: UiLink
 summary: >
   UiLink is the main text-link component for inline navigation and inline actions that should
   still read as links rather than buttons.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uilink--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -21,6 +22,7 @@ api:
     - name: external
     - name: appearance
     - name: size
+      notes: Defaults to body text. Use size="small" inside UiTable cells to match table body typography.
     - name: accent
     - name: ellipsis
   slots:
@@ -44,8 +46,46 @@ geometry:
   root_display: inline-flex
   width_behavior: content-sized by default
 
+composition:
+  works_well_with:
+    - UiTable
+    - UiToolbarLink
+    - UiButton
+  patterns:
+    - title: Table primary link
+      notes: Use size="small", accent, and ellipsis for the primary object link in a table cell.
+    - title: External link
+      notes: Use external when the link opens outside the current extension context.
+    - title: Button-shaped navigation
+      notes: Use UiButton with href when the navigation should visually read as a command button.
+
 ai_notes:
   do:
     - Use UiLink for real link semantics and inline navigation.
+    - Use size="small" for links inside UiTable body cells.
+    - Use ellipsis when a table-cell link can contain long names.
   avoid:
     - Do not use UiLink where the action should read as a button.
+    - Do not leave table-cell links at the default body size unless the link is intentionally emphasized.
+
+behavior:
+  notes:
+    - Read key_props first to identify supported states and variants.
+    - Prefer controlled props and documented emits when synchronizing component state with screen logic.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-link

package/docs/profiles/UiLoader.yml

@@ -1,6 +1,7 @@
 component: UiLoader
 summary: >
   UiLoader displays loading progress or waiting state. It can be used inline or as an overlay.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiskeleton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -35,4 +36,38 @@ geometry:
 
 ai_notes:
   do:
+    - Use overlay=true when the loader should dim the covered page or module content.
     - Use overlay or fixed only when the loader should escape normal inline flow.
+    - Preserve surrounding filters and headers when only the content area is loading.
+  avoid:
+    - Do not create custom dimming markup around UiLoader; use the overlay prop.
+    - Do not replace content-shaped loading with a page-wide loader when UiSkeleton would communicate layout better.
+
+behavior:
+  notes:
+    - overlay=true adds the dimmed backdrop for covered content.
+    - fixed and overlay change the loader from inline feedback into a surface-covering state.
+    - diameter and thickness tune the visual weight of the indicator.
+
+composition:
+  works_well_with:
+    - UiSkeleton
+    - UiAlert
+  patterns:
+    - title: Table loading
+      notes: Keep filters visible and show loading in the table area.
+    - title: Blocking operation
+      notes: Use overlay only when interaction with the covered content must be blocked.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-loader

package/docs/profiles/UiMenuItem.yml

@@ -2,6 +2,7 @@ component: UiMenuItem
 summary: >
   UiMenuItem is a structured menu row component with support for icons, avatar, description,
   counters, and active or danger styling.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/uimenuitem--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -55,3 +56,40 @@ geometry:
 ai_notes:
   do:
     - Use structured slots instead of custom wrappers inside menu rows.
+    - Use danger only for destructive menu actions.
+  avoid:
+    - Do not use as a generic card or list row outside menu-like surfaces.
+
+behavior:
+  notes:
+    - active marks the current or selected item.
+    - disabled prevents interaction.
+    - danger changes semantic tone for destructive actions.
+
+composition:
+  works_well_with:
+    - UiMenuItemGroup
+    - UiAvatar
+    - UiTag
+  patterns:
+    - title: Command menu row
+      notes: Use leading-icon for action identity and trailing-icon for disclosure or shortcut-like hints.
+    - title: Entity menu row
+      notes: Use avatar and description slots for users, customers, or entities.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-menu-item

package/docs/profiles/UiMenuItemGroup.yml

@@ -2,6 +2,7 @@ component: UiMenuItemGroup
 summary: >
   UiMenuItemGroup groups related menu items and exposes dedicated zones for group label
   and quantity metadata.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/uimenuitem--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -48,3 +49,29 @@ geometry:
 ai_notes:
   do:
     - Use for grouped menu structure instead of manual heading-plus-list markup.
+  avoid:
+    - Do not group unrelated actions only for visual spacing.
+
+behavior:
+  notes:
+    - The group organizes nested menu rows but does not manage selection by itself.
+
+composition:
+  works_well_with:
+    - UiMenuItem
+  patterns:
+    - title: Grouped options
+      notes: Use label and quantity slots to clarify large option groups.
+
+accessibility:
+  notes:
+    - Keep visible labels and slot content meaningful.
+    - Prefer documented props and slots over custom DOM replacements so host-side accessibility behavior is preserved.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-menu-item-group

package/docs/profiles/UiModalSidebar.yml

@@ -2,6 +2,7 @@ component: UiModalSidebar
 summary: >
   UiModalSidebar is a side-docked modal surface with open state, direction, size, and
   scrolling control. Use it when the UI should slide from an edge instead of opening as a centered dialog.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uimodalsidebar--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -44,3 +45,34 @@ behavior:
 ai_notes:
   do:
     - Use UiModalSidebar when page context should stay visually connected to the modal content.
+    - Use for inspect, edit, or secondary workflows that relate to the current list or page.
+  avoid:
+    - Do not use for short confirmations; use UiModalWindow.
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiField
+    - UiButton
+  patterns:
+    - title: Row detail side panel
+      notes: Open from a table row when the user should keep list context visible.
+    - title: Side edit form
+      notes: Put primary actions in the sidebar footer when the form edits the selected object.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-modal-sidebar-overlay

package/docs/profiles/UiModalWindow.yml

@@ -2,6 +2,7 @@ component: UiModalWindow
 summary: >
   UiModalWindow is the main centered modal container. It supports open state, closability,
   appearance variants, fullscreen and responsive behavior, and dialog roles.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uimodalwindow--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -42,3 +43,44 @@ geometry:
   layout: teleported modal layer with centered surface
   root_display: flex
   width_behavior: viewport-covering overlay with content-sized or responsive surface
+
+behavior:
+  notes:
+    - opened controls modal visibility.
+    - closable should be false only when the user must complete or acknowledge a blocking flow.
+    - fullscreen and responsive affect surface sizing rather than modal semantics.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiField
+    - UiModalWindowSurface
+  patterns:
+    - title: Confirmation dialog
+      notes: Keep copy concise and put primary and secondary actions in the footer.
+    - title: Focused form
+      notes: Use for short forms that should not navigate away from the current page.
+
+ai_notes:
+  do:
+    - Use for focused blocking tasks and confirmations.
+    - Provide clear title, body, and footer actions when the modal asks the user to decide.
+  avoid:
+    - Do not use as a general page layout or for long workflows that deserve a full page or sidebar.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-modal-window

package/docs/profiles/UiModalWindowSurface.yml

@@ -2,6 +2,7 @@ component: UiModalWindowSurface
 summary: >
   UiModalWindowSurface is the lower-level modal surface API behind modal window flows.
   Use it when you need modal surface behavior with more explicit composition control.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uimodalwindow--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -39,3 +40,34 @@ geometry:
   layout: teleported modal overlay
   root_display: flex
   width_behavior: viewport-covering overlay with content-sized or responsive surface
+
+behavior:
+  notes:
+    - Lower-level surface keeps modal mechanics while leaving more composition responsibility to the caller.
+    - Use role intentionally for dialog or alertdialog flows.
+
+composition:
+  works_well_with:
+    - UiModalWindow
+  patterns:
+    - title: Custom modal shell
+      notes: Use only when UiModalWindow does not expose enough structure for the required modal.
+
+ai_notes:
+  do:
+    - Prefer UiModalWindow for ordinary centered dialogs.
+  avoid:
+    - Do not choose the surface API just to change simple body content.
+
+accessibility:
+  notes:
+    - Keep visible labels and slot content meaningful.
+    - Prefer documented props and slots over custom DOM replacements so host-side accessibility behavior is preserved.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-modal-window

package/docs/profiles/UiNumberStepper.yml

@@ -2,6 +2,7 @@ component: UiNumberStepper
 summary: >
   UiNumberStepper is a numeric input with increase and decrease controls. It is built for
   constrained numeric entry where arrowing and step-based changes matter.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uinumberstepper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -50,3 +51,38 @@ behavior:
   notes:
     - Can clamp values into range.
     - Supports horizontal and vertical direction.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTextbox
+    - UiSlider
+  patterns:
+    - title: Exact bounded number
+      notes: Use for quantities, limits, delays, and other settings where increment and decrement controls are useful.
+    - title: Numeric filter
+      notes: In table filters, keep the value in query parameters when routing exists.
+
+ai_notes:
+  do:
+    - Use for precise numeric settings with known min, max, or step.
+    - Prefer nullable when clearing the value is a valid state.
+  avoid:
+    - Do not use when the value is an identifier, phone, code, or other numeric-looking text.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-number-stepper

package/docs/profiles/UiPageHeader.yml

@@ -3,6 +3,7 @@ summary: >
   UiPageHeader is a page or major section header with an optional inline addon next to the title
   and an optional actions area on the right. In display state it renders the title as a semantic h1;
   in edit state it switches to UiTextbox.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipageheader--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -209,29 +210,6 @@ composition:
     - title: Compact actions
       notes: Keep only one or two compact actions on the right.
 
-examples:
-  - title: Editable header with addon and actions
-    goal: Build a page header with inline validation and a link near the title.
-    code: |
-      <UiPageHeader
-        v-model:value="title"
-        :invalid="!title"
-        :error="title ? '' : 'Title is required'"
-        editable
-        placeholder="Enter a title"
-      >
-        <template #addon>
-          <UiLink>
-            Collapse filter
-          </UiLink>
-        </template>
-
-        <template #actions>
-          <UiButton appearance="tertiary">
-            Actions
-          </UiButton>
-        </template>
-      </UiPageHeader>
 
 ai_notes:
   do:

package/docs/profiles/UiPopper.yml

@@ -3,6 +3,7 @@ summary: >
   UiPopper is the low-level floating layer used for tooltips, dropdowns, and popups.
   It controls visibility, teleport container, positioning, and trigger logic, but is usually
   consumed as part of a higher-level component rather than as a standalone content wrapper.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipopper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -178,19 +179,6 @@ composition:
     - title: Shared target context
       notes: The target ref usually comes through UiPopperConnector and UiPopperTarget.
 
-examples:
-  - title: Mental model
-    goal: Understand the basic target plus floating content pattern.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget>
-          <button type="button">Open</button>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Popup content
-        </UiPopper>
-      </UiPopperConnector>
 
 ai_notes:
   do:

package/docs/profiles/UiPopperConnector.yml

@@ -3,6 +3,7 @@ summary: >
   UiPopperConnector is a lightweight wrapper that gives target-side and popper-side parts
   a shared target context. It has almost no UI meaning on its own, but is often required
   for correct target-driven floating behavior.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipopper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -80,31 +81,6 @@ composition:
     - title: Explicit anchor
       notes: Add UiPopperTarget only when the anchor must be limited to a specific wrapper or sub-area.
 
-examples:
-  - title: Shared target context
-    goal: Connect target and popper through one shared wrapper.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget>
-          <button type="button">Open</button>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Content
-        </UiPopper>
-      </UiPopperConnector>
-  - title: Connector without explicit target
-    goal: Use a button as the implicit anchor.
-    code: |
-      <UiPopperConnector>
-        <UiButton appearance="secondary">
-          Open
-        </UiButton>
-
-        <UiPopper :visible="open">
-          Content
-        </UiPopper>
-      </UiPopperConnector>
 
 ai_notes:
   do:
@@ -113,3 +89,9 @@ ai_notes:
   avoid:
     - Do not use it as a styling wrapper.
     - Do not add UiPopperTarget automatically around every trigger.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.

package/docs/profiles/UiPopperTarget.yml

@@ -2,6 +2,7 @@ component: UiPopperTarget
 summary: >
   UiPopperTarget is the target-side wrapper that registers a DOM element in popper context.
   A good mental model is "this node is the anchor", not "this is a visual layout wrapper".
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipopper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -83,31 +84,6 @@ composition:
     - title: Not always needed
       notes: Connector-only composition is enough when the trigger already exposes its root element.
 
-examples:
-  - title: Tooltip anchor
-    goal: Anchor a floating layer to a specific title or button wrapper.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget tag="span">
-          <span>Title</span>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Tooltip
-        </UiPopper>
-      </UiPopperConnector>
-  - title: Explicit title-only anchor
-    goal: Bind the floating layer to a title wrapper instead of the whole row.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget tag="span">
-          <span class="header-title">Title</span>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Tooltip
-        </UiPopper>
-      </UiPopperConnector>
 
 ai_notes:
   do:
@@ -116,3 +92,9 @@ ai_notes:
   avoid:
     - Do not treat the wrapper as decorative only; it affects what the floating layer anchors to.
     - Do not wrap every UiButton or similar trigger with UiPopperTarget if connector already gives the correct anchor.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.