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

package/docs/README.md

@@ -10,6 +10,8 @@ These docs are optimized for two main scenarios:
 
 ## Documentation Map
 
+- [`../AGENTS.md`](../AGENTS.md)
+  package-level instructions for AI assistants using the installed package.
 - [`AI.md`](./AI.md)
   a compact quickstart for AI agents: which entrypoint to prefer, which reading order to use,
   and which boundaries are safe by default.
@@ -19,6 +21,8 @@ These docs are optimized for two main scenarios:
   the target component profile format for AI assistants.
 - [`STYLING.md`](./STYLING.md)
   shared guidance for reading classes, CSS variables, and typography in profiles.
+- [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md)
+  page composition rules for agents generating full RetailCRM extension screens.
 - [`PROFILES.md`](./PROFILES.md)
   the index of YAML component profiles.
 
@@ -53,13 +57,18 @@ The same rule applies to `.ui-v1-*` selectors in profile `styling` sections.
 
 If you need to generate UI quickly:
 
-1. [`AI.md`](./AI.md)
-2. [`COMPONENTS.md`](./COMPONENTS.md)
-3. the relevant profile from [`PROFILES.md`](./PROFILES.md)
-4. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
+1. [`../README.md`](../README.md)
+2. [`../AGENTS.md`](../AGENTS.md)
+3. [`AI.md`](./AI.md)
+4. [`COMPONENTS.md`](./COMPONENTS.md)
+5. the relevant profile from [`PROFILES.md`](./PROFILES.md)
+6. [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md) if the task is about complete pages,
+   modals, sidebars, filters, tables, or settings layouts
+7. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
 
 If you are extending the docs:
 
 1. [`FORMAT.md`](./FORMAT.md)
 2. [`STYLING.md`](./STYLING.md)
-3. the existing profiles in [`PROFILES.md`](./PROFILES.md)
+3. [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md)
+4. the existing profiles in [`PROFILES.md`](./PROFILES.md)

package/docs/profiles/UiAddButton.yml

@@ -2,6 +2,7 @@ component: UiAddButton
 summary: >
   UiAddButton is an action-first button for add or create flows. It is close to UiButton,
   but tuned for "create another item" scenarios and supports small descriptive additions.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiaddbutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -53,5 +54,34 @@ behavior:
 ai_notes:
   do:
     - Use for create and add flows rather than generic submit actions.
+    - Use description only when it clarifies what will be added.
   avoid:
     - Do not replace a plain UiButton unless the add semantics are intentional.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiPageHeader
+    - UiToolbarButton
+  patterns:
+    - title: Add item action
+      notes: Use near a list, empty state, or repeatable form section where the action creates another item.
+    - title: Page primary create
+      notes: UiButton in UiPageHeader is often better for a main create action; use UiAddButton for local add-another flows.
+
+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-add-button

package/docs/profiles/UiAlert.yml

@@ -2,6 +2,7 @@ component: UiAlert
 summary: >
   UiAlert is a compact contextual message block for status, warning, success, and danger feedback.
   It can be shown inline in normal page flow and can be closable.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uialert--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -44,5 +45,31 @@ behavior:
 ai_notes:
   do:
     - Use UiAlert for inline feedback that should stay in normal layout flow.
+    - Keep the message close to the section or form it describes.
   avoid:
     - Do not use it as a replacement for modal confirmation.
+    - Do not use for field-level validation when UiField or UiError is more precise.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiInfobox
+    - UiError
+  patterns:
+    - title: Section-level feedback
+      notes: Place above or inside the affected section, not at the page top by default.
+    - title: Recoverable error
+      notes: Pair with a retry or fix action when the user can recover immediately.
+
+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-alert

package/docs/profiles/UiAvatar.yml

@@ -2,6 +2,7 @@ component: UiAvatar
 summary: >
   UiAvatar renders a user or entity avatar with optional name, status, and link semantics.
   It is meant for compact identity display rather than generic image rendering.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiavatar--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -44,5 +45,30 @@ behavior:
 ai_notes:
   do:
     - Use UiAvatar for identity display, not for general media.
+    - Provide name whenever possible so fallback identity stays meaningful.
   avoid:
     - Do not use it where UiImage is the better semantic fit.
+
+composition:
+  works_well_with:
+    - UiAvatarList
+    - UiTable
+    - UiMenuItem
+  patterns:
+    - title: Table identity cell
+      notes: Pair with UiLink size="small" when an avatar appears next to a linked user or customer name.
+    - title: Menu identity row
+      notes: Use in UiMenuItem avatar slot for users, customers, or accounts.
+
+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-avatar

package/docs/profiles/UiAvatarList.yml

@@ -2,6 +2,7 @@ component: UiAvatarList
 summary: >
   UiAvatarList renders a compact list of avatars with consistent sizing. It is useful for showing
   several users or actors in a narrow area.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiavatar--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -38,5 +39,32 @@ geometry:
 ai_notes:
   do:
     - Use for compact grouped identity display.
+    - Keep the list short enough to scan.
   avoid:
     - Do not use it as a replacement for a full people list.
+
+behavior:
+  notes:
+    - avatars prop should contain concise identity data, not full profile records.
+    - size should match the density of the surrounding table, menu, or card.
+
+composition:
+  works_well_with:
+    - UiAvatar
+    - UiTooltip
+  patterns:
+    - title: Compact collaborators
+      notes: Use when several actors must be shown in a narrow table or header area.
+
+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-avatar-list

package/docs/profiles/UiButton.yml

@@ -3,6 +3,7 @@ summary: >
   UiButton is the main action component in the library. It covers primary, secondary,
   tertiary, and outlined use cases, can render as either a button or an anchor,
   and adapts well to text-plus-icon and icon-only content.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uibutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -211,14 +212,6 @@ composition:
     - UiInfobox
     - modal actions
 
-examples:
-  - title: Dangerous secondary action
-    goal: Build a secondary destructive action.
-    code: |
-      <UiButton appearance="secondary" variant="danger">
-        <IconDelete aria-hidden="true" />
-        Delete
-      </UiButton>
 
 ai_notes:
   do:

package/docs/profiles/UiCalendar.yml

@@ -2,6 +2,7 @@ component: UiCalendar
 summary: >
   UiCalendar is the date selection primitive behind date and date-range flows. It supports
   single and range selection, multiple visual appearances, and locale-sensitive behavior.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicalendar--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -46,3 +47,30 @@ ai_notes:
     - Use UiCalendar when inline calendar selection is the actual UI.
   avoid:
     - Use UiDatePicker instead if users expect textbox plus popup behavior.
+
+composition:
+  works_well_with:
+    - UiDatePicker
+    - UiField
+  patterns:
+    - title: Inline calendar panel
+      notes: Use in dashboards or popover content when the calendar itself should remain visible.
+    - title: Date input
+      notes: Prefer UiDatePicker for normal forms and filters because it provides the textbox trigger and popper behavior.
+
+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-calendar

package/docs/profiles/UiCheckbox.yml

@@ -2,6 +2,7 @@ component: UiCheckbox
 summary: >
   UiCheckbox is a boolean or set-membership control. It supports single boolean-like usage
   as well as model-plus-value patterns for checkbox groups.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicheckbox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -49,5 +50,36 @@ behavior:
 ai_notes:
   do:
     - Use for boolean choice or checkbox-group membership.
+    - Use indeterminate for parent selection such as "select all visible rows".
   avoid:
     - Do not use for mutually exclusive options.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTable
+    - UiTableColumn
+  patterns:
+    - title: Form boolean
+      notes: Wrap in UiField when the checkbox needs a persistent label, hint, or validation text.
+    - title: Table row selection
+      notes: Use in the first narrow UiTableColumn for row selection; use indeterminate in the header checkbox for partial selection.
+  avoid:
+    - Do not use as a visual switch replacement when the action is an immediate on or off setting.
+
+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-checkbox

package/docs/profiles/UiCollapse.yml

@@ -2,6 +2,7 @@ component: UiCollapse
 summary: >
   UiCollapse is a low-level show and hide container for expandable content. It controls
   whether content is hidden or disposed and how the transition behaves.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicollapse--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -38,3 +39,36 @@ ai_notes:
     - Use UiCollapse as a primitive for expandable content regions.
   avoid:
     - Do not use it when a full disclosure component is the actual need.
+
+behavior:
+  notes:
+    - expanded controls visibility.
+    - collapseBehaviour controls whether collapsed content stays mounted or is disposed.
+    - duration controls transition timing.
+
+composition:
+  works_well_with:
+    - UiCollapseBox
+    - UiCollapseGroup
+  patterns:
+    - title: Custom disclosure
+      notes: Use UiCollapse when the trigger and header are custom and only the body transition is needed.
+    - title: Standard disclosure box
+      notes: Use UiCollapseBox when the screen needs built-in header, icon, and box chrome.
+
+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-collapse

package/docs/profiles/UiCollapseBox.yml

@@ -2,6 +2,7 @@ component: UiCollapseBox
 summary: >
   UiCollapseBox is a structured expandable container with built-in header, state handling,
   and visual treatment. It is a higher-level companion to UiCollapse.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicollapsebox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -47,5 +48,34 @@ behavior:
 ai_notes:
   do:
     - Use UiCollapseBox for structured disclosure UI.
+    - Put the summary in the header and details in the body; avoid hiding critical required fields.
   avoid:
     - Do not rebuild collapse header UI manually when this component already fits.
+
+composition:
+  works_well_with:
+    - UiCollapse
+    - UiCollapseGroup
+    - UiInfobox
+  patterns:
+    - title: Settings section
+      notes: Use for optional or advanced settings groups.
+    - title: Grouped disclosures
+      notes: Use inside UiCollapseGroup when multiple boxes should coordinate active state.
+
+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-collapse-box

package/docs/profiles/UiCollapseGroup.yml

@@ -2,6 +2,7 @@ component: UiCollapseGroup
 summary: >
   UiCollapseGroup coordinates several collapse boxes and tracks which box is active.
   It is useful when multiple disclosures should behave as one grouped unit.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicollapsebox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -37,3 +38,28 @@ geometry:
 ai_notes:
   do:
     - Use with UiCollapseBox when grouped expansion matters.
+  avoid:
+    - Do not introduce a group for a single collapsible section.
+
+behavior:
+  notes:
+    - activeBoxId tracks which child section is active.
+    - The component is mostly coordination logic rather than a visual container.
+
+composition:
+  works_well_with:
+    - UiCollapseBox
+  patterns:
+    - title: Accordion-like settings
+      notes: Use when users should move between several related expandable sections.
+
+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.

package/docs/profiles/UiCopyButton.yml

@@ -2,6 +2,7 @@ component: UiCopyButton
 summary: >
   UiCopyButton is an action component for copying text values with tooltip feedback.
   It wraps copy behavior and copied-state hinting into one compact UI.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicopybutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -50,3 +51,37 @@ geometry:
 ai_notes:
   do:
     - Use for copy-specific flows instead of recreating copy state manually.
+    - Provide the exact text prop that should be copied.
+  avoid:
+    - Do not use for actions whose primary purpose is not copying.
+
+behavior:
+  notes:
+    - Shows normal hint content before copy and copied-state hint after successful copy.
+    - tooltipOptions customizes the hint surface.
+
+composition:
+  works_well_with:
+    - UiTooltip
+    - UiButton
+    - UiTable
+  patterns:
+    - title: Copy value in a table
+      notes: Use for IDs, tokens, phones, or links where copying is a repeated row action.
+
+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-copy-button

package/docs/profiles/UiDate.yml

@@ -2,6 +2,7 @@ component: UiDate
 summary: >
   UiDate is a display component for formatted date or date-time output. It is for presenting
   date values, not for editing them.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uidate--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -36,3 +37,30 @@ geometry:
 ai_notes:
   do:
     - Use UiDate for formatted output and UiDatePicker for input.
+    - Use withTime only when the time changes user interpretation.
+  avoid:
+    - Do not use for editable date fields or filter controls.
+
+behavior:
+  notes:
+    - Renders semantic time output for display.
+    - locale should be explicit when the surrounding screen uses a specific locale.
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiDatePicker
+  patterns:
+    - title: Table date
+      notes: Use plain formatted output in tables; split date and time into separate lines only for compact scanning.
+
+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/UiDatePicker.yml

@@ -2,6 +2,7 @@ component: UiDatePicker
 summary: >
   UiDatePicker combines textbox-like date display, popper behavior, and calendar selection.
   It supports single-date and range flows, constraints, and quick options.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uidatepicker--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -55,5 +56,34 @@ behavior:
 ai_notes:
   do:
     - Prefer UiDatePicker for typed or popup date input.
+    - Use textboxOptions for trigger sizing and placeholder behavior instead of custom trigger markup.
   avoid:
     - Do not use UiCalendar directly if a textbox trigger is expected.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTable
+    - UiCalendar
+  patterns:
+    - title: Date filter
+      notes: Use in the filter area above UiTable for date and date-range filters; persist selected values in URL query parameters when routing exists.
+    - title: Form date input
+      notes: Wrap in UiField so label, hint, and validation are preserved.
+
+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-date-picker

package/docs/profiles/UiError.yml

@@ -2,6 +2,7 @@ component: UiError
 summary: >
   UiError is a compact error-state component for short error messages or fallback states.
   It is intended for concise inline error display rather than large alert copy.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uierror--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -15,6 +16,19 @@ use_when:
 avoid_when:
   - You need a richer feedback block, use UiAlert or UiInfobox instead.
 
+api:
+  key_props:
+    - name: message
+      notes: Fallback error text when default slot is not provided.
+    - name: align
+      notes: left or right text alignment.
+    - name: ellipsis
+      notes: Truncates long error text instead of wrapping.
+  slots:
+    - name: default
+      zone: error-content
+      creates: Error text or compact fallback content.
+
 rendered_structure:
   descriptive_only: true
   root:
@@ -30,3 +44,34 @@ geometry:
 ai_notes:
   do:
     - Use for compact error presentation.
+    - Keep the message short and specific.
+  avoid:
+    - Do not use for multi-paragraph explanations or page-level failures.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiAlert
+  patterns:
+    - title: Field or section error
+      notes: Use where the user needs to see a concise local error message.
+    - title: Page-level failure
+      notes: Use UiAlert or UiInfobox instead when the error needs explanation and actions.
+
+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:
+    - 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-error